javax.jcr.observation
Interface ObservationManager


public interface ObservationManager

The ObservationManager object.

Acquired via Workspace.getObservationManager(). Allows for the registration and deregistration of event listeners.


Method Summary
 void addEventListener(EventListener listener, int eventTypes, java.lang.String absPath, boolean isDeep, java.lang.String[] uuid, java.lang.String[] nodeTypeName, boolean noLocal)
          Adds an event listener that listens for the specified eventTypes (a combination of one or more event types encoded as a bit mask value).
 EventJournal getEventJournal()
          Retrieves the event journal for this workspace.
 EventJournal getEventJournal(int eventTypes, java.lang.String absPath, boolean isDeep, java.lang.String[] uuid, java.lang.String[] nodeTypeName)
          Retrieves the event journal for this workspace.
 EventListenerIterator getRegisteredEventListeners()
          Returns all event listeners that have been registered through this session.
 void removeEventListener(EventListener listener)
          Deregisters an event listener.
 void setUserData(java.lang.String userData)
          Sets the user data information that will be returned by Event.getUserData().
 

Method Detail

addEventListener

void addEventListener(EventListener listener,
                      int eventTypes,
                      java.lang.String absPath,
                      boolean isDeep,
                      java.lang.String[] uuid,
                      java.lang.String[] nodeTypeName,
                      boolean noLocal)
                      throws RepositoryException
Adds an event listener that listens for the specified eventTypes (a combination of one or more event types encoded as a bit mask value).

The set of events will be further filtered by the access rights of the current Session as well as the restrictions specified by the parameters of this method. These restrictions are stated in terms of characteristics of the associated parent node of the event.

The associated parent node of an event is the parent node of the item at (or formerly at) the path returned by Event.getPath(). The following restrictions are available:

The restrictions are "ANDed" together. In other words, for a particular node to be "listened to" it must meet all the restrictions.

Additionally, if noLocal is true, then events generated by the session through which the listener was registered are ignored. Otherwise, they are not ignored.

The filters of an already-registered EventListener can be changed at runtime by re-registering the same EventListener object (i.e. the same actual Java object) with a new set of filter arguments. The implementation must ensure that no events are lost during the changeover.

In addition to the filters placed on a listener above, the scope of observation support, in terms of which subgraphs are observable, may also be subject to implementation-specific restrictions. For example, in some repositories observation of changes in the jcr:system subgraph may not be supported

Parameters:
listener - an EventListener object.
eventTypes - A combination of one or more event type constants encoded as a bitmask.
absPath - an absolute path.
isDeep - a boolean.
uuid - array of identifiers.
nodeTypeName - array of node type names.
noLocal - a boolean.
Throws:
RepositoryException - If an error occurs.

removeEventListener

void removeEventListener(EventListener listener)
                         throws RepositoryException
Deregisters an event listener.

A listener may be deregistered while it is being executed. The deregistration method will block until the listener has completed executing. An exception to this rule is a listener which deregisters itself from within the onEvent method. In this case, the deregistration method returns immediately, but deregistration will effectively be delayed until the listener completes.

Parameters:
listener - The listener to deregister.
Throws:
RepositoryException - If an error occurs.

getRegisteredEventListeners

EventListenerIterator getRegisteredEventListeners()
                                                  throws RepositoryException
Returns all event listeners that have been registered through this session. If no listeners have been registered, an empty iterator is returned.

Returns:
an EventListenerIterator.
Throws:
RepositoryException - If an error occurs

setUserData

void setUserData(java.lang.String userData)
                 throws RepositoryException
Sets the user data information that will be returned by Event.getUserData().

Parameters:
userData - the user data
Throws:
RepositoryException - if an error occurs

getEventJournal

EventJournal getEventJournal()
                             throws RepositoryException
Retrieves the event journal for this workspace. If journaled observation is not supported for this workspace, null is returned. Events recorded in the EventJournal instance will be filtered according to the current session's access rights as well as any additional restrictions specified through implemention-specific configuration.

Returns:
an EventJournal or null.
Throws:
RepositoryException - if an error occurs

getEventJournal

EventJournal getEventJournal(int eventTypes,
                             java.lang.String absPath,
                             boolean isDeep,
                             java.lang.String[] uuid,
                             java.lang.String[] nodeTypeName)
                             throws RepositoryException
Retrieves the event journal for this workspace.

If journaled observation is not supported for this workspace, null is returned.

Events returned in the EventJournal instance will be filtered according to the parameters of this method, the current session's access restrictions as well as any additional restrictions specified through implemention-specific configuration.

The parameters of this method filter the event set in the same way as they do in addEventListener(javax.jcr.observation.EventListener, int, java.lang.String, boolean, java.lang.String[], java.lang.String[], boolean).

Parameters:
eventTypes - A combination of one or more event type constants encoded as a bitmask.
absPath - an absolute path.
isDeep - a boolean.
uuid - array of identifiers.
nodeTypeName - array of node type names.
Returns:
an EventJournal or null.
Throws:
RepositoryException - If an error occurs.