Author: laubai Date: 2009-11-24 01:41:27 -0500 (Tue, 24 Nov 2009) New Revision: 11666 Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Persistence.xml Log: Edited Persistence chapter. Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Persistence.xml =================================================================== --- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Persistence.xml 2009-11-24 05:55:24 UTC (rev 11665) +++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Persistence.xml 2009-11-24 06:41:27 UTC (rev 11666) @@ -13,28 +13,26 @@ <title>Introduction</title> <para> - Seam grew out of the frustration of the Hibernate team with the - statelessness typical of the previous generation of Java application - architectures. The state management architecture of Seam was originally - designed to solve problems relating to persistence&#8212;in particular - problems associated with <emphasis>optimistic transaction processing</emphasis>. - Scalable online applications always use optimistic transactions. An atomic - (database/JTA) level transaction should not span a user interaction unless - the application is designed to support only a very small number of concurrent - clients. But almost all interesting work involves first displaying data - to a user, and then, slightly later, updating the same data. So Hibernate was - designed to support the idea of a persistence context which spanned an - optimistic transaction. + + Seam was created because of frustration with the statelessness typical of the + previous generation of Java application architectures. Seam's state management + architecture was originally designed to solve problems relating to persistence, + particularly problems associated with optimistic transaction processing. Scalable + online applications always use optimistic transactions. An atomic (database/JTA) + level transaction should not span a user interaction unless the application is + designed to support only a very small number of concurrent clients. But almost all + work involves first displaying data to a user, and then updating that data. + Hibernate was designed to support a persistence context that spanned an optimistic + transaction. </para> <para> - Unfortunately, the so-called "stateless" architectures that preceded Seam and - EJB 3.0 had no construct for representing an optimistic transaction. So, instead, - these architectures provided persistence contexts scoped to the atomic - transaction. Of course, this resulted in many problems for users, and is the - cause of the number one user complaint about Hibernate: the dreaded - <literal>LazyInitializationException</literal>. What we need is a construct - for representing an optimistic transaction in the application tier. + Unfortunately, the "stateless" architectures that preceded Seam and EJB3 had no + construct to represent an optimistic transaction. Instead, these architectures + provided persistence contexts scoped to the atomic transaction. This resulted in + many problems for users, and causes the number one user complaint: Hibernate's + <exceptionname>LazyInitializationException</exceptionname>. A construct was + required to represent an optimistic transaction in the application tier. </para> <para> @@ -42,15 +40,14 @@ component (a stateful session bean) with an <emphasis>extended persistence context</emphasis> scoped to the lifetime of the component. This is a partial solution to the problem (and is a useful construct in and of - itself) however there are two problems: + itself), but there are still two issues with this approach: </para> <itemizedlist> <listitem> <para> The lifecycle of the stateful session bean must be managed manually - via code in the web tier (it turns out that this is a subtle problem - and much more difficult in practice than it sounds). + via code in the web tier. </para> </listitem> <listitem> @@ -62,16 +59,15 @@ </itemizedlist> <para> - Seam solves the first problem by providing conversations, and stateful - session bean components scoped to the conversation. (Most conversations - actually represent optimistic transactions in the data layer.) This is - sufficient for many simple applications (such as the Seam booking - demo) where persistence context propagation is not needed. For more - complex applications, with many loosly-interacting components in each - conversation, propagation of the persistence context across components - becomes an important issue. So Seam extends the persistence context - management model of EJB 3.0, to provide conversation-scoped extended - persistence contexts. + Seam solves the first problem by providing conversations, and scoping stateful + session bean components to the conversation. (Most conversations actually + represent optimistic transactions in the data layer.) This is sufficient for many + simple applications where persistence context propagation is not required, such as + the Seam booking example application. For more complex applications, with many + loosely-interacting components in each conversation, propagation of the + persistence context across components becomes an important issue. Therefore, Seam + extends the persistence context management model of EJB3, to provide conversation- + scoped extended persistence contexts. </para> </section> @@ -79,96 +75,93 @@ <section id="persistence.seam-managed-transactions"> <title>Seam managed transactions</title> <para> - EJB session beans feature declarative transaction management. The EJB container is able - to start a transaction transparently when the bean is invoked, and end it when the - invocation ends. If we write a session bean method that acts as a JSF action listener, - we can do all the work associated with that action in one transaction, and be sure that - it is committed or rolled back when we finish processing the action. This is a great feature, - and all that is needed by some Seam applications. + EEJB session beans feature declarative transaction management. The EJB + container can start a transaction transparently when the bean is invoked, and + end it when the invocation ends. If we write a session bean method that acts + as a JSF action listener, all work associated with that action can be + performed as one transaction, and committed or rolled back when the action is + completely processed. This is a useful feature, and for some Seam + applications, this is all that is required. </para> <para> - However, there is a problem with this approach. A Seam application may not perform all data - access for a request from a single method call to a session bean. + However, there is a problem with this approach: in a request from a single + method call to a session bean, a Seam application may not perform all data + access. </para> <itemizedlist> <listitem> <para> - The request might require processing by several loosly-coupled components, each - of which is called independently from the web layer. It is common to see several - or even many calls per request from the web layer to EJB components in Seam. + when the request requires processing by several loosely-coupled + components, with each component being called independently from the + web layer. It is common to see multiple calls per request from the web + layer to EJB components in Seam. </para> </listitem> <listitem> <para> - Rendering of the view might require lazy fetching of associations. + when view rendering requires lazily-fetched associations. </para> </listitem> </itemizedlist> <para> - The more transactions per request, the more likely we are to encounter atomicity - and isolation problems when our application is processing many concurrent requests. - Certainly, all write operations should occur in the same transaction! + The more transactions that exist per request, the more likely we are to + encounter atomicity and isolation problems while our application processes + many concurrent requests. All write operations should occur in the same + transaction. </para> <para> - Hibernate users developed the <emphasis>"open session in view"</emphasis> pattern to work - around this problem. In the Hibernate community, "open session in view" was historically - even more important because frameworks like Spring use transaction-scoped persistence contexts. - So rendering the view would cause <literal>LazyInitializationException</literal>s when - unfetched associations were accessed. + To work around this problem, Hibernate users developed the <emphasis>open + session in view</emphasis> pattern. This is also important because some + frameworks (Spring, for example) use transaction-scoped persistence contexts, + which caused <exceptionname>LazyInitializationException</exceptionname>s when + unfetched associations were accessed. </para> <para> - This pattern is usually implemented as a single transaction which spans the entire request. - There are several problems with this implementation, the most serious being that we - can never be sure that a transaction is successful until we commit it&#8212;but by the - time the "open session in view" transaction is committed, the view is fully rendered, and - the rendered response may already have been flushed to the client. How can we notify the - user that their transaction was unsuccessful? + <emphasis>Open session in view</emphasis> is usually implemented as a single + transaction that spans the entire request. The most serious problem with this + implementation is that we cannot be certain that a transaction is successful + until we commit it — but when the transaction commits, the view is fully + rendered, and the rendered response may already be synchronized the client, so + there is no way to notify the user that their transaction did not succeed. </para> <para> - Seam solves both the transaction isolation problem and the association fetching problem, - while working around the problems with "open session in view". The solution comes in two - parts: + Seam solves the problems with transaction isolation and association fetching, + while working around the major flaw in <emphasis>open session in + view</emphasis>, with two changes: </para> <itemizedlist> <listitem> <para> - use an extended persistence context that is scoped to the conversation, - instead of to the transaction + Seam uses an extended persistence context that is scoped to the + conversation instead of the transaction. </para> </listitem> <listitem> <para> - use two transactions per request; the first spans the beginning of the restore view - phase (some transaction managers begin the transaction later at the beginning of the - apply request vaues phase) until the end of the invoke application phase; the second spans the - render response phase + Seam uses two transactions per request. The first spans from the + beginning of the restore view phase until the end of the invoke + application phase; the second spans the length of the render response + phase. (In some applications, the first phase will begin later, at the + beginning of the apply request values phase.) </para> </listitem> </itemizedlist> <para> - In the next section, we'll tell you how to set up a conversation-scope persistence - context. But first we need to tell you how to enable Seam transaction management. - Note that you can use conversation-scoped persistence contexts without Seam - transaction management, and there are good reasons to use Seam transaction management - even when you're not using Seam-managed persistence contexts. However, the two - facilities were designed to work together, and work best when used together. + The next section takes you through the setup of a conversation-scoped + persistence context. Before this, we will enable Seam transaction management. + You can use conversation-scoped persistence contexts without Seam transaction + management, and Seam transaction management is useful even without Seam- + managed persistence contexts, but they work most effectively together. </para> - <para> - Seam transaction management is useful even if you're using EJB 3.0 - container-managed persistence contexts. But it is especially useful - if you use Seam outside a Java EE 5 environment, or in any other - case where you would use a Seam-managed persistence context. - </para> - <section> <title>Disabling Seam-managed transactions</title> @@ -197,7 +190,7 @@ <programlisting role="XML"><![CDATA[<transaction:ejb-transaction />]]></programlisting> <para> - However, if you are working in a non EE 5 container, Seam will try auto detect the transaction + However, if you are working in a non EE 5 container, Seam will try to auto detect the transaction synchronization mechanism to use. However, if Seam is unable to detect the correct transaction synchronization to use, you may find you need configure one of the following: </para> @@ -234,23 +227,23 @@ </listitem> </itemizedlist> <para> - Configure JPA RESOURCE_LOCAL transaction management by adding the following to your components.xml where + Configure JPA RESOURCE_LOCAL transaction management by adding the following to your <filename>components.xml</filename> where <literal>#{em}</literal> is the name of the <literal>persistence:managed-persistence-context</literal> component. If your managed persistence context is named <literal>entityManager</literal>, you can opt to leave out the <literal>entity-manager</literal> attribute. (see - <xref linkend="persistence.seam-managed-persistence-contexts"/>Seam-managed persistence contexts) + <xref linkend="persistence.seam-managed-persistence-contexts"/>.) </para> <programlisting role="XML"><![CDATA[<transaction:entity-transaction entity-manager="#{em}"/>]]></programlisting> <para> - To configure Hibernate managed transactions declare the following in your components.xml where + To configure Hibernate managed transactions declare the following in your <filename>components.xml</filename> where <literal>#{hibernateSession}</literal> is the name of the project's <literal>persistence:managed-hibernate-session</literal> component. If your managed hibernate session is named <literal>session</literal>, you can - opt to leave out the <literal>session</literal> attribute. (see - <xref linkend="persistence.seam-managed-persistence-contexts"/>Seam-managed persistence contexts) + opt to leave out the <literal>session</literal> attribute. (See + <xref linkend="persistence.seam-managed-persistence-contexts"/>.) </para> <programlisting role="XML"><![CDATA[<transaction:hibernate-transaction session="#{hibernateSession}"/>]]></programlisting> <para> @@ -259,8 +252,7 @@ <programlisting role="XML"><![CDATA[<transaction:no-transaction />]]></programlisting> <para> For configuring Spring managed transactions see - <xref linkend="spring-transactions"/>using Spring PlatformTransactionManagement. - . + <xref linkend="spring-transactions"/>. </para> </section> <section> @@ -283,29 +275,24 @@ <title>Seam-managed persistence contexts</title> <para> - If you're using Seam outside of a Java EE 5 environment, you can't rely upon the - container to manage the persistence context lifecycle for you. Even if you are - in an EE 5 environment, you might have a complex application with many loosly - coupled components that collaborate together in the scope of a single conversation, - and in this case you might find that propagation of the persistence context between - component is tricky and error-prone. + If you use Seam outside a Java EE 5 environment, you cannot rely upon the + container to manage the persistence context lifestyle. Even within EE 5 + environments, propagating the persistence context between loosely-coupled + components in a complex application can be difficult and error-prone. </para> <para> - In either case, you'll need to use a <emphasis>managed persistence context</emphasis> - (for JPA) or a <emphasis>managed session</emphasis> (for Hibernate) in your components. - A Seam-managed persistence context is just a built-in Seam component that manages an - instance of <literal>EntityManager</literal> or <literal>Session</literal> in the - conversation context. You can inject it with <literal>@In</literal>. + In this case, you will need to use a <emphasis>managed persistence context</emphasis> (for JPA) or a <emphasis>managed session</emphasis> (for Hibernate) in your components. A Seam-managed persistence context is just a built-in Seam component that manages an instance of <literal>EntityManager</literal> or <literal>Session</literal> in the conversation context. You can inject it with <literal>@In</literal>. + </para> <para> - Seam-managed persistence contexts are extremely efficient in a clustered environment. - Seam is able to perform an optimization that EJB 3.0 specification does not allow - containers to use for container-managed extended persistence contexts. Seam supports - transparent failover of extended persisence contexts, without the need to replicate - any persistence context state between nodes. (We hope to fix this oversight in the - next revision of the EJB spec.) + Seam-managed persistence contexts are extremely efficient in a clustered + environment. Seam can perform optimizations for container-managed persistence + contexts that the EJB3 specification does not allow. Seam supports transparent + failover of extended persistence contexts, without replicating any persistence + context state between nodes. (We hope to add this support to the next revision + of the EJB specification.) </para> <section> @@ -381,13 +368,14 @@ <property name="connection.datasource">java:/bookingDatasource</property> ... </session-factory>]]></programlisting> - + <note> <para> - Note that Seam does not flush the session, so you should always enable - <literal>hibernate.transaction.flush_before_completion</literal> to - ensure that the session is automatically flushed before the JTA transaction - commits. + Seam does not synchronize the session with the database, so always enable + <literal>hibernate.transaction.flush_before_completion</literal> to ensure + that the session is automatically synchronized before the JTA transaction + commits. </para> + </note> <para> We can now have a managed Hibernate <literal>Session</literal> injected into our @@ -417,17 +405,13 @@ </para> <para> - By default, the persistence context is flushed (synchronized with the database) - at the end of each transaction. This is sometimes the desired behavior. But very - often, we would prefer that all changes are held in memory and only written to - the database when the conversation ends successfully. This allows for truly - atomic conversations. As the result of a truly stupid and shortsighted decision - by certain non-JBoss, non-Sun and non-Sybase members of the EJB 3.0 expert group, - there is currently no simple, usable and portable way to implement atomic - conversations using EJB 3.0 persistence. However, Hibernate provides this feature - as a vendor extension to the <literal>FlushModeType</literal>s defined by the - specification, and it is our expectation that other vendors will soon provide - a similar extension. + By default, the persistence context is synchronized with the database + (flushed) at the end of each transaction. Sometimes this is desirable, but + often we prefer all changes to be held in memory, and only written to the + database when the conversation ends successfully. This allows for truly atomic + conversations with EJB3 persistence. However, Hibernate provides this feature + as a vendor extension to the <literal>FlushModeTypes</literal> defined by the specification. We + expect other vendors will soon provide a similar extension. </para> <para> @@ -478,19 +462,11 @@ <title>Using the JPA "delegate"</title> <para> - The <literal>EntityManager</literal> interface lets you access a vendor-specific - API via the <literal>getDelegate()</literal> method. Naturally, the most interesting - vendor is Hibernate, and the most powerful delegate interface is - <literal>org.hibernate.Session</literal>. You'd be nuts to use anything else. Trust - me, I'm not biased at all. If you must use a different JPA provider see - <xref linkend="alt-jpa-providers"/>Using Alternate JPA Providers. + The <literal>EntityManager</literal> interface lets you access a vendor-specific API with the <literal>getDelegate()</literal> method. We recommend using Hibernate as your vendor, and <literal>org.hibernate.Session</literal> as your delegate interface, but if you require a different JPA provider, <xref linkend="alt-jpa-providers"/> for further information. </para> <para> - But regardless of whether you're using Hibernate (genius!) or something else - (masochist, or just not very bright), you'll almost certainly want to use the - delegate in your Seam components from time to time. One approach would be the - following: + Regardless of your vendor, there are several approaches to using the delegate in your Seam components. One approach is: </para> <programlisting role="JAVA"><![CDATA[@In EntityManager entityManager; @@ -501,9 +477,7 @@ }]]></programlisting> <para> - But typecasts are unquestionably the ugliest syntax in the Java language, so most - people avoid them whenever possible. Here's a different way to get at the - delegate. First, add the following line to <literal>components.xml</literal>: + If you, like most Java users, would rather avoid using typecasts, you can also access the delegate by adding the following line to <filename>components.xml</filename>: </para> <programlisting role="XML"><![CDATA[<factory name="session" @@ -542,17 +516,19 @@ <programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=:username") .setParameter("username", user.getUsername()) .getSingleResult();]]></programlisting> - + + <warning> <para> - Of course, you should never, ever write it like this: + This should never be written as: </para> - <programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=" + user.getUsername()) //BAD! + <programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=" + user.getUsername()) .getSingleResult();]]></programlisting> <para> - (It is inefficient and vulnerable to SQL injection attacks.) + This is inefficient, but more importantly, it is vulnerable to SQL injection attacks. </para> + </warning> </section> @@ -560,18 +536,11 @@ <title>Using Hibernate filters</title> <para> - The coolest, and most unique, feature of Hibernate is <emphasis>filters</emphasis>. - Filters let you provide a restricted view of the data in the database. You can find - out more about filters in the Hibernate documentation. But we thought we'd mention - an easy way to incorporate filters into a Seam application, one that works especially - well with the Seam Application Framework. + Hibernate's most unique, useful feature is the filter. Filters provide a restricted view of the data in the database. You can find more information in the Hibernate documentation, but this section takes you through one easy, effective method of incorporating filters into Seam. </para> <para> - Seam-managed persistence contexts may have a list of filters defined, which will be - enabled whenever an <literal>EntityManager</literal> or Hibernate <literal>Session</literal> - is first created. (Of course, they may only be used when Hibernate is the underlying - persistence provider.) + Seam-managed persistence contexts can have a list of filters defined, which will be enabled whenever an <literal>EntityManager</literal> or Hibernate <literal>Session</literal> is first created. (These can only be used when Hibernate is the underlying persistence provider.) </para> <programlisting role="XML"><![CDATA[<persistence:filter name="regionFilter">