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
