docs/3.0/persistent-object-lifecycle.html

Title: Persistent Object Lifecycle

	<P>A lifecycle of a persistent object can be represented as a number of states and transitions between them. These states are formally defined as &quot;int&quot; constants in <TT>org.apache.cayenne.PersistenceState</TT> class. Transitions between states (see the diagram below) occur in response to the application interacting with either persistent objects or Cayenne context. Whenever a transition occurs, Cayenne automatically updates &quot;persistenceState&quot; property of all affected objects by calling <TT>setPersistenceState()</TT>.</P>

<TABLE class="sectionMacro" border="0" cellpadding="5" cellspacing="0" width="100%"><TBODY><TR>
<TD class="confluenceTd" valign="top">
<P>A new object state transformations:<BR>
<SPAN class="image-wrap" style=""><IMG src="persistent-object-lifecycle.data/new-persistent-object.png" style="border: 0px solid black"></SPAN></P></TD>

<TD class="confluenceTd" valign="top">
<P>A fetched or committed object state transformations:<BR>
<SPAN class="image-wrap" style=""><IMG src="persistent-object-lifecycle.data/fetched-persistent-object.png" style="border: 0px solid black"></SPAN></P></TD></TR></TBODY></TABLE>

<P>The states are defined as follows:</P>

<DIV class="table-wrap">
<TABLE class="confluenceTable"><TBODY>
<TR>
<TH class="confluenceTh">State</TH>
<TH class="confluenceTh">Value</TH>
<TH class="confluenceTh">Description</TH>
</TR>
<TR>
<TD class="confluenceTd">TRANSIENT</TD>
<TD class="confluenceTd">1</TD>
<TD class="confluenceTd">The object is not registered in a <TT>DataContext</TT> and will not persist.</TD>
</TR>
<TR>
<TD class="confluenceTd">NEW</TD>
<TD class="confluenceTd">2</TD>
<TD class="confluenceTd">The object is freshly registered in a <TT>DataContext</TT>, but has not been persisted to the database (there is no matching database record).</TD>
</TR>
<TR>
<TD class="confluenceTd">COMMITTED</TD>
<TD class="confluenceTd">3</TD>
<TD class="confluenceTd">The object is registered in a <TT>DataContext</TT> and has been persisted to the database (there is a matching database record).</TD>
</TR>
<TR>
<TD class="confluenceTd">MODIFIED</TD>
<TD class="confluenceTd">4</TD>
<TD class="confluenceTd">The object is registered in a <TT>DataContext</TT> and there is a matching database record and the object has been modified in memory, but the changes have not yet been persisted back to the database.</TD>
</TR>
<TR>
<TD class="confluenceTd">HOLLOW</TD>
<TD class="confluenceTd">5</TD>
<TD class="confluenceTd">The object is registered in a <TT>DataContext</TT> and has a corresponding database row, but the values have not yet been fetched from the database.  The values will be fetched/faulted from the database automatically by Cayenne if any fields are requested from the object.</TD>
</TR>
<TR>
<TD class="confluenceTd">DELETED</TD>
<TD class="confluenceTd">6</TD>
<TD class="confluenceTd">The object is registered in a <TT>DataContext</TT> and will be deleted from the database upon commit.</TD>
</TR>
</TBODY></TABLE>
</DIV>