001 /*
002 * Copyright 2002-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.management;
027
028 // java import
029 import java.io.IOException;
030 import java.util.Set;
031
032 /**
033 * This interface represents a way to talk to an MBean server, whether
034 * local or remote. The {@link MBeanServer} interface, representing a
035 * local MBean server, extends this interface.
036 *
037 *
038 * @since 1.5
039 */
040 public interface MBeanServerConnection {
041 /**
042 * <p>Instantiates and registers an MBean in the MBean server. The
043 * MBean server will use its {@link
044 * javax.management.loading.ClassLoaderRepository Default Loader
045 * Repository} to load the class of the MBean. An object name is
046 * associated to the MBean. If the object name given is null, the
047 * MBean must provide its own name by implementing the {@link
048 * javax.management.MBeanRegistration MBeanRegistration} interface
049 * and returning the name from the {@link
050 * MBeanRegistration#preRegister preRegister} method.</p>
051 *
052 * <p>This method is equivalent to {@link
053 * #createMBean(String,ObjectName,Object[],String[])
054 * createMBean(className, name, (Object[]) null, (String[])
055 * null)}.</p>
056 *
057 * @param className The class name of the MBean to be instantiated.
058 * @param name The object name of the MBean. May be null.
059 *
060 * @return An <CODE>ObjectInstance</CODE>, containing the
061 * <CODE>ObjectName</CODE> and the Java class name of the newly
062 * instantiated MBean. If the contained <code>ObjectName</code>
063 * is <code>n</code>, the contained Java class name is
064 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
065 *
066 * @exception ReflectionException Wraps a
067 * <CODE>java.lang.ClassNotFoundException</CODE> or a
068 * <CODE>java.lang.Exception</CODE> that occurred
069 * when trying to invoke the MBean's constructor.
070 * @exception InstanceAlreadyExistsException The MBean is already
071 * under the control of the MBean server.
072 * @exception MBeanRegistrationException The
073 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
074 * interface) method of the MBean has thrown an exception. The
075 * MBean will not be registered.
076 * @exception MBeanException The constructor of the MBean has
077 * thrown an exception
078 * @exception NotCompliantMBeanException This class is not a JMX
079 * compliant MBean
080 * @exception RuntimeOperationsException Wraps a
081 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
082 * passed in parameter is null, the <CODE>ObjectName</CODE> passed
083 * in parameter contains a pattern or no <CODE>ObjectName</CODE>
084 * is specified for the MBean.
085 * @exception IOException A communication problem occurred when
086 * talking to the MBean server.
087 *
088 */
089 public ObjectInstance createMBean(String className, ObjectName name)
090 throws ReflectionException, InstanceAlreadyExistsException,
091 MBeanRegistrationException, MBeanException,
092 NotCompliantMBeanException, IOException;
093
094 /**
095 * <p>Instantiates and registers an MBean in the MBean server. The
096 * class loader to be used is identified by its object name. An
097 * object name is associated to the MBean. If the object name of
098 * the loader is null, the ClassLoader that loaded the MBean
099 * server will be used. If the MBean's object name given is null,
100 * the MBean must provide its own name by implementing the {@link
101 * javax.management.MBeanRegistration MBeanRegistration} interface
102 * and returning the name from the {@link
103 * MBeanRegistration#preRegister preRegister} method.</p>
104 *
105 * <p>This method is equivalent to {@link
106 * #createMBean(String,ObjectName,ObjectName,Object[],String[])
107 * createMBean(className, name, loaderName, (Object[]) null,
108 * (String[]) null)}.</p>
109 *
110 * @param className The class name of the MBean to be instantiated.
111 * @param name The object name of the MBean. May be null.
112 * @param loaderName The object name of the class loader to be used.
113 *
114 * @return An <CODE>ObjectInstance</CODE>, containing the
115 * <CODE>ObjectName</CODE> and the Java class name of the newly
116 * instantiated MBean. If the contained <code>ObjectName</code>
117 * is <code>n</code>, the contained Java class name is
118 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
119 *
120 * @exception ReflectionException Wraps a
121 * <CODE>java.lang.ClassNotFoundException</CODE> or a
122 * <CODE>java.lang.Exception</CODE> that occurred when trying to
123 * invoke the MBean's constructor.
124 * @exception InstanceAlreadyExistsException The MBean is already
125 * under the control of the MBean server.
126 * @exception MBeanRegistrationException The
127 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
128 * interface) method of the MBean has thrown an exception. The
129 * MBean will not be registered.
130 * @exception MBeanException The constructor of the MBean has
131 * thrown an exception
132 * @exception NotCompliantMBeanException This class is not a JMX
133 * compliant MBean
134 * @exception InstanceNotFoundException The specified class loader
135 * is not registered in the MBean server.
136 * @exception RuntimeOperationsException Wraps a
137 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
138 * passed in parameter is null, the <CODE>ObjectName</CODE> passed
139 * in parameter contains a pattern or no <CODE>ObjectName</CODE>
140 * is specified for the MBean.
141 * @exception IOException A communication problem occurred when
142 * talking to the MBean server.
143 */
144 public ObjectInstance createMBean(String className,
145 ObjectName name, ObjectName loaderName)
146 throws ReflectionException, InstanceAlreadyExistsException,
147 MBeanRegistrationException, MBeanException,
148 NotCompliantMBeanException, InstanceNotFoundException,
149 IOException;
150
151 /**
152 * Instantiates and registers an MBean in the MBean server. The
153 * MBean server will use its {@link
154 * javax.management.loading.ClassLoaderRepository Default Loader
155 * Repository} to load the class of the MBean. An object name is
156 * associated to the MBean. If the object name given is null, the
157 * MBean must provide its own name by implementing the {@link
158 * javax.management.MBeanRegistration MBeanRegistration} interface
159 * and returning the name from the {@link
160 * MBeanRegistration#preRegister preRegister} method.
161 *
162 * @param className The class name of the MBean to be instantiated.
163 * @param name The object name of the MBean. May be null.
164 * @param params An array containing the parameters of the
165 * constructor to be invoked.
166 * @param signature An array containing the signature of the
167 * constructor to be invoked.
168 *
169 * @return An <CODE>ObjectInstance</CODE>, containing the
170 * <CODE>ObjectName</CODE> and the Java class name of the newly
171 * instantiated MBean. If the contained <code>ObjectName</code>
172 * is <code>n</code>, the contained Java class name is
173 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
174 *
175 * @exception ReflectionException Wraps a
176 * <CODE>java.lang.ClassNotFoundException</CODE> or a
177 * <CODE>java.lang.Exception</CODE> that occurred when trying to
178 * invoke the MBean's constructor.
179 * @exception InstanceAlreadyExistsException The MBean is already
180 * under the control of the MBean server.
181 * @exception MBeanRegistrationException The
182 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
183 * interface) method of the MBean has thrown an exception. The
184 * MBean will not be registered.
185 * @exception MBeanException The constructor of the MBean has
186 * thrown an exception
187 * @exception NotCompliantMBeanException This class is not a JMX
188 * compliant MBean
189 * @exception RuntimeOperationsException Wraps a
190 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
191 * passed in parameter is null, the <CODE>ObjectName</CODE> passed
192 * in parameter contains a pattern or no <CODE>ObjectName</CODE>
193 * is specified for the MBean.
194 * @exception IOException A communication problem occurred when
195 * talking to the MBean server.
196 *
197 */
198 public ObjectInstance createMBean(String className,
199 ObjectName name, Object params[], String signature[])
200 throws ReflectionException, InstanceAlreadyExistsException,
201 MBeanRegistrationException, MBeanException,
202 NotCompliantMBeanException, IOException;
203
204 /**
205 * Instantiates and registers an MBean in the MBean server. The
206 * class loader to be used is identified by its object name. An
207 * object name is associated to the MBean. If the object name of
208 * the loader is not specified, the ClassLoader that loaded the
209 * MBean server will be used. If the MBean object name given is
210 * null, the MBean must provide its own name by implementing the
211 * {@link javax.management.MBeanRegistration MBeanRegistration}
212 * interface and returning the name from the {@link
213 * MBeanRegistration#preRegister preRegister} method.
214 *
215 * @param className The class name of the MBean to be instantiated.
216 * @param name The object name of the MBean. May be null.
217 * @param params An array containing the parameters of the
218 * constructor to be invoked.
219 * @param signature An array containing the signature of the
220 * constructor to be invoked.
221 * @param loaderName The object name of the class loader to be used.
222 *
223 * @return An <CODE>ObjectInstance</CODE>, containing the
224 * <CODE>ObjectName</CODE> and the Java class name of the newly
225 * instantiated MBean. If the contained <code>ObjectName</code>
226 * is <code>n</code>, the contained Java class name is
227 * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
228 *
229 * @exception ReflectionException Wraps a
230 * <CODE>java.lang.ClassNotFoundException</CODE> or a
231 * <CODE>java.lang.Exception</CODE> that occurred when trying to
232 * invoke the MBean's constructor.
233 * @exception InstanceAlreadyExistsException The MBean is already
234 * under the control of the MBean server.
235 * @exception MBeanRegistrationException The
236 * <CODE>preRegister</CODE> (<CODE>MBeanRegistration</CODE>
237 * interface) method of the MBean has thrown an exception. The
238 * MBean will not be registered.
239 * @exception MBeanException The constructor of the MBean has
240 * thrown an exception
241 * @exception NotCompliantMBeanException This class is not a JMX
242 * compliant MBean
243 * @exception InstanceNotFoundException The specified class loader
244 * is not registered in the MBean server.
245 * @exception RuntimeOperationsException Wraps a
246 * <CODE>java.lang.IllegalArgumentException</CODE>: The className
247 * passed in parameter is null, the <CODE>ObjectName</CODE> passed
248 * in parameter contains a pattern or no <CODE>ObjectName</CODE>
249 * is specified for the MBean.
250 * @exception IOException A communication problem occurred when
251 * talking to the MBean server.
252 *
253 */
254 public ObjectInstance createMBean(String className,
255 ObjectName name, ObjectName loaderName, Object params[],
256 String signature[]) throws ReflectionException,
257 InstanceAlreadyExistsException, MBeanRegistrationException,
258 MBeanException, NotCompliantMBeanException,
259 InstanceNotFoundException, IOException;
260
261 /**
262 * Unregisters an MBean from the MBean server. The MBean is
263 * identified by its object name. Once the method has been
264 * invoked, the MBean may no longer be accessed by its object
265 * name.
266 *
267 * @param name The object name of the MBean to be unregistered.
268 *
269 * @exception InstanceNotFoundException The MBean specified is not
270 * registered in the MBean server.
271 * @exception MBeanRegistrationException The preDeregister
272 * ((<CODE>MBeanRegistration</CODE> interface) method of the MBean
273 * has thrown an exception.
274 * @exception RuntimeOperationsException Wraps a
275 * <CODE>java.lang.IllegalArgumentException</CODE>: The object
276 * name in parameter is null or the MBean you are when trying to
277 * unregister is the {@link javax.management.MBeanServerDelegate
278 * MBeanServerDelegate} MBean.
279 * @exception IOException A communication problem occurred when
280 * talking to the MBean server.
281 *
282 */
283 public void unregisterMBean(ObjectName name)
284 throws InstanceNotFoundException,
285 MBeanRegistrationException, IOException;
286
287 /**
288 * Gets the <CODE>ObjectInstance</CODE> for a given MBean
289 * registered with the MBean server.
290 *
291 * @param name The object name of the MBean.
292 *
293 * @return The <CODE>ObjectInstance</CODE> associated with the MBean
294 * specified by <VAR>name</VAR>. The contained <code>ObjectName</code>
295 * is <code>name</code> and the contained class name is
296 * <code>{@link #getMBeanInfo getMBeanInfo(name)}.getClassName()</code>.
297 *
298 * @exception InstanceNotFoundException The MBean specified is not
299 * registered in the MBean server.
300 * @exception IOException A communication problem occurred when
301 * talking to the MBean server.
302 */
303 public ObjectInstance getObjectInstance(ObjectName name)
304 throws InstanceNotFoundException, IOException;
305
306 /**
307 * Gets MBeans controlled by the MBean server. This method allows
308 * any of the following to be obtained: All MBeans, a set of
309 * MBeans specified by pattern matching on the
310 * <CODE>ObjectName</CODE> and/or a Query expression, a specific
311 * MBean. When the object name is null or no domain and key
312 * properties are specified, all objects are to be selected (and
313 * filtered if a query is specified). It returns the set of
314 * <CODE>ObjectInstance</CODE> objects (containing the
315 * <CODE>ObjectName</CODE> and the Java Class name) for the
316 * selected MBeans.
317 *
318 * @param name The object name pattern identifying the MBeans to
319 * be retrieved. If null or no domain and key properties are
320 * specified, all the MBeans registered will be retrieved.
321 * @param query The query expression to be applied for selecting
322 * MBeans. If null no query expression will be applied for
323 * selecting MBeans.
324 *
325 * @return A set containing the <CODE>ObjectInstance</CODE>
326 * objects for the selected MBeans. If no MBean satisfies the
327 * query an empty list is returned.
328 *
329 * @exception IOException A communication problem occurred when
330 * talking to the MBean server.
331 */
332 public Set<ObjectInstance> queryMBeans(ObjectName name,
333 QueryExp query) throws IOException;
334
335 /**
336 * Gets the names of MBeans controlled by the MBean server. This
337 * method enables any of the following to be obtained: The names
338 * of all MBeans, the names of a set of MBeans specified by
339 * pattern matching on the <CODE>ObjectName</CODE> and/or a Query
340 * expression, a specific MBean name (equivalent to testing
341 * whether an MBean is registered). When the object name is null
342 * or no domain and key properties are specified, all objects are
343 * selected (and filtered if a query is specified). It returns the
344 * set of ObjectNames for the MBeans selected.
345 *
346 * @param name The object name pattern identifying the MBean names
347 * to be retrieved. If null or no domain and key properties are
348 * specified, the name of all registered MBeans will be retrieved.
349 * @param query The query expression to be applied for selecting
350 * MBeans. If null no query expression will be applied for
351 * selecting MBeans.
352 *
353 * @return A set containing the ObjectNames for the MBeans
354 * selected. If no MBean satisfies the query, an empty list is
355 * returned.
356 *
357 * @exception IOException A communication problem occurred when
358 * talking to the MBean server.
359 */
360 public Set<ObjectName> queryNames(ObjectName name, QueryExp query)
361 throws IOException;
362
363 /**
364 * Checks whether an MBean, identified by its object name, is
365 * already registered with the MBean server.
366 *
367 * @param name The object name of the MBean to be checked.
368 *
369 * @return True if the MBean is already registered in the MBean
370 * server, false otherwise.
371 *
372 * @exception RuntimeOperationsException Wraps a
373 * <CODE>java.lang.IllegalArgumentException</CODE>: The object
374 * name in parameter is null.
375 * @exception IOException A communication problem occurred when
376 * talking to the MBean server.
377 */
378 public boolean isRegistered(ObjectName name) throws IOException;
379
380 /**
381 * Returns the number of MBeans registered in the MBean server.
382 *
383 * @return the number of MBeans registered.
384 *
385 * @exception IOException A communication problem occurred when
386 * talking to the MBean server.
387 */
388 public Integer getMBeanCount() throws IOException;
389
390 /**
391 * Gets the value of a specific attribute of a named MBean. The MBean
392 * is identified by its object name.
393 *
394 * @param name The object name of the MBean from which the
395 * attribute is to be retrieved.
396 * @param attribute A String specifying the name of the attribute
397 * to be retrieved.
398 *
399 * @return The value of the retrieved attribute.
400 *
401 * @exception AttributeNotFoundException The attribute specified
402 * is not accessible in the MBean.
403 * @exception MBeanException Wraps an exception thrown by the
404 * MBean's getter.
405 * @exception InstanceNotFoundException The MBean specified is not
406 * registered in the MBean server.
407 * @exception ReflectionException Wraps a
408 * <CODE>java.lang.Exception</CODE> thrown when trying to invoke
409 * the setter.
410 * @exception RuntimeOperationsException Wraps a
411 * <CODE>java.lang.IllegalArgumentException</CODE>: The object
412 * name in parameter is null or the attribute in parameter is
413 * null.
414 * @exception IOException A communication problem occurred when
415 * talking to the MBean server.
416 *
417 * @see #setAttribute
418 */
419 public Object getAttribute(ObjectName name, String attribute)
420 throws MBeanException, AttributeNotFoundException,
421 InstanceNotFoundException, ReflectionException, IOException;
422
423 /**
424 * Enables the values of several attributes of a named MBean. The MBean
425 * is identified by its object name.
426 *
427 * @param name The object name of the MBean from which the
428 * attributes are retrieved.
429 * @param attributes A list of the attributes to be retrieved.
430 *
431 * @return The list of the retrieved attributes.
432 *
433 * @exception InstanceNotFoundException The MBean specified is not
434 * registered in the MBean server.
435 * @exception ReflectionException An exception occurred when
436 * trying to invoke the getAttributes method of a Dynamic MBean.
437 * @exception RuntimeOperationsException Wrap a
438 * <CODE>java.lang.IllegalArgumentException</CODE>: The object
439 * name in parameter is null or attributes in parameter is null.
440 * @exception IOException A communication problem occurred when
441 * talking to the MBean server.
442 *
443 * @see #setAttributes
444 */
445 public AttributeList getAttributes(ObjectName name,
446 String[] attributes) throws InstanceNotFoundException,
447 ReflectionException, IOException;
448
449 /**
450 * Sets the value of a specific attribute of a named MBean. The MBean
451 * is identified by its object name.
452 *
453 * @param name The name of the MBean within which the attribute is
454 * to be set.
455 * @param attribute The identification of the attribute to be set
456 * and the value it is to be set to.
457 *
458 * @exception InstanceNotFoundException The MBean specified is not
459 * registered in the MBean server.
460 * @exception AttributeNotFoundException The attribute specified
461 * is not accessible in the MBean.
462 * @exception InvalidAttributeValueException The value specified
463 * for the attribute is not valid.
464 * @exception MBeanException Wraps an exception thrown by the
465 * MBean's setter.
466 * @exception ReflectionException Wraps a
467 * <CODE>java.lang.Exception</CODE> thrown when trying to invoke
468 * the setter.
469 * @exception RuntimeOperationsException Wraps a
470 * <CODE>java.lang.IllegalArgumentException</CODE>: The object
471 * name in parameter is null or the attribute in parameter is
472 * null.
473 * @exception IOException A communication problem occurred when
474 * talking to the MBean server.
475 *
476 * @see #getAttribute
477 */
478 public void setAttribute(ObjectName name, Attribute attribute)
479 throws InstanceNotFoundException,
480 AttributeNotFoundException, InvalidAttributeValueException,
481 MBeanException, ReflectionException, IOException;
482
483 /**
484 * Sets the values of several attributes of a named MBean. The MBean is
485 * identified by its object name.
486 *
487 * @param name The object name of the MBean within which the
488 * attributes are to be set.
489 * @param attributes A list of attributes: The identification of
490 * the attributes to be set and the values they are to be set to.
491 *
492 * @return The list of attributes that were set, with their new
493 * values.
494 *
495 * @exception InstanceNotFoundException The MBean specified is not
496 * registered in the MBean server.
497 * @exception ReflectionException An exception occurred when
498 * trying to invoke the getAttributes method of a Dynamic MBean.
499 * @exception RuntimeOperationsException Wraps a
500 * <CODE>java.lang.IllegalArgumentException</CODE>: The object
501 * name in parameter is null or attributes in parameter is null.
502 * @exception IOException A communication problem occurred when
503 * talking to the MBean server.
504 *
505 * @see #getAttributes
506 */
507 public AttributeList setAttributes(ObjectName name,
508 AttributeList attributes) throws InstanceNotFoundException,
509 ReflectionException, IOException;
510
511 /**
512 * Invokes an operation on an MBean.
513 *
514 * @param name The object name of the MBean on which the method is
515 * to be invoked.
516 * @param operationName The name of the operation to be invoked.
517 * @param params An array containing the parameters to be set when
518 * the operation is invoked
519 * @param signature An array containing the signature of the
520 * operation. The class objects will be loaded using the same
521 * class loader as the one used for loading the MBean on which the
522 * operation was invoked.
523 *
524 * @return The object returned by the operation, which represents
525 * the result of invoking the operation on the MBean specified.
526 *
527 * @exception InstanceNotFoundException The MBean specified is not
528 * registered in the MBean server.
529 * @exception MBeanException Wraps an exception thrown by the
530 * MBean's invoked method.
531 * @exception ReflectionException Wraps a
532 * <CODE>java.lang.Exception</CODE> thrown while trying to invoke
533 * the method.
534 * @exception IOException A communication problem occurred when
535 * talking to the MBean server.
536 *
537 */
538 public Object invoke(ObjectName name, String operationName,
539 Object params[], String signature[])
540 throws InstanceNotFoundException, MBeanException,
541 ReflectionException, IOException;
542
543 /**
544 * Returns the default domain used for naming the MBean.
545 * The default domain name is used as the domain part in the ObjectName
546 * of MBeans if no domain is specified by the user.
547 *
548 * @return the default domain.
549 *
550 * @exception IOException A communication problem occurred when
551 * talking to the MBean server.
552 */
553 public String getDefaultDomain() throws IOException;
554
555 /**
556 * <p>Returns the list of domains in which any MBean is currently
557 * registered. A string is in the returned array if and only if
558 * there is at least one MBean registered with an ObjectName whose
559 * {@link ObjectName#getDomain() getDomain()} is equal to that
560 * string. The order of strings within the returned array is
561 * not defined.</p>
562 *
563 * @return the list of domains.
564 *
565 * @exception IOException A communication problem occurred when
566 * talking to the MBean server.
567 *
568 */
569 public String[] getDomains() throws IOException;
570
571 /**
572 * <p>Adds a listener to a registered MBean.</p>
573 *
574 * <P> A notification emitted by an MBean will be forwarded by the
575 * MBeanServer to the listener. If the source of the notification
576 * is a reference to an MBean object, the MBean server will replace it
577 * by that MBean's ObjectName. Otherwise the source is unchanged.
578 *
579 * @param name The name of the MBean on which the listener should
580 * be added.
581 * @param listener The listener object which will handle the
582 * notifications emitted by the registered MBean.
583 * @param filter The filter object. If filter is null, no
584 * filtering will be performed before handling notifications.
585 * @param handback The context to be sent to the listener when a
586 * notification is emitted.
587 *
588 * @exception InstanceNotFoundException The MBean name provided
589 * does not match any of the registered MBeans.
590 * @exception IOException A communication problem occurred when
591 * talking to the MBean server.
592 *
593 * @see #removeNotificationListener(ObjectName, NotificationListener)
594 * @see #removeNotificationListener(ObjectName, NotificationListener,
595 * NotificationFilter, Object)
596 */
597 public void addNotificationListener(ObjectName name,
598 NotificationListener listener, NotificationFilter filter,
599 Object handback) throws InstanceNotFoundException,
600 IOException;
601
602 /**
603 * <p>Adds a listener to a registered MBean.</p>
604 *
605 * <p>A notification emitted by an MBean will be forwarded by the
606 * MBeanServer to the listener. If the source of the notification
607 * is a reference to an MBean object, the MBean server will
608 * replace it by that MBean's ObjectName. Otherwise the source is
609 * unchanged.</p>
610 *
611 * <p>The listener object that receives notifications is the one
612 * that is registered with the given name at the time this method
613 * is called. Even if it is subsequently unregistered, it will
614 * continue to receive notifications.</p>
615 *
616 * @param name The name of the MBean on which the listener should
617 * be added.
618 * @param listener The object name of the listener which will
619 * handle the notifications emitted by the registered MBean.
620 * @param filter The filter object. If filter is null, no
621 * filtering will be performed before handling notifications.
622 * @param handback The context to be sent to the listener when a
623 * notification is emitted.
624 *
625 * @exception InstanceNotFoundException The MBean name of the
626 * notification listener or of the notification broadcaster does
627 * not match any of the registered MBeans.
628 * @exception RuntimeOperationsException Wraps an {@link
629 * IllegalArgumentException}. The MBean named by
630 * <code>listener</code> exists but does not implement the {@link
631 * NotificationListener} interface.
632 * @exception IOException A communication problem occurred when
633 * talking to the MBean server.
634 *
635 * @see #removeNotificationListener(ObjectName, ObjectName)
636 * @see #removeNotificationListener(ObjectName, ObjectName,
637 * NotificationFilter, Object)
638 */
639 public void addNotificationListener(ObjectName name,
640 ObjectName listener, NotificationFilter filter,
641 Object handback) throws InstanceNotFoundException,
642 IOException;
643
644 /**
645 * Removes a listener from a registered MBean.
646 *
647 * <P> If the listener is registered more than once, perhaps with
648 * different filters or callbacks, this method will remove all
649 * those registrations.
650 *
651 * @param name The name of the MBean on which the listener should
652 * be removed.
653 * @param listener The object name of the listener to be removed.
654 *
655 * @exception InstanceNotFoundException The MBean name provided
656 * does not match any of the registered MBeans.
657 * @exception ListenerNotFoundException The listener is not
658 * registered in the MBean.
659 * @exception IOException A communication problem occurred when
660 * talking to the MBean server.
661 *
662 * @see #addNotificationListener(ObjectName, ObjectName,
663 * NotificationFilter, Object)
664 */
665 public void removeNotificationListener(ObjectName name,
666 ObjectName listener) throws InstanceNotFoundException,
667 ListenerNotFoundException, IOException;
668
669 /**
670 * <p>Removes a listener from a registered MBean.</p>
671 *
672 * <p>The MBean must have a listener that exactly matches the
673 * given <code>listener</code>, <code>filter</code>, and
674 * <code>handback</code> parameters. If there is more than one
675 * such listener, only one is removed.</p>
676 *
677 * <p>The <code>filter</code> and <code>handback</code> parameters
678 * may be null if and only if they are null in a listener to be
679 * removed.</p>
680 *
681 * @param name The name of the MBean on which the listener should
682 * be removed.
683 * @param listener The object name of the listener to be removed.
684 * @param filter The filter that was specified when the listener
685 * was added.
686 * @param handback The handback that was specified when the
687 * listener was added.
688 *
689 * @exception InstanceNotFoundException The MBean name provided
690 * does not match any of the registered MBeans.
691 * @exception ListenerNotFoundException The listener is not
692 * registered in the MBean, or it is not registered with the given
693 * filter and handback.
694 * @exception IOException A communication problem occurred when
695 * talking to the MBean server.
696 *
697 * @see #addNotificationListener(ObjectName, ObjectName,
698 * NotificationFilter, Object)
699 *
700 */
701 public void removeNotificationListener(ObjectName name,
702 ObjectName listener, NotificationFilter filter,
703 Object handback) throws InstanceNotFoundException,
704 ListenerNotFoundException, IOException;
705
706 /**
707 * <p>Removes a listener from a registered MBean.</p>
708 *
709 * <P> If the listener is registered more than once, perhaps with
710 * different filters or callbacks, this method will remove all
711 * those registrations.
712 *
713 * @param name The name of the MBean on which the listener should
714 * be removed.
715 * @param listener The listener to be removed.
716 *
717 * @exception InstanceNotFoundException The MBean name provided
718 * does not match any of the registered MBeans.
719 * @exception ListenerNotFoundException The listener is not
720 * registered in the MBean.
721 * @exception IOException A communication problem occurred when
722 * talking to the MBean server.
723 *
724 * @see #addNotificationListener(ObjectName, NotificationListener,
725 * NotificationFilter, Object)
726 */
727 public void removeNotificationListener(ObjectName name,
728 NotificationListener listener)
729 throws InstanceNotFoundException,
730 ListenerNotFoundException, IOException;
731
732 /**
733 * <p>Removes a listener from a registered MBean.</p>
734 *
735 * <p>The MBean must have a listener that exactly matches the
736 * given <code>listener</code>, <code>filter</code>, and
737 * <code>handback</code> parameters. If there is more than one
738 * such listener, only one is removed.</p>
739 *
740 * <p>The <code>filter</code> and <code>handback</code> parameters
741 * may be null if and only if they are null in a listener to be
742 * removed.</p>
743 *
744 * @param name The name of the MBean on which the listener should
745 * be removed.
746 * @param listener The listener to be removed.
747 * @param filter The filter that was specified when the listener
748 * was added.
749 * @param handback The handback that was specified when the
750 * listener was added.
751 *
752 * @exception InstanceNotFoundException The MBean name provided
753 * does not match any of the registered MBeans.
754 * @exception ListenerNotFoundException The listener is not
755 * registered in the MBean, or it is not registered with the given
756 * filter and handback.
757 * @exception IOException A communication problem occurred when
758 * talking to the MBean server.
759 *
760 * @see #addNotificationListener(ObjectName, NotificationListener,
761 * NotificationFilter, Object)
762 *
763 */
764 public void removeNotificationListener(ObjectName name,
765 NotificationListener listener, NotificationFilter filter,
766 Object handback) throws InstanceNotFoundException,
767 ListenerNotFoundException, IOException;
768
769 /**
770 * This method discovers the attributes and operations that an
771 * MBean exposes for management.
772 *
773 * @param name The name of the MBean to analyze
774 *
775 * @return An instance of <CODE>MBeanInfo</CODE> allowing the
776 * retrieval of all attributes and operations of this MBean.
777 *
778 * @exception IntrospectionException An exception occurred during
779 * introspection.
780 * @exception InstanceNotFoundException The MBean specified was
781 * not found.
782 * @exception ReflectionException An exception occurred when
783 * trying to invoke the getMBeanInfo of a Dynamic MBean.
784 * @exception IOException A communication problem occurred when
785 * talking to the MBean server.
786 */
787 public MBeanInfo getMBeanInfo(ObjectName name)
788 throws InstanceNotFoundException, IntrospectionException,
789 ReflectionException, IOException;
790
791 /**
792 * <p>Returns true if the MBean specified is an instance of the
793 * specified class, false otherwise.</p>
794 *
795 * <p>If <code>name</code> does not name an MBean, this method
796 * throws {@link InstanceNotFoundException}.</p>
797 *
798 * <p>Otherwise, let<br>
799 * X be the MBean named by <code>name</code>,<br>
800 * L be the ClassLoader of X,<br>
801 * N be the class name in X's {@link MBeanInfo}.</p>
802 *
803 * <p>If N equals <code>className</code>, the result is true.</p>
804 *
805 * <p>Otherwise, if L successfully loads <code>className</code>
806 * and X is an instance of this class, the result is true.
807 *
808 * <p>Otherwise, if L successfully loads both N and
809 * <code>className</code>, and the second class is assignable from
810 * the first, the result is true.</p>
811 *
812 * <p>Otherwise, the result is false.</p>
813 *
814 * @param name The <CODE>ObjectName</CODE> of the MBean.
815 * @param className The name of the class.
816 *
817 * @return true if the MBean specified is an instance of the
818 * specified class according to the rules above, false otherwise.
819 *
820 * @exception InstanceNotFoundException The MBean specified is not
821 * registered in the MBean server.
822 * @exception IOException A communication problem occurred when
823 * talking to the MBean server.
824 *
825 * @see Class#isInstance
826 */
827 public boolean isInstanceOf(ObjectName name, String className)
828 throws InstanceNotFoundException, IOException;
829 }
|