Source for javax.management.MBeanServer

   1: /* MBeanServer.java -- Represents a management server.
   2:    Copyright (C) 2006 Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: package javax.management;
  39: 
  40: import java.io.ObjectInputStream;
  41: 
  42: import java.util.Set;
  43: 
  44: import javax.management.loading.ClassLoaderRepository;
  45: 
  46: /**
  47:  * <p>
  48:  * This interface represents a server for management beans,
  49:  * providing facilities for the creation, registration and
  50:  * removal of such beans.  This interface is central to the
  51:  * Java management architecture.  Users do not usually implement
  52:  * this class.  Instead, implementations of this class
  53:  * may be obtained using an {@link MBeanServerFactory}.
  54:  * </p>
  55:  * <p>
  56:  * Registering a bean with the server makes its attributes and
  57:  * operations accessible via the server.  Only JMX compliant
  58:  * beans may be registered with the server.  When a bean
  59:  * is registered or unregistered, an {@link MBeanServerNotification}
  60:  * is emitted by the server's {@link MBeanServerDelegate}.
  61:  * Listeners may be registered with this bean in order to
  62:  * obtain such notifications.  It has the {@link ObjectName}
  63:  * <code>JMImplementation:type=MBeanServerDelegate</code>.
  64:  * </p>
  65:  * <p>
  66:  * Security checks are applied on the methods of the server,
  67:  * as detailed below, if it is obtained using the
  68:  * {@link MBeanServerFactory#createMBeanServer()} or
  69:  * {@link MBeanServerFactory#newMBeanServer()} methods and
  70:  * {@link System.getSecurityManager()} returns a non-<code>null</code>
  71:  * value.  If a check fails, a {@link SecurityException}
  72:  * is thrown.  Note than the class name used in the exception
  73:  * is that of the bean, and thus, as a result, an
  74:  * {@link InstanceNotFoundException}
  75:  * precludes these security checks, due to the class name
  76:  * that would be used in the exception being unavailable.
  77:  * </p>
  78:  *
  79:  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  80:  * @since 1.5
  81:  */
  82: public interface MBeanServer
  83:   extends MBeanServerConnection
  84: {
  85: 
  86:   /**
  87:    * Registers the supplied listener with the specified management
  88:    * bean.  Notifications emitted by the management bean are forwarded
  89:    * to the listener via the server, which will convert any MBean
  90:    * references in the source to portable {@link ObjectName}
  91:    * instances.  The notification is otherwise unchanged.
  92:    *
  93:    * @param name the name of the management bean with which the listener
  94:    *             should be registered.
  95:    * @param listener the listener which will handle notifications from
  96:    *                 the bean.
  97:    * @param filter the filter to apply to incoming notifications, or
  98:    *               <code>null</code> if no filtering should be applied.
  99:    * @param passback an object to be passed to the listener when a
 100:    *                 notification is emitted.
 101:    * @throws InstanceNotFoundException if the name of the management bean
 102:    *                                   could not be resolved.
 103:    * @throws SecurityException if a security manager exists and the
 104:    *                           caller's permissions don't imply {@link
 105:    *                           MBeanPermission(String,String,ObjectName,String)
 106:    *                           <code>MBeanPermission(className, null, name,
 107:    *                           "addNotificationListener")</code>}.
 108:    * @see #removeNotificationListener(ObjectName, NotificationListener)
 109:    * @see #removeNotificationListener(ObjectName, NotificationListener,
 110:    *                                  NotificationFilter, Object)
 111:    * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
 112:    *                                                      NotificationFilter,
 113:    *                                                      Object)
 114:    */
 115:   void addNotificationListener(ObjectName name, NotificationListener listener,
 116:                                NotificationFilter filter, Object passback)
 117:     throws InstanceNotFoundException;
 118: 
 119:   /**
 120:    * <p>
 121:    * Registers the supplied listener with the specified management
 122:    * bean.  Notifications emitted by the management bean are forwarded
 123:    * to the listener via the server, which will convert any MBean
 124:    * references in the source to portable {@link ObjectName}
 125:    * instances.  The notification is otherwise unchanged.
 126:    * </p>
 127:    * <p>
 128:    * The listener that receives notifications will be the one that is
 129:    * registered with the given name at the time this method is called.
 130:    * Even if it later unregisters and ceases to use that name, it will
 131:    * still receive notifications.
 132:    * </p>
 133:    *
 134:    * @param name the name of the management bean with which the listener
 135:    *             should be registered.
 136:    * @param listener the name of the listener which will handle
 137:    *                 notifications from the bean.
 138:    * @param filter the filter to apply to incoming notifications, or
 139:    *               <code>null</code> if no filtering should be applied.
 140:    * @param passback an object to be passed to the listener when a
 141:    *                 notification is emitted.
 142:    * @throws InstanceNotFoundException if the name of the management bean
 143:    *                                   could not be resolved.
 144:    * @throws RuntimeOperationsException if the bean associated with the given
 145:    *                                    object name is not a
 146:    *                                    {@link NotificationListener}.  This
 147:    *                                    exception wraps an
 148:    *                                    {@link IllegalArgumentException}.
 149:    * @throws SecurityException if a security manager exists and the
 150:    *                           caller's permissions don't imply {@link
 151:    *                           MBeanPermission(String,String,ObjectName,String)
 152:    *                           <code>MBeanPermission(className, null, name,
 153:    *                           "addNotificationListener")</code>}.
 154:    * @see #removeNotificationListener(ObjectName, NotificationListener)
 155:    * @see #removeNotificationListener(ObjectName, NotificationListener,
 156:    *                                  NotificationFilter, Object)
 157:    * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
 158:    *                                                      NotificationFilter,
 159:    *                                                      Object)
 160:    */
 161:   void addNotificationListener(ObjectName name, ObjectName listener,
 162:                                NotificationFilter filter, Object passback)
 163:     throws InstanceNotFoundException;
 164: 
 165:   /**
 166:    * <p>
 167:    * Instantiates a new instance of the specified management bean
 168:    * using the default constructor and registers it with the server
 169:    * under the supplied name.  The class is loaded using the
 170:    * {@link javax.management.loading.ClassLoaderRepository default
 171:    * loader repository} of the server.
 172:    * </p>
 173:    * <p>
 174:    * If the name supplied is <code>null</code>, then the bean is
 175:    * expected to implement the {@link MBeanRegistration} interface.
 176:    * The {@link MBeanRegistration#preRegister preRegister} method
 177:    * of this interface will be used to obtain the name in this case.
 178:    * </p>
 179:    * <p>
 180:    * This method is equivalent to calling {@link
 181:    * #createMBean(String, ObjectName, Object[], String[])
 182:    * <code>createMBean(className, name, (Object[]) null,
 183:    * (String[]) null)</code>} with <code>null</code> parameters
 184:    * and signature.
 185:    * </p>
 186:    *
 187:    * @param className the class of the management bean, of which
 188:    *                  an instance should be created.
 189:    * @param name the name to register the new bean with.
 190:    * @return an {@link ObjectInstance} containing the {@link ObjectName}
 191:    *         and Java class name of the created instance.
 192:    * @throws ReflectionException if an exception occurs in creating
 193:    *                             an instance of the bean.
 194:    * @throws InstanceAlreadyExistsException if a matching instance
 195:    *                                        already exists.
 196:    * @throws MBeanRegistrationException if an exception occurs in
 197:    *                                    calling the preRegister
 198:    *                                    method.
 199:    * @throws MBeanException if the bean's constructor throws an exception.
 200:    * @throws NotCompliantMBeanException if the created bean is not
 201:    *                                    compliant with the JMX specification.
 202:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 203:    *                                    is thrown by the server due to a
 204:    *                                    <code>null</code> class name or object
 205:    *                                    name or if the object name is a pattern.
 206:    * @throws SecurityException if a security manager exists and the
 207:    *                           caller's permissions don't imply the
 208:    *                           use of the <code>instantiate</code>
 209:    *                           and <code>registerMBean</code> methods.
 210:    * @see #createMBean(String, ObjectName, Object[], String[])
 211:    */
 212:   ObjectInstance createMBean(String className, ObjectName name)
 213:     throws ReflectionException, InstanceAlreadyExistsException,
 214:            MBeanRegistrationException, MBeanException,
 215:            NotCompliantMBeanException;
 216: 
 217:   /**
 218:    * <p>
 219:    * Instantiates a new instance of the specified management bean
 220:    * using the given constructor and registers it with the server
 221:    * under the supplied name.  The class is loaded using the
 222:    * {@link javax.management.loading.ClassLoaderRepository default
 223:    * loader repository} of the server.
 224:    * </p>
 225:    * <p>
 226:    * If the name supplied is <code>null</code>, then the bean is
 227:    * expected to implement the {@link MBeanRegistration} interface.
 228:    * The {@link MBeanRegistration#preRegister preRegister} method
 229:    * of this interface will be used to obtain the name in this case.
 230:    * </p>
 231:    *
 232:    * @param className the class of the management bean, of which
 233:    *                  an instance should be created.
 234:    * @param name the name to register the new bean with.
 235:    * @param params the parameters for the bean's constructor.
 236:    * @param sig the signature of the constructor to use.
 237:    * @return an {@link ObjectInstance} containing the {@link ObjectName}
 238:    *         and Java class name of the created instance.
 239:    * @throws ReflectionException if an exception occurs in creating
 240:    *                             an instance of the bean.
 241:    * @throws InstanceAlreadyExistsException if a matching instance
 242:    *                                        already exists.
 243:    * @throws MBeanRegistrationException if an exception occurs in
 244:    *                                    calling the preRegister
 245:    *                                    method.
 246:    * @throws MBeanException if the bean's constructor throws an exception.
 247:    * @throws NotCompliantMBeanException if the created bean is not
 248:    *                                    compliant with the JMX specification.
 249:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 250:    *                                    is thrown by the server due to a
 251:    *                                    <code>null</code> class name or object
 252:    *                                    name or if the object name is a pattern.
 253:    * @throws SecurityException if a security manager exists and the
 254:    *                           caller's permissions don't imply the
 255:    *                           use of the <code>instantiate</code>
 256:    *                           and <code>registerMBean</code> methods.
 257:    */
 258:   ObjectInstance createMBean(String className, ObjectName name,
 259:                              Object[] params, String[] sig)
 260:     throws ReflectionException, InstanceAlreadyExistsException,
 261:            MBeanRegistrationException, MBeanException,
 262:            NotCompliantMBeanException;
 263: 
 264:   /**
 265:    * <p>
 266:    * Instantiates a new instance of the specified management bean
 267:    * using the default constructor and registers it with the server
 268:    * under the supplied name.  The class is loaded using the
 269:    * given class loader.  If this argument is <code>null</code>,
 270:    * then the same class loader as was used to load the server
 271:    * is used.
 272:    * </p>
 273:    * <p>
 274:    * If the name supplied is <code>null</code>, then the bean is
 275:    * expected to implement the {@link MBeanRegistration} interface.
 276:    * The {@link MBeanRegistration#preRegister preRegister} method
 277:    * of this interface will be used to obtain the name in this case.
 278:    * </p>
 279:    * <p>
 280:    * This method is equivalent to calling {@link
 281:    * #createMBean(String, ObjectName, ObjectName, Object[], String)
 282:    * <code>createMBean(className, name, loaderName, (Object[]) null,
 283:    * (String) null)</code>} with <code>null</code> parameters
 284:    * and signature.
 285:    * </p>
 286:    *
 287:    * @param className the class of the management bean, of which
 288:    *                  an instance should be created.
 289:    * @param name the name to register the new bean with.
 290:    * @param loaderName the name of the class loader.
 291:    * @return an {@link ObjectInstance} containing the {@link ObjectName}
 292:    *         and Java class name of the created instance.
 293:    * @throws ReflectionException if an exception occurs in creating
 294:    *                             an instance of the bean.
 295:    * @throws InstanceAlreadyExistsException if a matching instance
 296:    *                                        already exists.
 297:    * @throws MBeanRegistrationException if an exception occurs in
 298:    *                                    calling the preRegister
 299:    *                                    method.
 300:    * @throws MBeanException if the bean's constructor throws an exception.
 301:    * @throws NotCompliantMBeanException if the created bean is not
 302:    *                                    compliant with the JMX specification.
 303:    * @throws InstanceNotFoundException if the specified class loader is not
 304:    *                                   registered with the server.
 305:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 306:    *                                    is thrown by the server due to a
 307:    *                                    <code>null</code> class name or object
 308:    *                                    name or if the object name is a pattern.
 309:    * @throws SecurityException if a security manager exists and the
 310:    *                           caller's permissions don't imply the
 311:    *                           use of the <code>instantiate</code>
 312:    *                           and <code>registerMBean</code> methods.
 313:    * @see #createMBean(String, ObjectName, ObjectName, Object[], String[])
 314:    */
 315:   ObjectInstance createMBean(String className, ObjectName name,
 316:                              ObjectName loaderName)
 317:     throws ReflectionException, InstanceAlreadyExistsException,
 318:            MBeanRegistrationException, MBeanException,
 319:            NotCompliantMBeanException, InstanceNotFoundException;
 320: 
 321:   /**
 322:    * <p>
 323:    * Instantiates a new instance of the specified management bean
 324:    * using the given constructor and registers it with the server
 325:    * under the supplied name.  The class is loaded using the
 326:    * given class loader.  If this argument is <code>null</code>,
 327:    * then the same class loader as was used to load the server
 328:    * is used.
 329:    * </p>
 330:    * <p>
 331:    * If the name supplied is <code>null</code>, then the bean is
 332:    * expected to implement the {@link MBeanRegistration} interface.
 333:    * The {@link MBeanRegistration#preRegister preRegister} method
 334:    * of this interface will be used to obtain the name in this case.
 335:    * </p>
 336:    *
 337:    * @param className the class of the management bean, of which
 338:    *                  an instance should be created.
 339:    * @param name the name to register the new bean with.
 340:    * @param loaderName the name of the class loader.
 341:    * @param params the parameters for the bean's constructor.
 342:    * @param sig the signature of the constructor to use.
 343:    * @return an {@link ObjectInstance} containing the {@link ObjectName}
 344:    *         and Java class name of the created instance.
 345:    * @throws ReflectionException if an exception occurs in creating
 346:    *                             an instance of the bean.
 347:    * @throws InstanceAlreadyExistsException if a matching instance
 348:    *                                        already exists.
 349:    * @throws MBeanRegistrationException if an exception occurs in
 350:    *                                    calling the preRegister
 351:    *                                    method.
 352:    * @throws MBeanException if the bean's constructor throws an exception.
 353:    * @throws NotCompliantMBeanException if the created bean is not
 354:    *                                    compliant with the JMX specification.
 355:    * @throws InstanceNotFoundException if the specified class loader is not
 356:    *                                   registered with the server.
 357:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 358:    *                                    is thrown by the server due to a
 359:    *                                    <code>null</code> class name or object
 360:    *                                    name or if the object name is a pattern.
 361:    * @throws SecurityException if a security manager exists and the
 362:    *                           caller's permissions don't imply the
 363:    *                           use of the <code>instantiate</code>
 364:    *                           and <code>registerMBean</code> methods.
 365:    */
 366:   ObjectInstance createMBean(String className, ObjectName name,
 367:                              ObjectName loaderName, Object[] params,
 368:                              String[] sig)
 369:     throws ReflectionException, InstanceAlreadyExistsException,
 370:            MBeanRegistrationException, MBeanException,
 371:            NotCompliantMBeanException, InstanceNotFoundException;
 372: 
 373:   /**
 374:    * Deserializes a byte array using the class loader of the specified
 375:    * management bean as its context.
 376:    *
 377:    * @param name the name of the bean whose class loader should be used.
 378:    * @param data the byte array to be deserialized.
 379:    * @return the deserialized object stream.
 380:    * @deprecated {@link #getClassLoaderFor(ObjectName)} should be used
 381:    *             to obtain the class loader of the bean, which can then
 382:    *             be used to perform deserialization in the user's code.
 383:    * @throws InstanceNotFoundException if the specified bean is not
 384:    *                                   registered with the server.
 385:    * @throws OperationsException if any I/O error is thrown by the
 386:    *                             deserialization process.
 387:    * @throws SecurityException if a security manager exists and the
 388:    *                           caller's permissions don't imply {@link
 389:    *                           MBeanPermission(String,String,ObjectName,String)
 390:    *                           <code>MBeanPermission(className, null, name,
 391:    *                           "getClassLoaderFor")</code>
 392:    */
 393:   ObjectInputStream deserialize(ObjectName name, byte[] data)
 394:     throws InstanceNotFoundException, OperationsException;
 395: 
 396:   /**
 397:    * Deserializes a byte array using the same class loader for its context
 398:    * as was used to load the given class.  This class loader is obtained by
 399:    * loading the specified class using the {@link
 400:    * javax.management.loading.ClassLoaderRepository Class Loader Repository}
 401:    * and then using the class loader of the resulting {@link Class} instance.
 402:    *
 403:    * @param name the name of the class which should be loaded to obtain the
 404:    *             class loader.
 405:    * @param data the byte array to be deserialized.
 406:    * @return the deserialized object stream.
 407:    * @deprecated {@link #getClassLoaderRepository} should be used
 408:    *             to obtain the class loading repository, which can then
 409:    *             be used to obtain the {@link Class} instance and deserialize
 410:    *             the array using its class loader.
 411:    * @throws OperationsException if any I/O error is thrown by the
 412:    *                             deserialization process.
 413:    * @throws ReflectionException if an error occurs in obtaining the
 414:    *                             {@link Class} instance.
 415:    * @throws SecurityException if a security manager exists and the
 416:    *                           caller's permissions don't imply {@link
 417:    *                           MBeanPermission(String,String,ObjectName,String)
 418:    *                           <code>MBeanPermission(null, null, null,
 419:    *                           "getClassLoaderRepository")</code>
 420:    */
 421:   ObjectInputStream deserialize(String name, byte[] data)
 422:     throws OperationsException, ReflectionException;
 423: 
 424:   /**
 425:    * Deserializes a byte array using the same class loader for its context
 426:    * as was used to load the given class.  The name of the class loader to
 427:    * be used is supplied, and may be <code>null</code> if the server's
 428:    * class loader should be used instead.
 429:    *
 430:    * @param name the name of the class which should be loaded to obtain the
 431:    *             class loader.
 432:    * @param loader the name of the class loader to use, or <code>null</code>
 433:    *               if the class loader of the server should be used.
 434:    * @param data the byte array to be deserialized.
 435:    * @return the deserialized object stream.
 436:    * @deprecated {@link #getClassLoader(ObjectName} can be used to obtain
 437:    *              the named class loader and deserialize the array.
 438:    * @throws InstanceNotFoundException if the specified class loader is not
 439:    *                                   registered with the server.
 440:    * @throws OperationsException if any I/O error is thrown by the
 441:    *                             deserialization process.
 442:    * @throws ReflectionException if an error occurs in obtaining the
 443:    *                             {@link Class} instance.
 444:    * @throws SecurityException if a security manager exists and the
 445:    *                           caller's permissions don't imply {@link
 446:    *                           MBeanPermission(String,String,ObjectName,String)
 447:    *                           <code>MBeanPermission(className, null, loader,
 448:    *                           "getClassLoader")</code>
 449:    */
 450:   ObjectInputStream deserialize(String name, ObjectName loader, byte[] data)
 451:     throws InstanceNotFoundException, ReflectionException,
 452:            OperationsException;
 453: 
 454:   /**
 455:    * Returns the value of the supplied attribute from the specified
 456:    * management bean.
 457:    *
 458:    * @param bean the bean to retrieve the value from.
 459:    * @param name the name of the attribute to retrieve.
 460:    * @return the value of the attribute.
 461:    * @throws AttributeNotFoundException if the attribute could not be
 462:    *                                    accessed from the bean.
 463:    * @throws MBeanException if the management bean's accessor throws
 464:    *                        an exception.
 465:    * @throws InstanceNotFoundException if the bean can not be found.
 466:    * @throws ReflectionException if an exception was thrown in trying
 467:    *                             to invoke the bean's accessor.
 468:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 469:    *                                    is thrown by the server due to a
 470:    *                                    <code>null</code> bean or attribute
 471:    *                                    name.
 472:    * @throws SecurityException if a security manager exists and the
 473:    *                           caller's permissions don't imply {@link
 474:    *                           MBeanPermission(String,String,ObjectName,String)
 475:    *                           <code>MBeanPermission(className, name, bean,
 476:    *                           "getAttribute")</code>}.
 477:    * @see DynamicMBean#getAttribute(String)
 478:    */
 479:   Object getAttribute(ObjectName bean, String name)
 480:     throws MBeanException, AttributeNotFoundException,
 481:            InstanceNotFoundException, ReflectionException;
 482: 
 483:   /**
 484:    * Returns the values of the named attributes from the specified
 485:    * management bean.
 486:    *
 487:    * @param bean the bean to retrieve the value from.
 488:    * @param names the names of the attributes to retrieve.
 489:    * @return the values of the attributes.
 490:    * @throws InstanceNotFoundException if the bean can not be found.
 491:    * @throws ReflectionException if an exception was thrown in trying
 492:    *                             to invoke the bean's accessor.
 493:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 494:    *                                    is thrown by the server due to a
 495:    *                                    <code>null</code> bean or attribute
 496:    *                                    name.
 497:    * @throws SecurityException if a security manager exists and the
 498:    *                           caller's permissions don't imply {@link
 499:    *                           MBeanPermission(String,String,ObjectName,String)
 500:    *                           <code>MBeanPermission(className, null, bean,
 501:    *                           "getAttribute")</code>}.  Additionally,
 502:    *                           for an attribute name, <code>n</code>, the
 503:    *                           caller's permission must imply {@link
 504:    *                           MBeanPermission(String,String,ObjectName,String)
 505:    *                           <code>MBeanPermission(className, n, bean,
 506:    *                           "getAttribute")</code>} or that attribute will
 507:    *                           not be included.
 508:    *
 509:    * @see DynamicMBean#getAttributes(String[])
 510:    */
 511:   AttributeList getAttributes(ObjectName bean, String[] names)
 512:     throws InstanceNotFoundException, ReflectionException;
 513: 
 514:   /**
 515:    * Returns the specified class loader.  If the specified value is
 516:    * <code>null</code>, then the class loader of the server will be
 517:    * returned.  If <code>l</code> is the requested class loader,
 518:    * and <code>r</code> is the actual class loader returned, then
 519:    * either <code>l</code> and <code>r</code> will be identical,
 520:    * or they will at least return the same class from
 521:    * {@link ClassLoader#loadClass(String)} for any given string.
 522:    * They may not be identical due to one or the other
 523:    * being wrapped in another class loader (e.g. for security).
 524:    *
 525:    * @param name the name of the class loader to return.
 526:    * @return the class loader.
 527:    * @throws InstanceNotFoundException if the class loader can not
 528:    *                                   be found.
 529:    * @throws SecurityException if a security manager exists and the
 530:    *                           caller's permissions don't imply {@link
 531:    *                           MBeanPermission(String,String,ObjectName,String)
 532:    *                           <code>MBeanPermission(className, null, name,
 533:    *                           "getClassLoader")</code>
 534:    */
 535:   ClassLoader getClassLoader(ObjectName name)
 536:     throws InstanceNotFoundException;
 537: 
 538:   /**
 539:    * Returns the class loader of the specified management bean.  If
 540:    * <code>l</code> is the requested class loader, and <code>r</code>
 541:    * is the actual class loader returned, then either <code>l</code>
 542:    * and <code>r</code> will be identical, or they will at least
 543:    * return the same class from {@link ClassLoader#loadClass(String)}
 544:    * for any given string.  They may not be identical due to one or
 545:    * the other being wrapped in another class loader (e.g. for
 546:    * security).
 547:    *
 548:    * @param name the name of the bean whose class loader should be
 549:    *             returned.
 550:    * @return the class loader.
 551:    * @throws InstanceNotFoundException if the bean is not registered
 552:    *                                   with the server.
 553:    * @throws SecurityException if a security manager exists and the
 554:    *                           caller's permissions don't imply {@link
 555:    *                           MBeanPermission(String,String,ObjectName,String)
 556:    *                           <code>MBeanPermission(className, null, name,
 557:    *                           "getClassLoaderFor")</code>
 558:    */
 559:   ClassLoader getClassLoaderFor(ObjectName name)
 560:     throws InstanceNotFoundException;
 561: 
 562:   /**
 563:    * Returns the class loader repository used by this server.
 564:    *
 565:    * @return the class loader repository.
 566:    * @throws SecurityException if a security manager exists and the
 567:    *                           caller's permissions don't imply {@link
 568:    *                           MBeanPermission(String,String,ObjectName,String)
 569:    *                           <code>MBeanPermission(null, null, null,
 570:    *                           "getClassLoaderRepository")</code>
 571:    */
 572:   ClassLoaderRepository getClassLoaderRepository();
 573: 
 574:   /**
 575:    * Returns the default domain this server applies to beans that have
 576:    * no specified domain.
 577:    *
 578:    * @return the default domain.
 579:    */
 580:   String getDefaultDomain();
 581: 
 582:   /**
 583:    * Returns an array containing all the domains used by beans registered
 584:    * with this server.  The ordering of the array is undefined.
 585:    *
 586:    * @return the list of domains.
 587:    * @throws SecurityException if a security manager exists and the
 588:    *                           caller's permissions don't imply {@link
 589:    *                           MBeanPermission(String,String,ObjectName,String)
 590:    *                           <code>MBeanPermission(null, null, name,
 591:    *                           "getDomains")</code>}.  Additionally,
 592:    *                           for an domain, <code>d</code>, the
 593:    *                           caller's permission must imply {@link
 594:    *                           MBeanPermission(String,String,ObjectName,String)
 595:    *                           <code>MBeanPermission(null, null,
 596:    *                           new ObjectName("d:x=x"), "getDomains")</code>}
 597:    *                           or that domain will not be included.  Note
 598:    *                           that "x=x" is an arbitrary key-value pair
 599:    *                           provided to satisfy the constructor.
 600:    * @see ObjectName#getDomain()
 601:    */
 602:   String[] getDomains();
 603: 
 604:   /**
 605:    * Returns the number of management beans registered with this server.
 606:    * This may be less than the real number if the caller's access is
 607:    * restricted.
 608:    *
 609:    * @return the number of registered beans.
 610:    */
 611:   Integer getMBeanCount();
 612: 
 613:   /**
 614:    * Returns information on the given management bean.
 615:    *
 616:    * @param name the name of the management bean.
 617:    * @return an instance of {@link MBeanInfo} for the bean.
 618:    * @throws IntrospectionException if an exception occurs in examining
 619:    *                                the bean.
 620:    * @throws InstanceNotFoundException if the bean can not be found.
 621:    * @throws ReflectionException if an exception occurs when trying
 622:    *                             to invoke {@link DynamicMBean#getMBeanInfo()}
 623:    *                             on the bean.
 624:    * @throws SecurityException if a security manager exists and the
 625:    *                           caller's permissions don't imply {@link
 626:    *                           MBeanPermission(String,String,ObjectName,String)
 627:    *                           <code>MBeanPermission(className, null, name,
 628:    *                           "getMBeanInfo")</code>}.
 629:    * @see DynamicMBean#getMBeanInfo()
 630:    */
 631:   MBeanInfo getMBeanInfo(ObjectName name)
 632:     throws InstanceNotFoundException, IntrospectionException,
 633:            ReflectionException;
 634: 
 635:   /**
 636:    * Returns the {@link ObjectInstance} created for the specified
 637:    * management bean on registration.
 638:    *
 639:    * @param name the name of the bean.
 640:    * @return the corresponding {@link ObjectInstance} instance.
 641:    * @throws InstanceNotFoundException if the bean can not be found.
 642:    * @throws SecurityException if a security manager exists and the
 643:    *                           caller's permissions don't imply {@link
 644:    *                           MBeanPermission(String,String,ObjectName,String)
 645:    *                           <code>MBeanPermission(className, null, name,
 646:    *                           "getObjectInstance")</code>
 647:    * @see #createMBean(String, ObjectName)
 648:    */
 649:   ObjectInstance getObjectInstance(ObjectName name)
 650:     throws InstanceNotFoundException;
 651: 
 652:   /**
 653:    * <p>
 654:    * Creates an instance of the specified class using the list of
 655:    * class loaders from the {@link
 656:    * javax.management.loading.ClassLoaderRepository Class Loader
 657:    * Repository}.  The class should have a public constructor
 658:    * with no arguments.  A reference to the new instance is returned,
 659:    * but the instance is not yet registered with the server.
 660:    * </p>
 661:    * <p>
 662:    * This method is equivalent to calling {@link
 663:    * #instantiate(String, Object[], String[])
 664:    * <code>instantiate(name, (Object[]) null, (String[]) null)</code>}
 665:    * with <code>null</code> parameters and signature.
 666:    * </p>
 667:    *
 668:    * @param name the name of the class of bean to be instantiated.
 669:    * @return an instance of the given class.
 670:    * @throws ReflectionException if an exception is thrown during
 671:    *                             loading the class or calling the
 672:    *                             constructor.
 673:    * @throws MBeanException if the constructor throws an exception.
 674:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 675:    *                                    is thrown by the server due to a
 676:    *                                    <code>null</code> name.
 677:    * @throws SecurityException if a security manager exists and the
 678:    *                           caller's permissions don't imply {@link
 679:    *                           MBeanPermission(String,String,ObjectName,String)
 680:    *                           <code>MBeanPermission(className, null, null,
 681:    *                           "instantiate")</code>}.
 682:    * @see #instantiate(String, Object[], String[])
 683:    */
 684:   Object instantiate(String name)
 685:     throws ReflectionException, MBeanException;
 686: 
 687:   /**
 688:    * Creates an instance of the specified class using the list of
 689:    * class loaders from the {@link
 690:    * javax.management.loading.ClassLoaderRepository Class Loader
 691:    * Repository}.  The class should have a public constructor
 692:    * matching the supplied signature.  A reference to the new
 693:    * instance is returned, but the instance is not yet
 694:    * registered with the server.
 695:    *
 696:    * @param name the name of the class of bean to be instantiated.
 697:    * @param params the parameters for the constructor.
 698:    * @param sig the signature of the constructor.
 699:    * @return an instance of the given class.
 700:    * @throws ReflectionException if an exception is thrown during
 701:    *                             loading the class or calling the
 702:    *                             constructor.
 703:    * @throws MBeanException if the constructor throws an exception.
 704:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 705:    *                                    is thrown by the server due to a
 706:    *                                    <code>null</code> name.
 707:    * @throws SecurityException if a security manager exists and the
 708:    *                           caller's permissions don't imply {@link
 709:    *                           MBeanPermission(String,String,ObjectName,String)
 710:    *                           <code>MBeanPermission(className, null, null,
 711:    *                           "instantiate")</code>}.
 712:    */
 713:   Object instantiate(String name, Object[] params, String[] sig)
 714:     throws ReflectionException, MBeanException;
 715: 
 716:   /**
 717:    * <p>
 718:    * Creates an instance of the specified class using the supplied
 719:    * class loader.  If the class loader given is <code>null</code>,
 720:    * then the class loader of the server will be used.  The class
 721:    * should have a public constructor with no arguments.  A reference
 722:    * to the new instance is returned, but the instance is not yet
 723:    * registered with the server.
 724:    * </p>
 725:    * <p>
 726:    * This method is equivalent to calling {@link
 727:    * #instantiate(String, ObjectName, Object[], String[])
 728:    * <code>instantiate(name, loaderName, (Object[]) null,
 729:    * (String[]) null)</code>} with <code>null</code> parameters
 730:    * and signature.
 731:    * </p>
 732:    *
 733:    * @param name the name of the class of bean to be instantiated.
 734:    * @param loaderName the name of the class loader to use.
 735:    * @return an instance of the given class.
 736:    * @throws InstanceNotFoundException if the class loader is not
 737:    *                                   registered with the server.
 738:    * @throws ReflectionException if an exception is thrown during
 739:    *                             loading the class or calling the
 740:    *                             constructor.
 741:    * @throws MBeanException if the constructor throws an exception.
 742:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 743:    *                                    is thrown by the server due to a
 744:    *                                    <code>null</code> name.
 745:    * @throws SecurityException if a security manager exists and the
 746:    *                           caller's permissions don't imply {@link
 747:    *                           MBeanPermission(String,String,ObjectName,String)
 748:    *                           <code>MBeanPermission(className, null, null,
 749:    *                           "instantiate")</code>}.
 750:    * @see #instantiate(String, Object[], String[])
 751:    */
 752:   Object instantiate(String name, ObjectName loaderName)
 753:     throws InstanceNotFoundException, ReflectionException,
 754:            MBeanException;
 755: 
 756:   /**
 757:    * Creates an instance of the specified class using the supplied
 758:    * class loader.  If the class loader given is <code>null</code>,
 759:    * then the class loader of the server will be used.  The class
 760:    * should have a public constructor matching the supplied
 761:    * signature.  A reference to the new instance is returned,
 762:    * but the instance is not yet registered with the server.
 763:    *
 764:    * @param name the name of the class of bean to be instantiated.
 765:    * @param loaderName the name of the class loader to use.
 766:    * @param params the parameters for the constructor.
 767:    * @param sig the signature of the constructor.
 768:    * @return an instance of the given class.
 769:    * @throws InstanceNotFoundException if the class loader is not
 770:    *                                   registered with the server.
 771:    * @throws ReflectionException if an exception is thrown during
 772:    *                             loading the class or calling the
 773:    *                             constructor.
 774:    * @throws MBeanException if the constructor throws an exception.
 775:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 776:    *                                    is thrown by the server due to a
 777:    *                                    <code>null</code> name.
 778:    * @throws SecurityException if a security manager exists and the
 779:    *                           caller's permissions don't imply {@link
 780:    *                           MBeanPermission(String,String,ObjectName,String)
 781:    *                           <code>MBeanPermission(className, null, null,
 782:    *                           "instantiate")</code>}.
 783:    */
 784:   Object instantiate(String name, ObjectName loaderName,
 785:                      Object[] params, String[] sig)
 786:     throws InstanceNotFoundException, ReflectionException,
 787:            MBeanException;
 788: 
 789:   /**
 790:    * Invokes the supplied operation on the specified management
 791:    * bean.  The class objects specified in the signature are loaded
 792:    * using the same class loader as was used for the management bean.
 793:    *
 794:    * @param bean the management bean whose operation should be invoked.
 795:    * @param name the name of the operation to invoke.
 796:    * @param params the parameters of the operation.
 797:    * @param sig the signature of the operation.
 798:    * @return the return value of the method.
 799:    * @throws InstanceNotFoundException if the bean can not be found.
 800:    * @throws MBeanException if the method invoked throws an exception.
 801:    * @throws ReflectionException if an exception is thrown in invoking the
 802:    *                             method.
 803:    * @throws SecurityException if a security manager exists and the
 804:    *                           caller's permissions don't imply {@link
 805:    *                           MBeanPermission(String,String,ObjectName,String)
 806:    *                           <code>MBeanPermission(className, name, bean,
 807:    *                           "invoke")</code>}.
 808:    * @see DynamicMBean#invoke(String, Object[], String[])
 809:    */
 810:   Object invoke(ObjectName bean, String name, Object[] params, String[] sig)
 811:     throws InstanceNotFoundException, MBeanException,
 812:            ReflectionException;
 813: 
 814:   /**
 815:    * <p>
 816:    * Returns true if the specified management bean is an instance
 817:    * of the supplied class.
 818:    * </p>
 819:    * <p>
 820:    * A bean, B, is an instance of a class, C, if either of the following
 821:    * conditions holds:
 822:    * </p>
 823:    * <ul>
 824:    * <li>The class name in B's {@link MBeanInfo} is equal to the supplied
 825:    * name.</li>
 826:    * <li>Both the class of B and C were loaded by the same class loader,
 827:    * and B is assignable to C.</li>
 828:    * </ul>
 829:    *
 830:    * @param name the name of the management bean.
 831:    * @param className the name of the class to test if <code>name</code> is
 832:    *                  an instance of.
 833:    * @return true if either B is directly an instance of the named class,
 834:    *         or B is assignable to the class, given that both it and B's
 835:    *         current class were loaded using the same class loader.
 836:    * @throws InstanceNotFoundException if the bean can not be found.
 837:    * @throws SecurityException if a security manager exists and the
 838:    *                           caller's permissions don't imply {@link
 839:    *                           MBeanPermission(String,String,ObjectName,String)
 840:    *                           <code>MBeanPermission(className, null, name,
 841:    *                           "isInstanceOf")</code>
 842:    */
 843:   boolean isInstanceOf(ObjectName name, String className)
 844:     throws InstanceNotFoundException;
 845: 
 846:   /**
 847:    * Returns true if the specified management bean is registered with
 848:    * the server.
 849:    *
 850:    * @param name the name of the management bean.
 851:    * @return true if the bean is registered.
 852:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 853:    *                                    is thrown by the server due to a
 854:    *                                    <code>null</code> bean name.
 855:    */
 856:   boolean isRegistered(ObjectName name);
 857: 
 858:   /**
 859:    * <p>
 860:    * Returns a set of {@link ObjectInstance}s matching the specified
 861:    * criteria.  The full set of beans registered with the server
 862:    * are passed through two filters:
 863:    * </p>
 864:    * <ol>
 865:    * <li>Pattern matching is performed using the supplied
 866:    * {@link ObjectName}.</li>
 867:    * <li>The supplied query expression is applied.</li>
 868:    * </ol>
 869:    * <p>
 870:    * If both the object name and the query expression are <code>null</code>,
 871:    * or the object name has no domain and no key properties,
 872:    * no filtering will be performed and all beans are returned.
 873:    * </p>
 874:    *
 875:    * @param name an {@link ObjectName} to use as a filter.
 876:    * @param query a query expression to apply to each of the beans that match
 877:    *              the given object name.
 878:    * @return a set of {@link ObjectInstance}s matching the filtered beans.
 879:    * @throws SecurityException if a security manager exists and the
 880:    *                           caller's permissions don't imply {@link
 881:    *                           MBeanPermission(String,String,ObjectName,String)
 882:    *                           <code>MBeanPermission(null, null, name,
 883:    *                           "queryMBeans")</code>}.  Additionally,
 884:    *                           for an bean, <code>b</code>, the
 885:    *                           caller's permission must imply {@link
 886:    *                           MBeanPermission(String,String,ObjectName,String)
 887:    *                           <code>MBeanPermission(className, b, name,
 888:    *                           "queryMBeans")</code>} or that bean will
 889:    *                           not be included.  Such an exception may also
 890:    *                           arise from the execution of the query, in which
 891:    *                           case that particular bean will again be excluded.
 892:    */
 893:   Set<ObjectInstance> queryMBeans(ObjectName name, QueryExp query);
 894: 
 895:   /**
 896:    * <p>
 897:    * Returns a set of {@link ObjectName}s matching the specified
 898:    * criteria.  The full set of beans registered with the server
 899:    * are passed through two filters:
 900:    * </p>
 901:    * <ol>
 902:    * <li>Pattern matching is performed using the supplied
 903:    * {@link ObjectName}.</li>
 904:    * <li>The supplied query expression is applied.</li>
 905:    * </ol>
 906:    * <p>
 907:    * If both the object name and the query expression are <code>null</code>,
 908:    * or the object name has no domain and no key properties,
 909:    * no filtering will be performed and all beans are returned.
 910:    * </p>
 911:    *
 912:    * @param name an {@link ObjectName} to use as a filter.
 913:    * @param query a query expression to apply to each of the beans that match
 914:    *              the given object name.
 915:    * @return a set of {@link ObjectName}s matching the filtered beans.
 916:    * @throws SecurityException if a security manager exists and the
 917:    *                           caller's permissions don't imply {@link
 918:    *                           MBeanPermission(String,String,ObjectName,String)
 919:    *                           <code>MBeanPermission(null, null, name,
 920:    *                           "queryNames")</code>}.  Additionally,
 921:    *                           for an name, <code>n</code>, the
 922:    *                           caller's permission must imply {@link
 923:    *                           MBeanPermission(String,String,ObjectName,String)
 924:    *                           <code>MBeanPermission(className, n, name,
 925:    *                           "queryNames")</code>} or that name will
 926:    *                           not be included.  Such an exception may also
 927:    *                           arise from the execution of the query, in which
 928:    *                           case that particular bean will again be excluded.
 929:    *                           Note that these permissions are implied if the
 930:    *                           <code>queryMBeans</code> permissions are available.
 931:    */
 932:   Set<ObjectName> queryNames(ObjectName name, QueryExp query);
 933: 
 934:   /**
 935:    * Registers the supplied instance with the server, using the specified
 936:    * {@link ObjectName}.  If the name given is <code>null</code>, then
 937:    * the bean supplied is expected to implement the {@link MBeanRegistration}
 938:    * interface and provide the name via the
 939:    * {@link MBeanRegistration#preRegister preRegister} method
 940:    * of this interface.
 941:    *
 942:    * @param obj the object to register with the server.
 943:    * @param name the name under which to register the object,
 944:    *             or <code>null</code> if the {@link MBeanRegistration}
 945:    *             interface should be used.
 946:    * @throws InstanceAlreadyExistsException if a matching instance
 947:    *                                        already exists.
 948:    * @throws MBeanRegistrationException if an exception occurs in
 949:    *                                    calling the preRegister
 950:    *                                    method.
 951:    * @throws NotCompliantMBeanException if the created bean is not
 952:    *                                    compliant with the JMX specification.
 953:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 954:    *                                    is thrown by the server due to a
 955:    *                                    <code>null</code> object.
 956:    * @throws SecurityException if a security manager exists and the
 957:    *                           caller's permissions don't imply {@link
 958:    *                           MBeanPermission(String,String,ObjectName,String)
 959:    *                           <code>MBeanPermission(className, null, name,
 960:    *                           "registerMBean")</code>}.  <code>className</code>
 961:    *                           here corresponds to the result of
 962:    *                           {@link MBeanInfo#getClassName()} for objects of
 963:    *                           this class.  If this check succeeds, a check
 964:    *                           is also made on its
 965:    *                           {@link java.security.ProtectionDomain} to ensure
 966:    *                           it implies {@link MBeanTrustPermission(String)
 967:    *                           <code>MBeanTrustPermission("register")</code>}.
 968:    *                           The use of the {@link MBeanRegistration} interface
 969:    *                           results in another {@link MBeanPermission} check
 970:    *                           being made on the returned {@link ObjectName}.
 971:    */
 972:   ObjectInstance registerMBean(Object obj, ObjectName name)
 973:     throws InstanceAlreadyExistsException, MBeanRegistrationException,
 974:            NotCompliantMBeanException;
 975: 
 976:   /**
 977:    * Removes the specified listener from the list of recipients
 978:    * of notifications from the supplied bean.  This includes all
 979:    * combinations of filters and passback objects registered for
 980:    * this listener.  For more specific removal of listeners, see
 981:    * {@link #removeNotificationListener(ObjectName,
 982:    * NotificationListener,NotificationFilter,Object)}
 983:    *
 984:    * @param name the name of the management bean from which the
 985:    *             listener should be removed.
 986:    * @param listener the listener to remove.
 987:    * @throws InstanceNotFoundException if the bean can not be found.
 988:    * @throws ListenerNotFoundException if the specified listener
 989:    *                                   is not registered with the bean.
 990:    * @throws SecurityException if a security manager exists and the
 991:    *                           caller's permissions don't imply {@link
 992:    *                           MBeanPermission(String,String,ObjectName,String)
 993:    *                           <code>MBeanPermission(className, null, name,
 994:    *                           "removeNotificationListener")</code>}.
 995:    * @see #addNotificationListener(NotificationListener, NotificationFilter,
 996:    *                               java.lang.Object)
 997:    * @see NotificationBroadcaster#removeNotificationListener(NotificationListener)
 998:    */
 999:   void removeNotificationListener(ObjectName name,
1000:                                   NotificationListener listener)
1001:     throws InstanceNotFoundException, ListenerNotFoundException;
1002: 
1003:   /**
1004:    * Removes the specified listener from the list of recipients
1005:    * of notifications from the supplied bean.  Only the first instance with
1006:    * the supplied filter and passback object is removed.
1007:    * <code>null</code> is used as a valid value for these parameters,
1008:    * rather than as a way to remove all registration instances for
1009:    * the specified listener; for this behaviour instead, see
1010:    * {@link #removeNotificationListener(ObjectName, NotificationListener)}.
1011:    *
1012:    * @param name the name of the management bean from which the
1013:    *             listener should be removed.
1014:    * @param listener the listener to remove.
1015:    * @param filter the filter of the listener to remove.
1016:    * @param passback the passback object of the listener to remove.
1017:    * @throws InstanceNotFoundException if the bean can not be found.
1018:    * @throws ListenerNotFoundException if the specified listener
1019:    *                                   is not registered with the bean.
1020:    * @throws SecurityException if a security manager exists and the
1021:    *                           caller's permissions don't imply {@link
1022:    *                           MBeanPermission(String,String,ObjectName,String)
1023:    *                           <code>MBeanPermission(className, null, name,
1024:    *                           "removeNotificationListener")</code>}.
1025:    * @see #addNotificationListener(ObjectName, NotificationListener,
1026:    *                               NotificationFilter, Object)
1027:    * @see NotificationEmitter#removeNotificationListener(NotificationListener,
1028:    *                                                     NotificationFilter,
1029:    *                                                     Object)
1030:    */
1031:   void removeNotificationListener(ObjectName name,
1032:                                   NotificationListener listener,
1033:                                   NotificationFilter filter,
1034:                                   Object passback)
1035:     throws InstanceNotFoundException, ListenerNotFoundException;
1036: 
1037:   /**
1038:    * Removes the specified listener from the list of recipients
1039:    * of notifications from the supplied bean.  This includes all
1040:    * combinations of filters and passback objects registered for
1041:    * this listener.  For more specific removal of listeners, see
1042:    * {@link #removeNotificationListener(ObjectName,
1043:    * ObjectName,NotificationFilter,Object)}
1044:    *
1045:    * @param name the name of the management bean from which the
1046:    *             listener should be removed.
1047:    * @param listener the name of the listener to remove.
1048:    * @throws InstanceNotFoundException if a name doesn't match a registered
1049:    *                                   bean.
1050:    * @throws ListenerNotFoundException if the specified listener
1051:    *                                   is not registered with the bean.
1052:    * @throws SecurityException if a security manager exists and the
1053:    *                           caller's permissions don't imply {@link
1054:    *                           MBeanPermission(String,String,ObjectName,String)
1055:    *                           <code>MBeanPermission(className, null, name,
1056:    *                           "removeNotificationListener")</code>}.
1057:    * @see #addNotificationListener(NotificationListener, NotificationFilter,
1058:    *                               java.lang.Object)
1059:    * @see NotificationBroadcaster#removeNotificationListener(NotificationListener)
1060:    */
1061:   void removeNotificationListener(ObjectName name, ObjectName listener)
1062:     throws InstanceNotFoundException, ListenerNotFoundException;
1063: 
1064:   /**
1065:    * Removes the specified listener from the list of recipients
1066:    * of notifications from the supplied bean.  Only the first instance with
1067:    * the supplied filter and passback object is removed.
1068:    * <code>null</code> is used as a valid value for these parameters,
1069:    * rather than as a way to remove all registration instances for
1070:    * the specified listener; for this behaviour instead, see
1071:    * {@link #removeNotificationListener(ObjectName, ObjectName)}.
1072:    *
1073:    * @param name the name of the management bean from which the
1074:    *             listener should be removed.
1075:    * @param listener the name of the listener to remove.
1076:    * @param filter the filter of the listener to remove.
1077:    * @param passback the passback object of the listener to remove.
1078:    * @throws InstanceNotFoundException if a name doesn't match a registered
1079:    *                                   bean.
1080:    * @throws ListenerNotFoundException if the specified listener
1081:    *                                   is not registered with the bean.
1082:    * @throws SecurityException if a security manager exists and the
1083:    *                           caller's permissions don't imply {@link
1084:    *                           MBeanPermission(String,String,ObjectName,String)
1085:    *                           <code>MBeanPermission(className, null, name,
1086:    *                           "removeNotificationListener")</code>}.
1087:    * @see #addNotificationListener(ObjectName, NotificationListener,
1088:    *                               NotificationFilter, Object)
1089:    * @see NotificationEmitter#removeNotificationListener(NotificationListener,
1090:    *                                                     NotificationFilter,
1091:    *                                                     Object)
1092:    */
1093:   void removeNotificationListener(ObjectName name,
1094:                                   ObjectName listener,
1095:                                   NotificationFilter filter,
1096:                                   Object passback)
1097:     throws InstanceNotFoundException, ListenerNotFoundException;
1098: 
1099:   /**
1100:    * Sets the value of the specified attribute of the supplied
1101:    * management bean.
1102:    *
1103:    * @param name the name of the management bean.
1104:    * @param attribute the attribute to set.
1105:    * @throws InstanceNotFoundException if the bean can not be found.
1106:    * @throws AttributeNotFoundException if the attribute does not
1107:    *                                    correspond to an attribute
1108:    *                                    of the bean.
1109:    * @throws InvalidAttributeValueException if the value is invalid
1110:    *                                        for this particular
1111:    *                                        attribute of the bean.
1112:    * @throws MBeanException if setting the attribute causes
1113:    *                        the bean to throw an exception (which
1114:    *                        becomes the cause of this exception).
1115:    * @throws ReflectionException if an exception occurred in trying
1116:    *                             to use the reflection interface
1117:    *                             to lookup the attribute.  The
1118:    *                             thrown exception is the cause of
1119:    *                             this exception.
1120:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1121:    *                                    is thrown by the server due to a
1122:    *                                    <code>null</code> bean or attribute
1123:    *                                    name.
1124:    * @throws SecurityException if a security manager exists and the
1125:    *                           caller's permissions don't imply {@link
1126:    *                           MBeanPermission(String,String,ObjectName,String)
1127:    *                           <code>MBeanPermission(className, name, bean,
1128:    *                           "setAttribute")</code>}.
1129:    * @see #getAttribute(ObjectName, String)
1130:    * @see DynamicMBean#setAttribute(Attribute)
1131:    */
1132:   void setAttribute(ObjectName name, Attribute attribute)
1133:     throws InstanceNotFoundException, AttributeNotFoundException,
1134:            InvalidAttributeValueException, MBeanException,
1135:            ReflectionException;
1136: 
1137:   /**
1138:    * Sets the value of each of the specified attributes
1139:    * of the supplied management bean to that specified by
1140:    * the {@link Attribute} object.  The returned list contains
1141:    * the attributes that were set and their new values.
1142:    *
1143:    * @param name the name of the management bean.
1144:    * @param attributes the attributes to set.
1145:    * @return a list of the changed attributes.
1146:    * @throws InstanceNotFoundException if the bean can not be found.
1147:    * @throws ReflectionException if an exception occurred in trying
1148:    *                             to use the reflection interface
1149:    *                             to lookup the attribute.  The
1150:    *                             thrown exception is the cause of
1151:    *                             this exception.
1152:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1153:    *                                    is thrown by the server due to a
1154:    *                                    <code>null</code> bean or attribute
1155:    *                                    list.
1156:    * @throws SecurityException if a security manager exists and the
1157:    *                           caller's permissions don't imply {@link
1158:    *                           MBeanPermission(String,String,ObjectName,String)
1159:    *                           <code>MBeanPermission(className, null, bean,
1160:    *                           "setAttribute")</code>}.  Additionally,
1161:    *                           for an attribute name, <code>n</code>, the
1162:    *                           caller's permission must imply {@link
1163:    *                           MBeanPermission(String,String,ObjectName,String)
1164:    *                           <code>MBeanPermission(className, n, bean,
1165:    *                           "setAttribute")</code>} or that attribute will
1166:    *                           not be included.
1167:    * @see #getAttributes(ObjectName, String[])
1168:    * @see DynamicMBean#setAttributes(AttributeList)
1169:    */
1170:   AttributeList setAttributes(ObjectName name, AttributeList attributes)
1171:     throws InstanceNotFoundException, ReflectionException;
1172: 
1173:   /**
1174:    * Unregisters the specified management bean.  Following this operation,
1175:    * the bean instance is no longer accessible from the server via this
1176:    * name.  Prior to unregistering the bean, the
1177:    * {@link MBeanRegistration#preDeregister()} method will be called if
1178:    * the bean implements the {@link MBeanRegistration} interface.
1179:    *
1180:    * @param name the name of the management bean.
1181:    * @throws InstanceNotFoundException if the bean can not be found.
1182:    * @throws MBeanRegistrationException if an exception occurs in
1183:    *                                    calling the preDeregister
1184:    *                                    method.
1185:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1186:    *                                    is thrown by the server due to a
1187:    *                                    <code>null</code> bean name or a
1188:    *                                    request being made to unregister the
1189:    *                                    {@link MBeanServerDelegate} bean.
1190:    * @throws SecurityException if a security manager exists and the
1191:    *                           caller's permissions don't imply {@link
1192:    *                           MBeanPermission(String,String,ObjectName,String)
1193:    *                           <code>MBeanPermission(className, null, name,
1194:    *                           "unregisterMBean")</code>}.
1195:    */
1196:   void unregisterMBean(ObjectName name)
1197:     throws InstanceNotFoundException, MBeanRegistrationException;
1198: 
1199: }