The Apache Cayenne Project

• 3.0.x Documentation
  • Overview
  • Cayenne Guide
  • Remote Client Guide
  • Modeler Guide
  • JavaDoc
  • Back...

Lifecycle Callbacks

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 JPA Specification, 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 callback on a persistent object itself or as a callback on an arbitrary listener object.

Callbacks feature supercedes the following 1.2/2.0 features: Interception of object state transitions inside "Persistent.setPersistenceState()". Event mechanism defined in "org.apache.cayenne.access.event" package that was removed in 3.0. "DataObject.validateForX" - it is a good idea to use it strictly for validation; updating the state before commit should be done via callbacks. "DataObject.fetchFinished()" - scheduled for removal in 3.0

Callback Method Semantics

• No formal interface is required to mark a method to be used for callback (although org.apache.cayenne.LifecycleListener can optionally be implemented for type-safety and to simplify registration).
• A callback method signature looks like "void someMethod()" for persistent classes.
• It looks like "void method(Type entityObject)" for listener classes.
• A callback method can have an arbitrary name.
• A callback method can use public, private, protected or default access.
• It must NOT be static.
• 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.

Callback on persistent object example:

public class Artist { 
   ...

   // a valid callback method
   protected void setDefaultProperties() {
      ...
   }
}

Callback on a listener class example:

public class MyListener { 
   ...

   // a valid callback method
   public void initArtist(Artist a) {
      ...
   }
}

Note that empty callback methods are generated as a part of persistent class generation (either with Maven, Ant or CayenneModeler).

Types of Callbacks

Valid callback types are defined as Java enumerated constants in the org.apache.cayenne.map.LifecycleEvent enumeration.

Registering Callbacks

Normally listeners and persistent object callbacks are mapped in the Modeler, but this can also be done in the code. Callbacks are registered with LifecycleCallbackRegistry, which is shared by all contexts within a DataDomain.

Obtaining the shared registry instance:

import org.apache.cayenne.reflect.LifecycleCallbackRegistry;
...
DataDomain domain = ...
LifecycleCallbackRegistry registry = domain.getEntityResolver().getCallbackRegistry();

Registry obtained this way already contains callbacks mapped in the DataMap. To add extra callbacks in runtimes, use various addListener(...) methods.

Adding a listener object that implements LifecycleListener interface:

import org.apache.cayenne.LifecycleListener

public class MyListener implements LifecycleListener {
	public void prePersist(Object entity) {
		Persistent p = (Persistent) entity;
	    System.out.println("New object created for entity " + p.getObjectId().getEntityName());	
	}
	
	... 
}

// listen for events on a single entity - Artist
registry.addListener(Artist.class, new MyListener());

// listen for events on ALL entities:
registry.addDefaultListener(new MyListener());

Adding a listener of an arbitrary class

public class MyOtherListener {
	
	// note that callback method doesn't have to be 
	// public or called any predefined name
    void onEntityLoad(Object entity) {
		Persistent p = (Persistent) entity;
	    System.out.println("Object fetched: " + p.getObjectId().getEntityName());	
	}
	
	// also we can pass the object already cast to the entity class 
	// if the method is only going to handle this type of entities
	void onArtistChange(Artist artist) {
	    System.out.println("Artist changed " + artist.getArtistName());	
	}
	
	... 
}

Object listener = new MyOtherListener();

// listen for different events on a single entity - Artist. The same
// method can be registered for multiple events
registry.addListener(LifecycleListener.PRE_PERSIST, Artist.class, listener, "onArtistChange");
registry.addListener(LifecycleListener.PRE_REMOVE, Artist.class, listener, "onArtistChange");
registry.addListener(LifecycleListener.PRE_UPDATE, Artist.class, listener, "onArtistChange");

// register another method to listen for ALL entities
registry.addListener(LifecycleListener.POST_LOAD, listener, "onEntityLoad");

Finally a persistent object can implement callbacks as well, being notified of its own events:

// "extends _Artist" implies "implements Persistent" via a superclass
public class Artist extends _Artist {
	
	// note that callback on entity is a no-arg method.
	void onLoad() {
		Persistent p = (Persistent) entity;
	    System.out.println("Object fetched: " + this);	
	}
}

// register Artist class callback
registry.addListener(LifecycleListener.POST_LOAD, Artist.class, "onLoad");

Copyright © 2001-2017 Apache Software Foundation. Apache Cayenne, Cayenne, Apache, the Apache feather logo, and the Apache Cayenne project logo are trademarks of The Apache Software Foundation. Privacy policy.