Integrating and Configuring Hibernate - Beginning Hibernate: From Novice to Professional - page 20

on the classpath, respectively. We discuss mapping file configuration in the next section and
caching in Chapter 9.
After placing your XML configuration file in the root directory of the classpath, you will
need to call one of the configure() methods on your application's Configuration object. With
the default file name ( hibernate.cfg.xml ), you can call configure() with no arguments. If you
used a different file name (for instance, because you have production, staging, user accept-
ance test, and development environments, with different databases), use one of the following
methods on a Configuration object:
• public Configuration configure(String) throws HibernateException : Loads the XML
configuration from a resource accessible by the current thread's context class loader
• public Configuration configure(URL) throws HibernateException : Retrieves the XML
configuration from a valid URL
• public Configuration configure(File) throws HibernateException : Uses an XML
configuration file on the file system
Mapping Documents
Once you have created your mapping documents for Hibernate, it needs to know where to
find them. Before you create the session factory, add them to your Configuration object, or
specify them in the hibernate.cfg.xml XML configuration file. If you choose to add the map-
ping documents directly to an instance of Configuration , use one of the following methods:
• addFile(String) : Uses the path to an XML mapping document for Hibernate. An
example of this would be com/hibernatebook/config/Example.hbm.xml
• addFile(File) : Uses a File object that represents an XML mapping document
• addClass(Class) : Translates a Java class name into a file name, which Hibernate then
loads as an input stream from the Java class's class loader; for example, Hibernate
would look for the file called com/hibernatebook/config/Example.hbm.xml for a class
named com.hibernatebook.config.Example
• addJar(File) : Adds any mapping documents ( *.hbm.xml ) in the specified JAR file to the
Configuration object
• addDirectory(File) : Adds any mapping documents ( *.hbm.xml ) in the specified direc-
tory to the Configuration object
The following methods also add mapping documents to the Configuration object, but
you are unlikely to need them unless you have specialized application deployment issues:
• addXML(String) : Takes a String object that contains the Hibernate mapping XML.
• addURL(URL) : Requires a valid URL to the Hibernate mapping XML.