Hibernate Developer Guide

You can configure database connections using a properties file, an XML deployment descriptor or programmatically.

All available Hibernate settings are defined as constants and discussed on the org.hibernate.cfg.AvailableSettings interface. See its source code or JavaDoc for details.

C3P0 is an open source JDBC connection pool distributed along with Hibernate in the lib/ directory. Hibernate uses its org.hibernate.service.jdbc.connections.internal.C3P0ConnectionProvider for connection pooling if you set the hibernate.c3p0.* properties. properties.

To use Hibernate inside an application server, configure Hibernate to obtain connections from an application server javax.sql.Datasource registered in JNDI, by setting at least one of the following properties:

JDBC connections obtained from a JNDI datasource automatically participate in the container-managed transactions of the application server.

You can pass arbitrary connection properties by prepending hibernate.connection to the connection property name. For example, specify a charSet connection property as hibernate.connection.charSet.

You can define your own plugin strategy for obtaining JDBC connections by implementing the interface org.hibernate.service.jdbc.connections.spi.ConnectionProvider and specifying your custom implementation with the hibernate.connection.provider_class property.

The developer may manually specify the Dialect to use by setting the hibernate.dialect configuration property to the name of a specific org.hibernate.dialect.Dialect class to use.

Assuming a org.hibernate.service.jdbc.connections.spi.ConnectionProvider has been set up, Hibernate will attempt to automatically determine the Dialect to use based on the java.sql.DatabaseMetaData reported by a java.sql.Connection obtained from that org.hibernate.service.jdbc.connections.spi.ConnectionProvider.

This functionality is provided by a series of org.hibernate.service.jdbc.dialect.spi.DialectResolver instances registered with Hibernate internally. Hibernate comes with a standard set of recognitions. If your application requires extra Dialect resolution capabilities, it would simply register a custom implementation of org.hibernate.service.jdbc.dialect.spi.DialectResolver as follows:

Registered org.hibernate.service.jdbc.dialect.spi.DialectResolver are prepended to an internal list of resolvers, so they take precedence before any already registered resolvers including the standard one.

The SchemaExport tool writes a DDL script to standard output, executes the DDL statements, or both.

JDBC-based transaction management leverages the JDBC defined methods java.sql.Connection.commit() and java.sql.Connection.rollback() (JDBC does not define an explicit method of beginning a transaction). In Hibernate, this approach is represented by the org.hibernate.engine.transaction.internal.jdbc.JdbcTransactionFactory class.

JTA-based transaction approach which leverages the javax.transaction.UserTransaction interface as obtained from org.hibernate.service.jta.platform.spi.JtaPlatform API. This approach is represented by the org.hibernate.engine.transaction.internal.jta.JtaTransactionFactory class.

Another JTA-based transaction approach which leverages the JTA javax.transaction.TransactionManager interface as obtained from org.hibernate.service.jta.platform.spi.JtaPlatform API. This approach is represented by the org.hibernate.engine.transaction.internal.jta.CMTTransactionFactory class. In an actual JEE CMT environment, access to the javax.transaction.UserTransaction is restricted.

Its is also possible to plug in a custom transaction approach by implementing the org.hibernate.engine.transaction.spi.TransactionFactory contract. The default service initiator has built-in support for understanding custom transaction approaches via the hibernate.transaction.factory_class which can name either:

During development of 4.0, most of these classes named here were moved to new packages. To help facilitate upgrading, Hibernate will also recognize the legacy names here for a short period of time.

This is an anti-pattern of opening and closing a Session for each database call in a single thread. It is also an anti-pattern in terms of database transactions. Group your database calls into a planned sequence. In the same way, do not auto-commit after every SQL statement in your application. Hibernate disables, or expects the application server to disable, auto-commit mode immediately. Database transactions are never optional. All communication with a database must be encapsulated by a transaction. Avoid auto-commit behavior for reading data, because many small transactions are unlikely to perform better than one clearly-defined unit of work, and are more difficult to maintain and extend.

This is the most common transaction pattern. The term request here relates to the concept of a system that reacts to a series of requests from a client/user. Web applications are a prime example of this type of system, though certainly not the only one. At the beginning of handling such a request, the application opens a Hibernate Session, starts a transaction, performs all data related work, ends the transaction and closes the Session. The crux of the pattern is the one-to-one relationship between the transaction and the Session.

Within this pattern there is a common technique of defining a current session to simplify the need of passing this Session around to all the application components that may need access to it. Hibernate provides support for this technique through the getCurrentSession method of the SessionFactory. The concept of a "current" session has to have a scope that defines the bounds in which the notion of "current" is valid. This is purpose of the org.hibernate.context.spi.CurrentSessionContext contract. There are 2 reliable defining scopes:

The session-per-request pattern is not the only valid way of designing units of work. Many business processes require a whole series of interactions with the user that are interleaved with database accesses. In web and enterprise applications, it is not acceptable for a database transaction to span a user interaction. Consider the following example:

Even though we have multiple databases access here, from the point of view of the user, this series of steps represents a single unit of work. There are many ways to implement this in your application.

A first naive implementation might keep the Session and database transaction open while the user is editing, using database-level locks to prevent other users from modifying the same data and to guarantee isolation and atomicity. This is an anti-pattern, because lock contention is a bottleneck which will prevent scalability in the future.

Several database transactions are used to implement the conversation. In this case, maintaining isolation of business processes becomes the partial responsibility of the application tier. A single conversation usually spans several database transactions. These multiple database accesses can only be atomic as a whole if only one of these database transactions (typically the last one) stores the updated data. All others only read data. A common way to receive this data is through a wizard-style dialog spanning several request/response cycles. Hibernate includes some features which make this easy to implement.

Session-per-request-with-detached-objects and session-per-conversation each have advantages and disadvantages.

Discussion coming soon..

Reattachment is the process of taking an incoming entity instance that is in detached state and re-associating it with the current persistence context.

The method name update is a bit misleading here. It does not mean that an SQL UPDATE is immediately performed. It does, however, mean that an SQL UPDATE will be performed when the persistence context is flushed since Hibernate does not know its previous state against which to compare for changes. Unless the entity is mapped with select-before-update, in which case Hibernate will pull the current state from the database and see if an update is needed.

Provided the entity is detached, update and saveOrUpdate operate exactly the same.

Merging is the process of taking an incoming entity instance that is in detached state and copying its data over onto a new instance that is in managed state.

That is not exactly what happens, but its a good visualization.

The FROM clause can only refer to a single entity, which can be aliased. If the entity name is aliased, any property references must be qualified using that alias. If the entity name is not aliased, then it is illegal for any property references to be qualified.

Joins, either implicit or explicit, are prohibited in a bulk HQL query. You can use sub-queries in the WHERE clause, and the sub-queries themselves can contain joins.

In keeping with the EJB3 specification, HQL UPDATE statements, by default, do not effect the version or the timestamp property values for the affected entities. You can use a versioned update to force Hibernate to reset the version or timestamp property values, by adding the VERSIONED keyword after the UPDATE keyword.

Method Query.executeUpdate() returns an int value, which indicates the number of entities effected by the operation. This may or may not correlate to the number of rows effected in the database. An HQL bulk operation might result in multiple SQL statements being executed, such as for joined-subclass. In the example of joined-subclass, a DELETE against one of the subclasses may actually result in deletes in the tables underlying the join, or further down the inheritance hierarchy.

Only the INSERT INTO ... SELECT ... form is supported. You cannot specify explicit values to insert.

The properties_list is analogous to the column specification in the SQL INSERT statement. For entities involved in mapped inheritance, you can only use properties directly defined on that given class-level in the properties_list. Superclass properties are not allowed and subclass properties are irrelevant. In other words, INSERT statements are inherently non-polymorphic.

The select_statement can be any valid HQL select query, but the return types must match the types expected by the INSERT. Hibernate verifies the return types during query compilation, instead of expecting the database to check it. Problems might result from Hibernate types which are equivalent, rather than equal. One such example is a mismatch between a property defined as an org.hibernate.type.DateType and a property defined as an org.hibernate.type.TimestampType, even though the database may not make a distinction, or may be capable of handling the conversion.

If id property is not specified in the properties_list, Hibernate generates a value automatically. Automatic generation is only available if you use ID generators which operate on the database. Otherwise, Hibernate throws an exception during parsing. Available in-database generators are org.hibernate.id.SequenceGenerator and its subclasses, and objects which implement org.hibernate.id.PostInsertIdentifierGenerator. The most notable exception is org.hibernate.id.TableHiLoGenerator, which does not expose a selectable way to get its values.

For properties mapped as either version or timestamp, the insert statement gives you two options. You can either specify the property in the properties_list, in which case its value is taken from the corresponding select expressions, or omit it from the properties_list, in which case the seed value defined by the org.hibernate.type.VersionType is used.

The version number mechanism for optimistic locking is provided through a @Version annotation.

The version column can be any kind of type, as long as you define and implement the appropriate UserVersionType.

Your application is forbidden from altering the version number set by Hibernate. To artificially increase the version number, see the documentation for properties LockModeType.OPTIMISTIC_FORCE_INCREMENT or LockModeType.PESSIMISTIC_FORCE_INCREMENTcheck in the Hibernate Entity Manager reference documentation.

Timestamps are a less reliable way of optimistic locking than version numbers, but can be used by applications for other purposes as well. Timestamping is automatically used if you the @Version annotation on a Date or Calendar.

Hibernate can retrieve the timestamp value from the database or the JVM, by reading the value you specify for the @org.hibernate.annotations.Source annotation. The value can be either org.hibernate.annotations.SourceType.DB or org.hibernate.annotations.SourceType.VM. The default behavior is to use the database, and is also used if you don't specify the annotation at all.

The timestamp can also be generated by the database instead of Hibernate, if you use the @org.hibernate.annotations.Generated(GenerationTime.ALWAYS) annotation.

The LockMode class defines the different lock levels that Hibernate can acquire.

The explicit user request mentioned above occurs as a consequence of any of the following actions:

If you call Session.load() with option UPGRADE or UPGRADE_NOWAIT, and the requested object is not already loaded by the session, the object is loaded using SELECT ... FOR UPDATE. If you call load() for an object that is already loaded with a less restrictive lock than the one you request, Hibernate calls lock() for that object.

Session.lock() performs a version number check if the specified lock mode is READ, UPGRADE, or UPGRADE_NOWAIT. In the case of UPGRADE or UPGRADE_NOWAIT, SELECT ... FOR UPDATE syntax is used.

If the requested lock mode is not supported by the database, Hibernate uses an appropriate alternate mode instead of throwing an exception. This ensures that applications are portable.

For fine-grained control over query cache expiration policies, specify a named cache region for a particular query by calling Query.setCacheRegion().

To force the query cache to refresh one of its regions and disregard any cached results in the region, call org.hibernate.Query.setCacheMode(CacheMode.REFRESH). In conjunction with the region defined for the given query, Hibernate selectively refreshes the results cached in that particular region. This is much more efficient than bulk eviction of the region via org.hibernate.SessionFactory.evictQueries().

You can configure your cache providers using either annotations or mapping files.

Syncing or removing a cached item.  The state of an object is synchronized with the database when you call method flush(). To avoid this synchronization, you can remove the object and all collections from the first-level cache with the evict() method. To remove all items from the Session cache, use method Session.clear().

Determining whether an item belongs to the Session cache.  The Session provides a contains() method to determine if an instance belongs to the session cache.

Any method on the service implementation class accepting a single parameter and annotated with @InjectService is considered requesting injection of another service.

By default the type of the method parameter is expected to be the service role to be injected. If the parameter type is different than the service role, the serviceRole attribute of the InjectService should be used to explicitly name the role.

By default injected services are considered required, that is the start up will fail if a named dependent service is missing. If the service to be injected is optional, the required attribute of the InjectService should be declared as false (default is true).

The second approach is a pull approach where the service implements the optional service interface org.hibernate.service.spi.ServiceRegistryAwareService which declares a single injectServices method. During startup, Hibernate will inject the org.hibernate.service.ServiceRegistry itself into services which implement this interface. The service can then use the ServiceRegistry reference to locate any additional services it needs.

While it is best practice to treat instances of all the registry types as targeting a given org.hibernate.SessionFactory, the instances of services in this group explicitly belong to a single org.hibernate.SessionFactory. The difference is a matter of timing in when they need to be initiated. Generally they need access to the org.hibernate.SessionFactory to be initiated. This special registry is org.hibernate.service.spi.SessionFactoryServiceRegistry

The main use cases for an org.hibernate.integrator.spi.Integrator right now are registering event listeners and providing services (see org.hibernate.integrator.spi.ServiceContributingIntegrator). With 5.0 we plan on expanding that to allow altering the metamodel describing the mapping between object and relational models.

Basic value types usually map a single database value, or column, to a single, non-aggregated Java type. Hibernate provides a number of built-in basic types, which follow the natural mappings recommended in the JDBC specifications. You can override these mappings and provide and use alternative mappings. These topics are discussed further on.

National Character types, which is a new feature since JDBC 4.0 API, now available in hibernate type system. National Language Support enables you retrieve data or insert data into a database in any character set that the underlying database supports.

Depending on your environment, you might want to set the configuration option hibernate.use_nationalized_character_data to true and having all string or clob based attributes having this national character support automatically. There is nothing else to be changed, and you don't have to use any hibernate specific mapping, so it is portable ( though the national character support feature is not required and may not work on other JPA provider impl ).

The other way of using this feature is having the @Nationalized annotation on the attribute that should be nationalized. This only works on string based attributes, including string, char, char array and clob.

                @Entity( name="NationalizedEntity")
                public static class NationalizedEntity {
                    @Id
                    private Integer id;

                    @Nationalized
                    private String nvarcharAtt;

                    @Lob
                    @Nationalized
                    private String materializedNclobAtt;

                    @Lob
                    @Nationalized
                    private NClob nclobAtt;

                    @Nationalized
                    private Character ncharacterAtt;

                    @Nationalized
                    private Character[] ncharArrAtt;

                    @Type(type = "ntext")
                    private String nlongvarcharcharAtt;
                }

Composite types, or embedded types, as they are called by the Java Persistence API, have traditionally been called components in Hibernate. All of these terms mean the same thing.

Components represent aggregations of values into a single Java type. An example is an Address class, which aggregates street, city, state, and postal code. A composite type behaves in a similar way to an entity. They are each classes written specifically for an application. They may both include references to other application-specific classes, as well as to collections and simple JDK types. The only distinguishing factors are that a component does not have its own lifecycle or define an identifier.

A collection type refers to the data type itself, not its contents.

A Collection denotes a one-to-one or one-to-many relationship between tables of a database.

Refer to the chapter on Collections for more information on collections.