You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cayenne.apache.org by aa...@apache.org on 2012/03/16 12:32:01 UTC
svn commit: r1301439 - in
/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx:
persistent-objects-objectcontext.xml starting-cayenne.xml
Author: aadamchik
Date: Fri Mar 16 11:32:01 2012
New Revision: 1301439
URL: http://svn.apache.org/viewvc?rev=1301439&view=rev
Log:
docbook
objectcontext docs
Modified:
cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml?rev=1301439&r1=1301438&r2=1301439&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/persistent-objects-objectcontext.xml Fri Mar 16 11:32:01 2012
@@ -4,9 +4,75 @@
<title>Persistent Objects and ObjectContext</title>
<section xml:id="objectcontext">
<title>ObjectContext</title>
+ <para>ObjectContext is an interface that users normally work with to access the database. It
+ provides the API to execute database operations and to manage persistent objects. A
+ context is obtained from the
+ ServerRuntime:<programlisting>ObjectContext context = runtime.getContext();</programlisting></para>
+ <para>The call above creates a new instance of ObjectContext that can work with this
+ particualr Cayenne stack. ObjectContext is a single "work area" in Cayenne, storing
+ persistent objects. ObjectContext guarantees that for each database row with a unique ID
+ it will contain at most one instance of an object, thus ensuring object graph
+ consistency between multiple selects (a feature called "uniquing"). At the same time
+ different ObjectContexts will have independent copies of objects for each unique
+ database row. This allows users to isolate object changes from one another by using
+ separate ObjectContexts.</para>
+ <para>These properties directly affect the strategies for scoping and sharing (or not
+ sharing) ObjectContexts. Contexts that are only used to fetch objects from the database
+ and whose objects are never modified by the application can be shared between mutliple
+ users (and multiple threads). Contexts that store modified objects should be accessed
+ only by a single user (e.g. a web application user might reuse a context instance
+ between multiple web requests in the same HttpSession, thus carrying uncommitted changes
+ to objects from request to request, until he decides to commit or rollback them). Even
+ for a single user it might make sense to use mutliple ObjectContexts (e.g.
+ request-scoped contexts to allow concurrent requests from the browser that change and
+ commit objects independently).</para>
+ <para>ObjectContext is serializable and does not permanently hold to any of the application
+ resources. So it does not have to be closed. If the context is not used anymore, it
+ should simply be allowed to go out of scope and get garbage collected, just like any
+ other Java object.</para>
</section>
<section xml:id="persistent-lifecycle">
<title>Persistent and its Lifecycle</title>
+ <para>Cayenne can persist Java objects that implement
+ <code>org.apache.cayenne.Persistent</code> interface. The interface provides access
+ to 3 persistence-related properties - objectId, persistenceState and objectContext.
+ Generally persistent objects are created from the model using class generation as
+ described above, so users do not have to worry about implementation details. Still
+ access to 3 properties above is very often useful in the application code (e.g. ObjectId
+ can be used for quick equality check of 2 objects, persistence state can allow
+ highlighting changed objects, etc.),</para>
+ <para>Each persistent object belongs to a single ObjectContext, and can be in one of the
+ following persistence states that are managed by Cayenne:<table frame="void">
+ <caption>Persistence States</caption>
+ <col width="50%"/>
+ <col width="50%"/>
+ <tbody>
+ <tr>
+ <td/>
+ <td/>
+ </tr>
+ <tr>
+ <td/>
+ <td/>
+ </tr>
+ <tr>
+ <td/>
+ <td/>
+ </tr>
+ <tr>
+ <td/>
+ <td/>
+ </tr>
+ <tr>
+ <td/>
+ <td/>
+ </tr>
+ <tr>
+ <td/>
+ <td/>
+ </tr>
+ </tbody>
+ </table></para>
</section>
<section xml:id="persistent-operations">
<title>Persistent Operations</title>
Modified: cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml
URL: http://svn.apache.org/viewvc/cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml?rev=1301439&r1=1301438&r2=1301439&view=diff
==============================================================================
--- cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml (original)
+++ cayenne/main/trunk/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml Fri Mar 16 11:32:01 2012
@@ -29,7 +29,7 @@
ServerRuntime runtime =
new ServerRuntime("com/example/cayenne-project.xml", extensions);</programlisting></para>
<para>It is a good idea to shut down the runtime when it is no longer needed, usually before the
- application itself is shutdown: <programlisting>runtime.shutdwon();</programlisting>When
+ application itself is shutdown: <programlisting>runtime.shutdown();</programlisting>When
a runtime object has the same scope as the application, this may not be always
necessary, however in some cases it is essential, and is generally considered a good
practice. E.g. in a web container hot redeploy of a webapp will cause resource leaks and