Hibernate example source code file (transactions.pot)

This example Hibernate source code file (transactions.pot) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Hibernate tags/keywords

a, hibernate, hibernate, if, in, it, jta, tag, tag, the, the, this, this, you

The Hibernate transactions.pot source code

# 
# AUTHOR <EMAIL@ADDRESS>, YEAR.
#
msgid ""
msgstr ""
"Project-Id-Version: 0\n"
"POT-Creation-Date: 2010-02-11T05:38:16\n"
"PO-Revision-Date: 2010-02-11T05:38:16\n"
"Last-Translator: Automatically generated\n"
"Language-Team: None\n"
"MIME-Version: 1.0\n"
"Content-Type: application/x-publican; charset=UTF-8\n"
"Content-Transfer-Encoding: 8bit\n"

#. Tag: title
#, no-c-format
msgid "Transactions and Concurrency"
msgstr ""

#. Tag: para
#, no-c-format
msgid "The most important point about Hibernate and concurrency control is that it is easy to understand. Hibernate directly uses JDBC connections and JTA resources without adding any additional locking behavior. It is recommended that you spend some time with the JDBC, ANSI, and transaction isolation specification of your database management system."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Hibernate does not lock objects in memory. Your application can expect the behavior as defined by the isolation level of your database transactions. Through <literal>Session, which is also a transaction-scoped cache, Hibernate provides repeatable reads for lookup by identifier and entity queries and not reporting queries that return scalar values."
msgstr ""

#. Tag: para
#, no-c-format
msgid "In addition to versioning for automatic optimistic concurrency control, Hibernate also offers, using the <literal>SELECT FOR UPDATE syntax, a (minor) API for pessimistic locking of rows. Optimistic concurrency control and this API are discussed later in this chapter."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The discussion of concurrency control in Hibernate begins with the granularity of <literal>Configuration, SessionFactory, and Session, as well as database transactions and long conversations."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Session and transaction scopes"
msgstr ""

#. Tag: para
#, no-c-format
msgid "A <literal>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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "A <literal>Session is an inexpensive, non-threadsafe object that should be used once and then discarded for: a single request, a conversation or a single unit of work. A Session will not obtain a JDBC Connection, or a Datasource, unless it is needed. It will not consume any resources until used."
msgstr ""

#. Tag: para
#, no-c-format
msgid "In order to reduce lock contention in the database, a database transaction has to be as short as possible. Long database transactions will prevent your application from scaling to a highly concurrent load. It is not recommended that you hold a database transaction open during user think time until the unit of work is complete."
msgstr ""

#. Tag: para
#, no-c-format
msgid "What is the scope of a unit of work? Can a single Hibernate <literal>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? These questions are addressed in the following sections."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Unit of work"
msgstr ""

#. Tag: para
#, no-c-format
msgid "First, let's define a unit of work. A unit of work is a design pattern described by Martin Fowler as <quote> [maintaining] a list of objects affected by a business transaction and coordinates the writing out of changes and the resolution of concurrency problems. PoEAA In other words, its a series of operations we wish to carry out against the database together. Basically, it is a transaction, though fulfilling a unit of work will often span multiple physical database transactions (see ). So really we are talking about a more abstract notion of a transaction. The term \"business transaction\" is also sometimes used in lieu of unit of work."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Do not use the <emphasis>session-per-operation antipattern: do not open and close a Session for every simple database call in a single thread. 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. This also means that auto-commit after every single SQL statement is useless in an application as this mode is intended for ad-hoc SQL console work. Hibernate disables, or expects the application server to disable, auto-commit mode immediately. Database transactions are never optional. All communication with a database has to occur inside a transaction. 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 more maintainable and extensible."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The most common pattern in a multi-user client/server application is <emphasis>session-per-request. In this model, a request from the client is sent 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. On completion of the work, and once the response for the client has been prepared, the session is flushed and closed. 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The challenge lies in the implementation. Hibernate provides built-in management of the \"current session\" to simplify this pattern. Start a transaction when a server request has to be processed, and end the transaction before the response is sent to the client. Common solutions are <literal>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 use programmatic transaction demarcation, for ease of use and code portability use the Hibernate Transaction API shown later in this chapter."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Your application code can access a \"current session\" to process the request by calling <literal>sessionFactory.getCurrentSession(). 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 ."
msgstr ""

#. Tag: para
#, no-c-format
msgid "You can extend the scope of a <literal>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 achieved by implementing your own interceptor. However, this will be difficult if you rely on EJBs with container-managed transactions. 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 relating to this Open Session in View pattern."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Long conversations"
msgstr ""

#. Tag: para
#, no-c-format
msgid "The session-per-request pattern is not the only 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:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "The first screen of a dialog opens. The data seen by the user has been loaded in a particular <literal>Session and database transaction. The user is free to modify the objects."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The user clicks \"Save\" after 5 minutes and expects their modifications to be made persistent. The user also expects that they were the only person editing this information and that no conflicting modification has occurred."
msgstr ""

#. Tag: para
#, no-c-format
msgid "From the point of view of the user, we call this unit of work a long-running <emphasis>conversation or application transaction. There are many ways to implement this in your application."
msgstr ""

#. Tag: para
#, no-c-format
msgid "A first naive implementation might keep the <literal>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 an anti-pattern, since lock contention would not allow the application to scale with the number of concurrent users."
msgstr ""

#. Tag: para
#, no-c-format
msgid "You have to use several database transactions 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. It will be atomic if only one of these database transactions (the last one) stores the updated data. All others simply read data (for example, in a wizard-style dialog spanning several request/response cycles). This is easier to implement than it might sound, especially if you utilize some of Hibernate's features:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "<emphasis>Automatic Versioning: Hibernate can perform automatic optimistic concurrency control for you. It can automatically detect if a concurrent modification occurred during user think time. Check for this at the end of the conversation."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<emphasis>Detached Objects: if you decide to use the session-per-request pattern, all loaded instances will be in the 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<emphasis>Extended (or Long) Session: the Hibernate Session can 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 will not be allowed to be flushed automatically, but explicitly."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Both <emphasis>session-per-request-with-detached-objects and session-per-conversation have advantages and disadvantages. These disadvantages are discussed later in this chapter in the context of optimistic concurrency control."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Considering object identity"
msgstr ""

#. Tag: para
#, no-c-format
msgid "An application can concurrently access the same persistent state in two different <literal>Sessions. However, an instance of a persistent class is never shared between two Session instances. It is for this reason that there are two different notions of identity:"
msgstr ""

#. Tag: term
#, no-c-format
msgid "Database Identity"
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>foo.getId().equals( bar.getId() )"
msgstr ""

#. Tag: term
#, no-c-format
msgid "JVM Identity"
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>foo==bar"
msgstr ""

#. Tag: para
#, no-c-format
msgid "For objects attached to a <emphasis>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. 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 an optimistic approach and automatic versioning at flush/commit time."
msgstr ""

#. Tag: para
#, no-c-format
msgid "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 means that it does not need expensive locking or other means of synchronization. The application does not need to synchronize on any business object, as long as it maintains a single thread per <literal>Session. Within a Session the application can safely use == to compare objects."
msgstr ""

#. Tag: para
#, no-c-format
msgid "However, an application that uses <literal>== outside of a Session might produce 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). JVM identity, however, is by definition not guaranteed for instances in a detached state. The developer has to override the equals() and hashCode() methods in persistent classes and implement their own notion of object equality. There is one caveat: never use the database identifier to implement equality. Use a business key that is 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 do not 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. Please note that this is not a Hibernate issue, but simply how Java object identity and equality has to be implemented."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Common issues"
msgstr ""

#. Tag: para
#, no-c-format
msgid "Do not use the anti-patterns <emphasis>session-per-user-session or session-per-application (there are, however, rare exceptions to this rule). Some of the following issues might also arise within the recommended patterns, so ensure that you understand the implications before making a design decision:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "A <literal>Session is not thread-safe. Things that work concurrently, like HTTP requests, session beans, or Swing workers, will cause race conditions if a Session instance is shared. If you keep your Hibernate Session in your HttpSession (this is discussed later in the chapter), you should consider synchronizing access to your Http session. Otherwise, a user that clicks reload fast enough can use the same Session in two concurrently running threads."
msgstr ""

#. Tag: para
#, no-c-format
msgid "An exception thrown by Hibernate means you have to rollback your database transaction and close the <literal>Session immediately (this is discussed in more detail later in the chapter). If your Session is bound to the application, you have to stop the application. Rolling back the database transaction does not put your business objects back into the state they were at the start of the transaction. This means that the database state and the business objects will be out of sync. Usually this is not a problem, because exceptions are not recoverable and you will have to start over after rollback anyway."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The <literal>Session caches every object that is in a persistent state (watched and checked for dirty state by Hibernate). If you keep it open for a long time or simply load too much data, it will grow endlessly until you get an OutOfMemoryException. One solution is to call clear() and evict() to manage the Session cache, but you should consider a Stored Procedure if you need mass data operations. Some solutions are shown in . Keeping a Session open for the duration of a user session also means a higher probability of stale data."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Database transaction demarcation"
msgstr ""

#. Tag: para
#, no-c-format
msgid "Database, 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "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 (begin, commit, or rollback database transactions) themselves. 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "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 use programmatic transaction demarcation. Hibernate offers a wrapper API called <literal>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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Ending a <literal>Session usually involves four distinct phases:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "flush the session"
msgstr ""

#. Tag: para
#, no-c-format
msgid "commit the transaction"
msgstr ""

#. Tag: para
#, no-c-format
msgid "close the session"
msgstr ""

#. Tag: para
#, no-c-format
msgid "handle exceptions"
msgstr ""

#. Tag: para
#, no-c-format
msgid "We discussed Flushing the session earlier, so we will now have a closer look at transaction demarcation and exception handling in both managed and non-managed environments."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Non-managed environment"
msgstr ""

#. Tag: para
#, no-c-format
msgid "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:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "You do not have to <literal>flush() the Session explicitly: the call to commit() automatically triggers the synchronization depending on the FlushMode 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "As outlined earlier, a much more flexible solution is Hibernate's built-in \"current session\" context management:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "You will not 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 <literal>RuntimeException (and usually can only clean up and exit), are in different layers. The current context management by Hibernate can significantly simplify this design by accessing a SessionFactory. Exception handling is discussed later in this chapter."
msgstr ""

#. Tag: para
#, no-c-format
msgid "You should select <literal>org.hibernate.transaction.JDBCTransactionFactory, which is the default, and for the second example select \"thread\" as your hibernate.current_session_context_class."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Using JTA"
msgstr ""

#. Tag: para
#, no-c-format
msgid "If your persistence layer runs in an application server (for example, 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "If you use bean-managed transactions (BMT), Hibernate will tell the application server to start and end a BMT transaction if you use the <literal>Transaction API. The transaction management code is identical to the non-managed environment."
msgstr ""

#. Tag: para
#, no-c-format
msgid "If you want to use a transaction-bound <literal>Session, that is, the getCurrentSession() functionality for easy context propagation, use the JTA UserTransaction API directly:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "With CMT, transaction demarcation is completed in session bean deployment descriptors, not programmatically. The code is reduced to:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "In a CMT/EJB, even rollback happens automatically. An unhandled <literal>RuntimeException thrown by a session bean method tells the container to set the global transaction to rollback. 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "When configuring Hibernate's transaction factory, choose <literal>org.hibernate.transaction.JTATransactionFactory if you use JTA directly (BMT), and org.hibernate.transaction.CMTTransactionFactory in a CMT session bean. Remember to also set hibernate.transaction.manager_lookup_class. Ensure that your hibernate.current_session_context_class is either unset (backwards compatibility), or is set to \"jta\"."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The <literal>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 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) explicitly from a finally block. Most applications can easily avoid using scroll() or iterate() from the JTA or CMT code.)"
msgstr ""

#. Tag: title
#, no-c-format
msgid "Exception handling"
msgstr ""

#. Tag: para
#, no-c-format
msgid "If the <literal>Session throws an exception, including any SQLException, 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The <literal>HibernateException, which wraps most of the errors that can occur in a Hibernate persistence layer, is an unchecked exception. It was not in older versions of Hibernate. In our opinion, we should not 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 either 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 that are not a HibernateException. These are not recoverable and appropriate action should be taken."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Hibernate wraps <literal>SQLExceptions thrown while interacting with the database in a JDBCException. In fact, Hibernate will attempt to convert the exception into a more meaningful 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:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>JDBCConnectionException: indicates an error with the underlying JDBC communication."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>SQLGrammarException: indicates a grammar or syntax problem with the issued SQL."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>ConstraintViolationException: indicates some form of integrity constraint violation."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>LockAcquisitionException: indicates an error acquiring a lock level necessary to perform the requested operation."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>GenericJDBCException: a generic exception which did not fall into any of the other categories."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Transaction timeout"
msgstr ""

#. Tag: para
#, no-c-format
msgid "An 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 functionality is abstracted by the Hibernate <literal>Transaction object."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>setTimeout() cannot be called in a CMT bean, where transaction timeouts must be defined declaratively."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Optimistic concurrency control"
msgstr ""

#. Tag: para
#, no-c-format
msgid "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 three possible approaches to writing application code that uses optimistic concurrency. The use cases we discuss are in the context of long conversations, but version checking also has the benefit of preventing lost updates in single database transactions."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Application version checking"
msgstr ""

#. Tag: para
#, no-c-format
msgid "In an implementation without much help from Hibernate, each interaction with the database occurs in a new <literal>Session and the developer is responsible for reloading all persistent instances from the database before manipulating them. The application is forced 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The <literal>version property is mapped using <version>, and Hibernate will automatically increment it during flush if the entity is dirty."
msgstr ""

#. Tag: para
#, no-c-format
msgid "If you are operating in a low-data-concurrency environment, and do not require version checking, you can use this approach and skip the version check. In this case, <emphasis>last commit wins is the default strategy for long conversations. Be aware 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Manual version checking is only feasible in trivial circumstances and not practical for most applications. Often not only single instances, but complete graphs of modified objects, have to be checked. Hibernate offers automatic version checking with either an extended <literal>Session or detached instances as the design paradigm."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Extended session and automatic versioning"
msgstr ""

#. Tag: para
#, no-c-format
msgid "A single <literal>Session instance and its persistent instances that are used for the whole conversation are known as session-per-conversation. Hibernate checks instance versions at flush time, throwing an exception if concurrent modification is detected. It is 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The <literal>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 does not version check or reattach detached instances, nor does it have to reload instances in every database transaction."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The <literal>foo object 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 are not updating, you can call Session.lock() with LockMode.READ on any objects that might have been updated by another transaction. You do not need to lock any data that you are updating. Usually you would set FlushMode.MANUAL on an extended Session, so that only the last database transaction cycle is allowed to actually persist all modifications made in this conversation. Only this last database transaction will include the flush() operation, and then close() the session to end the conversation."
msgstr ""

#. Tag: para
#, no-c-format
msgid "This pattern is problematic if the <literal>Session is too big to be stored during user think time (for example, an HttpSession should be kept as small as possible). As the Session is also the first-level cache and contains all loaded objects, we can probably use this strategy only for a few request/response cycles. Use a Session only for a single conversation as it will soon have stale data."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Note"
msgstr ""

#. Tag: para
#, no-c-format
msgid "Earlier versions of Hibernate required explicit disconnection and reconnection of a <literal>Session. These methods are deprecated, as beginning and ending a transaction has the same effect."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Keep the disconnected <literal>Session close to the persistence layer. Use an EJB stateful session bean to hold the Session in a three-tier environment. Do not transfer it to the web layer, or even serialize it to a separate tier, to store it in the HttpSession."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The extended session pattern, or <emphasis>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."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Detached objects and automatic versioning"
msgstr ""

#. Tag: para
#, no-c-format
msgid "Each interaction with the persistent store occurs in a new <literal>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()."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Again, Hibernate will check instance versions during flush, throwing an exception if conflicting updates occurred."
msgstr ""

#. Tag: para
#, no-c-format
msgid "You can also call <literal>lock() instead of update(), and use LockMode.READ (performing a version check and bypassing all caches) if you are sure that the object has not been modified."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Customizing automatic versioning"
msgstr ""

#. Tag: para
#, no-c-format
msgid "You can disable Hibernate's automatic version increment for particular properties and collections by setting the <literal>optimistic-lock mapping attribute to false. Hibernate will then no longer increment versions if the property is dirty."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Legacy database schemas are often static and cannot be modified. Or, other applications might access the same database and will not know how to handle version numbers or even timestamps. In both cases, versioning cannot rely on a particular column in a table. To force a version check with a comparison of the state of all fields in a row but without a version or timestamp property mapping, turn on <literal>optimistic-lock=\"all\" in the <class> mapping. This conceptually only works if Hibernate can compare the old and the new state (i.e., if you use a single long Session and not session-per-request-with-detached-objects)."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Concurrent modification can be permitted in instances where the changes that have been made do not overlap. If you set <literal>optimistic-lock=\"dirty\" when mapping the <class>, Hibernate will only compare dirty fields during flush."
msgstr ""

#. Tag: para
#, no-c-format
msgid "In both cases, with dedicated version/timestamp columns or with a full/dirty field comparison, Hibernate uses a single <literal>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 may execute unnecessary 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 occur before updating the row."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Pessimistic locking"
msgstr ""

#. Tag: para
#, no-c-format
msgid "It is not intended that users spend much time worrying about locking strategies. It is 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 wish to obtain exclusive pessimistic locks or re-obtain locks at the start of a new transaction."
msgstr ""

#. Tag: para
#, no-c-format
msgid "Hibernate will always use the locking mechanism of the database; it never lock objects in memory."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The <literal>LockMode class defines the different lock levels that can be acquired by Hibernate. A lock is obtained by the following mechanisms:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>LockMode.WRITE is acquired automatically when Hibernate updates or inserts a row."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>LockMode.UPGRADE can be acquired upon explicit user request using SELECT ... FOR UPDATE on databases which support that syntax."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>LockMode.UPGRADE_NOWAIT can be acquired upon explicit user request using a SELECT ... FOR UPDATE NOWAIT under Oracle."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>LockMode.READ is acquired automatically when Hibernate reads data under Repeatable Read or Serializable isolation level. It can be re-acquired by explicit user request."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The \"explicit user request\" is expressed in one of the following ways:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "A call to <literal>Session.load(), specifying a LockMode."
msgstr ""

#. Tag: para
#, no-c-format
msgid "A call to <literal>Session.lock()."
msgstr ""

#. Tag: para
#, no-c-format
msgid "A call to <literal>Query.setLockMode()."
msgstr ""

#. Tag: para
#, no-c-format
msgid "If <literal>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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "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."
msgstr ""

#. Tag: title
#, no-c-format
msgid "Connection release modes"
msgstr ""

#. Tag: para
#, no-c-format
msgid "One of the legacies of Hibernate 2.x JDBC connection management meant that a <literal>Session would obtain a connection when it was first required and then maintain that connection until the session was closed. Hibernate 3.x introduced the notion of connection release modes that would instruct a session how to handle its JDBC connections. 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:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>ON_CLOSE: is the legacy behavior described above. The Hibernate session obtains a connection when it first needs to perform some JDBC access and maintains that connection until the session is closed."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>AFTER_TRANSACTION: releases connections after a org.hibernate.Transaction has been completed."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>AFTER_STATEMENT (also referred to as aggressive release): releases connections after 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "The configuration parameter <literal>hibernate.connection.release_mode is used to specify which release mode to use. The possible values are as follows:"
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>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. Do not change this default behavior as failures due to the value of this setting tend to indicate bugs and/or invalid assumptions in user code."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>on_close: uses ConnectionReleaseMode.ON_CLOSE. This setting is left for backwards compatibility, but its use is discouraged."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>after_transaction: uses 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."
msgstr ""

#. Tag: para
#, no-c-format
msgid "<literal>after_statement: uses 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 you make a call into ConnectionProvider.getConnection() or in auto-commit environments where it does not matter if we re-establish the same connection."
msgstr ""