You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by sk...@apache.org on 2007/09/06 13:49:59 UTC
svn commit: r573232 - in /myfaces/orchestra/trunk/core/src/site/xdoc:
introduction.xml persistence.xml
Author: skitching
Date: Thu Sep 6 04:49:59 2007
New Revision: 573232
URL: http://svn.apache.org/viewvc?rev=573232&view=rev
Log:
Improve docs
Modified:
myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml
myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml?rev=573232&r1=573231&r2=573232&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/introduction.xml Thu Sep 6 04:49:59 2007
@@ -38,5 +38,9 @@
</p>
<p>Orchestra Core requires only Java 1.4 and JSF 1.1.</p>.
</section>
+ <section name="Important Information">
+ <p>At the current time, Orchestra is not safe for use with distributed sessions.
+ If you need this feature, please contact the development list.</p>
+ </section>
</body>
</document>
Modified: myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml
URL: http://svn.apache.org/viewvc/myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml?rev=573232&r1=573231&r2=573232&view=diff
==============================================================================
--- myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml (original)
+++ myfaces/orchestra/trunk/core/src/site/xdoc/persistence.xml Thu Sep 6 04:49:59 2007
@@ -26,22 +26,30 @@
</properties>
<body>
- <section name="Apache MyFaces Orchestra Core">
- <p>Apache MyFaces Orchestra aims to simplify developers life when it comes
- to build web based applications, especially when they build on a persistence
- layer including object-relational-mapping tools such as a JPA implementation
- (e.g. Toplink or Hibernate).</p>
+ <section name="Introduction">
+ <p>Orchestra's persistence support aims to simplify developers life when it comes
+ to build web based applications that extensively use ORM persistence including
+ JPA (Java Persistence Architecture), Toplink or Hibernate.</p>
+ <p>Persistent objects often participate in a conversation (ie a sequence of requests).
+ For example, an address-management module may need to read a person from a database
+ on the first request of a conversation, then later requests may modify attributes
+ and add child records for address, telephone, email, etc. Only at the end of the
+ conversation is the data saved back to the database.</p>
+ </section>
+
+ <section name="The Problem">
<p>Whoever has web-application development experience with an ORM layer
- has run into exceptions like the dreaded LazyInitializationException
+ has run into exceptions like the dreaded LazyInitializationException which
+ occurs when following a relationship from one persistent object to another,
or the NonUniqueObjectException that occurs if you try to <code>merge</code>
- your detached objects back into the persistence session. Most of those problems,
+ detached objects back into the persistence session. Most of those problems,
if not all, result from the fact that a persistence session is opened and closed
for each HTTP request. In this case, the ORM tool has no chance to manage your
entities for the duration of a business process - once you close a persistence
layer session at the end of the HTTP request, all entities are detached from the
persistence layer session.</p>
- <p>So, the magic is to keep such a persistence session open as long as required, but
- as short as possible; contrary to the often propagated OpenSessionInView or
+ <p>The magic is to keep such a persistence session open as long as required, but
+ as short as possible, contrary to the well-known OpenSessionInView or
OpenSessionPerRequest-patterns. In those patterns, the session is closed too early
for completing a full business process. Keeping the session alive for exactly the
necessary timespan is one of the cool features of Apache MyFaces Orchestra.</p>
@@ -51,6 +59,153 @@
<p>A conversation scope is (like the request or session scope) a place where you can
store your beans. A conversation-scoped bean will have an attached entity manager
which is in use for each database access until the application ends the conversation.</p>
+ </section>
+
+ <section name="Quick review of the Java Persistence API (JPA)">
+ <p>JPA defines the concept of a "PersistenceContext", aka an EntityManager (or in Hibernate
+ terminology, a "Session"). This represents a pool of persistent objects. First the context
+ has to be created. Then data can be loaded from the database, causing objects to be created
+ and placed in the context. Objects in the context can be modified, and new objects can be
+ placed in the context. When entityManager.flush() is called, any modified data in the
+ context is written back out to the database.</p>
+ <p>When an object is read from the database which has a reference to some other persistent
+ object, what happens depends on whether that reference ("relation") is marked as "eager"
+ or "lazy":
+ <ul>
+ <li><p>For eager relations, the associated data is read immediately from the database,
+ and an object created to hold it (which is also added to the persistence context). The
+ relation can then be followed (ie the reference used) even after the associated
+ persistence context is no longer valid, as the object is already in memory.</p></li>
+ <li><p>For lazy relations, the reference in the original object points instead at a
+ JPA-created proxy object, and only if a method is invoked on the proxy is a database
+ operation triggered to load the actual object. Lazy relations are very useful, but mean
+ that the relation can only be followed while the persistence context is still valid; if
+ the proxy is triggered after the persistence context is no longer valid then a
+ LazyInitializationException occurs.</p></li>
+ </ul>
+ </p>
+ <p>A context can be closed (which automatically flushes it). When this happens, all objects in
+ the context become "detached"; code that holds references to them can still access the objects.
+ However because the context no longer exists, they cannot be written back to the database.
+ In addition, any attempt to fetch a related object causes a LazyIntializationException because
+ there is no longer a context into which the related object can be fetched.</p>
+ <p>Contexts are closed when no longer used because they do take up a lot of memory. The art of
+ persistence is to keep contexts around for as long as necessary but no longer. Note that in
+ some ORM implementations it is possible to partially discard contexts, ie to remove from the
+ context objects that are known to no longer be needed, but that is not a general-purpose
+ solution; it is just too hard to manually track exactly what is in use and what is not.</p>
+ <p>An object which has been detached (ie whose context has been closed) can be reattached to a
+ different context. This allows code to load an object, detach it, modify it and later
+ (potentially days later) create a new context, reattach the object then flush the new
+ context causing that object to be written to the database. Of course if the database has
+ been modified in the meantime then the save will fail.</p>
+ <p>The above information about JPA also applies to Hibernate and Toplink, which work in
+ a very similar manner.</p>
+<!--
+ -->
+ </section>
+
+ <section name="Using EJBs (separated web tier and business logic)">
+ <p>When using the full jee framework, the web and logic tiers are strongly separated, and may be
+ on separate physical machines. The logic tier (EJBs) are responsible for performing all
+ database access; they use declarative security and other mechanisms to ensure that external
+ code (including a web tier, native gui applications, etc) can only read data that they have
+ rights to read, and can only modify data via the APIs provided by the EJBs.</p>
+ <p>In this case, the web tier has no database connection, and clearly can only navigate relations
+ that are present in the serialized data returned by EJBs. In the old days (before JPA),
+ fields representing such relationships would simply be null, and accessing them would
+ trigger a NullPointerException or similar. If an EJB uses JPA to load objects, then
+ returns those objects to a remote client, then any attempt to navigate a relationship
+ that is not populated will instead result in a LazyInitializationException; the effect
+ is the same but the difference exists because JPA uses proxy objects to implement lazy
+ loading. These proxy objects get returned along with the "real" data, but as there is
+ no longer a context that the real referenced objects can be loaded into (and no
+ database connection to do it with!) they cannot execute.</p>
+ <p>In practice, this does mean that the EJB tier has to be very aware of the needs of its
+ presentation tier (eg the web tier), but this does seem unavoidable, and is the price
+ of the strong separation between business and presentation.</p>
+ <p>Because an application using this architecture provides no database connection to
+ the web tier, Orchestra <i>can not provide any support for conversation-scoped persistence
+ contexts</i>. Orchestra's persistence support is only for use with applications that have
+ their business logic and presentation logic in the same tier.</p>
+ <p>Note that JBoss Seam provides similar "conversation-scoped" persistence support, but this
+ also only applies when the business logic and the presentation logic are in the same
+ "tier". When remote EJBs are used to implement interactions with the database then
+ there is simply nothing the web tier can do about this.</p>
+ </section>
+
+ <section name="Single Tier Applications -- Old Style">
+ <p>Much code that does not use EJBs is nevertheless written in the stateless-session-bean
+ style. When displaying a persistent object a backing bean method will open a
+ persistence-context, read the relevant objects into it and then close the context.
+ JSF components then render the object, but must be careful not to access any
+ relations that were not initialised before the context was closed. A later action
+ method which wants to save data will open a new context, reattach the object
+ retrieved earlier, flush the context to the database, then close the context again.</p>
+ <p>An alternative is to allow the object context to exist for the entire http request,
+ closing it only when the request is about to return (after render phase). This is
+ referred to as the "Open Session In View" pattern. In this way, the context is cached
+ (eg in a thread-local variable) for the duration of the request, and any JSF action
+ method that wants to access persistent objects just retrieves that context and uses
+ it. This is an extremely useful pattern, with no known drawbacks.</p>
+ <p>However with "Open Session In View" the context is still tied to just one request.
+ This still exposes the application to potential LazyInitialisationExceptions, as
+ follows:
+ <ul>
+ <li><p>request #1 loads an object from the database and stores it in the http session.
+ The page is nicely rendered, and no LazyInitialisationException can occur. The pool
+ is closed at the end of the request.</p></li>
+ <li><p>request #2 is executed, which tries to display more data from the object that
+ is cached in the session. That data is not currently loaded, however, and the
+ object is no longer in a context. An exception therefore occurs.</p></li>
+ </ul>
+ </p>
+ </section>
+
+ <section name="Single Tier Applications -- With Conversation Scoped Persistence">
+ <p>The solution to the problems described above is simply to store the PersistenceContext
+ object in the http session, and only close it after the conversation has ended, ie
+ when it has been decided to write to the database or abandon any changes made.</p>
+ <p>Although the default behaviour of JPA is to close the persistence context when a
+ transaction commits or rolls back, this is optional and simply disabling this allows
+ the persistence context to be cached over multiple requests. Instead, the db
+ connection associated with the persistence context is simply removed from the
+ context at the end of each request and returned to the connection pool. At the
+ start of the next request a different connection is retrieved from the db pool
+ and attached to the persistence context again.</p>
+ <p>Note that database transactions still occur; typically a transaction is started
+ on the context's connection at the beginning of each request and committed at the
+ end of each request. However as long as no flush() operation has been invoked on
+ the context, modifications made to objects in the context do not get written to
+ disk. Of course it is not possible for a real database transaction to be kept
+ open across requests, as that would require the database to keep rows in the
+ database locked for as long as the http session lasts (potentially hours), which
+ is simply unacceptable.</p>
+ <p>There are dangers to this approach; a persistence context can become large if
+ many objects have been loaded into it. Care needs to be taken to control the
+ amount of persistent data read/written during a conversation. Manual removal
+ of objects from the context which are no longer needed can be useful, or
+ secondary persistence contexts can be created to perform operations on objects
+ that are not needed to be kept in the conversation scope - particularly reads of
+ objects that will not be modified as part of the conversation.</p>
+ <p>There is also a potential problem when inserting new objects into the context
+ which have a database key that is generated via a database write. In this case,
+ the database write occurs in the request in which the object was added to the
+ context, even though the object's data does not get written until the end of
+ the conversation. If the conversation is "rolled back" then the key operation
+ remains, as that transaction has long since been committed.</p>
+ </section>
+
+ <section name="Handling Transactions">
+ <p>The scope of a persistence context and database transaction boundaries
+ (begin/commit) are separate issues. Multiple database transactions *can*
+ occur within the lifetime of a single persistence context. It isn't the
+ default - by default, close/rollback will close the associated context.
+ However it is possible to disable this default in which case the
+ persistence-context can last longer.</p>
+ <p>TODO: document Orchestra's transaction support features</p>
+ <p>TODO: is the persistence-context serializable? Are all persistent objects
+ in the context always serializable?</p>
</section>
</body>
</document>