docs/1.2/cayenne-contract.html

Title: Cayenne Contract

	
<P>There is an implied contract between persistent objects and Cayenne runtime. Cayenne expects persistent objects to follow certain conventions, while itself providing management of the various aspects of a persistent object graph.</P>

<H2><A name="CayenneContract-PersistentObjectRequirements"></A>Persistent Object Requirements</H2>

<H3><A name="CayenneContract-PersistentInterfaces"></A>Persistent Interfaces</H3>

<P>Cayenne can persist Java objects that implement <TT>org.objectstyle.cayenne.Persistent</TT> interface. The interface requires for an object to provide getters and setters for three bean properties: <TT>objectId</TT>, <A href="persistent-object-lifecycle.html" title="Persistent Object Lifecycle"><TT>persistenceState</TT></A> and <TT>objectContext</TT>:</P>

<DIV class="code panel" style="border-width: 1px;"><DIV class="codeHeader panelHeader" style="border-bottom-width: 1px;"><B>Persistent.java</B></DIV><DIV class="codeContent panelContent">
<PRE class="code-java"><SPAN class="code-keyword">public</SPAN> <SPAN class="code-keyword">interface</SPAN> Persistent <SPAN class="code-keyword">extends</SPAN> Serializable {
    ObjectId getObjectId();

    void setObjectId(ObjectId id);

    <SPAN class="code-object">int</SPAN> getPersistenceState();

    void setPersistenceState(<SPAN class="code-object">int</SPAN> state);

    ObjectContext getObjectContext();

    void setObjectContext(ObjectContext objectContext);
}</PRE>
</DIV></DIV>

<P>Furthermore the most commonly used implementation of <A href="objectcontext.html" title="ObjectContext">ObjectContext</A> - <A href="datacontext.html" title="DataContext">DataContext</A> - requires a more complicated subinterface of Persistent - <TT>org.objectstyle.cayenne.DataObject</TT>, that specifies generic methods for property access. The easiest way to satisfy these requirements is by using class generation mechanism provided by Cayenne (using <A href="cgen.html" title="cgen">cgen</A> Ant task or <A href="generate-java-classes.html" title="Generate Java Classes">CayenneModeler UI</A>). </P>

<P>It is worth noting that both requirements will likely become optional in the future releases, being substituted with reflection, bytecode enhancements and other such techniques. Still it is important to understand both benefits and shortcomings of the persistent interface requirement. </P>

<P>The obvious (and only) shortcoming is that the users have to implement it, most often using a class generation template that relies on a framework superclass (such as <TT>org.objectstyle.cayenne.CayenneDataObject</TT>). This may somewhat limit the flexibility of the application design.</P>

<P>In returns users (and Cayenne framework internally) get extra capabilities:</P>

<UL>
	<LI>Fast and consistent mechanism for the framework to inspect, cache, manipulate the objects.</LI>
	<LI>Meaningless primary key doesn't have to be an object property.</LI>
	<LI>An object always knows its context, and thus can access the database from its business logic methods without any external context.</LI>
	<LI>An object always knows how its state compares to the state of the backing database row, and can implement logic based on that knowledge (e.g. objects that are modified, but not yet committed, can be shown in a different color in the user interface).</LI>
	<LI>DataObject interface makes possible <A href="generic-persistent-class.html" title="Generic Persistent Class">generic persistent objects</A>, i.e. the same generic class can map to more than one entity, and persistent behavior can be defined dynamically in runtime.</LI>
</UL>


<H3><A name="CayenneContract-PropertyAccessors"></A>Property Accessors</H3>

<P>Another convention, that is not required strictly speaking, but is almost always implemented by persistent objects is invoking a callback method on their enclosing context before reading or setting their properties. Intercepting property accessors enables lazy on-demand resolution of objects and their relationships and also automatic bidirectional relationships, as discussed below. As with Persistent interface, property interception code is usually created via class generation.</P>


<H2><A name="CayenneContract-HandlingPersistentObjects"></A>Handling Persistent Objects</H2>

<P>Cayenne part of the &quot;persistence contract&quot; is the services it provides, including persistence per se and persistence-related object graph management capabilities.</P>

<H3><A name="CayenneContract-QueryCapabilities"></A>Query Capabilities</H3>

<P>Queries can be executed, bringing back objects matching certain criteria. As a part of this procedure, persistent objects are created and inflated with database values.</P>

<H3><A name="CayenneContract-SingleMethodCallCommitandRollback"></A>Single Method Call Commit and Rollback</H3>

<P>Multiple persistent object changes can be committed with a single method call (and in a single transaction). Similarly, object graph changes made since last commit can be discarded with a single method call.</P>

<H3><A name="CayenneContract-MultipleLevelsofCommitandRollbackNesting"></A>Multiple Levels of Commit and Rollback Nesting</H3>

<P>Commit and rollback functionality can have <A href="nested-datacontexts.html" title="Nested DataContexts">multiple levels of nesting</A> (i.e. a context can rollback its changes without affecting the parent context; or commit its changes to parent without committing them all the way to the database). </P>

<H3><A name="CayenneContract-Relationships"></A>Relationships</H3>

<P>Relationship support - objects related to the previously fetched objects can be accessed via a simple method call. Cayenne will do whatever is necessary to resolve related objects at the right moment behind the scenes. </P>

<P>Unless the user <A href="prefetching.html" title="Prefetching">specifies otherwise</A> in the query that fetched the initial objects, relationships are not fetched together with the objects. When a user requests a related object (or collection of objects), Cayenne ensures that the actual database query to read it is deferred as much as possible, so hopefully there won't be a need to do it at all. E.g. a to-many relationship is resolved only when a list is queried for its size, or a user tries to access one of the elements.</P>

<H3><A name="CayenneContract-AutomaticBidirectionalRelationshipManagemenet"></A>Automatic Bi-directional Relationship Managemenet</H3>

<P>If entity A has a relationship to entity B and entity B has a relationshop back to entity A, Cayenne would maintain consistency of the reverse relationship automatically. Consider this example of a many-to-one relationship, written in a form of a unit test:</P>

<DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent">
<PRE class="code-java">A a1;
B b1;
B b2;

a1.setB(b1);
assertTrue(b1.getListOfA().contains(a1));

a1.setB(b2);
assertTrue(b2.getListOfA().contains(a1));
assertFalse(b1.getListOfA().contains(a1));</PRE>
</DIV></DIV>

<P>This significantly simplifies coding and reduces possibility of errors in managing complex object graphs.</P>

<H3><A name="CayenneContract-ContextInjection"></A>Context Injection</H3>

<P>Cayenne framework injects all three properties defined in <TT>Persistent</TT> interface - <TT>objectId</TT>, <TT>persistenceState</TT> and <TT>objectContext</TT> - at the right moments in the lifecycle. It automatically maintans persistence state changes when an object undergoes state transformations.</P>

<H3><A name="CayenneContract-Uniquing"></A>Uniquing</H3>

<P>Cayenne ensures that each <A href="objectcontext.html" title="ObjectContext">ObjectContext</A> contains at most one instance of each <B>unique</B> persistent object. In other words if two separate independent queries fetched a row with the same primary key, the same object instance will be used in both results. This behavior (not supported by some other frameworks), is extremely important in maintaining consistency of the object graph.</P>

<H3><A name="CayenneContract-LazyObjectResolution"></A>Lazy Object Resolution</H3>

<P>One of the object states is HOLLOW, corresponding to unresolved objects that only have their PK known. Most often HOLLOW objects are returned from to-one relationships. Whenever such object is &quot;touched&quot; by the user (i.e. a  setter or a getter is invoked), Cayenne automatically infaltes it with the database values.</P>