| Title: Lifecycle Callbacks |
| |
| <H2><A name="LifecycleCallbacks-LifecycleCallbacks"></A>Lifecycle Callbacks</H2> |
| |
| <P>Users can register callback methods that will be invoked during the lifecycle of persistent objects. Callback mechanism is similar to the one defined in the <A href="../CAYJPA/jpa-guide.html" title="JPA Guide">JPA Specification</A>, however there are some noteable differences introduced to better follow the Cayenne object lifecycle. There are eight lifecycle callbacks described below (PostAdd, PrePersist, PostPersist, PreUpdate, PostUpdate, PreRemove, PostRemove, PostLoad). Each one cab be invoked as a <B>callback on a persistent object</B> itself or as a <B>callback on an arbitrary listener object</B>.</P> |
| |
| <DIV class="panelMacro"><TABLE class="noteMacro"><COLGROUP><COL width="24"><COL></COLGROUP><TR><TD valign="top"><IMG src="http://cayenne.apache.org/docs/3.0/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></TD><TD><B>Callbacks feature supercedes the following 1.2/2.0 features:</B><BR><UL> |
| <LI>Interception of object state transitions inside <TT>"Persistent.setPersistenceState()"</TT>.</LI> |
| <LI>Event mechanism defined in <TT>"org.apache.cayenne.access.event"</TT> package that was removed in 3.0.</LI> |
| <LI><TT>"DataObject.validateForX"</TT> - it is a good idea to use it strictly for validation; updating the state before commit should be done via callbacks.</LI> |
| <LI><TT>"DataObject.fetchFinished()"</TT> - scheduled for removal in 3.0</LI> |
| </UL> |
| </TD></TR></TABLE></DIV> |
| |
| <H2><A name="LifecycleCallbacks-CallbackMethodSemantics"></A>Callback Method Semantics</H2> |
| |
| <UL> |
| <LI>No formal interface is required to mark a method to be used for callback (although <TT>org.apache.cayenne.LifecycleListener</TT> can optionally be implemented for type-safety and to simplify registration).</LI> |
| <LI>A callback method signature looks like <TT>"void someMethod()"</TT> <EM>for persistent classes</EM>.</LI> |
| <LI>It looks like <TT>"void method(Type entityObject)"</TT> <EM>for listener classes</EM>.</LI> |
| <LI>A callback method can have an arbitrary name.</LI> |
| <LI>A callback method can use public, private, protected or default access.</LI> |
| <LI>It must NOT be static.</LI> |
| <LI>Callback methods are polymorphic - registering a callback on a superclass (even if the superclass does not map to an entity) will ensure the callback will be invoked on all entity subclasses, using the overriding subclass method if applicable.</LI> |
| </UL> |
| |
| |
| <P>Callback on persistent object example:</P> |
| |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java"><SPAN class="code-keyword">public</SPAN> class Artist { |
| ... |
| |
| <SPAN class="code-comment">// a valid callback method |
| </SPAN> <SPAN class="code-keyword">protected</SPAN> void setDefaultProperties() { |
| ... |
| } |
| }</PRE> |
| </DIV></DIV> |
| |
| |
| <P>Callback on a listener class example:</P> |
| |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java"><SPAN class="code-keyword">public</SPAN> class MyListener { |
| ... |
| |
| <SPAN class="code-comment">// a valid callback method |
| </SPAN> <SPAN class="code-keyword">public</SPAN> void initArtist(Artist a) { |
| ... |
| } |
| }</PRE> |
| </DIV></DIV> |
| |
| <P>Note that empty callback methods are generated as a part of persistent class generation (either with <A href="maven2-cgen.html" title="maven2-cgen">Maven</A>, <A href="cgen.html" title="cgen">Ant</A> or CayenneModeler).</P> |
| |
| <H2><A name="LifecycleCallbacks-TypesofCallbacks"></A>Types of Callbacks</H2> |
| |
| <P>Valid callback types are defined as Java enumerated constants in the <TT>org.apache.cayenne.map.LifecycleEvent</TT> enumeration.</P> |
| |
| <DIV class="table-wrap"> |
| <TABLE class="confluenceTable"><TBODY> |
| <TR> |
| <TH class="confluenceTh">Callback</TH> |
| <TH class="confluenceTh">Invoked...</TH> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">PostAdd</TD> |
| <TD class="confluenceTd">Within <TT>"ObjectContext.newObject()"</TT> after ObjectId and ObjectContext are set.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">PrePersist</TD> |
| <TD class="confluenceTd">Prior to commit (and prior to "validateFor*") within <TT>"ObjectContext.commitChanges()"</TT> and <TT>"ObjectContext.commitChangesToParent()"</TT></TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">PreRemove</TD> |
| <TD class="confluenceTd">Before an object is deleted inside <TT>"ObjectContext.deleteObject()"</TT>; also includes all objects that will be deleted as a result of CASCADE delete rule.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">PreUpdate</TD> |
| <TD class="confluenceTd">Prior to commit (and prior to "validateFor*") within <TT>"ObjectContext.commitChanges()"</TT> and <TT>"ObjectContext.commitChangesToParent()"</TT></TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">PostPersist</TD> |
| <TD class="confluenceTd">Within <TT>"ObjectContext.commitChanges()"</TT>, after commit of a new object is done.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">PostRemove</TD> |
| <TD class="confluenceTd">Within <TT>"ObjectContext.commitChanges()"</TT>, after commit of a deleted object is done.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">PostUpdate</TD> |
| <TD class="confluenceTd">Within <TT>"ObjectContext.commitChanges()"</TT>, after commit of a modified object is done.</TD> |
| </TR> |
| <TR> |
| <TD class="confluenceTd">PostLoad</TD> |
| <TD class="confluenceTd"><UL> |
| <LI>Within <TT>"ObjectContext.performQuery()"</TT> after the object is fetched.</LI> |
| <LI>Within <TT>"ObjectContext.rollbackChanges()"</TT> after the object is reverted.</LI> |
| <LI>Anytime a faulted object is resolved (i.e. if a relationship is fetched.</LI> |
| </UL> |
| </TD> |
| </TR> |
| </TBODY></TABLE> |
| </DIV> |
| |
| |
| <H2><A name="LifecycleCallbacks-RegisteringCallbacks"></A>Registering Callbacks</H2> |
| |
| <P>Normally listeners and persistent object callbacks are mapped in the Modeler, but this can also be done in the code. Callbacks are registered with <TT>LifecycleCallbackRegistry</TT>, which is shared by all contexts within a DataDomain.</P> |
| |
| <P>Obtaining the shared registry instance:</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java"><SPAN class="code-keyword">import</SPAN> org.apache.cayenne.reflect.LifecycleCallbackRegistry; |
| ... |
| DataDomain domain = ... |
| LifecycleCallbackRegistry registry = domain.getEntityResolver().getCallbackRegistry();</PRE> |
| </DIV></DIV> |
| |
| |
| <P>Registry obtained this way already contains callbacks mapped in the DataMap. To add extra callbacks in runtimes, use various <TT>addListener(...)</TT> methods. </P> |
| |
| <P>Adding a listener object that implements <TT>LifecycleListener</TT> interface:</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java"><SPAN class="code-keyword">import</SPAN> org.apache.cayenne.LifecycleListener |
| |
| <SPAN class="code-keyword">public</SPAN> class MyListener <SPAN class="code-keyword">implements</SPAN> LifecycleListener { |
| <SPAN class="code-keyword">public</SPAN> void prePersist(<SPAN class="code-object">Object</SPAN> entity) { |
| Persistent p = (Persistent) entity; |
| <SPAN class="code-object">System</SPAN>.out.println(<SPAN class="code-quote">"New object created <SPAN class="code-keyword">for</SPAN> entity "</SPAN> + p.getObjectId().getEntityName()); |
| } |
| |
| ... |
| } |
| |
| <SPAN class="code-comment">// listen <SPAN class="code-keyword">for</SPAN> events on a single entity - Artist |
| </SPAN>registry.addListener(Artist.class, <SPAN class="code-keyword">new</SPAN> MyListener()); |
| |
| <SPAN class="code-comment">// listen <SPAN class="code-keyword">for</SPAN> events on ALL entities: |
| </SPAN>registry.addDefaultListener(<SPAN class="code-keyword">new</SPAN> MyListener());</PRE> |
| </DIV></DIV> |
| |
| <P>Adding a listener of an arbitrary class</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java"><SPAN class="code-keyword">public</SPAN> class MyOtherListener { |
| |
| <SPAN class="code-comment">// note that callback method doesn't have to be |
| </SPAN> <SPAN class="code-comment">// <SPAN class="code-keyword">public</SPAN> or called any predefined name |
| </SPAN> void onEntityLoad(<SPAN class="code-object">Object</SPAN> entity) { |
| Persistent p = (Persistent) entity; |
| <SPAN class="code-object">System</SPAN>.out.println(<SPAN class="code-quote">"<SPAN class="code-object">Object</SPAN> fetched: "</SPAN> + p.getObjectId().getEntityName()); |
| } |
| |
| <SPAN class="code-comment">// also we can pass the object already <SPAN class="code-keyword">cast</SPAN> to the entity class |
| </SPAN> <SPAN class="code-comment">// <SPAN class="code-keyword">if</SPAN> the method is only going to handle <SPAN class="code-keyword">this</SPAN> type of entities |
| </SPAN> void onArtistChange(Artist artist) { |
| <SPAN class="code-object">System</SPAN>.out.println(<SPAN class="code-quote">"Artist changed "</SPAN> + artist.getArtistName()); |
| } |
| |
| ... |
| } |
| |
| <SPAN class="code-object">Object</SPAN> listener = <SPAN class="code-keyword">new</SPAN> MyOtherListener(); |
| |
| <SPAN class="code-comment">// listen <SPAN class="code-keyword">for</SPAN> different events on a single entity - Artist. The same |
| </SPAN><SPAN class="code-comment">// method can be registered <SPAN class="code-keyword">for</SPAN> multiple events |
| </SPAN>registry.addListener(LifecycleListener.PRE_PERSIST, Artist.class, listener, <SPAN class="code-quote">"onArtistChange"</SPAN>); |
| registry.addListener(LifecycleListener.PRE_REMOVE, Artist.class, listener, <SPAN class="code-quote">"onArtistChange"</SPAN>); |
| registry.addListener(LifecycleListener.PRE_UPDATE, Artist.class, listener, <SPAN class="code-quote">"onArtistChange"</SPAN>); |
| |
| <SPAN class="code-comment">// register another method to listen <SPAN class="code-keyword">for</SPAN> ALL entities |
| </SPAN>registry.addListener(LifecycleListener.POST_LOAD, listener, <SPAN class="code-quote">"onEntityLoad"</SPAN>);</PRE> |
| </DIV></DIV> |
| |
| <P>Finally a persistent object can implement callbacks as well, being notified of its own events:</P> |
| <DIV class="code panel" style="border-width: 1px;"><DIV class="codeContent panelContent"> |
| <PRE class="code-java"><SPAN class="code-comment">// <SPAN class="code-quote">"<SPAN class="code-keyword">extends</SPAN> _Artist"</SPAN> implies <SPAN class="code-quote">"<SPAN class="code-keyword">implements</SPAN> Persistent"</SPAN> via a superclass |
| </SPAN><SPAN class="code-keyword">public</SPAN> class Artist <SPAN class="code-keyword">extends</SPAN> _Artist { |
| |
| <SPAN class="code-comment">// note that callback on entity is a no-arg method. |
| </SPAN> void onLoad() { |
| Persistent p = (Persistent) entity; |
| <SPAN class="code-object">System</SPAN>.out.println(<SPAN class="code-quote">"<SPAN class="code-object">Object</SPAN> fetched: "</SPAN> + <SPAN class="code-keyword">this</SPAN>); |
| } |
| } |
| |
| <SPAN class="code-comment">// register Artist class callback |
| </SPAN>registry.addListener(LifecycleListener.POST_LOAD, Artist.class, <SPAN class="code-quote">"onLoad"</SPAN>);</PRE> |
| </DIV></DIV> |
| |
