From 7225b367351ea35837933516a4a958f332cf0680 Mon Sep 17 00:00:00 2001 From: Christian Bauer Date: Tue, 17 Aug 2004 10:42:31 +0000 Subject: [PATCH] First batch of doco updates git-svn-id: https://svn.jboss.org/repos/hibernate/trunk/Hibernate3/doc@4363 1b8cb986-b30d-0410-93ca-fae66ebed9b2 --- reference/en/modules/architecture.xml | 31 ++++- reference/en/modules/configuration.xml | 149 +++++++++++++++---------- reference/en/modules/quickstart.xml | 111 +++++++++--------- 3 files changed, 171 insertions(+), 120 deletions(-) diff --git a/reference/en/modules/architecture.xml b/reference/en/modules/architecture.xml index bba1703517..1cad8b7806 100644 --- a/reference/en/modules/architecture.xml +++ b/reference/en/modules/architecture.xml @@ -2,7 +2,7 @@ Architecture - + Overview @@ -113,7 +113,9 @@ (Optional) A single-threaded, short-lived object used by the application to specify atomic units of work. Abstracts application from underlying JDBC, JTA or CORBA transaction. A Session might span several - Transactions in some cases. + Transactions in some cases. However, transaction demarcation, + either using the underlying API or Transaction, is never + optional! @@ -136,6 +138,15 @@ + + Extension Interfaces + + + Hibernate offers many optional extension interfaces you can implement to customize + the behavior of your persistence layer. See the API documentation for details. + + + @@ -146,8 +157,9 @@ - + JMX Integration + JMX is the J2EE standard for management of Java components. Hibernate may be managed via a JMX standard MBean but because most application servers do not yet support JMX, Hibernate @@ -156,7 +168,13 @@ Please see the Hibernate website for more information on how to configure Hibernate to - run as a JMX component inside JBoss. + run as a JMX component inside JBoss. Integration with other JMX containers is also + possible. + + + + + TODO: More documentation about JMX integration. @@ -166,6 +184,11 @@ Hibernate may also be configured as a JCA connector. Please see the website for more details. + + + + TODO: More documentation about JCA integration. + diff --git a/reference/en/modules/configuration.xml b/reference/en/modules/configuration.xml index 0af04c0fe9..061f9ff61e 100644 --- a/reference/en/modules/configuration.xml +++ b/reference/en/modules/configuration.xml @@ -1,17 +1,18 @@ - + - SessionFactory Configuration + Configuration Because Hibernate is designed to operate in many different environments, there are a large number of configuration parameters. Fortunately, most have sensible default values and Hibernate is distributed with an example - hibernate.properties file that shows the various options. - You usually only have to put that file in your classpath and customize it. + hibernate.properties file in etc/ that shows + the various options. You usually only have to put that file in your classpath + and customize it. - - Programmatic Configuration + + Programmatic configuration An instance of org.hibernate.cfg.Configuration @@ -24,7 +25,7 @@ You may obtain a Configuration instance by instantiating it directly. Heres an example of setting up a datastore from - mappings defined in two XML configuration files (in the classpath): + mappings defined in two XML mapping files (in the classpath): - A Configuration is intended as a configuration-time object, to be + A Configuration is intended as a startup-time object, to be discarded once a SessionFactory is built. + + Instead of adding mapping files and setting properties programatially, you may + also place Hibernate configuration files in your classpath, as you will see + later. + + @@ -83,7 +90,7 @@ Configuration cfg = new Configuration() - + User provided JDBC connection @@ -102,10 +109,16 @@ Session session = sessions.openSession(conn); Sessions on the same JDBC connection! + + We don't recommend user-provided JDBC connections, as Hibernate will disable + caching (it doesn't know what else you might have executed on the given connection) + and one of the following options is usually more appropriate. + + - + Hibernate provided JDBC connection @@ -217,25 +230,20 @@ Session session = sessions.openSession(conn); - Hibernate's own connection pooling algorithm is quite rudimentary. It is intended + Hibernate's own connection pooling algorithm is however quite rudimentary. It is intended to help you get started and is not intended for use in a production system or even for performance testing. Use a third party pool for best performance and stability, i.e., replace the hibernate.connection.pool_size property with - connection pool specific settings. + connection pool specific settings. This will turn off Hibernate's internal pool. C3P0 is an open source JDBC connection pool distributed along with - Hibernate in the lib directory. Hibernate will use the built-in + Hibernate in the lib directory. Hibernate will use its C3P0ConnectionProvider for connection pooling if you set - the hibernate.c3p0.* properties. - There is also built-in support for Apache DBCP and for Proxool. You must set the - properties hibernate.dbcp.* (DBCP connection pool properties) - to enable the DBCPConnectionProvider. Prepared statement caching is - enabled (highly recommend) if hibernate.dbcp.ps.* - (DBCP statement cache properties) are set. Please refer the the Apache commons-pool - documentation for the interpretation of these properties. You should set the - hibernate.proxool.* properties if you wish to use Proxool. + hibernate.c3p0.* properties. If you'd like to use Proxool + refer to the packaged hibernate.properties and the Hibernate + web site for more information. @@ -345,7 +353,7 @@ hibernate.dialect = \ - + Optional configuration properties @@ -356,10 +364,11 @@ hibernate.dialect = \ System-level properties can only be set via java -Dproperty=value or be defined in hibernate.properties and not with an instance of - Properties passed to the Configuration. + Properties passed to the Configuration. They + are also not available in the hibernate.cfg.xml file, discusse later. - +
Hibernate Configuration Properties @@ -410,18 +419,6 @@ hibernate.dialect = \ - - - hibernate.use_outer_join - - - Enables outer join fetching. Deprecated, use max_fetch_depth. - - eg. - true | false - - - hibernate.max_fetch_depth @@ -719,6 +716,22 @@ hibernate.dialect = \ + + + hibernate.generate_statistics + + + If turned on, several runtime statistics are available by calling + SessionFactory.getStatistics(). Also see the + StatisticsServiceMBean if you are using a + JMX server, documented on the Hibernate web site. + + eg. + true | false + + + +
@@ -814,7 +827,7 @@ hibernate.dialect = \ - + Outer Join Fetching @@ -828,7 +841,10 @@ hibernate.dialect = \ By default, the fetched graph when loading an objects ends at leaf objects, - collections, objects with proxies, or where circularities occur. + collections, objects with proxies, or where circularities occur in the case + of *-to-one associations. Hibernate will however execute an immediate additional + SELECT for any persistent collection (we recommend that you + turn on lazy loading for all collection mappings). @@ -845,12 +861,13 @@ hibernate.dialect = \ to auto outer join. However, one-to-many associations and collections are never fetched with an outer-join, unless explicitely declared for each particular association. This behavior can also be overriden at runtime - with Hibernate queries. + with Hibernate queries. See the query chapters in the documentation for more + details. - + Binary Streams @@ -858,28 +875,30 @@ hibernate.dialect = \ be passed to/from its JDBC driver. If you wish to use large instances of binary or serializable type, you should enable hibernate.jdbc.use_streams_for_binary. - This is a JVM-level setting only. + This is a system-level setting only. - + Custom <literal>CacheProvider</literal> You may integrate a JVM-level (or clustered) second-level cache system by implementing the interface org.hibernate.cache.CacheProvider. You may select the custom implementation by setting - hibernate.cache.provider_class. + hibernate.cache.provider_class. See the "Performance" chapter + for more details. - + Transaction strategy configuration - If you wish to use the Hibernate Transaction API, you must + If you wish to use the Hibernate Transaction API instead + of directly calling a particular transaction API, you must specify a factory class for Transaction instances by setting the property hibernate.transaction.factory_class. The Transaction API hides the underlying transaction @@ -971,17 +990,18 @@ hibernate.dialect = \ - + JNDI-bound <literal>SessionFactory</literal> A JNDI bound Hibernate SessionFactory can simplify the lookup - of the factory and the creation of new Sessions. + of the factory and the creation of new Sessions. Note that this + is not related to a JNDI bound Datasource in a managed environment. If you wish to have the SessionFactory bound to a JNDI namespace, specify - a name (eg. java:comp/env/hibernate/SessionFactory) using the property + a name (eg. java:hibernate/SessionFactory) using the property hibernate.session_factory_name. If this property is omitted, the SessionFactory will not be bound to JNDI. (This is especially useful in environments with a read-only JNDI default implementation, eg. Tomcat.) @@ -995,8 +1015,16 @@ hibernate.dialect = \ - If you do choose to use JNDI, an EJB or other utility class may obtain the - SessionFactory using a JNDI lookup. + Hibernate will automatically place the SessionFactory in JNDI after + you call cfg.buildSessionFactory(). This means you will at least have + this call in some startup code (or utility class) in your application. + + + + If you use a JNDI SessionFactory, an EJB or any other class may + obtain the SessionFactory using a JNDI lookup. Note that this + setup is not neccessary if you use the HibernateUtil helper class + introduced in chapter 1, which acts as a Singleton registry. @@ -1089,14 +1117,14 @@ hibernate.dialect = \ - + XML Configuration File - An alternative approach is to specify a full configuration in a file named - hibernate.cfg.xml. This file can be used as a replacement - for the hibernate.properties file or, if both are present, - override properties. + An alternative approach to configuration is to specify a full configuration in + a file named hibernate.cfg.xml. This file can be used as a + replacement for the hibernate.properties file or, if both + are present, override properties. @@ -1113,13 +1141,12 @@ hibernate.dialect = \ + name="java:hibernate/SessionFactory"> - my/first/datasource + java:/comp/env/jdbc/MyDB org.hibernate.dialect.MySQLDialect false - true org.hibernate.transaction.JTATransactionFactory @@ -1133,6 +1160,12 @@ hibernate.dialect = \ ]]> + + As you can see, the advantage of this approach is the externalization of the + mapping file names to configuration. The hibernate.cfg.xml + is also more convenient once you have to tune the Hibernate cache. + + Configuring Hibernate is then as simple as diff --git a/reference/en/modules/quickstart.xml b/reference/en/modules/quickstart.xml index 61d353701a..42fce0926a 100644 --- a/reference/en/modules/quickstart.xml +++ b/reference/en/modules/quickstart.xml @@ -1,15 +1,15 @@ Quickstart with Tomcat - + Getting started with Hibernate - This tutorial explains a setup of Hibernate 2.1 with the Apache Tomcat + This tutorial explains a setup of Hibernate 3.0 with the Apache Tomcat servlet container for a web-based application. Hibernate works well in a managed environment with all major J2EE application servers, or even in standalone Java applications. The database system used in this - tutorial is PostgreSQL 7.3, support for other database is only a matter + tutorial is PostgreSQL 7.4, support for other database is only a matter of changing the Hibernate SQL dialect configuration. @@ -35,7 +35,7 @@ Hibernate uses JDBC connections to execute SQL on the database, so you either have to provide pooled JDBC connections or configure Hibernate to use one of the directly supported pools (C3P0, Proxool). For this tutorial, - copy the pg73jdbc3.jar library (for PostgreSQL 7.3 and JDK 1.4) + copy the pg74jdbc3.jar library (for PostgreSQL 7.4 and JDK 1.4) to the global classloaders path. If you'd like to use a different database, simply copy its appropriate JDBC driver. @@ -52,7 +52,7 @@ - Hibernate is packaged as a JAR library. The hibernate2.jar + Hibernate is packaged as a JAR library. The hibernate3.jar file should be copied in the context classpath together with other classes of the application. Hibernate requires some 3rd party libraries at runtime, these come bundled with the Hibernate distribution in the lib/ @@ -107,17 +107,6 @@ Commons project. - - - ODMG4 (required) - - - Hibernate provides an optional ODMG compliant persistence manager - interface. It is required if you like to map collections, even - if you don't intend to use the ODMG API. We don't map collections - in this tutorial, but it's a good idea to copy the JAR anyway. - - EHCache (required) @@ -213,12 +202,11 @@ any servlets, call the path http://localhost:8080/quickstart in your browser (of course, adding the name of the servlet as mapped in your web.xml). You may also go ahead and create a simple servlet - now that has an empty process() + now that has an empty process() method. - Tomcat uses the DBCP connection pool with this configuration and provides pooled - JDBC Connections through JNDI at + Tomcat provides connections now through JNDI at java:comp/env/jdbc/quickstart. If you have trouble getting the connection pool running, refer to the Tomcat documentation. If you get JDBC driver exception messages, try to setup JDBC connection pool without Hibernate first. @@ -226,11 +214,11 @@ - The next step is to configure Hibernate, using the connections from the JNDI bound pool. - We use Hibernates XML based configuration. The basic approach, using properties, is - equivalent in features, but doesn't offer any advantages. We use the XML configuration - because it is usually more convenient. The XML configuration file is placed in the - context classpath (WEB-INF/classes), as + Your next step is to configure Hibernate. Hibernate has to know how it should obtain + JDBC connections We use Hibernates XML-based configuration. The other approach, using + a properties file, is equivalent in features, but doesn't offer any advantages. We use + the XML configuration because it is usually more convenient. The XML configuration file + is placed in the context classpath (WEB-INF/classes), as hibernate.cfg.xml: @@ -257,7 +245,7 @@ We turn logging of SQL commands off and tell Hibernate what database SQL dialect is used and where to get the JDBC connections (by declaring the JNDI - address of the Tomcat bound datasource pool). The dialect is a required setting, + address of the Tomcat bound pool). The dialect is a required setting, databases differ in their interpretation of the SQL "standard". Hibernate will take care of the differences and comes bundled with dialects for all major commercial and open source databases. @@ -274,14 +262,14 @@ The last element of the hibernate.cfg.xml declares Cat.hbm.xml as the name of a Hibernate XML mapping file for the persistent class Cat. This file contains - the metadata for the mapping of the POJO class to a datbase table (or multiple - tables). We'll come back to that file soon. Let's write the POJO class first - and then declare the mapping metadata for it. + the metadata for the mapping of the POJO class Cat to + a datbase table (or tables). We'll come back to that file soon. Let's write + the POJO class first and then declare the mapping metadata for it. - + First persistent class @@ -289,7 +277,7 @@ called Plain Ordinary Java Objects) programming model for persistent classes. A POJO is much like a JavaBean, with properties of the class accessible via getter and setter methods, shielding the internal representation from the publicly - visible interface: + visible interface (Hibernate can also access fields directly, if needed): - No special interface has to be implemented for persistent classes nor do we have - to subclass from a special root persistent class. Hibernate also doesn't use any - build time processing, such as byte-code manipulation, it relies solely on + No special interface has to be implemented for persistent classes nor do you have + to subclass from a special root persistent class. Hibernate also doesn't require + any build time processing, such as byte-code manipulation, it relies solely on Java reflection and runtime class enhancement (through CGLIB). So, without any - dependency in the POJO class on Hibernate, we can map it to a database table. + dependency of the POJO class on Hibernate, we can map it to a database table. - + Mapping the cat @@ -400,7 +388,7 @@ public class Cat { Every persistent class should have an identifer attribute (actually, only - classes representing entities, not dependent value objects, which + classes representing entities, not dependent value-typed classes, which are mapped as components of an entity). This property is used to distinguish persistent objects: Two cats are equal if catA.getId().equals(catB.getId()) is true, this concept is @@ -435,29 +423,29 @@ Indexes: cat_pkey primary key btree (cat_id)]]> You should now create this table in your database manually, and later read if you want to automate this step with the - SchemaExport tool. This tool can create a full SQL DDL, including table - definition, custom column type constraints, unique constraints and indexes. + hbm2ddl tool. This tool can create a full SQL DDL, including + table definition, custom column type constraints, unique constraints and indexes. - + Playing with cats We're now ready to start Hibernate's Session. It is the - persistence managerinterface, we use it - to store and retrieve Cats to and from the database. - But first, we've to get a Session (Hibernate's unit-of-work) - from the SessionFactory: + persistence manager, we use it to store and retrieve + Cats to and from the database. But first, we've to get a + Session (Hibernate's unit-of-work) from the + SessionFactory: - - A SessionFactory is responsible for one database and - may only use one XML configuration file (hibernate.cfg.xml). + + The call to configure() loads the hibernate.cfg.xml + configuration file and initializes the Configuration instance. You can set other properties (and even change the mapping metadata) by accessing the Configuration before you build the SessionFactory (it is immutable). Where @@ -472,7 +460,7 @@ Indexes: cat_pkey primary key btree (cat_id)]]> servlets, but in some other location. Furthermore, we need some kind of Singleton, so we can access the SessionFactory easily in application code. The approach - shown next solves both problems: configuration and easy access to a + shown next solves both problems: startup configuration and easy access to a SessionFactory. @@ -494,6 +482,7 @@ public class HibernateUtil { // Create the SessionFactory sessionFactory = new Configuration().configure().buildSessionFactory(); } catch (Throwable ex) { + // Make sure you log the exception, as it might be swallowed log.error("Initial SessionFactory creation failed.", ex); throw new ExceptionInInitializerError(ex); } @@ -521,10 +510,11 @@ public class HibernateUtil { This class does not only take care of the SessionFactory - with its static attribute, but also has a ThreadLocal to - hold the Session for the current executing thread. Make - sure you understand the Java concept of a thread-local variable before you - try to use this helper. + with its static initializer, but also has a ThreadLocal + variable which holds the Session for the current thread. + Make sure you understand the Java concept of a thread-local variable before you + try to use this helper. A more complex and powerful HibernateUtil + class can be found in CaveatEmptor, http://caveatemptor.hibernate.org/ @@ -532,12 +522,13 @@ public class HibernateUtil { it concurrently and request Sessions. A Session is a non-threadsafe object that represents a single unit-of-work with the database. Sessions are opened by a SessionFactory and - are closed when all work is completed: + are closed when all work is completed. An example in your servlet's + process() method might look like this (sans exception handling): We use Hibernates Transaction API to abstract from the underlying transaction strategy (in our case, JDBC transactions). This allows our code to be deployed with container-managed transactions (using JTA) without any changes. - Please note that the example above does not handle any exceptions. - Also note that you may call HibernateUtil.currentSession(); + Note that you may call HibernateUtil.currentSession(); as many times as you like, you will always get the current Session of this thread. You have to make sure the Session is closed after your unit-of-work completes, either in your servlet code or in a servlet filter - before the HTTP response is send. The nice side effect of the latter is easy + before the HTTP response is send. The nice side effect of the second option is easy lazy initialization: the Session is still open when the view is - rendered, so Hibernate can load unitialized objects while you navigate the graph. + rendered, so Hibernate can load unitialized objects while you navigate the current + object graph. @@ -595,7 +586,7 @@ tx.commit();]]> - + Finally @@ -610,6 +601,10 @@ tx.commit();]]> Make sure you understand the implications of this design. + + For a more complex application design, see http://caveatemptor.hibernate.org/ + +