EclipseLink 1.2.0, build 'v20091016-r5565' API Reference

org.eclipse.persistence.descriptors
Class DescriptorEventManager

java.lang.Object
  extended by org.eclipse.persistence.descriptors.DescriptorEventManager
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable

public class DescriptorEventManager
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

Purpose: The event manager allows for a descriptor to specify that an object should be notified when a EclipseLink event occurs. It also determines how the object will be notified. To specify an event a method name can be registered to be called on the object when the event occurs. Events can be used to extend the EclipseLink reading and writing behavior.

These events include:

See Also:
ClassDescriptor, Serialized Form

Field Summary
static int AboutToDeleteEvent
           
static int AboutToInsertEvent
           
static int AboutToUpdateEvent
           
protected  java.util.Vector defaultEventListeners
           
protected  ClassDescriptor descriptor
           
protected  DescriptorEventListener entityEventListener
           
protected  java.util.Vector entityEventManagers
           
protected  java.util.Vector entityListenerEventListeners
           
protected  java.util.Vector entityListenerEventManagers
           
protected  java.util.Vector eventListeners
           
protected  java.util.Vector eventMethods
           
protected  java.util.Vector eventSelectors
           
protected  boolean excludeDefaultListeners
           
protected  boolean excludeSuperclassListeners
           
protected  boolean hasAnyEventListeners
          PERF: Cache if any events listener exist.
protected  java.util.List<DescriptorEventListener> internalListeners
          Listeners that are fired after all other listeners are fired
protected static int NumberOfEvents
           
static int PostBuildEvent
           
static int PostCloneEvent
           
static int PostDeleteEvent
           
static int PostInsertEvent
           
static int PostMergeEvent
           
static int PostRefreshEvent
           
static int PostUpdateEvent
           
static int PostWriteEvent
           
static int PreDeleteEvent
           
static int PreInsertEvent
           
static int PrePersistEvent
           
static int PreRemoveEvent
           
static int PreUpdateEvent
           
static int PreUpdateWithChangesEvent
           
static int PreWriteEvent
           
 
Constructor Summary
DescriptorEventManager()
          INTERNAL: Returns a new DescriptorEventManager for the specified ClassDescriptor.
 
Method Summary
 void addDefaultEventListener(DescriptorEventListener listener)
          PUBLIC: EJB 3.0 support for default listeners.
 void addEntityListenerEventListener(DescriptorEventListener listener)
          PUBLIC: EJB 3.0 support for lifecycle callback events defined on an entity listener class.
 void addinternalListener(DescriptorEventListener listener)
          INTERNAL:
 void addListener(DescriptorEventListener listener)
          PUBLIC: Listener objects can be registered with the event manager to be notified when an event occurs on any instance of the descriptor's class.
 java.lang.Object clone()
          INTERNAL: Clone the manager and its private parts.
 boolean excludeDefaultListeners()
          INTERNAL: EJB 3.0 support.
 boolean excludeSuperclassListeners()
          INTERNAL: EJB 3.0 support.
 void executeEvent(DescriptorEvent event)
          INTERNAL: Execute the given selector with the event as argument.
protected  java.lang.reflect.Method findMethod(int selector)
          Find the method corresponding to the event selector.
 java.lang.String getAboutToInsertSelector()
          INTERNAL:
 java.lang.String getAboutToUpdateSelector()
          INTERNAL:
 java.util.Vector getDefaultEventListeners()
          INTERNAL: EJB 3.0 support.
protected  ClassDescriptor getDescriptor()
          INTERNAL:
 DescriptorEventListener getEntityEventListener()
          INTERNAL: EJB 3.0 support.
 java.util.Vector getEntityListenerEventListeners()
          INTERNAL: EJB 3.0 support.
 java.util.Vector getEventListeners()
          PUBLIC: Returns the Listener objects that have been added.
protected  java.util.Vector getEventMethods()
           
protected  java.util.Vector getEventSelectors()
           
 java.lang.String getPostBuildSelector()
          PUBLIC: The name of the method called after an object is built
 java.lang.String getPostCloneSelector()
          PUBLIC: The name of the method called after an object is cloned
 java.lang.String getPostDeleteSelector()
          PUBLIC: The name of the method called after an object is deleted
 java.lang.String getPostInsertSelector()
          PUBLIC: The name of the method called after an object is inserted
 java.lang.String getPostMergeSelector()
          PUBLIC: The name of the method called after an object is merged
 java.lang.String getPostRefreshSelector()
          PUBLIC: The name of the method called after an object is refreshed
 java.lang.String getPostUpdateSelector()
          PUBLIC: The name of the method called after an object is updated
 java.lang.String getPostWriteSelector()
          PUBLIC: The name of the method called after an object is written
 java.lang.String getPreDeleteSelector()
          PUBLIC: The name of the method called before an object is deleted
 java.lang.String getPreInsertSelector()
          PUBLIC: The name of the method called before an object is inserted
 java.lang.String getPrePersistSelector()
          PUBLIC: The name of the method called before the create operation is applied to an object
 java.lang.String getPreRemoveSelector()
          PUBLIC: The name of the method called before the remove operation is applied to an object
 java.lang.String getPreUpdateSelector()
          PUBLIC: The name of the method called before an object is updated
 java.lang.String getPreWriteSelector()
          PUBLIC: The name of the method called before an object is written
 boolean hasAnyEventListeners()
          INTERNAL: Return if the event manager has any event listeners, or event methods.
protected  boolean hasAnyListeners()
           
 boolean hasEntityEventListener()
          INTERNAL: EJB 3.0 support.
 boolean hasEntityListenerEventListeners()
          INTERNAL: EJB 3.0 support.
 void initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Configure inherited selectors.
protected  void initializeEJB30EventManagers()
          INTERNAL: EJB 3.0 support.
protected  void notifyEJB30Listeners(DescriptorEvent event)
          INTERNAL: Notify the EJB 3.0 event listeners.
protected  void notifyListener(DescriptorEventListener listener, DescriptorEvent event)
          INTERNAL: Big ugly case statement to notify listeners.
 void notifyListeners(DescriptorEvent event)
          INTERNAL: Notify the event listeners.
 void remoteInitialization(org.eclipse.persistence.internal.sessions.AbstractSession session)
          INTERNAL: Used to initialize a remote DescriptorEventManager.
 void removeListener(DescriptorEventListener listener)
          PUBLIC: Remove a event listener.
 void setAboutToInsertSelector(java.lang.String aboutToInsertSelector)
          PUBLIC: A method can be registered to be called when an object's row it about to be inserted.
 void setAboutToUpdateSelector(java.lang.String aboutToUpdateSelector)
          PUBLIC: A method can be registered to be called when an object's row it about to be updated.
 void setDescriptor(ClassDescriptor descriptor)
          INTERNAL: Set the descriptor.
 void setEntityEventListener(DescriptorEventListener listener)
          PUBLIC: EJB 3.0 support for lifecycle callback events defined on an entity class.
protected  void setEventListeners(java.util.Vector eventListeners)
           
protected  void setEventMethods(java.util.Vector eventMethods)
           
protected  void setEventSelectors(java.util.Vector eventSelectors)
           
 void setExcludeDefaultListeners(boolean excludeDefaultListeners)
          INTERNAL: EJB 3.0 support.
 void setExcludeSuperclassListeners(boolean excludeSuperclassListeners)
          INTERNAL: EJB 3.0 support.
protected  void setHasAnyEventListeners(boolean hasAnyEventListeners)
          INTERNAL: Set if the event manager has any event listeners, or event methods.
 void setPostBuildSelector(java.lang.String postBuildSelector)
          PUBLIC: A method can be registered to be called on a object that has just been built from the database.
 void setPostCloneSelector(java.lang.String postCloneSelector)
          PUBLIC: A method can be registered to be called on a object that has just been cloned into a unit of work.
 void setPostDeleteSelector(java.lang.String postDeleteSelector)
          PUBLIC: A method can be registered to be called on a object that has just been deleted from the database.
 void setPostInsertSelector(java.lang.String postInsertSelector)
          PUBLIC: A method can be registered to be called on a object that has just been inserted into the database.
 void setPostMergeSelector(java.lang.String postMergeSelector)
          PUBLIC: A method can be registered to be called on a object that has just been merge from a unit of work.
 void setPostRefreshSelector(java.lang.String postRefreshSelector)
          PUBLIC: A method can be registered to be called on a object that has just been refreshed from the database.
 void setPostUpdateSelector(java.lang.String postUpdateSelector)
          PUBLIC: A method can be registered to be called on a object that has just been updated into the database.
 void setPostWriteSelector(java.lang.String postWriteSelector)
          PUBLIC: A method can be registered to be called on a object that has just been written to the database.
 void setPreDeleteSelector(java.lang.String preDeleteSelector)
          PUBLIC: A method can be registered to be called on a object that is going to be deleted from the database.
 void setPreInsertSelector(java.lang.String preInsertSelector)
          PUBLIC: A method can be registered to be called on a object that is going to be inserted into the database.
 void setPrePersistSelector(java.lang.String prePersistSelector)
          PUBLIC: A method can be registered to be called on a object when that object has the create operation applied to it.
 void setPreRemoveSelector(java.lang.String preRemoveSelector)
          PUBLIC: A method can be registered to be called on a object when that object has the remove operation applied to it.
 void setPreUpdateSelector(java.lang.String preUpdateSelector)
          PUBLIC: A method can be registered to be called on a object that is going to be updated into the database.
 void setPreWriteSelector(java.lang.String preWriteSelector)
          PUBLIC: A method can be registered to be called on a object that is going to be written to the database.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

descriptor

protected ClassDescriptor descriptor

eventSelectors

protected java.util.Vector eventSelectors

eventMethods

protected transient java.util.Vector eventMethods

eventListeners

protected transient java.util.Vector eventListeners

defaultEventListeners

protected transient java.util.Vector defaultEventListeners

entityListenerEventListeners

protected transient java.util.Vector entityListenerEventListeners

entityEventListener

protected transient DescriptorEventListener entityEventListener

internalListeners

protected transient java.util.List<DescriptorEventListener> internalListeners
Listeners that are fired after all other listeners are fired


entityEventManagers

protected transient java.util.Vector entityEventManagers

entityListenerEventManagers

protected transient java.util.Vector entityListenerEventManagers

excludeDefaultListeners

protected boolean excludeDefaultListeners

excludeSuperclassListeners

protected boolean excludeSuperclassListeners

hasAnyEventListeners

protected boolean hasAnyEventListeners
PERF: Cache if any events listener exist.


PreWriteEvent

public static final int PreWriteEvent
See Also:
Constant Field Values

PostWriteEvent

public static final int PostWriteEvent
See Also:
Constant Field Values

PreDeleteEvent

public static final int PreDeleteEvent
See Also:
Constant Field Values

PostDeleteEvent

public static final int PostDeleteEvent
See Also:
Constant Field Values

PreInsertEvent

public static final int PreInsertEvent
See Also:
Constant Field Values

PostInsertEvent

public static final int PostInsertEvent
See Also:
Constant Field Values

PreUpdateEvent

public static final int PreUpdateEvent
See Also:
Constant Field Values

PostUpdateEvent

public static final int PostUpdateEvent
See Also:
Constant Field Values

PostBuildEvent

public static final int PostBuildEvent
See Also:
Constant Field Values

PostRefreshEvent

public static final int PostRefreshEvent
See Also:
Constant Field Values

PostCloneEvent

public static final int PostCloneEvent
See Also:
Constant Field Values

PostMergeEvent

public static final int PostMergeEvent
See Also:
Constant Field Values

AboutToInsertEvent

public static final int AboutToInsertEvent
See Also:
Constant Field Values

AboutToUpdateEvent

public static final int AboutToUpdateEvent
See Also:
Constant Field Values

AboutToDeleteEvent

public static final int AboutToDeleteEvent
See Also:
Constant Field Values

PrePersistEvent

public static final int PrePersistEvent
See Also:
Constant Field Values

PreRemoveEvent

public static final int PreRemoveEvent
See Also:
Constant Field Values

PreUpdateWithChangesEvent

public static final int PreUpdateWithChangesEvent
See Also:
Constant Field Values

NumberOfEvents

protected static final int NumberOfEvents
See Also:
Constant Field Values
Constructor Detail

DescriptorEventManager

public DescriptorEventManager()
INTERNAL: Returns a new DescriptorEventManager for the specified ClassDescriptor.

Method Detail

addDefaultEventListener

public void addDefaultEventListener(DescriptorEventListener listener)
PUBLIC: EJB 3.0 support for default listeners.


addEntityListenerEventListener

public void addEntityListenerEventListener(DescriptorEventListener listener)
PUBLIC: EJB 3.0 support for lifecycle callback events defined on an entity listener class.


addListener

public void addListener(DescriptorEventListener listener)
PUBLIC: Listener objects can be registered with the event manager to be notified when an event occurs on any instance of the descriptor's class.


addinternalListener

public void addinternalListener(DescriptorEventListener listener)
INTERNAL:


clone

public java.lang.Object clone()
INTERNAL: Clone the manager and its private parts.

Overrides:
clone in class java.lang.Object

excludeDefaultListeners

public boolean excludeDefaultListeners()
INTERNAL: EJB 3.0 support. Returns true if this event manager should exclude the invocation of the default listeners for this descriptor.


excludeSuperclassListeners

public boolean excludeSuperclassListeners()
INTERNAL: EJB 3.0 support. Returns true is this event manager should exclude the invocation of the listeners defined by the entity listener classes for the superclasses of this descriptor.


executeEvent

public void executeEvent(DescriptorEvent event)
                  throws DescriptorException
INTERNAL: Execute the given selector with the event as argument.

Throws:
DescriptorException - - the method cannot be found or executed

findMethod

protected java.lang.reflect.Method findMethod(int selector)
                                       throws DescriptorException
Find the method corresponding to the event selector. The method MUST take DescriptorEvent as argument, Session is also supported as argument for backward compatibility.

Throws:
DescriptorException

getAboutToInsertSelector

public java.lang.String getAboutToInsertSelector()
INTERNAL:


getAboutToUpdateSelector

public java.lang.String getAboutToUpdateSelector()
INTERNAL:


getDefaultEventListeners

public java.util.Vector getDefaultEventListeners()
INTERNAL: EJB 3.0 support. Returns the default listeners.


getDescriptor

protected ClassDescriptor getDescriptor()
INTERNAL:


getEntityEventListener

public DescriptorEventListener getEntityEventListener()
INTERNAL: EJB 3.0 support. Returns the entity event listener.


getEntityListenerEventListeners

public java.util.Vector getEntityListenerEventListeners()
INTERNAL: EJB 3.0 support. Returns the entity listener event listeners.


getEventListeners

public java.util.Vector getEventListeners()
PUBLIC: Returns the Listener objects that have been added.

See Also:
addListener(DescriptorEventListener)

getEventMethods

protected java.util.Vector getEventMethods()

getEventSelectors

protected java.util.Vector getEventSelectors()

getPostBuildSelector

public java.lang.String getPostBuildSelector()
PUBLIC: The name of the method called after an object is built


getPostCloneSelector

public java.lang.String getPostCloneSelector()
PUBLIC: The name of the method called after an object is cloned


getPostDeleteSelector

public java.lang.String getPostDeleteSelector()
PUBLIC: The name of the method called after an object is deleted


getPostInsertSelector

public java.lang.String getPostInsertSelector()
PUBLIC: The name of the method called after an object is inserted


getPostMergeSelector

public java.lang.String getPostMergeSelector()
PUBLIC: The name of the method called after an object is merged


getPostRefreshSelector

public java.lang.String getPostRefreshSelector()
PUBLIC: The name of the method called after an object is refreshed


getPostUpdateSelector

public java.lang.String getPostUpdateSelector()
PUBLIC: The name of the method called after an object is updated


getPostWriteSelector

public java.lang.String getPostWriteSelector()
PUBLIC: The name of the method called after an object is written


getPrePersistSelector

public java.lang.String getPrePersistSelector()
PUBLIC: The name of the method called before the create operation is applied to an object


getPreDeleteSelector

public java.lang.String getPreDeleteSelector()
PUBLIC: The name of the method called before an object is deleted


getPreInsertSelector

public java.lang.String getPreInsertSelector()
PUBLIC: The name of the method called before an object is inserted


getPreRemoveSelector

public java.lang.String getPreRemoveSelector()
PUBLIC: The name of the method called before the remove operation is applied to an object


getPreUpdateSelector

public java.lang.String getPreUpdateSelector()
PUBLIC: The name of the method called before an object is updated


getPreWriteSelector

public java.lang.String getPreWriteSelector()
PUBLIC: The name of the method called before an object is written


hasAnyEventListeners

public boolean hasAnyEventListeners()
INTERNAL: Return if the event manager has any event listeners, or event methods. If nothing is listening to event they can be avoided.


hasAnyListeners

protected boolean hasAnyListeners()

hasEntityEventListener

public boolean hasEntityEventListener()
INTERNAL: EJB 3.0 support. Return true if this event manager has any entity event listeners.


hasEntityListenerEventListeners

public boolean hasEntityListenerEventListeners()
INTERNAL: EJB 3.0 support. Return true if this event manager has any entity listener event listeners.


initialize

public void initialize(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Configure inherited selectors.


initializeEJB30EventManagers

protected void initializeEJB30EventManagers()
INTERNAL: EJB 3.0 support. Builds our chains of descriptor event managers that will need to be notified. The chains are cache so we only need to build them once.


notifyEJB30Listeners

protected void notifyEJB30Listeners(DescriptorEvent event)
INTERNAL: Notify the EJB 3.0 event listeners.


notifyListener

protected void notifyListener(DescriptorEventListener listener,
                              DescriptorEvent event)
                       throws DescriptorException
INTERNAL: Big ugly case statement to notify listeners.

Throws:
DescriptorException

notifyListeners

public void notifyListeners(DescriptorEvent event)
INTERNAL: Notify the event listeners.


remoteInitialization

public void remoteInitialization(org.eclipse.persistence.internal.sessions.AbstractSession session)
INTERNAL: Used to initialize a remote DescriptorEventManager.


removeListener

public void removeListener(DescriptorEventListener listener)
PUBLIC: Remove a event listener.


setAboutToInsertSelector

public void setAboutToInsertSelector(java.lang.String aboutToInsertSelector)
PUBLIC: A method can be registered to be called when an object's row it about to be inserted. This uses the optional event argument of the DatabaseRow. This is different from pre/postInsert because it occurs after the row has already been built. This event can be used to modify the row before insert, such as adding a user inserted by.


setAboutToUpdateSelector

public void setAboutToUpdateSelector(java.lang.String aboutToUpdateSelector)
PUBLIC: A method can be registered to be called when an object's row it about to be updated. This uses the optional event argument of the DatabaseRow. This is different from pre/postUpdate because it occurs after the row has already been built, and it ONLY called if the update is required (changed within a unit of work), as the other occur ALWAYS. This event can be used to modify the row before insert, such as adding a user inserted by.


setDescriptor

public void setDescriptor(ClassDescriptor descriptor)
INTERNAL: Set the descriptor.


setEntityEventListener

public void setEntityEventListener(DescriptorEventListener listener)
PUBLIC: EJB 3.0 support for lifecycle callback events defined on an entity class.


setEventListeners

protected void setEventListeners(java.util.Vector eventListeners)

setEventMethods

protected void setEventMethods(java.util.Vector eventMethods)

setEventSelectors

protected void setEventSelectors(java.util.Vector eventSelectors)

setExcludeDefaultListeners

public void setExcludeDefaultListeners(boolean excludeDefaultListeners)
INTERNAL: EJB 3.0 support. Default listeners apply to all entities in a persistence unit. Set this flag to true to exclude the invocation of the default listeners for this descriptor.


setExcludeSuperclassListeners

public void setExcludeSuperclassListeners(boolean excludeSuperclassListeners)
INTERNAL: EJB 3.0 support. If multiple entity classes in an inheritance hierarchy define entity listeners, the listeners defined for a superclass are invoked before the listeners defined for its subclasses. Set this flag to true to exclude the invocation of the listeners defined by the entity listener classes for the superclasses of this descriptor.


setHasAnyEventListeners

protected void setHasAnyEventListeners(boolean hasAnyEventListeners)
INTERNAL: Set if the event manager has any event listeners, or event methods. If nothing is listening to event they can be avoided.


setPostBuildSelector

public void setPostBuildSelector(java.lang.String postBuildSelector)
PUBLIC: A method can be registered to be called on a object that has just been built from the database. This uses the optional event argument for the DatabaseRow. This event can be used to correctly initialize an object's non-persistent attributes or to perform complex optimizations or mappings. This event is called whenever an object is built.


setPostCloneSelector

public void setPostCloneSelector(java.lang.String postCloneSelector)
PUBLIC: A method can be registered to be called on a object that has just been cloned into a unit of work. This uses the optional event argument for the original object (the source object is the clone). This event can be used to correctly initialize an object's non-persistent attributes.


setPostDeleteSelector

public void setPostDeleteSelector(java.lang.String postDeleteSelector)
PUBLIC: A method can be registered to be called on a object that has just been deleted from the database. This event can notify/remove any dependents on the object.


setPostInsertSelector

public void setPostInsertSelector(java.lang.String postInsertSelector)
PUBLIC: A method can be registered to be called on a object that has just been inserted into the database. This event can be used to notify any dependent on the object, or to update information not accessible until the object has been inserted.


setPostMergeSelector

public void setPostMergeSelector(java.lang.String postMergeSelector)
PUBLIC: A method can be registered to be called on a object that has just been merge from a unit of work. This uses the optional event argument of the original object which is the object being merged from, the source object is the object being merged into. This event can be used to correctly initialize an object's non-persistent attributes.


setPostRefreshSelector

public void setPostRefreshSelector(java.lang.String postRefreshSelector)
PUBLIC: A method can be registered to be called on a object that has just been refreshed from the database. This uses the optional event argument of the DatabaseRow. This event can be used to correctly initialize an object's non-persistent attributes or to perform complex optimizations or mappings. This event is only called on refreshes of existing objects.


setPostUpdateSelector

public void setPostUpdateSelector(java.lang.String postUpdateSelector)
PUBLIC: A method can be registered to be called on a object that has just been updated into the database.


setPostWriteSelector

public void setPostWriteSelector(java.lang.String postWriteSelector)
PUBLIC: A method can be registered to be called on a object that has just been written to the database. This event is raised on any registered object in a unit of work, even if it has not changed, refer to the "aboutToUpdate" selector if it is required for the event to be raised only when the object has been changed. This will be called on all inserts and updates, after the "postInsert/Update" event has been raised. This event can be used to notify any dependent on the object.


setPreDeleteSelector

public void setPreDeleteSelector(java.lang.String preDeleteSelector)
PUBLIC: A method can be registered to be called on a object that is going to be deleted from the database. This event can notify/remove any dependents on the object.


setPreInsertSelector

public void setPreInsertSelector(java.lang.String preInsertSelector)
PUBLIC: A method can be registered to be called on a object that is going to be inserted into the database. This event can be used to notify any dependent on the object or acquire the object's id through a custom mechanism.


setPrePersistSelector

public void setPrePersistSelector(java.lang.String prePersistSelector)
PUBLIC: A method can be registered to be called on a object when that object has the create operation applied to it.


setPreRemoveSelector

public void setPreRemoveSelector(java.lang.String preRemoveSelector)
PUBLIC: A method can be registered to be called on a object when that object has the remove operation applied to it.


setPreUpdateSelector

public void setPreUpdateSelector(java.lang.String preUpdateSelector)
PUBLIC: A method can be registered to be called on a object that is going to be updated into the database. This event is raised on any registered object in a unit of work, even if it has not changed, refer to the "aboutToUpdate" selector if it is required for the event to be raised only when the object has been changed. This event can be used to notify any dependent on the object.


setPreWriteSelector

public void setPreWriteSelector(java.lang.String preWriteSelector)
PUBLIC: A method can be registered to be called on a object that is going to be written to the database. This event is raised on any registered object in a unit of work, even if it has not changed, refer to the "aboutToUpdate" selector if it is required for the event to be raised only when the object has been changed. This will be called on all inserts and updates, before the "preInsert/Update" event has been raised. This event can be used to notify any dependent on the object.


EclipseLink 1.2.0, build 'v20091016-r5565' API Reference