KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > jcr > observation > ObservationManager


1 /*
2  * $Id: ObservationManager.java,v 1.2 2004/07/24 00:16:23 benjmestrallet Exp $
3  *
4  * Copyright 2002-2004 Day Management AG, Switzerland.
5  *
6  * Licensed under the Day RI License, Version 2.0 (the "License"),
7  * as a reference implementation of the following specification:
8  *
9  * Content Repository API for Java Technology, revision 0.12
10  * <http://www.jcp.org/en/jsr/detail?id=170>
11  *
12  * You may not use this file except in compliance with the License.
13  * You may obtain a copy of the License files at
14  *
15  * http://www.day.com/content/en/licenses/day-ri-license-2.0
16  * http://www.apache.org/licenses/LICENSE-2.0
17  *
18  * Unless required by applicable law or agreed to in writing, software
19  * distributed under the License is distributed on an "AS IS" BASIS,
20  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21  * See the License for the specific language governing permissions and
22  * limitations under the License.
23  */
24 package javax.jcr.observation;
25
26 import javax.jcr.RepositoryException;
27
28 /**
29  * The ObservationManager object.
30  * <p/>
31  * <b>Level 2 only</b>
32  * <p/>
33  * Acquired via <code>Ticket.getObservationManager()</code>.
34  * Allows for the registration and deregistration of observation listeners.
35  *
36  * @author Tim Anderson
37  * @author Peeter Piegaze
38  * @author Stefan Guggisberg
39  */
40 public interface ObservationManager {
41
42   /**
43    * Add an observation listener (parameter <code>listener</code>) which listens
44    * for the specified <code>events</code> that originate from the item at
45    * <code>absPath</code> (including all children up to <code>depth</code>,
46    * where -1 indicates an "infinite" depth). It is possible to register a
47    * listener for a path where no item currently exists.
48    * <p/>
49    * If <code>noLocal</code> is true
50    * then events generated by the owning ticket are ignored. To reduce the
51    * number of events an observation selector can be specified. An observation selector
52    * discards events that aren’t applicable. The events are selected based on
53    * observation content rather than observation type. This also enables the repository
54    * implementation to filter events before they are dispatched, to reduce
55    * bandwidth. The <code>eventSelector</code> parameter specifies the
56    * expression used to filter events. This uses a subset of the ContentSQL
57    * syntax:
58    * <p/>
59    * <code>
60    * propertyname operator value { ["AND" | "OR"] propertyname operator value}
61    * </code>
62    *
63    * @param eventTypes A combination of one or more of the following constants
64    * encoded as a bitmask value:
65    * <ul>
66    * <li><code>EventType.ITEM_ADDED</code></li>
67    * <li><code>EventType.ITEM_CHANGED</code></li>
68    * <li><code>EventType.ITEM_REMOVED</code></li>
69    * <li><code>EventType.ITEM_VERSIONED</code></li>
70    * <li><code>EventType.LABEL_ADDED</code></li>
71    * <li><code>EventType.LABEL_REMOVED</code></li>
72    * <li><code>EventType.ITEM_LOCKED</code></li>
73    * <li><code>EventType.ITEM_UNLOCKED</code></li>
74    * <li><code>EventType.LOCK_EXPIRED</code></li>
75    * </ul>
76    * See <code>{EventType}</code>.
77    * @param absPath Specifies the item path that the listener wants to receive
78    * events for. It is possible to register a listener for a path
79    * where no item currently exists.
80    * @param depth Specifies whether the registration is for the item named
81    * by <code>absPath</code> (depth = 0), the item and its immediate children
82    * (depth = 1), or some other depth of tree. A depth value of –1 corresponds
83    * to an "infinite depth", meaning the entire sub-tree rooted at
84    * <code>absPath</code>.
85    * @param listener The listener object that will "do the listening".
86    * @param noLocal If <code>true</code>, supresses receipt of events
87    * generated by the owning ticket instance.
88    * @param selector An <code>EventSelector</code> object whose <code>accept</code>
89    * method can be used to filter events, based on their content.
90    * @throws RepositoryException If an error occurs.
91    */
92   public void addEventListener(long eventTypes, String JavaDoc absPath, int depth, EventListener listener, boolean noLocal, EventSelector selector)
93       throws RepositoryException;
94
95   /**
96    * Same as <code>{@link #addEventListener(long eventTypes, String absPath, int depth, EventListener listener, boolean noLocal, EventSelector selector)}</code>
97    * except for <code>VetoableEventListener</code>s instead of
98    * <code>EventListener</code>s.
99    *
100    * @param eventTypes A combination of one or more of the following constants
101    * encoded as a bitmask value:
102    * <ul>
103    * <li><code>EventType.ITEM_ADDED</code></li>
104    * <li><code>EventType.ITEM_CHANGED</code></li>
105    * <li><code>EventType.ITEM_REMOVED</code></li>
106    * <li><code>EventType.ITEM_VERSIONED</code></li>
107    * <li><code>EventType.LABEL_ADDED</code></li>
108    * <li><code>EventType.LABEL_REMOVED</code></li>
109    * <li><code>EventType.ITEM_LOCKED</code></li>
110    * <li><code>EventType.ITEM_UNLOCKED</code></li>
111    * <li><code>EventType.LOCK_EXPIRED</code></li>
112    * </ul>
113    * See <code>{EventType}</code>.
114    * @param absPath Specifies the item path that the listener wants to receive
115    * events for.
116    * @param depth Specifies whether the registration is for the item named
117    * by <code>absPath</code> (depth = 0), the item and its immediate children
118    * (depth = 1), or some other depth of tree. A depth value of –1 corresponds
119    * to an "infinite depth", meaning the entire sub-tree rooted at
120    * <code>absPath</code>.
121    * @param listener The listener object that will "do the listening".
122    * @param noLocal If <code>true</code>, supresses receipt of events
123    * generated by the owning ticket instance.
124    * @param selector An <code>EventSelector</code> object whose <code>accept</code>
125    * method can be used to filter events based on their content.
126    * @throws RepositoryException If an error occurs.
127    */
128   public void addVetoableEventListener(long eventTypes, String JavaDoc absPath, int depth, VetoableEventListener listener, boolean noLocal, EventSelector selector) throws RepositoryException;
129
130   /**
131    * Deregisters an observation listener.
132    * <p/>
133    * A listener may be deregistered while it is being executed. The
134    * deregistration method will block until the listener has completed
135    * executing. An exception to this rule is a listener which deregisters
136    * itself from within the <code>onEvent</code> method. In this case, the
137    * deregistration method returns immediately, but deregistration will
138    * effectively be delayed until the listener completes.
139    *
140    * @param listener The listener to deregister.
141    * @throws RepositoryException If an error occurs.
142    */
143   public void removeEventListener(EventListener listener) throws RepositoryException;
144
145   /**
146    * Deregisters a vetoable observation listener.
147    * <p/>
148    * A listener may be deregistered while it is being executed. The
149    * deregistration method will block until the listener has completed
150    * executing. An exception to this rule is a listener which deregisters
151    * itself from within the <code>onEvent</code> method. In this case, the
152    * deregistration method returns immediately, but deregistration will
153    * effectively be delayed until the listener completes.
154    *
155    * @param listener The vetoable listener to deregister.
156    * @throws RepositoryException If an error occurs.
157    */
158   public void removeVetoableEventListener(VetoableEventListener listener) throws RepositoryException;
159 }
160
Popular Tags