001    /* MBeanServerConnection.java -- Represents a connection to a management server.
002       Copyright (C) 2006 Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package javax.management;
039    
040    import java.io.IOException;
041    
042    import java.util.Set;
043    
044    /**
045     * This interface represents a communication mechanism which may
046     * be used to access an MBean server, whether this be local or
047     * remote.  The {@link MBeanServer} interface extends this with
048     * additional methods that apply only to local servers.
049     *
050     * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
051     * @since 1.5
052     */
053    public interface MBeanServerConnection
054    {
055    
056      /**
057       * Registers the supplied listener with the specified management
058       * bean.  Notifications emitted by the management bean are forwarded
059       * to the listener via the server, which will convert any MBean
060       * references in the source to portable {@link ObjectName}
061       * instances.  The notification is otherwise unchanged.
062       *
063       * @param name the name of the management bean with which the listener
064       *             should be registered.
065       * @param listener the listener which will handle notifications from
066       *                 the bean.
067       * @param filter the filter to apply to incoming notifications, or
068       *               <code>null</code> if no filtering should be applied.
069       * @param passback an object to be passed to the listener when a
070       *                 notification is emitted.
071       * @throws InstanceNotFoundException if the name of the management bean
072       *                                   could not be resolved.
073       * @throws IOException if an I/O error occurred in communicating with
074       *                     the bean server.
075       * @see #removeNotificationListener(ObjectName, NotificationListener)
076       * @see #removeNotificationListener(ObjectName, NotificationListener,
077       *                                  NotificationFilter, Object)
078       * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
079       *                                                      NotificationFilter,
080       *                                                      Object)
081       */
082      void addNotificationListener(ObjectName name, NotificationListener listener,
083                                   NotificationFilter filter, Object passback)
084        throws InstanceNotFoundException, IOException;
085    
086      /**
087       * <p>
088       * Registers the supplied listener with the specified management
089       * bean.  Notifications emitted by the management bean are forwarded
090       * to the listener via the server, which will convert any MBean
091       * references in the source to portable {@link ObjectName}
092       * instances.  The notification is otherwise unchanged.  
093       * </p>
094       * <p>
095       * The listener that receives notifications will be the one that is
096       * registered with the given name at the time this method is called.
097       * Even if it later unregisters and ceases to use that name, it will
098       * still receive notifications.
099       * </p>
100       *
101       * @param name the name of the management bean with which the listener
102       *             should be registered.
103       * @param listener the name of the listener which will handle
104       *                 notifications from the bean.
105       * @param filter the filter to apply to incoming notifications, or
106       *               <code>null</code> if no filtering should be applied.
107       * @param passback an object to be passed to the listener when a
108       *                 notification is emitted.
109       * @throws InstanceNotFoundException if the name of the management bean
110       *                                   could not be resolved.
111       * @throws RuntimeOperationsException if the bean associated with the given
112       *                                    object name is not a
113       *                                    {@link NotificationListener}.  This
114       *                                    exception wraps an
115       *                                    {@link IllegalArgumentException}.
116       * @throws IOException if an I/O error occurred in communicating with
117       *                     the bean server.
118       * @see #removeNotificationListener(ObjectName, NotificationListener)
119       * @see #removeNotificationListener(ObjectName, NotificationListener,
120       *                                  NotificationFilter, Object)
121       * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
122       *                                                      NotificationFilter,
123       *                                                      Object)
124       */
125      void addNotificationListener(ObjectName name, ObjectName listener,
126                                   NotificationFilter filter, Object passback)
127        throws InstanceNotFoundException, RuntimeOperationsException, IOException;
128    
129      /**
130       * <p>
131       * Instantiates a new instance of the specified management bean
132       * using the default constructor and registers it with the server
133       * under the supplied name.  The class is loaded using the
134       * {@link javax.management.loading.ClassLoaderRepository default
135       * loader repository} of the server. 
136       * </p>
137       * <p>
138       * If the name supplied is <code>null</code>, then the bean is
139       * expected to implement the {@link MBeanRegistration} interface.
140       * The {@link MBeanRegistration#preRegister preRegister} method
141       * of this interface will be used to obtain the name in this case.
142       * </p>
143       * <p>
144       * This method is equivalent to calling {@link 
145       * #createMBean(String, ObjectName, Object[], String[])
146       * <code>createMBean(className, name, (Object[]) null,
147       * (String[]) null)</code>} with <code>null</code> parameters
148       * and signature.
149       * </p>
150       *
151       * @param className the class of the management bean, of which
152       *                  an instance should be created.
153       * @param name the name to register the new bean with.
154       * @return an {@link ObjectInstance} containing the {@link ObjectName}
155       *         and Java class name of the created instance.
156       * @throws ReflectionException if an exception occurs in creating
157       *                             an instance of the bean.
158       * @throws InstanceAlreadyExistsException if a matching instance
159       *                                        already exists.
160       * @throws MBeanRegistrationException if an exception occurs in
161       *                                    calling the preRegister
162       *                                    method.
163       * @throws MBeanException if the bean's constructor throws an exception.
164       * @throws NotCompliantMBeanException if the created bean is not
165       *                                    compliant with the JMX specification.
166       * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
167       *                                    is thrown by the server due to a
168       *                                    <code>null</code> class name or object
169       *                                    name or if the object name is a pattern.
170       * @throws IOException if an I/O error occurred in communicating with
171       *                     the bean server.
172       * @see #createMBean(String, ObjectName, Object[], String[])
173       */
174      ObjectInstance createMBean(String className, ObjectName name)
175        throws ReflectionException, InstanceAlreadyExistsException,
176               MBeanRegistrationException, MBeanException,
177               NotCompliantMBeanException, IOException;
178    
179      /**
180       * <p>
181       * Instantiates a new instance of the specified management bean
182       * using the given constructor and registers it with the server
183       * under the supplied name.  The class is loaded using the
184       * {@link javax.management.loading.ClassLoaderRepository default
185       * loader repository} of the server. 
186       * </p>
187       * <p>
188       * If the name supplied is <code>null</code>, then the bean is
189       * expected to implement the {@link MBeanRegistration} interface.
190       * The {@link MBeanRegistration#preRegister preRegister} method
191       * of this interface will be used to obtain the name in this case.
192       * </p>
193       * 
194       * @param className the class of the management bean, of which
195       *                  an instance should be created.
196       * @param name the name to register the new bean with.
197       * @param params the parameters for the bean's constructor.
198       * @param sig the signature of the constructor to use.
199       * @return an {@link ObjectInstance} containing the {@link ObjectName}
200       *         and Java class name of the created instance.
201       * @throws ReflectionException if an exception occurs in creating
202       *                             an instance of the bean.
203       * @throws InstanceAlreadyExistsException if a matching instance
204       *                                        already exists.
205       * @throws MBeanRegistrationException if an exception occurs in
206       *                                    calling the preRegister
207       *                                    method.
208       * @throws MBeanException if the bean's constructor throws an exception.
209       * @throws NotCompliantMBeanException if the created bean is not
210       *                                    compliant with the JMX specification.
211       * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
212       *                                    is thrown by the server due to a
213       *                                    <code>null</code> class name or object
214       *                                    name or if the object name is a pattern.
215       * @throws IOException if an I/O error occurred in communicating with
216       *                     the bean server.
217       */
218      ObjectInstance createMBean(String className, ObjectName name,
219                                 Object[] params, String[] sig)
220        throws ReflectionException, InstanceAlreadyExistsException,
221               MBeanRegistrationException, MBeanException,
222               NotCompliantMBeanException, IOException;
223    
224      /**
225       * <p>
226       * Instantiates a new instance of the specified management bean
227       * using the default constructor and registers it with the server
228       * under the supplied name.  The class is loaded using the
229       * given class loader.  If this argument is <code>null</code>,
230       * then the same class loader as was used to load the server
231       * is used.
232       * </p>
233       * <p>
234       * If the name supplied is <code>null</code>, then the bean is
235       * expected to implement the {@link MBeanRegistration} interface.
236       * The {@link MBeanRegistration#preRegister preRegister} method
237       * of this interface will be used to obtain the name in this case.
238       * </p>
239       * <p>
240       * This method is equivalent to calling {@link 
241       * #createMBean(String, ObjectName, ObjectName, Object[], String)
242       * <code>createMBean(className, name, loaderName, (Object[]) null,
243       * (String) null)</code>} with <code>null</code> parameters
244       * and signature.
245       * </p>
246       *
247       * @param className the class of the management bean, of which
248       *                  an instance should be created.
249       * @param name the name to register the new bean with.
250       * @param loaderName the name of the class loader.
251       * @return an {@link ObjectInstance} containing the {@link ObjectName}
252       *         and Java class name of the created instance.
253       * @throws ReflectionException if an exception occurs in creating
254       *                             an instance of the bean.
255       * @throws InstanceAlreadyExistsException if a matching instance
256       *                                        already exists.
257       * @throws MBeanRegistrationException if an exception occurs in
258       *                                    calling the preRegister
259       *                                    method.
260       * @throws MBeanException if the bean's constructor throws an exception.
261       * @throws NotCompliantMBeanException if the created bean is not
262       *                                    compliant with the JMX specification.
263       * @throws InstanceNotFoundException if the specified class loader is not
264       *                                   registered with the server.
265       * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
266       *                                    is thrown by the server due to a
267       *                                    <code>null</code> class name or object
268       *                                    name or if the object name is a pattern.
269       * @throws IOException if an I/O error occurred in communicating with
270       *                     the bean server.
271       * @see #createMBean(String, ObjectName, ObjectName, Object[], String[])
272       */
273      ObjectInstance createMBean(String className, ObjectName name, 
274                                 ObjectName loaderName)
275        throws ReflectionException, InstanceAlreadyExistsException,
276               MBeanRegistrationException, MBeanException,
277               NotCompliantMBeanException, InstanceNotFoundException,
278               IOException;
279    
280      /**
281       * <p>
282       * Instantiates a new instance of the specified management bean
283       * using the given constructor and registers it with the server
284       * under the supplied name.  The class is loaded using the
285       * given class loader.  If this argument is <code>null</code>,
286       * then the same class loader as was used to load the server
287       * is used. 
288       * </p>
289       * <p>
290       * If the name supplied is <code>null</code>, then the bean is
291       * expected to implement the {@link MBeanRegistration} interface.
292       * The {@link MBeanRegistration#preRegister preRegister} method
293       * of this interface will be used to obtain the name in this case.
294       * </p>
295       * 
296       * @param className the class of the management bean, of which
297       *                  an instance should be created.
298       * @param name the name to register the new bean with.
299       * @param loaderName the name of the class loader.
300       * @param params the parameters for the bean's constructor.
301       * @param sig the signature of the constructor to use.
302       * @return an {@link ObjectInstance} containing the {@link ObjectName}
303       *         and Java class name of the created instance.
304       * @throws ReflectionException if an exception occurs in creating
305       *                             an instance of the bean.
306       * @throws InstanceAlreadyExistsException if a matching instance
307       *                                        already exists.
308       * @throws MBeanRegistrationException if an exception occurs in
309       *                                    calling the preRegister
310       *                                    method.
311       * @throws MBeanException if the bean's constructor throws an exception.
312       * @throws NotCompliantMBeanException if the created bean is not
313       *                                    compliant with the JMX specification.
314       * @throws InstanceNotFoundException if the specified class loader is not
315       *                                   registered with the server.
316       * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
317       *                                    is thrown by the server due to a
318       *                                    <code>null</code> class name or object
319       *                                    name or if the object name is a pattern.
320       * @throws IOException if an I/O error occurred in communicating with
321       *                     the bean server.
322       */
323      ObjectInstance createMBean(String className, ObjectName name,
324                                 ObjectName loaderName, Object[] params,
325                                 String[] sig)
326        throws ReflectionException, InstanceAlreadyExistsException,
327               MBeanRegistrationException, MBeanException,
328               NotCompliantMBeanException, InstanceNotFoundException,
329               IOException;
330    
331      /**
332       * Returns the value of the supplied attribute from the specified
333       * management bean.
334       *
335       * @param bean the bean to retrieve the value from.
336       * @param name the name of the attribute to retrieve.
337       * @return the value of the attribute.
338       * @throws AttributeNotFoundException if the attribute could not be
339       *                                    accessed from the bean.
340       * @throws MBeanException if the management bean's accessor throws
341       *                        an exception.
342       * @throws InstanceNotFoundException if the bean can not be found.
343       * @throws ReflectionException if an exception was thrown in trying
344       *                             to invoke the bean's accessor.
345       * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
346       *                                    is thrown by the server due to a
347       *                                    <code>null</code> bean or attribute
348       *                                    name.
349       * @throws IOException if an I/O error occurred in communicating with
350       *                     the bean server.
351       * @see DynamicMBean#getAttribute(String)
352       */
353      Object getAttribute(ObjectName bean, String name)
354        throws MBeanException, AttributeNotFoundException,
355               InstanceNotFoundException, ReflectionException,
356               IOException;
357    
358      /**
359       * Returns the values of the named attributes from the specified
360       * management bean.
361       *
362       * @param bean the bean to retrieve the value from.
363       * @param names the names of the attributes to retrieve.
364       * @return the values of the attributes.
365       * @throws InstanceNotFoundException if the bean can not be found.
366       * @throws ReflectionException if an exception was thrown in trying
367       *                             to invoke the bean's accessor.
368       * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
369       *                                    is thrown by the server due to a
370       *                                    <code>null</code> bean or attribute
371       *                                    name.
372       * @throws IOException if an I/O error occurred in communicating with
373       *                     the bean server.
374       * @see DynamicMBean#getAttributes(String[])
375       */
376      AttributeList getAttributes(ObjectName bean, String[] names)
377        throws InstanceNotFoundException, ReflectionException,
378               IOException;
379    
380      /**
381       * Returns the default domain this server applies to beans that have
382       * no specified domain.
383       *
384       * @return the default domain.
385       * @throws IOException if an I/O error occurred in communicating with
386       *                     the bean server.
387       */
388      String getDefaultDomain()
389        throws IOException;
390    
391      /**
392       * Returns an array containing all the domains used by beans registered
393       * with this server.  The ordering of the array is undefined.
394       *
395       * @return the list of domains.
396       * @throws IOException if an I/O error occurred in communicating with
397       *                     the bean server.
398       * @see ObjectName#getDomain()
399       */
400      String[] getDomains()
401        throws IOException;
402    
403      /**
404       * Returns the number of management beans registered with this server.
405       *
406       * @return the number of registered beans.
407       * @throws IOException if an I/O error occurred in communicating with
408       *                     the bean server.
409       */
410      Integer getMBeanCount()
411        throws IOException;
412    
413      /**
414       * Returns information on the given management bean.
415       *
416       * @param name the name of the management bean.
417       * @return an instance of {@link MBeanInfo} for the bean.
418       * @throws IntrospectionException if an exception occurs in examining
419       *                                the bean.
420       * @throws InstanceNotFoundException if the bean can not be found.
421       * @throws ReflectionException if an exception occurs when trying
422       *                             to invoke {@link DynamicMBean#getMBeanInfo()}
423       *                             on the bean.
424       * @throws IOException if an I/O error occurred in communicating with
425       *                     the bean server.
426       * @see DynamicMBean#getMBeanInfo()
427       */
428      MBeanInfo getMBeanInfo(ObjectName name)
429        throws InstanceNotFoundException, IntrospectionException,
430               ReflectionException, IOException;
431    
432      /**
433       * Returns the {@link ObjectInstance} created for the specified
434       * management bean on registration.
435       *
436       * @param name the name of the bean.
437       * @return the corresponding {@link ObjectInstance} instance.
438       * @throws InstanceNotFoundException if the bean can not be found.
439       * @throws IOException if an I/O error occurred in communicating with
440       *                     the bean server.
441       * @see #createMBean(String, ObjectName)
442       */
443      ObjectInstance getObjectInstance(ObjectName name)
444        throws InstanceNotFoundException, IOException;
445    
446      /**
447       * Invokes the supplied operation on the specified management
448       * bean.  The class objects specified in the signature are loaded
449       * using the same class loader as was used for the management bean.
450       *
451       * @param bean the management bean whose operation should be invoked.
452       * @param name the name of the operation to invoke.
453       * @param params the parameters of the operation.
454       * @param sig the signature of the operation.
455       * @return the return value of the method.
456       * @throws InstanceNotFoundException if the bean can not be found.
457       * @throws MBeanException if the method invoked throws an exception.
458       * @throws ReflectionException if an exception is thrown in invoking the
459       *                             method.
460       * @throws IOException if an I/O error occurred in communicating with
461       *                     the bean server.
462       * @see DynamicMBean#invoke(String, Object[], String[])
463       */
464      Object invoke(ObjectName bean, String name, Object[] params, String[] sig)
465        throws InstanceNotFoundException, MBeanException,
466               ReflectionException, IOException;
467    
468      /**
469       * <p>
470       * Returns true if the specified management bean is an instance
471       * of the supplied class.
472       * </p>
473       * <p>
474       * A bean, B, is an instance of a class, C, if either of the following
475       * conditions holds:
476       * </p>
477       * <ul>
478       * <li>The class name in B's {@link MBeanInfo} is equal to the supplied
479       * name.</li>
480       * <li>Both the class of B and C were loaded by the same class loader,
481       * and B is assignable to C.</li>
482       * </ul>
483       * 
484       * @param name the name of the management bean.
485       * @param className the name of the class to test if <code>name</code> is
486       *                  an instance of.
487       * @return true if either B is directly an instance of the named class,
488       *         or B is assignable to the class, given that both it and B's
489       *         current class were loaded using the same class loader.
490       * @throws InstanceNotFoundException if the bean can not be found.
491       * @throws IOException if an I/O error occurred in communicating with
492       *                     the bean server.
493       */
494      boolean isInstanceOf(ObjectName name, String className)
495        throws InstanceNotFoundException, IOException;
496    
497      /**
498       * Returns true if the specified management bean is registered with
499       * the server.
500       *
501       * @param name the name of the management bean.
502       * @return true if the bean is registered.
503       * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
504       *                                    is thrown by the server due to a
505       *                                    <code>null</code> bean name.
506       * @throws IOException if an I/O error occurred in communicating with
507       *                     the bean server.
508       */
509      boolean isRegistered(ObjectName name)
510        throws IOException;
511    
512      /**
513       * <p>
514       * Returns a set of {@link ObjectInstance}s matching the specified
515       * criteria.  The full set of beans registered with the server
516       * are passed through two filters:
517       * </p>
518       * <ol>
519       * <li>Pattern matching is performed using the supplied
520       * {@link ObjectName}.</li>
521       * <li>The supplied query expression is applied.</li>
522       * </ol>
523       * <p>
524       * If both the object name and the query expression are <code>null</code>,
525       * or the object name has no domain and no key properties,
526       * no filtering will be performed and all beans are returned. 
527       * </p>
528       *
529       * @param name an {@link ObjectName} to use as a filter.
530       * @param query a query expression to apply to each of the beans that match
531       *              the given object name.
532       * @return a set of {@link ObjectInstance}s matching the filtered beans.
533       * @throws IOException if an I/O error occurred in communicating with
534       *                     the bean server.
535       */
536      Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query)
537        throws IOException;
538      
539      /**
540       * <p>
541       * Returns a set of {@link ObjectName}s matching the specified
542       * criteria.  The full set of beans registered with the server
543       * are passed through two filters:
544       * </p>
545       * <ol>
546       * <li>Pattern matching is performed using the supplied
547       * {@link ObjectName}.</li>
548       * <li>The supplied query expression is applied.</li>
549       * </ol>
550       * <p>
551       * If both the object name and the query expression are <code>null</code>,
552       * or the object name has no domain and no key properties,
553       * no filtering will be performed and all beans are returned. 
554       * </p>
555       *
556       * @param name an {@link ObjectName} to use as a filter.
557       * @param query a query expression to apply to each of the beans that match
558       *              the given object name.
559       * @return a set of {@link ObjectName}s matching the filtered beans.
560       * @throws IOException if an I/O error occurred in communicating with
561       *                     the bean server.
562       */
563      Set<ObjectName> queryNames(ObjectName name, QueryExp query)
564        throws IOException;
565    
566      /**
567       * Removes the specified listener from the list of recipients
568       * of notifications from the supplied bean.  This includes all
569       * combinations of filters and passback objects registered for
570       * this listener.  For more specific removal of listeners, see
571       * {@link #removeNotificationListener(ObjectName,
572       * NotificationListener,NotificationFilter,Object)}
573       *
574       * @param name the name of the management bean from which the
575       *             listener should be removed.
576       * @param listener the listener to remove.
577       * @throws InstanceNotFoundException if the bean can not be found.
578       * @throws ListenerNotFoundException if the specified listener
579       *                                   is not registered with the bean.
580       * @throws IOException if an I/O error occurred in communicating with
581       *                     the bean server.
582       * @see #addNotificationListener(NotificationListener, NotificationFilter,
583       *                               java.lang.Object)
584       * @see NotificationBroadcaster#removeNotificationListener(NotificationListener)
585       */
586      void removeNotificationListener(ObjectName name,
587                                      NotificationListener listener)
588        throws InstanceNotFoundException, ListenerNotFoundException,
589               IOException;
590    
591      /**
592       * Removes the specified listener from the list of recipients
593       * of notifications from the supplied bean.  Only the first instance with
594       * the supplied filter and passback object is removed.
595       * <code>null</code> is used as a valid value for these parameters,
596       * rather than as a way to remove all registration instances for
597       * the specified listener; for this behaviour instead, see
598       * {@link #removeNotificationListener(ObjectName, NotificationListener)}.
599       *
600       * @param name the name of the management bean from which the
601       *             listener should be removed.
602       * @param listener the listener to remove.
603       * @param filter the filter of the listener to remove.
604       * @param passback the passback object of the listener to remove.
605       * @throws InstanceNotFoundException if the bean can not be found.
606       * @throws ListenerNotFoundException if the specified listener
607       *                                   is not registered with the bean.
608       * @throws IOException if an I/O error occurred in communicating with
609       *                     the bean server.
610       * @see #addNotificationListener(ObjectName, NotificationListener,
611       *                               NotificationFilter, Object)
612       * @see NotificationEmitter#removeNotificationListener(NotificationListener,
613       *                                                     NotificationFilter,
614       *                                                     Object)
615       */
616      void removeNotificationListener(ObjectName name,
617                                      NotificationListener listener,
618                                      NotificationFilter filter,
619                                      Object passback)
620        throws InstanceNotFoundException, ListenerNotFoundException,
621               IOException;
622    
623      /**
624       * Removes the specified listener from the list of recipients
625       * of notifications from the supplied bean.  This includes all
626       * combinations of filters and passback objects registered for
627       * this listener.  For more specific removal of listeners, see
628       * {@link #removeNotificationListener(ObjectName,
629       * ObjectName,NotificationFilter,Object)}
630       *
631       * @param name the name of the management bean from which the
632       *             listener should be removed.
633       * @param listener the name of the listener to remove.
634       * @throws InstanceNotFoundException if a name doesn't match a registered
635       *                                   bean.
636       * @throws ListenerNotFoundException if the specified listener
637       *                                   is not registered with the bean.
638       * @throws IOException if an I/O error occurred in communicating with
639       *                     the bean server.
640       * @see #addNotificationListener(NotificationListener, NotificationFilter,
641       *                               java.lang.Object)
642       * @see NotificationBroadcaster#removeNotificationListener(NotificationListener)
643       */
644      void removeNotificationListener(ObjectName name, ObjectName listener)
645        throws InstanceNotFoundException, ListenerNotFoundException,
646               IOException;
647    
648      /**
649       * Removes the specified listener from the list of recipients
650       * of notifications from the supplied bean.  Only the first instance with
651       * the supplied filter and passback object is removed.
652       * <code>null</code> is used as a valid value for these parameters,
653       * rather than as a way to remove all registration instances for
654       * the specified listener; for this behaviour instead, see
655       * {@link #removeNotificationListener(ObjectName, ObjectName)}.
656       *
657       * @param name the name of the management bean from which the
658       *             listener should be removed.
659       * @param listener the name of the listener to remove.
660       * @param filter the filter of the listener to remove.
661       * @param passback the passback object of the listener to remove.
662       * @throws InstanceNotFoundException if a name doesn't match a registered
663       *                                   bean.
664       * @throws ListenerNotFoundException if the specified listener
665       *                                   is not registered with the bean.
666       * @throws IOException if an I/O error occurred in communicating with
667       *                     the bean server.
668       * @see #addNotificationListener(ObjectName, NotificationListener,
669       *                               NotificationFilter, Object)
670       * @see NotificationEmitter#removeNotificationListener(NotificationListener,
671       *                                                     NotificationFilter,
672       *                                                     Object)
673       */
674      void removeNotificationListener(ObjectName name,
675                                      ObjectName listener,
676                                      NotificationFilter filter,
677                                      Object passback)
678        throws InstanceNotFoundException, ListenerNotFoundException,
679               IOException;
680    
681      /**
682       * Sets the value of the specified attribute of the supplied
683       * management bean.  
684       *
685       * @param name the name of the management bean.
686       * @param attribute the attribute to set.
687       * @throws InstanceNotFoundException if the bean can not be found.
688       * @throws AttributeNotFoundException if the attribute does not
689       *                                    correspond to an attribute
690       *                                    of the bean.
691       * @throws InvalidAttributeValueException if the value is invalid
692       *                                        for this particular
693       *                                        attribute of the bean.
694       * @throws MBeanException if setting the attribute causes
695       *                        the bean to throw an exception (which
696       *                        becomes the cause of this exception).
697       * @throws ReflectionException if an exception occurred in trying
698       *                             to use the reflection interface
699       *                             to lookup the attribute.  The
700       *                             thrown exception is the cause of
701       *                             this exception.
702       * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
703       *                                    is thrown by the server due to a
704       *                                    <code>null</code> bean or attribute
705       *                                    name.
706       * @throws IOException if an I/O error occurred in communicating with
707       *                     the bean server.
708       * @see #getAttribute(ObjectName, String)
709       * @see DynamicMBean#setAttribute(Attribute)
710       */
711      void setAttribute(ObjectName name, Attribute attribute)
712        throws InstanceNotFoundException, AttributeNotFoundException,
713               InvalidAttributeValueException, MBeanException,
714               ReflectionException, IOException;
715    
716      /**
717       * Sets the value of each of the specified attributes
718       * of the supplied management bean to that specified by
719       * the {@link Attribute} object.  The returned list contains
720       * the attributes that were set and their new values.
721       *
722       * @param name the name of the management bean.
723       * @param attributes the attributes to set.
724       * @return a list of the changed attributes.
725       * @throws InstanceNotFoundException if the bean can not be found.
726       * @throws ReflectionException if an exception occurred in trying
727       *                             to use the reflection interface
728       *                             to lookup the attribute.  The
729       *                             thrown exception is the cause of
730       *                             this exception.
731       * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
732       *                                    is thrown by the server due to a
733       *                                    <code>null</code> bean or attribute
734       *                                    list.
735       * @throws IOException if an I/O error occurred in communicating with
736       *                     the bean server.
737       * @see #getAttributes(ObjectName, String[])
738       * @see DynamicMBean#setAttributes(AttributeList)
739       */
740      AttributeList setAttributes(ObjectName name, AttributeList attributes)
741        throws InstanceNotFoundException, ReflectionException,
742               IOException;
743    
744      /**
745       * Unregisters the specified management bean.  Following this operation,
746       * the bean instance is no longer accessible from the server via this
747       * name.  Prior to unregistering the bean, the
748       * {@link MBeanRegistration#preDeregister()} method will be called if
749       * the bean implements the {@link MBeanRegistration} interface.
750       *
751       * @param name the name of the management bean.
752       * @throws InstanceNotFoundException if the bean can not be found.
753       * @throws MBeanRegistrationException if an exception occurs in
754       *                                    calling the preDeregister
755       *                                    method.
756       * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
757       *                                    is thrown by the server due to a
758       *                                    <code>null</code> bean name or a
759       *                                    request being made to unregister the
760       *                                    {@link MBeanServerDelegate} bean.
761       * @throws IOException if an I/O error occurred in communicating with
762       *                     the bean server.
763       */ 
764      void unregisterMBean(ObjectName name)
765        throws InstanceNotFoundException, MBeanRegistrationException,
766               IOException;
767    
768    }