|
1 /* |
|
2 * Copyright 2007 Sun Microsystems, Inc. All Rights Reserved. |
|
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
4 * |
|
5 * This code is free software; you can redistribute it and/or modify it |
|
6 * under the terms of the GNU General Public License version 2 only, as |
|
7 * published by the Free Software Foundation. Sun designates this |
|
8 * particular file as subject to the "Classpath" exception as provided |
|
9 * by Sun in the LICENSE file that accompanied this code. |
|
10 * |
|
11 * This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 * version 2 for more details (a copy is included in the LICENSE file that |
|
15 * accompanied this code). |
|
16 * |
|
17 * You should have received a copy of the GNU General Public License version |
|
18 * 2 along with this work; if not, write to the Free Software Foundation, |
|
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 * |
|
21 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
22 * CA 95054 USA or visit www.sun.com if you need additional information or |
|
23 * have any questions. |
|
24 */ |
|
25 |
|
26 package javax.management.event; |
|
27 |
|
28 import com.sun.jmx.mbeanserver.Util; |
|
29 import java.io.IOException; |
|
30 import javax.management.InstanceNotFoundException; |
|
31 import javax.management.ListenerNotFoundException; |
|
32 import javax.management.MBeanException; |
|
33 import javax.management.NotificationFilter; |
|
34 import javax.management.ObjectName; |
|
35 import javax.management.remote.NotificationResult; |
|
36 |
|
37 /** |
|
38 * <p>This interface specifies necessary methods on the MBean server |
|
39 * side for a JMX remote client to manage its notification listeners as |
|
40 * if they are local. |
|
41 * Users do not usually work directly with this MBean; instead, the {@link |
|
42 * EventClient} class is designed to be used directly by the user.</p> |
|
43 * |
|
44 * <p>A default implementation of this interface can be added to an MBean |
|
45 * Server in one of several ways.</p> |
|
46 * |
|
47 * <ul> |
|
48 * <li><p>The most usual is to insert an {@link |
|
49 * javax.management.remote.MBeanServerForwarder MBeanServerForwarder} between |
|
50 * the {@linkplain javax.management.remote.JMXConnectorServer Connector Server} |
|
51 * and the MBean Server, that will intercept accesses to the Event Client |
|
52 * Delegate MBean and treat them as the real MBean would. This forwarder is |
|
53 * inserted by default with the standard RMI Connector Server, and can also |
|
54 * be created explicitly using {@link EventClientDelegate#newForwarder()}. |
|
55 * |
|
56 * <li><p>A variant on the above is to replace the MBean Server that is |
|
57 * used locally with a forwarder as described above. Since |
|
58 * {@code MBeanServerForwarder} extends {@code MBeanServer}, you can use |
|
59 * a forwarder anywhere you would have used the original MBean Server. The |
|
60 * code to do this replacement typically looks something like this:</p> |
|
61 * |
|
62 * <pre> |
|
63 * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); // or whatever |
|
64 * MBeanServerForwarder mbsf = EventClientDelegate.newForwarder(); |
|
65 * mbsf.setMBeanServer(mbs); |
|
66 * mbs = mbsf; |
|
67 * // now use mbs just as you did before, but it will have an EventClientDelegate |
|
68 * </pre> |
|
69 * |
|
70 * <li><p>The final way is to create an instance of {@link EventClientDelegate} |
|
71 * and register it in the MBean Server under the standard {@linkplain |
|
72 * #OBJECT_NAME name}:</p> |
|
73 * |
|
74 * <pre> |
|
75 * MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); // or whatever |
|
76 * EventClientDelegate ecd = EventClientDelegate.getEventClientDelegate(mbs); |
|
77 * mbs.registerMBean(ecd, EventClientDelegateMBean.OBJECT_NAME); |
|
78 * <pre> |
|
79 * </ul> |
|
80 * |
|
81 * @since JMX 2.0 |
|
82 */ |
|
83 public interface EventClientDelegateMBean { |
|
84 /** |
|
85 * The string representation of {@link #OBJECT_NAME}. |
|
86 */ |
|
87 // This shouldn't really be necessary but an apparent javadoc bug |
|
88 // meant that the {@value} tags didn't work if this was a |
|
89 // field in EventClientDelegate, even a public field. |
|
90 public static final String OBJECT_NAME_STRING = |
|
91 "javax.management.event:type=EventClientDelegate"; |
|
92 |
|
93 /** |
|
94 * The standard <code>ObjectName</code> used to register the default |
|
95 * <code>EventClientDelegateMBean</code>. The name is |
|
96 * <code>{@value #OBJECT_NAME_STRING}</code>. |
|
97 */ |
|
98 public final static ObjectName OBJECT_NAME = |
|
99 Util.newObjectName(OBJECT_NAME_STRING); |
|
100 |
|
101 /** |
|
102 * A unique listener identifier specified for an EventClient. |
|
103 * Any notification associated with this id is intended for |
|
104 * the EventClient which receives the notification, rather than |
|
105 * a listener added using that EventClient. |
|
106 */ |
|
107 public static final int EVENT_CLIENT_LISTENER_ID = -100; |
|
108 |
|
109 /** |
|
110 * Adds a new client to the <code>EventClientDelegateMBean</code> with |
|
111 * a user-specified |
|
112 * {@link EventForwarder} to forward notifications to the client. The |
|
113 * <code>EventForwarder</code> is created by calling |
|
114 * {@link javax.management.MBeanServer#instantiate(String, Object[], |
|
115 * String[])}. |
|
116 * |
|
117 * @param className The class name used to create an |
|
118 * {@code EventForwarder}. |
|
119 * @param params An array containing the parameters of the constructor to |
|
120 * be invoked. |
|
121 * @param sig An array containing the signature of the constructor to be |
|
122 * invoked |
|
123 * @return A client identifier. |
|
124 * @exception IOException Reserved for a remote call to throw on the client |
|
125 * side. |
|
126 * @exception MBeanException An exception thrown when creating the user |
|
127 * specified <code>EventForwarder</code>. |
|
128 */ |
|
129 public String addClient(String className, Object[] params, String[] sig) |
|
130 throws IOException, MBeanException; |
|
131 |
|
132 /** |
|
133 * Adds a new client to the <code>EventClientDelegateMBean</code> with |
|
134 * a user-specified |
|
135 * {@link EventForwarder} to forward notifications to the client. The |
|
136 * <code>EventForwarder</code> is created by calling |
|
137 * {@link javax.management.MBeanServer#instantiate(String, ObjectName, |
|
138 * Object[], String[])}. A user-specified class loader is used to create |
|
139 * this <code>EventForwarder</code>. |
|
140 * |
|
141 * @param className The class name used to create an |
|
142 * {@code EventForwarder}. |
|
143 * @param classLoader An ObjectName registered as a |
|
144 * <code>ClassLoader</code> MBean. |
|
145 * @param params An array containing the parameters of the constructor to |
|
146 * be invoked. |
|
147 * @param sig An array containing the signature of the constructor to be |
|
148 * invoked |
|
149 * @return A client identifier. |
|
150 * @exception IOException Reserved for a remote call to throw on the client |
|
151 * side. |
|
152 * @exception MBeanException An exception thrown when creating the user |
|
153 * specified <code>EventForwarder</code>. |
|
154 */ |
|
155 public String addClient(String className, |
|
156 ObjectName classLoader, |
|
157 Object[] params, |
|
158 String[] sig) throws IOException, MBeanException; |
|
159 |
|
160 /** |
|
161 * Removes an added client. Calling this method will remove all listeners |
|
162 * added with the client. |
|
163 * |
|
164 * @exception EventClientNotFoundException If the {@code clientId} is |
|
165 * not found. |
|
166 * @exception IOException Reserved for a remote call to throw on the client |
|
167 * side. |
|
168 */ |
|
169 public void removeClient(String clientID) |
|
170 throws EventClientNotFoundException, IOException; |
|
171 |
|
172 /** |
|
173 * Returns the identifiers of listeners added or subscribed to with the |
|
174 * specified client identifier. |
|
175 * <P> If no listener is currently registered with the client, an empty |
|
176 * array is returned. |
|
177 * @param clientID The client identifier with which the listeners are |
|
178 * added or subscribed to. |
|
179 * @return An array of listener identifiers. |
|
180 * @exception EventClientNotFoundException If the {@code clientId} is |
|
181 * not found. |
|
182 * @exception IOException Reserved for a remote call to throw on the client |
|
183 * side. |
|
184 */ |
|
185 public Integer[] getListenerIds(String clientID) |
|
186 throws EventClientNotFoundException, IOException; |
|
187 |
|
188 /** |
|
189 * Adds a listener to receive notifications from an MBean and returns |
|
190 * a non-negative integer as the identifier of the listener. |
|
191 * <P>This method is called by an {@link EventClient} to implement the |
|
192 * method {@link EventClient#addNotificationListener(ObjectName, |
|
193 * NotificationListener, NotificationFilter, Object)}. |
|
194 * |
|
195 * @param name The name of the MBean onto which the listener should be added. |
|
196 * @param filter The filter object. If {@code filter} is null, |
|
197 * no filtering will be performed before handling notifications. |
|
198 * @param clientId The client identifier with which the listener is added. |
|
199 * @return A listener identifier. |
|
200 * @throws EventClientNotFoundException Thrown if the {@code clientId} is |
|
201 * not found. |
|
202 * @throws InstanceNotFoundException Thrown if the MBean is not found. |
|
203 * @throws IOException Reserved for a remote call to throw on the client |
|
204 * side. |
|
205 */ |
|
206 public Integer addListener(String clientId, |
|
207 ObjectName name, |
|
208 NotificationFilter filter) |
|
209 throws InstanceNotFoundException, EventClientNotFoundException, |
|
210 IOException; |
|
211 |
|
212 |
|
213 /** |
|
214 * <p>Subscribes a listener to receive notifications from an MBean or a |
|
215 * set of MBeans represented by an {@code ObjectName} pattern. (It is |
|
216 * not an error if no MBeans match the pattern at the time this method is |
|
217 * called.)</p> |
|
218 * |
|
219 * <p>Returns a non-negative integer as the identifier of the listener.</p> |
|
220 * |
|
221 * <p>This method is called by an {@link EventClient} to execute its |
|
222 * method {@link EventClient#subscribe(ObjectName, NotificationListener, |
|
223 * NotificationFilter, Object)}.</p> |
|
224 * |
|
225 * @param clientId The remote client's identifier. |
|
226 * @param name The name of an MBean or an {@code ObjectName} pattern |
|
227 * representing a set of MBeans to which the listener should listen. |
|
228 * @param filter The filter object. If {@code filter} is null, no |
|
229 * filtering will be performed before notifications are handled. |
|
230 * |
|
231 * @return A listener identifier. |
|
232 * |
|
233 * @throws IllegalArgumentException If the {@code name} or |
|
234 * {@code listener} is null. |
|
235 * @throws EventClientNotFoundException If the client ID is not found. |
|
236 * @throws IOException Reserved for a remote client to throw if |
|
237 * an I/O error occurs. |
|
238 * |
|
239 * @see EventConsumer#subscribe(ObjectName, NotificationListener, |
|
240 * NotificationFilter,Object) |
|
241 * @see #removeListenerOrSubscriber(String, Integer) |
|
242 */ |
|
243 public Integer addSubscriber(String clientId, ObjectName name, |
|
244 NotificationFilter filter) |
|
245 throws EventClientNotFoundException, IOException; |
|
246 |
|
247 /** |
|
248 * Removes a listener, to stop receiving notifications. |
|
249 * <P> This method is called by an {@link EventClient} to execute its |
|
250 * methods {@link EventClient#removeNotificationListener(ObjectName, |
|
251 * NotificationListener, NotificationFilter, Object)}, |
|
252 * {@link EventClient#removeNotificationListener(ObjectName, |
|
253 * NotificationListener)}, and {@link EventClient#unsubscribe}. |
|
254 * |
|
255 * @param clientId The client identifier with which the listener was added. |
|
256 * @param listenerId The listener identifier to be removed. This must be |
|
257 * an identifier returned by a previous {@link #addListener addListener} |
|
258 * or {@link #addSubscriber addSubscriber} call. |
|
259 * |
|
260 * @throws InstanceNotFoundException if the MBean on which the listener |
|
261 * was added no longer exists. |
|
262 * @throws ListenerNotFoundException if there is no listener with the |
|
263 * given {@code listenerId}. |
|
264 * @throws EventClientNotFoundException if the {@code clientId} is |
|
265 * not found. |
|
266 * @throws IOException Reserved for a remote call to throw on the client |
|
267 * side. |
|
268 */ |
|
269 public void removeListenerOrSubscriber(String clientId, Integer listenerId) |
|
270 throws InstanceNotFoundException, ListenerNotFoundException, |
|
271 EventClientNotFoundException, IOException; |
|
272 |
|
273 /** |
|
274 * Called by a client to fetch notifications that are to be sent to its |
|
275 * listeners. |
|
276 * |
|
277 * @param clientId The client's identifier. |
|
278 * @param startSequenceNumber The first sequence number to |
|
279 * consider. |
|
280 * @param timeout The maximum waiting time. |
|
281 * @param maxNotifs The maximum number of notifications to return. |
|
282 * |
|
283 * @throws EventClientNotFoundException Thrown if the {@code clientId} is |
|
284 * not found. |
|
285 * @throws IllegalArgumentException if the client was {@linkplain |
|
286 * #addClient(String, Object[], String[]) added} with an {@link |
|
287 * EventForwarder} that is not a {@link FetchingEventForwarder}. |
|
288 * @throws IOException Reserved for a remote call to throw on the client |
|
289 * side. |
|
290 */ |
|
291 public NotificationResult fetchNotifications(String clientId, |
|
292 long startSequenceNumber, |
|
293 int maxNotifs, |
|
294 long timeout) |
|
295 throws EventClientNotFoundException, IOException; |
|
296 |
|
297 /** |
|
298 * An {@code EventClient} calls this method to keep its {@code clientId} |
|
299 * alive in this MBean. The client will be removed if the lease times out. |
|
300 * |
|
301 * @param clientId The client's identifier. |
|
302 * @param timeout The time in milliseconds by which the lease is to be |
|
303 * extended. The value zero has no special meaning, so it will cause the |
|
304 * lease to time out immediately. |
|
305 * |
|
306 * @return The new lifetime of the lease in milliseconds. This may be |
|
307 * different from the requested time. |
|
308 * |
|
309 * @throws EventClientNotFoundException if the {@code clientId} is |
|
310 * not found. |
|
311 * @throws IOException reserved for a remote call to throw on the client |
|
312 * side. |
|
313 * @throws IllegalArgumentException if {@code clientId} is null or |
|
314 * {@code timeout} is negative. |
|
315 */ |
|
316 public long lease(String clientId, long timeout) |
|
317 throws IOException, EventClientNotFoundException; |
|
318 } |