Package org.eclipse.persistence.descriptors

Class DescriptorEventManager

java.lang.Object
org.eclipse.persistence.core.descriptors.CoreDescriptorEventManager<DescriptorEvent>
org.eclipse.persistence.descriptors.DescriptorEventManager
All Implemented Interfaces:
Serializable, Cloneable
public class DescriptorEventManager extends CoreDescriptorEventManager<DescriptorEvent> implements Cloneable, 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:

  • pre/postWrite - occurs when an object is written (occurs even if no changes to the object).
  • pre/postInsert - occurs when an object is inserted.
  • pre/postUpdate - occurs when an object is updated (occurs even if no changes to the object).
  • pre/postDeleted - occurs when an object is deleted.
  • postBuild/postRefresh - occurs after a object has been built/refreshed from its database row.
  • aboutTo/Insert/Update - occurs when an object is about to be inserted/update allows for row modification.
  • postClone - occurs when an object is registered/cloned in a unit of work.
  • postMerge - occurs when an object is merged with its original in a unit of work.
See Also:

  • Field Details

  • Constructor Details

    • DescriptorEventManager

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

  • Method Details

    • 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:

    • addEntityListenerHolder

      public void addEntityListenerHolder(SerializableDescriptorEventHolder holder)
      INTERNAL:

    • clone

      public Object clone()
      INTERNAL: Clone the manager and its private parts.
      Overrides:
      clone in class Object

    • processDescriptorEventHolders

      public void processDescriptorEventHolders(org.eclipse.persistence.internal.sessions.AbstractSession session, ClassLoader classLoader)
      INTERNAL: This method was added to allow JPA project caching so that DescriptorEventListeners could be serialized and re-added to the EventManager using a SerializableDescriptorEventHolder.
      Parameters:
      classLoader -

    • 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.
      Specified by:
      executeEvent in class CoreDescriptorEventManager<DescriptorEvent>
      Throws:
      DescriptorException - - the method cannot be found or executed

    • findMethod

      protected 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

    • getAboutToDeleteSelector

      public String getAboutToDeleteSelector()
      INTERNAL: bug 251180 - Missing method org.eclipse.persistence.descriptors.DescriptorEventManager#setAboutToDeleteSelector

    • getAboutToInsertSelector

      public String getAboutToInsertSelector()
      INTERNAL:

    • getAboutToUpdateSelector

      public String getAboutToUpdateSelector()
      INTERNAL:

    • getDefaultEventListeners

      public List<DescriptorEventListener> getDefaultEventListeners()
      INTERNAL: EJB 3.0 support. Returns the default listeners.

    • getDescriptor

      protected ClassDescriptor getDescriptor()
      INTERNAL:

    • getDescriptorEventHolders

      public List<SerializableDescriptorEventHolder> getDescriptorEventHolders()
      INTERNAL: used by JPA project caching to store DescriptorEventListener representations that can build the underlying DescriptorEventListener and add it to the EventManager.

    • setDescriptorEventHolders

      public void setDescriptorEventHolders(List<SerializableDescriptorEventHolder> descriptorEventHolders)
      INTERNAL: used by JPA project caching to store DescriptorEventListener representations that can build the underlying DescriptorEventListener and add it to the EventManager.

    • getEntityEventListener

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

    • getEntityListenerEventListeners

      public List<DescriptorEventListener> getEntityListenerEventListeners()
      INTERNAL: EJB 3.0 support. Returns the entity listener event listeners.

    • getEventListeners

      public List<DescriptorEventListener> getEventListeners()
      PUBLIC: Returns the Listener objects that have been added.
      See Also:

    • getEventMethods

      protected AtomicReferenceArray<Method> getEventMethods()

    • getEventSelectors

      protected AtomicReferenceArray<String> getEventSelectors()

    • getPostBuildSelector

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

    • getPostCloneSelector

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

    • getPostDeleteSelector

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

    • getPostInsertSelector

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

    • getPostMergeSelector

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

    • getPostRefreshSelector

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

    • getPostUpdateSelector

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

    • getPostWriteSelector

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

    • getPrePersistSelector

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

    • getPreDeleteSelector

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

    • getPreInsertSelector

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

    • getPreRemoveSelector

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

    • getPreUpdateSelector

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

    • getPreWriteSelector

      public 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.
      Specified by:
      hasAnyEventListeners in class CoreDescriptorEventManager<DescriptorEvent>

    • hasAnyListeners

      protected boolean hasAnyListeners()

    • hasDefaultEventListeners

      public boolean hasDefaultEventListeners()
      INTERNAL: This method will return true, if this event manager has default listeners and does not exclude them. Default listeners are always added to every event manager to allow users to turn them on a later time if so desired.

    • hasEntityEventListener

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

    • hasInternalEventListeners

      public boolean hasInternalEventListeners()
      INTERNAL: Internal event support. Return true if this event manager has any internal listener 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.

    • setAboutToDeleteSelector

      public void setAboutToDeleteSelector(String aboutToDeleteSelector)
      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.

    • setAboutToInsertSelector

      public void setAboutToInsertSelector(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(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(List<DescriptorEventListener> eventListeners)

    • setEventMethods

      protected void setEventMethods(AtomicReferenceArray<Method> eventMethods)

    • setEventSelectors

      protected void setEventSelectors(AtomicReferenceArray<String> 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(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(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(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(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(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(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(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(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(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(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(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(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(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(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.