001: /*
002: * Copyright 2006 Day Management AG, Switzerland. All rights reserved.
003: */
004: package javax.jcr.observation;
005:
006: import javax.jcr.RepositoryException;
007:
008: /**
009: * The ObservationManager object.
010: * <p>
011: * Acquired via <code>{@link javax.jcr.Workspace#getObservationManager()}</code>.
012: * Allows for the registration and deregistration of event listeners.
013: */
014: public interface ObservationManager {
015:
016: /**
017: * Adds an event listener that listens for the specified <code>eventTypes</code> (a combination of one or more
018: * event types encoded as a bit mask value).
019: * <p/>
020: * The set of events will be further filtered by the access rights of the
021: * current <code>Session</code> as well as the restrictions specified by the
022: * parameters of this method. These restrictions are stated in terms of
023: * characteristics of the <i>associated parent node</i> of the event.
024: * <p/>
025: * The associated parent node of an event is the parent node of the item at (or formerly at) the
026: * path returned by {@link Event#getPath}. The following restrictions are available:
027: * <ul>
028: * <li>
029: * <code>absPath</code>, <code>isDeep</code>: Only events whose associated parent node is at
030: * <code>absPath</code> (or within its subtree, if <code>isDeep</code> is <code>true</code>) will be received.
031: * It is permissible to register a listener for a path where no node currently exists.
032: * </li>
033: * <li>
034: * <code>uuid</code>: Only events whose associated parent node has one of the identifiers in this list will be
035: * received. If his parameter is <code>null</code> then no identifier-related restriction is placed on events
036: * received. Note that specifying an empty array instead of <code>null</code>
037: * would result in no nodes being listened to. The term "UUID" is used for
038: * compatibility with JCR 1.0.
039: * </li>
040: * <li>
041: * <code>nodeTypeName</code>: Only events whose associated parent node has one of the node types
042: * (or a subtype of one of the node types) in this list will be received. If his parameter is
043: * <code>null</code> then no node type-related restriction is placed on events received.
044: * Note that specifying an empty array instead of <code>null</code>
045: * would result in no nodes types being listened to.
046: * </li>
047: * </ul>
048: * The restrictions are "ANDed" together. In other words, for a particular node to be "listened to" it must meet all the restrictions.
049: * <p/>
050: * Additionally, if <code>noLocal</code> is <code>true</code>, then events generated by the session through which
051: * the listener was registered are ignored. Otherwise, they are not ignored.
052: * <p/>
053: * The filters of an already-registered <code>EventListener</code> can be changed at runtime by re-registering the
054: * same <code>EventListener</code> object (i.e. the same actual Java object) with a new set of filter arguments.
055: * The implementation must ensure that no events are lost during the changeover.
056: * <p/>
057: * In addition to the filters placed on a listener above, the scope of observation
058: * support, in terms of which subtrees are observable, may also be subject to
059: * implementation-specific restrictions. For example, in some repositories
060: * observation of changes in the <code>jcr:system</code> subtree may not be supported
061: *
062: * @param listener an {@link EventListener} object.
063: * @param eventTypes A combination of one or more event type constants encoded as a bitmask.
064: * @param absPath an absolute path.
065: * @param isDeep a <code>boolean</code>.
066: * @param uuid array of identifiers.
067: * @param nodeTypeName array of node type names.
068: * @param noLocal a <code>boolean</code>.
069: * @throws RepositoryException If an error occurs.
070: */
071: public void addEventListener(EventListener listener,
072: int eventTypes, String absPath, boolean isDeep,
073: String[] uuid, String[] nodeTypeName, boolean noLocal)
074: throws RepositoryException;
075:
076: /**
077: * Deregisters an event listener.
078: * <p>
079: * A listener may be deregistered while it is being executed. The
080: * deregistration method will block until the listener has completed
081: * executing. An exception to this rule is a listener which deregisters
082: * itself from within the <code>onEvent</code> method. In this case, the
083: * deregistration method returns immediately, but deregistration will
084: * effectively be delayed until the listener completes.
085: *
086: * @param listener The listener to deregister.
087: *
088: * @throws RepositoryException If an error occurs.
089: */
090: public void removeEventListener(EventListener listener)
091: throws RepositoryException;
092:
093: /**
094: * Returns all event listeners that have been registered through this session.
095: * If no listeners have been registered, an empty iterator is returned.
096: *
097: * @return an <code>EventListenerIterator</code>.
098: * @throws RepositoryException If an error occurs
099: */
100: public EventListenerIterator getRegisteredEventListeners()
101: throws RepositoryException;
102:
103: /**
104: * Sets the user data information that will be returned by {@link Event#getUserData}.
105: * @param userData
106: * @throws RepositoryException
107: */
108: public void setUserData(String userData) throws RepositoryException;
109: }
|