Chapter 11. Transactions And Concurrency
Prev |  | Next

## Chapter 11. Transactions And Concurrency

The most important point about Hibernate and concurrency control is that it is very easy to understand. Hibernate directly uses JDBC connections and JTA resources without adding any additional locking behavior. We highly recommend you spend some time with the JDBC, ANSI, and transaction isolation specification of your database management system.

Hibernate does not lock objects in memory. Your application can expect the behavior as defined by the isolation level of your database transactions. Note that thanks to the `Session`, which is also a transaction-scoped cache, Hibernate provides repeatable reads for lookup by identifier and entity queries (not reporting queries that return scalar values).

In addition to versioning for automatic optimistic concurrency control, Hibernate also offers a (minor) API for pessimistic locking of rows, using the `SELECT FOR UPDATE` syntax. Optimistic concurrency control and this API are discussed later in this chapter.

We start the discussion of concurrency control in Hibernate with the granularity of `Configuration`, `SessionFactory`, and `Session`, as well as database transactions and long conversations.

## 11.1. Session and transaction scopes

A `SessionFactory` is an expensive-to-create, threadsafe object intended to be shared by all application threads. It is created once, usually on application startup, from a `Configuration` instance.

A `Session` is an inexpensive, non-threadsafe object that should be used once, for a single request, a conversation, single unit of work, and then discarded. A `Session` will not obtain a JDBC `Connection` (or a `Datasource`) unless it is needed, hence consume no resources until used.

To complete this picture you also have to think about database transactions. A database transaction has to be as short as possible, to reduce lock contention in the database. Long database transactions will prevent your application from scaling to highly concurrent load. Hence, it is almost never good design to hold a database transaction open during user think time, until the unit of work is complete.

What is the scope of a unit of work? Can a single Hibernate `Session` span several database transactions or is this a one-to-one relationship of scopes? When should you open and close a `Session` and how do you demarcate the database transaction boundaries?

### 11.1.1. Unit of work

First, don't use the session-per-operation antipattern, that is, don't open and close a `Session` for every simple database call in a single thread! Of course, the same is true for database transactions. Database calls in an application are made using a planned sequence, they are grouped into atomic units of work. (Note that this also means that auto-commit after every single SQL statement is useless in an application, this mode is intended for ad-hoc SQL console work. Hibernate disables, or expects the application server to do so, auto-commit mode immediately.) Database transactions are never optional, all communication with a database has to occur inside a transaction, no matter if you read or write data. As explained, auto-commit behavior for reading data should be avoided, as many small transactions are unlikely to perform better than one clearly defined unit of work. The latter is also much more maintainable and extensible.

The most common pattern in a multi-user client/server application is session-per-request. In this model, a request from the client is send to the server (where the Hibernate persistence layer runs), a new Hibernate `Session` is opened, and all database operations are executed in this unit of work. Once the work has been completed (and the response for the client has been prepared), the session is flushed and closed. You would also use a single database transaction to serve the clients request, starting and committing it when you open and close the `Session`. The relationship between the two is one-to-one and this model is a perfect fit for many applications.

The challenge lies in the implementation. Hibernate provides built-in management of the "current session" to simplify this pattern. All you have to do is start a transaction when a server request has to be processed, and end the transaction before the response is send to the client. You can do this in any way you like, common solutions are `ServletFilter`, AOP interceptor with a pointcut on the service methods, or a proxy/interception container. An EJB container is a standardized way to implement cross-cutting aspects such as transaction demarcation on EJB session beans, declaratively with CMT. If you decide to use programmatic transaction demarcation, prefer the Hibernate `Transaction` API shown later in this chapter, for ease of use and code portability.

Your application code can access a "current session" to process the request by simply calling `sessionFactory.getCurrentSession()` anywhere and as often as needed. You will always get a `Session` scoped to the current database transaction. This has to be configured for either resource-local or JTA environments, see Section 2.5, “Contextual Sessions”.

Sometimes it is convenient to extend the scope of a `Session` and database transaction until the "view has been rendered". This is especially useful in servlet applications that utilize a separate rendering phase after the request has been processed. Extending the database transaction until view rendering is complete is easy to do if you implement your own interceptor. However, it is not easily doable if you rely on EJBs with container-managed transactions, as a transaction will be completed when an EJB method returns, before rendering of any view can start. See the Hibernate website and forum for tips and examples around this Open Session in View pattern.

### 11.1.2. Long conversations

The session-per-request pattern is not the only useful concept you can use to design units of work. Many business processes require a whole series of interactions with the user 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:

- The first screen of a dialog opens, the data seen by the user has been loaded in a particular `Session` and database transaction. The user is free to modify the objects.

- The user clicks "Save" after 5 minutes and expects his modifications to be made persistent; he also expects that he was the only person editing this information and that no conflicting modification can occur.

We call this unit of work, from the point of view of the user, a long running conversation (or application transaction). There are many ways how you can implement this in your application.

A first naive implementation might keep the `Session` and database transaction open during user think time, with locks held in the database to prevent concurrent modification, and to guarantee isolation and atomicity. This is of course an anti-pattern, since lock contention would not allow the application to scale with the number of concurrent users.

Clearly, we have to use several database transactions to implement the converastion. In this case, maintaining isolation of business processes becomes the partial responsibility of the application tier. A single conversation usually spans several database transactions. It will be atomic if only one of these database transactions (the last one) stores the updated data, all others simply read data (e.g. in a wizard-style dialog spanning several request/response cycles). This is easier to implement than it might sound, especially if you use Hibernate's features:

- Automatic Versioning - Hibernate can do automatic optimistic concurrency control for you, it can automatically detect if a concurrent modification occured during user think time. Usually we only check at the end of the conversation.

- Detached Objects - If you decide to use the already discussed session-per-request pattern, all loaded instances will be in detached state during user think time. Hibernate allows you to reattach the objects and persist the modifications, the pattern is called session-per-request-with-detached-objects. Automatic versioning is used to isolate concurrent modifications.

- Extended (or Long) Session - The Hibernate `Session` may be disconnected from the underlying JDBC connection after the database transaction has been committed, and reconnected when a new client request occurs. This pattern is known as session-per-conversation and makes even reattachment unnecessary. Automatic versioning is used to isolate concurrent modifications and the `Session` is usually not allowed to be flushed automatically, but explicitely.

Both session-per-request-with-detached-objects and session-per-conversation have advantages and disadvantages, we discuss them later in this chapter in the context of optimistic concurrency control.

### 11.1.3. Considering object identity

An application may concurrently access the same persistent state in two different `Session`s. However, an instance of a persistent class is never shared between two `Session` instances. Hence there are two different notions of identity:

Database Identity

  `foo.getId().equals( bar.getId() )`

JVM Identity

  `foo==bar`

Then for objects attached to a particular `Session` (i.e. in the scope of a `Session`) the two notions are equivalent, and JVM identity for database identity is guaranteed by Hibernate. However, while the application might concurrently access the "same" (persistent identity) business object in two different sessions, the two instances will actually be "different" (JVM identity). Conflicts are resolved using (automatic versioning) at flush/commit time, using an optimistic approach.

This approach leaves Hibernate and the database to worry about concurrency; it also provides the best scalability, since guaranteeing identity in single-threaded units of work only doesn't need expensive locking or other means of synchronization. The application never needs to synchronize on any business object, as long as it sticks to a single thread per `Session`. Within a `Session` the application may safely use `==` to compare objects.

However, an application that uses `==` outside of a `Session`, might see unexpected results. This might occur even in some unexpected places, for example, if you put two detached instances into the same `Set`. Both might have the same database identity (i.e. they represent the same row), but JVM identity is by definition not guaranteed for instances in detached state. The developer has to override the `equals()` and `hashCode()` methods in persistent classes and implement his own notion of object equality. There is one caveat: Never use the database identifier to implement equality, use a business key, a combination of unique, usually immutable, attributes. The database identifier will change if a transient object is made persistent. If the transient instance (usually together with detached instances) is held in a `Set`, changing the hashcode breaks the contract of the `Set`. Attributes for business keys don't have to be as stable as database primary keys, you only have to guarantee stability as long as the objects are in the same `Set`. See the Hibernate website for a more thorough discussion of this issue. Also note that this is not a Hibernate issue, but simply how Java object identity and equality has to be implemented.

### 11.1.4. Common issues

Never use the anti-patterns session-per-user-session or session-per-application (of course, there are rare exceptions to this rule). Note that some of the following issues might also appear with the recommended patterns, make sure you understand the implications before making a design decision:

- A `Session` is not thread-safe. Things which are supposed to work concurrently, like HTTP requests, session beans, or Swing workers, will cause race conditions if a `Session` instance would be shared. If you keep your Hibernate `Session` in your `HttpSession` (discussed later), you should consider synchronizing access to your Http session. Otherwise, a user that clicks reload fast enough may use the same `Session` in two concurrently running threads.

- An exception thrown by Hibernate means you have to rollback your database transaction and close the `Session` immediately (discussed later in more detail). If your `Session` is bound to the application, you have to stop the application. Rolling back the database transaction doesn't put your business objects back into the state they were at the start of the transaction. This means the database state and the business objects do get out of sync. Usually this is not a problem, because exceptions are not recoverable and you have to start over after rollback anyway.

- The `Session` caches every object that is in persistent state (watched and checked for dirty state by Hibernate). This means it grows endlessly until you get an OutOfMemoryException, if you keep it open for a long time or simply load too much data. One solution for this is to call `clear()` and `evict()` to manage the `Session` cache, but you most likely should consider a Stored Procedure if you need mass data operations. Some solutions are shown in Chapter 13, Batch processing. Keeping a `Session` open for the duration of a user session also means a high probability of stale data.

## 11.2. Database transaction demarcation

Datatabase (or system) transaction boundaries are always necessary. No communication with the database can occur outside of a database transaction (this seems to confuse many developers who are used to the auto-commit mode). Always use clear transaction boundaries, even for read-only operations. Depending on your isolation level and database capabilities this might not be required but there is no downside if you always demarcate transactions explicitly. Certainly, a single database transaction is going to perform better than many small transactions, even for reading data.

A Hibernate application can run in non-managed (i.e. standalone, simple Web- or Swing applications) and managed J2EE environments. In a non-managed environment, Hibernate is usually responsible for its own database connection pool. The application developer has to manually set transaction boundaries, in other words, begin, commit, or rollback database transactions himself. A managed environment usually provides container-managed transactions (CMT), with the transaction assembly defined declaratively in deployment descriptors of EJB session beans, for example. Programmatic transaction demarcation is then no longer necessary.

However, it is often desirable to keep your persistence layer portable between non-managed resource-local environments, and systems that can rely on JTA but use BMT instead of CMT. In both cases you'd use programmatic transaction demaracation. Hibernate offers a wrapper API called `Transaction` that translates into the native transaction system of your deployment environment. This API is actually optional, but we strongly encourage its use unless you are in a CMT session bean.

Usually, ending a `Session` involves four distinct phases:

- flush the session

- commit the transaction

- close the session

- handle exceptions

Flushing the session has been discussed earlier, we'll now have a closer look at transaction demarcation and exception handling in both managed- and non-managed environments.

### 11.2.1. Non-managed environment

If a Hibernate persistence layer runs in a non-managed environment, database connections are usually handled by simple (i.e. non-DataSource) connection pools from which Hibernate obtains connections as needed. The session/transaction handling idiom looks like this:

    // Non-managed environment idiom
    Session sess = factory.openSession();
    Transaction tx = null;
    try {
        tx = sess.beginTransaction();

        // do some work
        ...

        tx.commit();
    }
    catch (RuntimeException e) {
        if (tx != null) tx.rollback();
        throw e; // or display error message
    }
    finally {
        sess.close();
    }

You don't have to `flush()` the `Session` explicitly - the call to `commit()` automatically triggers the synchronization (depending upon the Section 10.10, “Flushing the Session” for the session. A call to `close()` marks the end of a session. The main implication of `close()` is that the JDBC connection will be relinquished by the session. This Java code is portable and runs in both non-managed and JTA environments.

A much more flexible solution is Hibernate's built-in "current session" context management, as described earlier:

    // Non-managed environment idiom with getCurrentSession()
    try {
        factory.getCurrentSession().beginTransaction();

        // do some work
        ...

        factory.getCurrentSession().getTransaction().commit();
    }
    catch (RuntimeException e) {
        factory.getCurrentSession().getTransaction().rollback();
        throw e; // or display error message
    }

You will very likely never see these code snippets in a regular application; fatal (system) exceptions should always be caught at the "top". In other words, the code that executes Hibernate calls (in the persistence layer) and the code that handles `RuntimeException` (and usually can only clean up and exit) are in different layers. The current context management by Hibernate can significantly simplify this design, as all you need is access to a `SessionFactory`. Exception handling is discussed later in this chapter.

Note that you should select `org.hibernate.transaction.JDBCTransactionFactory` (which is the default), and for the second example `"thread"` as your `hibernate.current_session_context_class`.

### 11.2.2. Using JTA

If your persistence layer runs in an application server (e.g. behind EJB session beans), every datasource connection obtained by Hibernate will automatically be part of the global JTA transaction. You can also install a standalone JTA implementation and use it without EJB. Hibernate offers two strategies for JTA integration.

If you use bean-managed transactions (BMT) Hibernate will tell the application server to start and end a BMT transaction if you use the `Transaction` API. So, the transaction management code is identical to the non-managed environment.

    // BMT idiom
    Session sess = factory.openSession();
    Transaction tx = null;
    try {
        tx = sess.beginTransaction();

        // do some work
        ...

        tx.commit();
    }
    catch (RuntimeException e) {
        if (tx != null) tx.rollback();
        throw e; // or display error message
    }
    finally {
        sess.close();
    }

If you want to use a transaction-bound `Session`, that is, the `getCurrentSession()` functionality for easy context propagation, you will have to use the JTA `UserTransaction` API directly:

    // BMT idiom with getCurrentSession()
    try {
        UserTransaction tx = (UserTransaction)new InitialContext()
                                .lookup("java:comp/UserTransaction");

        tx.begin();

        // Do some work on Session bound to transaction
        factory.getCurrentSession().load(...);
        factory.getCurrentSession().persist(...);

        tx.commit();
    }
    catch (RuntimeException e) {
        tx.rollback();
        throw e; // or display error message
    }

With CMT, transaction demarcation is done in session bean deployment descriptors, not programatically, hence, the code is reduced to:

    // CMT idiom
     Session sess = factory.getCurrentSession();

     // do some work
     ...

In a CMT/EJB even rollback happens automatically, since an unhandled `RuntimeException` thrown by a session bean method tells the container to set the global transaction to rollback. This means you do not need to use the Hibernate `Transaction` API at all with BMT or CMT, and you get automatic propagation of the "current" Session bound to the transaction.

Note that you should choose `org.hibernate.transaction.JTATransactionFactory` if you use JTA directly (BMT), and `org.hibernate.transaction.CMTTransactionFactory` in a CMT session bean, when you configure Hibernate's transaction factory. Remember to also set `hibernate.transaction.manager_lookup_class`. Furthermore, make sure that your `hibernate.current_session_context_class` is either unset (backwards compatiblity), or set to `"jta"`.

The `getCurrentSession()` operation has one downside in a JTA environment. There is one caveat to the use of `after_statement` connection release mode, which is then used by default. Due to a silly limitation of the JTA spec, it is not possible for Hibernate to automatically clean up any unclosed `ScrollableResults` or `Iterator` instances returned by `scroll()` or `iterate()`. You must release the underlying database cursor by calling `ScrollableResults.close()` or `Hibernate.close(Iterator)` explicity from a `finally` block. (Of course, most applications can easily avoid using `scroll()` or `iterate()` at all from the JTA or CMT code.)

### 11.2.3. Exception handling

If the `Session` throws an exception (including any `SQLException`), you should immediately rollback the database transaction, call `Session.close()` and discard the `Session` instance. Certain methods of `Session` will not leave the session in a consistent state. No exception thrown by Hibernate can be treated as recoverable. Ensure that the `Session` will be closed by calling `close()` in a `finally` block.

The `HibernateException`, which wraps most of the errors that can occur in a Hibernate persistence layer, is an unchecked exception (it wasn't in older versions of Hibernate). In our opinion, we shouldn't force the application developer to catch an unrecoverable exception at a low layer. In most systems, unchecked and fatal exceptions are handled in one of the first frames of the method call stack (i.e. in higher layers) and an error message is presented to the application user (or some other appropriate action is taken). Note that Hibernate might also throw other unchecked exceptions which are not a `HibernateException`. These are, again, not recoverable and appropriate action should be taken.

Hibernate wraps `SQLException`s thrown while interacting with the database in a `JDBCException`. In fact, Hibernate will attempt to convert the eexception into a more meningful subclass of `JDBCException`. The underlying `SQLException` is always available via `JDBCException.getCause()`. Hibernate converts the `SQLException` into an appropriate `JDBCException` subclass using the `SQLExceptionConverter` attached to the `SessionFactory`. By default, the `SQLExceptionConverter` is defined by the configured dialect; however, it is also possible to plug in a custom implementation (see the javadocs for the `SQLExceptionConverterFactory` class for details). The standard `JDBCException` subtypes are:

- `JDBCConnectionException` - indicates an error with the underlying JDBC communication.

- `SQLGrammarException` - indicates a grammar or syntax problem with the issued SQL.

- `ConstraintViolationException` - indicates some form of integrity constraint violation.

- `LockAcquisitionException` - indicates an error acquiring a lock level necessary to perform the requested operation.

- `GenericJDBCException` - a generic exception which did not fall into any of the other categories.

### 11.2.4. Transaction timeout

One extremely important feature provided by a managed environment like EJB that is never provided for non-managed code is transaction timeout. Transaction timeouts ensure that no misbehaving transaction can indefinitely tie up resources while returning no response to the user. Outside a managed (JTA) environment, Hibernate cannot fully provide this functionality. However, Hibernate can at least control data access operations, ensuring that database level deadlocks and queries with huge result sets are limited by a defined timeout. In a managed environment, Hibernate can delegate transaction timeout to JTA. This functioanlity is abstracted by the Hibernate `Transaction` object.

    Session sess = factory.openSession();
    try {
        //set transaction timeout to 3 seconds
        sess.getTransaction().setTimeout(3);
        sess.getTransaction().begin();

        // do some work
        ...

        sess.getTransaction().commit()
    }
    catch (RuntimeException e) {
        sess.getTransaction().rollback();
        throw e; // or display error message
    }
    finally {
        sess.close();
    }

Note that `setTimeout()` may not be called in a CMT bean, where transaction timeouts must be defined declaratively.

## 11.3. Optimistic concurrency control

The only approach that is consistent with high concurrency and high scalability is optimistic concurrency control with versioning. Version checking uses version numbers, or timestamps, to detect conflicting updates (and to prevent lost updates). Hibernate provides for three possible approaches to writing application code that uses optimistic concurrency. The use cases we show are in the context of long conversations, but version checking also has the benefit of preventing lost updates in single database transactions.

### 11.3.1. Application version checking

In an implementation without much help from Hibernate, each interaction with the database occurs in a new `Session` and the developer is responsible for reloading all persistent instances from the database before manipulating them. This approach forces the application to carry out its own version checking to ensure conversation transaction isolation. This approach is the least efficient in terms of database access. It is the approach most similar to entity EJBs.

    // foo is an instance loaded by a previous Session
    session = factory.openSession();
    Transaction t = session.beginTransaction();

    int oldVersion = foo.getVersion();
    session.load( foo, foo.getKey() ); // load the current state
    if ( oldVersion!=foo.getVersion ) throw new StaleObjectStateException();
    foo.setProperty("bar");

    t.commit();
    session.close();

The `version` property is mapped using `<version>`, and Hibernate will automatically increment it during flush if the entity is dirty.

Of course, if you are operating in a low-data-concurrency environment and don't require version checking, you may use this approach and just skip the version check. In that case, last commit wins will be the default strategy for your long conversations. Keep in mind that this might confuse the users of the application, as they might experience lost updates without error messages or a chance to merge conflicting changes.

Clearly, manual version checking is only feasible in very trivial circumstances and not practical for most applications. Often not only single instances, but complete graphs of modified ojects have to be checked. Hibernate offers automatic version checking with either an extended `Session` or detached instances as the design paradigm.

### 11.3.2. Extended session and automatic versioning

A single `Session` instance and its persistent instances are used for the whole conversation, known as session-per-conversation. Hibernate checks instance versions at flush time, throwing an exception if concurrent modification is detected. It's up to the developer to catch and handle this exception (common options are the opportunity for the user to merge changes or to restart the business conversation with non-stale data).

The `Session` is disconnected from any underlying JDBC connection when waiting for user interaction. This approach is the most efficient in terms of database access. The application need not concern itself with version checking or with reattaching detached instances, nor does it have to reload instances in every database transaction.

    // foo is an instance loaded earlier by the old session
    Transaction t = session.beginTransaction(); // Obtain a new JDBC connection, start transaction

    foo.setProperty("bar");

    session.flush();    // Only for last transaction in conversation
    t.commit();         // Also return JDBC connection
    session.close();    // Only for last transaction in conversation

The `foo` object still knows which `Session` it was loaded in. Beginning a new database transaction on an old session obtains a new connection and resumes the session. Committing a database transaction disconnects a session from the JDBC connection and returns the connection to the pool. After reconnection, to force a version check on data you aren't updating, you may call `Session.lock()` with `LockMode.READ` on any objects that might have been updated by another transaction. You don't need to lock any data that you are updating. Usually you would set `FlushMode.NEVER` on an extended `Session`, so that only the last database transaction cycle is allowed to actually persist all modifications made in this conversation. Hence, only this last database transaction would include the `flush()` operation, and then also `close()` the session to end the conversation.

This pattern is problematic if the `Session` is too big to be stored during user think time, e.g. an `HttpSession` should be kept as small as possible. As the `Session` is also the (mandatory) first-level cache and contains all loaded objects, we can probably use this strategy only for a few request/response cycles. You should use a `Session` only for a single conversation, as it will soon also have stale data.

(Note that earlier Hibernate versions required explicit disconnection and reconnection of a `Session`. These methods are deprecated, as beginning and ending a transaction has the same effect.)

Also note that you should keep the disconnected `Session` close to the persistence layer. In other words, use an EJB stateful session bean to hold the `Session` in a three-tier environment, and don't transfer it to the web layer (or even serialize it to a separate tier) to store it in the `HttpSession`.

The extended session pattern, or session-per-conversation, is more difficult to implement with automatic current session context management. You need to supply your own implementation of the `CurrentSessionContext` for this, see the Hibernate Wiki for examples.

### 11.3.3. Detached objects and automatic versioning

Each interaction with the persistent store occurs in a new `Session`. However, the same persistent instances are reused for each interaction with the database. The application manipulates the state of detached instances originally loaded in another `Session` and then reattaches them using `Session.update()`, `Session.saveOrUpdate()`, or `Session.merge()`.

    // foo is an instance loaded by a previous Session
    foo.setProperty("bar");
    session = factory.openSession();
    Transaction t = session.beginTransaction();
    session.saveOrUpdate(foo); // Use merge() if "foo" might have been loaded already
    t.commit();
    session.close();

Again, Hibernate will check instance versions during flush, throwing an exception if conflicting updates occured.

You may also call `lock()` instead of `update()` and use `LockMode.READ` (performing a version check, bypassing all caches) if you are sure that the object has not been modified.

### 11.3.4. Customizing automatic versioning

You may disable Hibernate's automatic version increment for particular properties and collections by setting the `optimistic-lock` mapping attribute to `false`. Hibernate will then no longer increment versions if the property is dirty.

Legacy database schemas are often static and can't be modified. Or, other applications might also access the same database and don't know how to handle version numbers or even timestamps. In both cases, versioning can't rely on a particular column in a table. To force a version check without a version or timestamp property mapping, with a comparison of the state of all fields in a row, turn on `optimistic-lock="all"` in the `<class>` mapping. Note that this concepetually only works if Hibernate can compare the old and new state, i.e. if you use a single long `Session` and not session-per-request-with-detached-objects.

Sometimes concurrent modification can be permitted as long as the changes that have been made don't overlap. If you set `optimistic-lock="dirty"` when mapping the `<class>`, Hibernate will only compare dirty fields during flush.

In both cases, with dedicated version/timestamp columns or with full/dirty field comparison, Hibernate uses a single `UPDATE` statement (with an appropriate `WHERE` clause) per entity to execute the version check and update the information. If you use transitive persistence to cascade reattachment to associated entities, Hibernate might execute uneccessary updates. This is usually not a problem, but on update triggers in the database might be executed even when no changes have been made to detached instances. You can customize this behavior by setting `select-before-update="true"` in the `<class>` mapping, forcing Hibernate to `SELECT` the instance to ensure that changes did actually occur, before updating the row.

## 11.4. Pessimistic Locking

It is not intended that users spend much time worring about locking strategies. Its usually enough to specify an isolation level for the JDBC connections and then simply let the database do all the work. However, advanced users may sometimes wish to obtain exclusive pessimistic locks, or re-obtain locks at the start of a new transaction.

Hibernate will always use the locking mechanism of the database, never lock objects in memory!

The `LockMode` class defines the different lock levels that may be acquired by Hibernate. A lock is obtained by the following mechanisms:

- `LockMode.WRITE` is acquired automatically when Hibernate updates or inserts a row.

- `LockMode.UPGRADE` may be acquired upon explicit user request using `SELECT ... FOR UPDATE` on databases which support that syntax.

- `LockMode.UPGRADE_NOWAIT` may be acquired upon explicit user request using a `SELECT ... FOR UPDATE NOWAIT` under Oracle.

- `LockMode.READ` is acquired automatically when Hibernate reads data under Repeatable Read or Serializable isolation level. May be re-acquired by explicit user request.

- `LockMode.NONE` represents the absence of a lock. All objects switch to this lock mode at the end of a `Transaction`. Objects associated with the session via a call to `update()` or `saveOrUpdate()` also start out in this lock mode.

The "explicit user request" is expressed in one of the following ways:

- A call to `Session.load()`, specifying a `LockMode`.

- A call to `Session.lock()`.

- A call to `Query.setLockMode()`.

If `Session.load()` is called with `UPGRADE` or `UPGRADE_NOWAIT`, and the requested object was not yet loaded by the session, the object is loaded using `SELECT ... FOR UPDATE`. If `load()` is called for an object that is already loaded with a less restrictive lock than the one requested, 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` is used.)

If the database does not support the requested lock mode, Hibernate will use an appropriate alternate mode (instead of throwing an exception). This ensures that applications will be portable.

## 11.5. Connection Release Modes

The legacy (2.x) behavior of Hibernate in regards to JDBC connection management was that a `Session` would obtain a connection when it was first needed and then hold unto that connection until the session was closed. Hibernate 3.x introduced the notion of connection release modes to tell a session how to handle its JDBC connections. Note that the following discussion is pertinent only to connections provided through a configured `ConnectionProvider`; user-supplied connections are outside the breadth of this discussion. The different release modes are identified by the enumerated values of `org.hibernate.ConnectionReleaseMode`:

- `ON_CLOSE` - is essentially the legacy behavior described above. The Hibernate session obatins a connection when it first needs to perform some JDBC access and holds unto that connection until the session is closed.

- `AFTER_TRANSACTION` - says to release connections after a `org.hibernate.Transaction` has completed.

- `AFTER_STATEMENT` (also referred to as aggressive release) - says to release connections after each and every statement execution. This aggressive releasing is skipped if that statement leaves open resources associated with the given session; currently the only situation where this occurs is through the use of `org.hibernate.ScrollableResults`.

The configuration parameter `hibernate.connection.release_mode` is used to specify which release mode to use. The possible values:

- `auto` (the default) - this choice delegates to the release mode returned by the `org.hibernate.transaction.TransactionFactory.getDefaultReleaseMode()` method. For JTATransactionFactory, this returns ConnectionReleaseMode.AFTER_STATEMENT; for JDBCTransactionFactory, this returns ConnectionReleaseMode.AFTER_TRANSACTION. It is rarely a good idea to change this default behavior as failures due to the value of this setting tend to indicate bugs and/or invalid assumptions in user code.

- `on_close` - says to use ConnectionReleaseMode.ON_CLOSE. This setting is left for backwards compatibility, but its use is highly discouraged.

- `after_transaction` - says to use ConnectionReleaseMode.AFTER_TRANSACTION. This setting should not be used in JTA environments. Also note that with ConnectionReleaseMode.AFTER_TRANSACTION, if a session is considered to be in auto-commit mode connections will be released as if the release mode were AFTER_STATEMENT.

- `after_statement` - says to use ConnectionReleaseMode.AFTER_STATEMENT. Additionally, the configured `ConnectionProvider` is consulted to see if it supports this setting (`supportsAggressiveRelease()`). If not, the release mode is reset to ConnectionReleaseMode.AFTER_TRANSACTION. This setting is only safe in environments where we can either re-acquire the same underlying JDBC connection each time we make a call into `ConnectionProvider.getConnection()` or in auto-commit environments where it does not matter whether we get back the same connection.

Prev | Up | Next
Chapter 10. Working with objects | Home | Chapter 12. Interceptors and events