Source for javax.management.remote.rmi.RMIConnection

   1: /* RMIConnection.java -- RMI object representing a MBean server connection.
   2:    Copyright (C) 2007, 2008 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.remote.rmi;
  39: 
  40: import java.io.Closeable;
  41: import java.io.IOException;
  42: 
  43: import java.rmi.MarshalledObject;
  44: import java.rmi.Remote;
  45: 
  46: import java.util.Set;
  47: 
  48: import javax.management.AttributeList;
  49: import javax.management.AttributeNotFoundException;
  50: import javax.management.InstanceAlreadyExistsException;
  51: import javax.management.InstanceNotFoundException;
  52: import javax.management.IntrospectionException;
  53: import javax.management.InvalidAttributeValueException;
  54: import javax.management.ListenerNotFoundException;
  55: import javax.management.MBeanInfo;
  56: import javax.management.MBeanException;
  57: import javax.management.MBeanRegistrationException;
  58: import javax.management.NotCompliantMBeanException;
  59: import javax.management.ObjectInstance;
  60: import javax.management.ObjectName;
  61: import javax.management.ReflectionException;
  62: 
  63: import javax.management.remote.NotificationResult;
  64: 
  65: import javax.security.auth.Subject;
  66: 
  67: /**
  68:  * <p>
  69:  * RMI interface for forwarding requests to a remote
  70:  * {@link javax.management.MBeanServer}.  This interface
  71:  * parallels the {@link javax.management.MBeanServerConnection}
  72:  * interface, providing a way of invoking those methods using
  73:  * the RMI protocol.  When a client wishes to call a method
  74:  * of an MBean server using RMI, the method is called on the stub
  75:  * on the client side, which serializes the object parameters
  76:  * and sends them to the server where they are deserialized and
  77:  * an implementation of this interface forwards them to the
  78:  * appropriate MBean server.  Return values follow the same
  79:  * process, only in reverse.  Each client obtains its own
  80:  * implementation of this interface from an {@link RMIServer}
  81:  * instance.
  82:  * </p>
  83:  * <p>
  84:  * Implementations of this interface do more than simply
  85:  * forward requests directly to the server.  The arguments
  86:  * of the server methods are wrapped in {@link MarshalledObject}
  87:  * instances, so that the correct classloader can be used to
  88:  * deserialize the arguments.  When a method is called, the
  89:  * implementation must first retrieve the appropriate classloader
  90:  * and then use it to deserialize the marshalled object.  Unless
  91:  * explicitly specified in the documentation for the method,
  92:  * a parameter of the type {@link MarshalledObject} or an array
  93:  * of that type should not be {@code null}.
  94:  * </p>
  95:  * <p>
  96:  * Security is also handled by this interface, as the methods
  97:  * use an additional {@link javax.security.auth.Subject} parameter
  98:  * for role delegation.
  99:  * </p>
 100:  *
 101:  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
 102:  * @since 1.5
 103:  */
 104: public interface RMIConnection
 105:   extends Closeable, Remote
 106: {
 107: 
 108:   /**
 109:    * Handles {@link
 110:    * MBeanServerConnection#addNotificationListener(ObjectName,
 111:    * ObjectName, NotificationFilter, Object)} by
 112:    * registering the supplied listener with the specified management
 113:    * bean.  Notifications emitted by the management bean are forwarded
 114:    * to the listener via the server, which will convert any MBean
 115:    * references in the source to portable {@link ObjectName}
 116:    * instances.  The notification is otherwise unchanged.  The filter
 117:    * and handback object are wrapped in a {@link MarshalledObject}
 118:    * so that they are deserialised using the bean's classloader.
 119:    *
 120:    * @param name the name of the management bean with which the listener
 121:    *             should be registered.
 122:    * @param listener the listener which will handle notifications from
 123:    *                 the bean.
 124:    * @param filter a wrapper containing a filter to apply to incoming
 125:    *               notifications, or <code>null</code> if no filtering
 126:    *               should be applied.
 127:    * @param passback a wrapper containing an object to be passed to the
 128:    *                 listener when a notification is emitted.
 129:    * @param delegationSubject a {@link javax.security.auth.Subject} instance
 130:    *                          containing the delegation principles or
 131:    *                          {@code null} if authentication is used.
 132:    * @throws InstanceNotFoundException if the name of the management bean
 133:    *                                   could not be resolved.
 134:    * @throws RuntimeOperationsException if the bean associated with the given
 135:    *                                    object name is not a
 136:    *                                    {@link NotificationListener}.  This
 137:    *                                    exception wraps an
 138:    *                                    {@link IllegalArgumentException}.
 139:    * @throws SecurityException if the client or delegated subject (if any)
 140:    *                           does not have permission to invoke this operation.
 141:    * @throws IOException if an I/O error occurred in communicating with
 142:    *                     the bean server.
 143:    * @see #removeNotificationListener(ObjectName, ObjectName,
 144:    *                                  javax.security.auth.Subject)
 145:    * @see #removeNotificationListener(ObjectName, ObjectName,
 146:    *                                  java.rmi.MarshalledObject,
 147:    *                                  java.rmi.MarshalledObject,
 148:    *                                  javax.security.auth.Subject)
 149:    * @see #removeNotificationListeners(ObjectName, Integer[],
 150:    *                                  javax.security.auth.Subject)
 151:    * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
 152:    *                                                      NotificationFilter,
 153:    *                                                      Object)
 154:    */
 155:   void addNotificationListener(ObjectName name, ObjectName listener,
 156:                    MarshalledObject filter, MarshalledObject passback,
 157:                    Subject delegationSubject)
 158:     throws InstanceNotFoundException, IOException;
 159: 
 160:   /**
 161:    * Handles {@link
 162:    * MBeanServerConnection#addNotificationListener(ObjectName,
 163:    * NotificationListener, NotificationFilter, Object)} by
 164:    * registering for notifications from the specified management
 165:    * beans.  The array of filters is assumed to be aligned with
 166:    * the array of bean names, so that the notifications from each
 167:    * bean are matched against the appropriate filter (or left as
 168:    * is if the filter is {@code null}.  Notifications emitted by
 169:    * the management beans are forwarded to a local listener created
 170:    * by this method, via the server, which converts any MBean
 171:    * references in the source to portable {@link ObjectName}
 172:    * instances.  The notification is otherwise unchanged.
 173:    * </p>
 174:    * <p>
 175:    * This local listener buffers the notifications for retrieval by
 176:    * {@link #fetchNotifications(long,int,long).  This method returns
 177:    * an array of listener identifiers which aligns with the supplied
 178:    * array of beans so that the appropriate listener can be identified
 179:    * by the client, which retains its own listener and handback object.
 180:    * The filters are wrapped in {@link MarshalledObject}s so that they are
 181:    * deserialised using the bean's classloader.
 182:    * </p>
 183:    *
 184:    * @param names the names of the management bean whose notifications
 185:    *              should be recorded.
 186:    * @param filters an array of wrappers containing filters to apply to
 187:    *                incoming notifications.  An element may be <code>null</code>
 188:    *                if no filtering should be applied to a bean's notifications.
 189:    * @param delegationSubjects an array of {@link javax.security.auth.Subject}
 190:    *                          instances containing the delegation principles for
 191:    *                          each listener.  An element may be {@code null} if
 192:    *                          authentication is used instead, or the entire
 193:    *                          argument itself may be {@code null}.  In the latter
 194:    *                          case, this is treated as an array of {@code null}
 195:    *                          values.
 196:    * @return an array of integers which act as listener identifiers, so that
 197:    *         notifications retrieved from {@link #fetchNotifications(long,int,long)
 198:    *         can be matched to the beans they were emitted from.  The array is
 199:    *         aligned against the array of beans supplied to this methods, so that
 200:    *         the identifier in position 0 represents the bean in position 0 of the
 201:    *         input array.
 202:    * @throws IllegalArgumentException if the {@code names} or {@code filters} array
 203:    *                                  is {@code null}, the {@code names} array contains
 204:    *                                  a {@code null} value or the three arrays are not
 205:    *                                  of the same size.
 206:    * @throws ClassCastException if an element of the {@code filters} array unmarshalls
 207:    *                            as a non-null object that is not a {@link NotificationFilter}.
 208:    * @throws InstanceNotFoundException if the name of one of the management beans
 209:    *                                   could not be resolved.
 210:    * @throws SecurityException if, for one of the beans, the client or delegated subject
 211:    *                           (if any) does not have permission to invoke this operation.
 212:    * @throws IOException if an I/O error occurred in communicating with
 213:    *                     the bean server.
 214:    * @see #removeNotificationListener(ObjectName, ObjectName,
 215:    *                                  javax.security.auth.Subject)
 216:    * @see #removeNotificationListener(ObjectName, ObjectName,
 217:    *                                  java.rmi.MarshalledObject,
 218:    *                                  java.rmi.MarshalledObject,
 219:    *                                  javax.security.auth.Subject)
 220:    * @see #removeNotificationListeners(ObjectName, Integer[],
 221:    *                                  javax.security.auth.Subject)
 222:    * @see NotificationBroadcaster#addNotificationListener(NotificationListener,
 223:    *                                                      NotificationFilter,
 224:    *                                                      Object)
 225:    */
 226:   Integer[] addNotificationListeners(ObjectName[] names, MarshalledObject[] filters,
 227:                      Subject[] delegationSubjects)
 228:     throws InstanceNotFoundException, IOException;
 229: 
 230:   /**
 231:    * Closes the connection and unexports the RMI object implementing this
 232:    * interface.  Following this call, future method calls to this instance
 233:    * will fail.
 234:    *
 235:    * @throws IOException if there is an I/O error in transmitting the close
 236:    *                     request via RMI, closing the connection, or unexporting
 237:    *                     the RMI object.
 238:    */
 239:   void close()
 240:     throws IOException;
 241: 
 242:   /**
 243:    * <p>
 244:    * Handles {@link
 245:    * MBeanServerConnection#createMBean(String, ObjectName,
 246:    * Object[], String[])}.  The array of parameters is wrapped in
 247:    * a {@link MarshalledObject} so that it is deserialised using the
 248:    * bean's classloader.
 249:    * </p>
 250:    * <p>
 251:    * Instantiates a new instance of the specified management bean
 252:    * using the given constructor and registers it with the server
 253:    * under the supplied name.  The class is loaded using the
 254:    * {@link javax.management.loading.ClassLoaderRepository default
 255:    * loader repository} of the server. 
 256:    * </p>
 257:    * <p>
 258:    * If the name supplied is <code>null</code>, then the bean is
 259:    * expected to implement the {@link MBeanRegistration} interface.
 260:    * The {@link MBeanRegistration#preRegister preRegister} method
 261:    * of this interface will be used to obtain the name in this case.
 262:    * </p>
 263:    * 
 264:    * @param className the class of the management bean, of which
 265:    *                  an instance should be created.
 266:    * @param name the name to register the new bean with.  This may
 267:    *             be <code>null</code>.
 268:    * @param params the parameters for the bean's constructor, encapsulated
 269:    *               in a {@link MarshalledObject}.  If this parameter is
 270:    *               <code>null</code>, it will be judged equivalent to an
 271:    *               empty array.
 272:    * @param sig the signature of the constructor to use.  If this parameter
 273:    *            is <code>null</code>, it will be judged equivalent to an
 274:    *            empty array.
 275:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 276:    *                          containing the delegation principles.  This may be
 277:    *                          {@code null} is authentication is used instead.
 278:    * @return an {@link ObjectInstance} containing the {@link ObjectName}
 279:    *         and Java class name of the created instance.
 280:    * @throws ReflectionException if an exception occurs in creating
 281:    *                             an instance of the bean.
 282:    * @throws InstanceAlreadyExistsException if a matching instance
 283:    *                                        already exists.
 284:    * @throws MBeanRegistrationException if an exception occurs in
 285:    *                                    calling the preRegister
 286:    *                                    method.
 287:    * @throws MBeanException if the bean's constructor throws an exception.
 288:    * @throws NotCompliantMBeanException if the created bean is not
 289:    *                                    compliant with the JMX specification.
 290:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 291:    *                                    is thrown by the server due to a
 292:    *                                    <code>null</code> class name or object
 293:    *                                    name or if the object name is a pattern.
 294:    * @throws SecurityException if the client or delegated subject (if any) does
 295:    *                           not have permission to invoke this operation.
 296:    * @throws IOException if an I/O error occurred in communicating with
 297:    *                     the bean server.
 298:    */  
 299:   ObjectInstance createMBean(String className, ObjectName name,
 300:                  MarshalledObject params, String[] sig,
 301:                  Subject delegationSubject)
 302:     throws ReflectionException, InstanceAlreadyExistsException,
 303:        MBeanRegistrationException, MBeanException,
 304:        NotCompliantMBeanException, IOException;
 305: 
 306:   /**
 307:    * <p>
 308:    * Handles {@link
 309:    * MBeanServerConnection#createMBean(String, ObjectName,
 310:    * ObjectName, Object[], String[])}.  The array of parameters is
 311:    * wrapped in a {@link MarshalledObject} so that it is deserialised
 312:    * using the bean's classloader.
 313:    * </p>
 314:    * <p>
 315:    * Instantiates a new instance of the specified management bean
 316:    * using the given constructor and registers it with the server
 317:    * under the supplied name.  The class is loaded using the
 318:    * given class loader.  If this argument is <code>null</code>,
 319:    * then the same class loader as was used to load the server
 320:    * is used. 
 321:    * </p>
 322:    * <p>
 323:    * If the name supplied is <code>null</code>, then the bean is
 324:    * expected to implement the {@link MBeanRegistration} interface.
 325:    * The {@link MBeanRegistration#preRegister preRegister} method
 326:    * of this interface will be used to obtain the name in this case.
 327:    * </p>
 328:    * 
 329:    * @param className the class of the management bean, of which
 330:    *                  an instance should be created.
 331:    * @param name the name to register the new bean with.  This may
 332:    *             be <code>null</code>.
 333:    * @param loaderName the name of the class loader.
 334:    * @param params the parameters for the bean's constructor, encapsulated
 335:    *               in a {@link MarshalledObject}.  If this parameter is
 336:    *               <code>null</code>, it will be judged equivalent to an
 337:    *               empty array.
 338:    * @param sig the signature of the constructor to use.  If this parameter
 339:    *            is <code>null</code>, it will be judged equivalent to an
 340:    *            empty array.
 341:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 342:    *                          containing the delegation principles.  This may be
 343:    *                          {@code null} is authentication is used instead.
 344:    * @return an {@link ObjectInstance} containing the {@link ObjectName}
 345:    *         and Java class name of the created instance.
 346:    * @throws ReflectionException if an exception occurs in creating
 347:    *                             an instance of the bean.
 348:    * @throws InstanceAlreadyExistsException if a matching instance
 349:    *                                        already exists.
 350:    * @throws MBeanRegistrationException if an exception occurs in
 351:    *                                    calling the preRegister
 352:    *                                    method.
 353:    * @throws MBeanException if the bean's constructor throws an exception.
 354:    * @throws NotCompliantMBeanException if the created bean is not
 355:    *                                    compliant with the JMX specification.
 356:    * @throws InstanceNotFoundException if the specified class loader is not
 357:    *                                   registered with the server.
 358:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 359:    *                                    is thrown by the server due to a
 360:    *                                    <code>null</code> class name or object
 361:    *                                    name or if the object name is a pattern.
 362:    * @throws SecurityException if the client or delegated subject (if any) does
 363:    *                           not have permission to invoke this operation.
 364:    * @throws IOException if an I/O error occurred in communicating with
 365:    *                     the bean server.
 366:    */
 367:   ObjectInstance createMBean(String className, ObjectName name,
 368:                  ObjectName loaderName, MarshalledObject params,
 369:                  String[] sig, Subject delegationSubject)
 370:     throws ReflectionException, InstanceAlreadyExistsException,
 371:        MBeanRegistrationException, MBeanException,
 372:        NotCompliantMBeanException, InstanceNotFoundException,
 373:        IOException;
 374: 
 375:   /**
 376:    * <p>
 377:    * Handles {@link
 378:    * MBeanServerConnection#createMBean(String, ObjectName,
 379:    * ObjectName)} by instantiating a new instance of the specified
 380:    * management bean using the default constructor and registering
 381:    * it with the server under the supplied name.  The class is loaded
 382:    * using the given class loader.  If this argument is <code>null</code>,
 383:    * then the same class loader as was used to load the server
 384:    * is used.
 385:    * </p>
 386:    * <p>
 387:    * If the name supplied is <code>null</code>, then the bean is
 388:    * expected to implement the {@link MBeanRegistration} interface.
 389:    * The {@link MBeanRegistration#preRegister preRegister} method
 390:    * of this interface will be used to obtain the name in this case.
 391:    * </p>
 392:    * <p>
 393:    * This method is equivalent to calling {@link 
 394:    * #createMBean(String, ObjectName, ObjectName, Object[], String)
 395:    * <code>createMBean(className, name, loaderName, (Object[]) null,
 396:    * (String) null)</code>} with <code>null</code> parameters
 397:    * and signature.
 398:    * </p>
 399:    *
 400:    * @param className the class of the management bean, of which
 401:    *                  an instance should be created.
 402:    * @param name the name to register the new bean with.  This may
 403:    *             be <code>null</code>.
 404:    * @param loaderName the name of the class loader.
 405:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 406:    *                          containing the delegation principles.  This may be
 407:    *                          {@code null} is authentication is used instead.
 408:    * @return an {@link ObjectInstance} containing the {@link ObjectName}
 409:    *         and Java class name of the created instance.
 410:    * @throws ReflectionException if an exception occurs in creating
 411:    *                             an instance of the bean.
 412:    * @throws InstanceAlreadyExistsException if a matching instance
 413:    *                                        already exists.
 414:    * @throws MBeanRegistrationException if an exception occurs in
 415:    *                                    calling the preRegister
 416:    *                                    method.
 417:    * @throws MBeanException if the bean's constructor throws an exception.
 418:    * @throws NotCompliantMBeanException if the created bean is not
 419:    *                                    compliant with the JMX specification.
 420:    * @throws InstanceNotFoundException if the specified class loader is not
 421:    *                                   registered with the server.
 422:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 423:    *                                    is thrown by the server due to a
 424:    *                                    <code>null</code> class name or object
 425:    *                                    name or if the object name is a pattern.
 426:    * @throws SecurityException if the client or delegated subject (if any) does
 427:    *                           not have permission to invoke this operation.
 428:    * @throws IOException if an I/O error occurred in communicating with
 429:    *                     the bean server.
 430:    * @see #createMBean(String, ObjectName, ObjectName, MarshalledObject,
 431:    *                   String[], Subject)
 432:    */
 433:   ObjectInstance createMBean(String className, ObjectName name, 
 434:                  ObjectName loaderName, Subject delegationSubject)
 435:     throws ReflectionException, InstanceAlreadyExistsException,
 436:        MBeanRegistrationException, MBeanException,
 437:        NotCompliantMBeanException, InstanceNotFoundException,
 438:        IOException;
 439: 
 440:   /**
 441:    * <p>
 442:    * Handles {@link
 443:    * MBeanServerConnection#createMBean(String, ObjectName)} by
 444:    * instantiating a new instance of the specified management bean
 445:    * using the default constructor and registering it with the server
 446:    * under the supplied name.  The class is loaded using the
 447:    * {@link javax.management.loading.ClassLoaderRepository default
 448:    * loader repository} of the server. 
 449:    * </p>
 450:    * <p>
 451:    * If the name supplied is <code>null</code>, then the bean is
 452:    * expected to implement the {@link MBeanRegistration} interface.
 453:    * The {@link MBeanRegistration#preRegister preRegister} method
 454:    * of this interface will be used to obtain the name in this case.
 455:    * </p>
 456:    * <p>
 457:    * This method is equivalent to calling {@link 
 458:    * #createMBean(String, ObjectName, Object[], String[])
 459:    * <code>createMBean(className, name, (Object[]) null,
 460:    * (String[]) null)</code>} with <code>null</code> parameters
 461:    * and signature.
 462:    * </p>
 463:    *
 464:    * @param className the class of the management bean, of which
 465:    *                  an instance should be created.
 466:    * @param name the name to register the new bean with.  This may
 467:    *             be <code>null</code>.
 468:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 469:    *                          containing the delegation principles.  This may be
 470:    *                          {@code null} is authentication is used instead.
 471:    * @return an {@link ObjectInstance} containing the {@link ObjectName}
 472:    *         and Java class name of the created instance.
 473:    * @throws ReflectionException if an exception occurs in creating
 474:    *                             an instance of the bean.
 475:    * @throws InstanceAlreadyExistsException if a matching instance
 476:    *                                        already exists.
 477:    * @throws MBeanRegistrationException if an exception occurs in
 478:    *                                    calling the preRegister
 479:    *                                    method.
 480:    * @throws MBeanException if the bean's constructor throws an exception.
 481:    * @throws NotCompliantMBeanException if the created bean is not
 482:    *                                    compliant with the JMX specification.
 483:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 484:    *                                    is thrown by the server due to a
 485:    *                                    <code>null</code> class name or object
 486:    *                                    name or if the object name is a pattern.
 487:    * @throws SecurityException if the client or delegated subject (if any) does
 488:    *                           not have permission to invoke this operation.
 489:    * @throws IOException if an I/O error occurred in communicating with
 490:    *                     the bean server.
 491:    * @see #createMBean(String, ObjectName, MarshalledObject, String[], Subject)
 492:    */
 493:   ObjectInstance createMBean(String className, ObjectName name,
 494:                  Subject delegationSubject)
 495:     throws ReflectionException, InstanceAlreadyExistsException,
 496:        MBeanRegistrationException, MBeanException,
 497:        NotCompliantMBeanException, IOException;
 498: 
 499:   /**
 500:    * <p>
 501:    * Retrieves any waiting notifications from the server.  When notifications
 502:    * are requested using the {@link #addNotificationListeners(ObjectName[],
 503:    * MarshalledObject[], Subject[])} method, the server sets up an internal
 504:    * listener to receive notifications from the bean and buffer them.  When
 505:    * this method is called, these buffered notifications can be retrieved.
 506:    * </p>
 507:    * <p>
 508:    * The blocking behaviour of this method depends on the timeout value specified.
 509:    * If there are no waiting notifications in the buffer, a value of 0 will cause
 510:    * the method to return immediately.  Conversely, if the value is
 511:    * {@link Long#MAX_VALUE}, then it will wait indefinitely until a notification
 512:    * arrives. For any other value, it waits until a notification arrives or the
 513:    * number of milliseconds specified by the timeout value is exceeded.  The
 514:    * behaviour for a negative timeout value is undefined.
 515:    * </p>
 516:    * <p>
 517:    * For a notification to be returned, the following criteria must be fulfilled:
 518:    * </p>
 519:    * <ul>
 520:    * <li>the client must have previously requested notifications from at least
 521:    * one bean</li>
 522:    * <li>a bean from which notifications have been requested must have emitted
 523:    * a notification since the last call to this method</li>
 524:    * <li>the emitted notification must pass through any filters established
 525:    * when notifications were requested</li>
 526:    * <li>the sequence number of the notification must be greater than or equal
 527:    * to the specified sequence number (if non-negative)</li>
 528:    * </ul>
 529:    *
 530:    * @param sequenceNumber the sequence number of each notification returned
 531:    *                       must be greater than or equal to this value.  If
 532:    *                       the number is negative, this is interpreted as
 533:    *                       meaning the sequence number of the next notification
 534:    *                       and so all notifications are allowed through.
 535:    * @param maxNotifications the maximum number of notifications to return.
 536:    *                         This does not include any duplicates so the
 537:    *                         number of actual notifications returned may
 538:    *                         be larger.
 539:    * @param timeout the number of milliseconds to wait for a notification
 540:    *                if the buffer is empty.  <code>0</code> causes the
 541:    *                method to return immediately even if there are no
 542:    *                notifications available (non-blocking behaviour) while
 543:    *                a value of {@link Long#MAX_VALUE} causes it to wait
 544:    *                indefinitely (blocking behaviour).  The response to
 545:    *                a negative value is undefined.
 546:    * @return a {@link NotificationResult} object containing the buffered
 547:    *         notifications.
 548:    * @throws IOException if an I/O error occurs.
 549:    */
 550:   NotificationResult fetchNotifications(long sequenceNumber,
 551:                     int maxNotifications,
 552:                     long timeout)
 553:     throws IOException;
 554: 
 555:   /**
 556:    * Handles {@link
 557:    * MBeanServerConnection#getAttribute(ObjectName, String)},
 558:    * returning the value of the supplied attribute from the specified
 559:    * management bean.
 560:    *
 561:    * @param bean the bean to retrieve the value from.
 562:    * @param name the name of the attribute to retrieve.
 563:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 564:    *                          containing the delegation principles.  This may be
 565:    *                          {@code null} is authentication is used instead.
 566:    * @return the value of the attribute.
 567:    * @throws AttributeNotFoundException if the attribute could not be
 568:    *                                    accessed from the bean.
 569:    * @throws MBeanException if the management bean's accessor throws
 570:    *                        an exception.
 571:    * @throws InstanceNotFoundException if the bean can not be found.
 572:    * @throws ReflectionException if an exception was thrown in trying
 573:    *                             to invoke the bean's accessor.
 574:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 575:    *                                    is thrown by the server due to a
 576:    *                                    <code>null</code> bean or attribute
 577:    *                                    name.
 578:    * @throws SecurityException if the client or delegated subject (if any) does
 579:    *                           not have permission to invoke this operation.
 580:    * @throws IOException if an I/O error occurred in communicating with
 581:    *                     the bean server.
 582:    * @see DynamicMBean#getAttribute(String)
 583:    */
 584:   Object getAttribute(ObjectName bean, String name, Subject delegationSubject)
 585:     throws MBeanException, AttributeNotFoundException,
 586:        InstanceNotFoundException, ReflectionException,
 587:        IOException;
 588: 
 589:   /**
 590:    * Handles {@link
 591:    * MBeanServerConnection#getAttribute(ObjectName, String)},
 592:    * returning the values of the named attributes from the specified
 593:    * management bean.
 594:    *
 595:    * @param bean the bean to retrieve the value from.
 596:    * @param names the names of the attributes to retrieve.
 597:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 598:    *                          containing the delegation principles.  This may be
 599:    *                          {@code null} is authentication is used instead.
 600:    * @return the values of the attributes.
 601:    * @throws InstanceNotFoundException if the bean can not be found.
 602:    * @throws ReflectionException if an exception was thrown in trying
 603:    *                             to invoke the bean's accessor.
 604:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 605:    *                                    is thrown by the server due to a
 606:    *                                    <code>null</code> bean or attribute
 607:    *                                    name.
 608:    * @throws SecurityException if the client or delegated subject (if any) does
 609:    *                           not have permission to invoke this operation.
 610:    * @throws IOException if an I/O error occurred in communicating with
 611:    *                     the bean server.
 612:    * @see DynamicMBean#getAttributes(String[])
 613:    */
 614:   AttributeList getAttributes(ObjectName bean, String[] names,
 615:                   Subject delegationSubject)
 616:     throws InstanceNotFoundException, ReflectionException,
 617:        IOException;
 618: 
 619:   /**
 620:    * Returns the unique identifier for this connection to the RMI
 621:    * server.  
 622:    *
 623:    * @return the connection ID.
 624:    * @throws IOException if an I/O error occurred.
 625:    */
 626:   String getConnectionId()
 627:     throws IOException;
 628: 
 629:   /**
 630:    * Handles {@link
 631:    * MBeanServerConnection#getDefaultDomain()} by returning the default
 632:    * domain this server applies to beans that have no specified domain.
 633:    *
 634:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 635:    *                          containing the delegation principles.  This may be
 636:    *                          {@code null} is authentication is used instead.
 637:    * @return the default domain.
 638:    * @throws SecurityException if the client or delegated subject (if any) does
 639:    *                           not have permission to invoke this operation.
 640:    * @throws IOException if an I/O error occurred in communicating with
 641:    *                     the bean server.
 642:    */
 643:   String getDefaultDomain(Subject delegationSubject)
 644:     throws IOException;
 645: 
 646:   /**
 647:    * Handles {@link
 648:    * MBeanServerConnection#getDomains()} by returning an array
 649:    * containing all the domains used by beans registered with
 650:    * this server.  The ordering of the array is undefined.
 651:    *
 652:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 653:    *                          containing the delegation principles.  This may be
 654:    *                          {@code null} is authentication is used instead.
 655:    * @return the list of domains.
 656:    * @throws SecurityException if the client or delegated subject (if any) does
 657:    *                           not have permission to invoke this operation.
 658:    * @throws IOException if an I/O error occurred in communicating with
 659:    *                     the bean server.
 660:    * @see ObjectName#getDomain()
 661:    */
 662:   String[] getDomains(Subject delegationSubject)
 663:     throws IOException;
 664: 
 665:   /**
 666:    * Handles {@link
 667:    * MBeanServerConnection#getMBeanCount()} by returning the number of
 668:    * management beans registered with this server.
 669:    *
 670:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 671:    *                          containing the delegation principles.  This may be
 672:    *                          {@code null} is authentication is used instead.
 673:    * @return the number of registered beans.
 674:    * @throws SecurityException if the client or delegated subject (if any) does
 675:    *                           not have permission to invoke this operation.
 676:    * @throws IOException if an I/O error occurred in communicating with
 677:    *                     the bean server.
 678:    */
 679:   Integer getMBeanCount(Subject delegationSubject)
 680:     throws IOException;
 681: 
 682:   /**
 683:    * Handles {@link
 684:    * MBeanServerConnection#getMBeanInfo(ObjectName)} by returning
 685:    * information on the given management bean.
 686:    *
 687:    * @param name the name of the management bean.
 688:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 689:    *                          containing the delegation principles.  This may be
 690:    *                          {@code null} is authentication is used instead.
 691:    * @return an instance of {@link MBeanInfo} for the bean.
 692:    * @throws IntrospectionException if an exception occurs in examining
 693:    *                                the bean.
 694:    * @throws InstanceNotFoundException if the bean can not be found.
 695:    * @throws ReflectionException if an exception occurs when trying
 696:    *                             to invoke {@link DynamicMBean#getMBeanInfo()}
 697:    *                             on the bean.
 698:    * @throws SecurityException if the client or delegated subject (if any) does
 699:    *                           not have permission to invoke this operation.
 700:    * @throws IOException if an I/O error occurred in communicating with
 701:    *                     the bean server.
 702:    * @see DynamicMBean#getMBeanInfo()
 703:    */
 704:   MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject)
 705:     throws InstanceNotFoundException, IntrospectionException,
 706:        ReflectionException, IOException;
 707: 
 708:   /**
 709:    * Handles {@link
 710:    * MBeanServerConnection#getObjectInstance(ObjectName)} by returning
 711:    * the {@link ObjectInstance} created for the specified management
 712:    * bean on registration.
 713:    *
 714:    * @param name the name of the bean.
 715:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 716:    *                          containing the delegation principles.  This may be
 717:    *                          {@code null} is authentication is used instead.
 718:    * @return the corresponding {@link ObjectInstance} instance.
 719:    * @throws InstanceNotFoundException if the bean can not be found.
 720:    * @throws SecurityException if the client or delegated subject (if any) does
 721:    *                           not have permission to invoke this operation.
 722:    * @throws IOException if an I/O error occurred in communicating with
 723:    *                     the bean server.
 724:    * @see #createMBean(String, ObjectName, Subject)
 725:    */
 726:   ObjectInstance getObjectInstance(ObjectName name, Subject delegationSubject)
 727:     throws InstanceNotFoundException, IOException;
 728: 
 729:   /**
 730:    * <p>
 731:    * Handles {@link
 732:    * MBeanServerConnection#invoke(ObjectName, String, Object[],
 733:    * String[])}.  The array of parameters is wrapped in a
 734:    * {@link MarshalledObject} so that it is deserialised
 735:    * using the bean's classloader.
 736:    * </p>
 737:    * <p>
 738:    * Invokes the supplied operation on the specified management
 739:    * bean.  The class objects specified in the signature are loaded
 740:    * using the same class loader as was used for the management bean.
 741:    *
 742:    * @param bean the management bean whose operation should be invoked.
 743:    * @param name the name of the operation to invoke.
 744:    * @param params the parameters for the bean's constructor, encapsulated
 745:    *               in a {@link MarshalledObject}.  If this parameter is
 746:    *               <code>null</code>, it will be judged equivalent to an
 747:    *               empty array.
 748:    * @param sig the signature of the constructor to use.  If this parameter
 749:    *            is <code>null</code>, it will be judged equivalent to an
 750:    *            empty array.  The class objects will be loaded using the
 751:    *            bean's classloader.
 752:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 753:    *                          containing the delegation principles.  This may be
 754:    *                          {@code null} is authentication is used instead.
 755:    * @return the return value of the method.
 756:    * @throws InstanceNotFoundException if the bean can not be found.
 757:    * @throws MBeanException if the method invoked throws an exception.
 758:    * @throws ReflectionException if an exception is thrown in invoking the
 759:    *                             method.
 760:    * @throws SecurityException if the client or delegated subject (if any) does
 761:    *                           not have permission to invoke this operation.
 762:    * @throws IOException if an I/O error occurred in communicating with
 763:    *                     the bean server.
 764:    * @see DynamicMBean#invoke(String, Object[], String[])
 765:    */
 766:   Object invoke(ObjectName bean, String name, MarshalledObject params,
 767:         String[] sig, Subject delegationSubject)
 768:     throws InstanceNotFoundException, MBeanException,
 769:        ReflectionException, IOException;
 770: 
 771:   /**
 772:    * <p>
 773:    * Handles {@link
 774:    * MBeanServerConnection#isInstanceOf(ObjectName, String) by
 775:    * returning true if the specified management bean is an instance
 776:    * of the supplied class.
 777:    * </p>
 778:    * <p>
 779:    * A bean, B, is an instance of a class, C, if either of the following
 780:    * conditions holds:
 781:    * </p>
 782:    * <ul>
 783:    * <li>The class name in B's {@link MBeanInfo} is equal to the supplied
 784:    * name.</li>
 785:    * <li>Both the class of B and C were loaded by the same class loader,
 786:    * and B is assignable to C.</li>
 787:    * </ul>
 788:    * 
 789:    * @param name the name of the management bean.
 790:    * @param className the name of the class to test if <code>name</code> is
 791:    *                  an instance of.
 792:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 793:    *                          containing the delegation principles.  This may be
 794:    *                          {@code null} is authentication is used instead.
 795:    * @return true if either B is directly an instance of the named class,
 796:    *         or B is assignable to the class, given that both it and B's
 797:    *         current class were loaded using the same class loader.
 798:    * @throws InstanceNotFoundException if the bean can not be found.
 799:    * @throws SecurityException if the client or delegated subject (if any) does
 800:    *                           not have permission to invoke this operation.
 801:    * @throws IOException if an I/O error occurred in communicating with
 802:    *                     the bean server.
 803:    */
 804:   boolean isInstanceOf(ObjectName name, String className,
 805:                Subject delegationSubject)
 806:     throws InstanceNotFoundException, IOException;
 807: 
 808:   /**
 809:    * Handles {@link
 810:    * MBeanServerConnection#isRegistered(ObjectName) by returning
 811:    * true if the specified management bean is registered with
 812:    * the server.
 813:    *
 814:    * @param name the name of the management bean.
 815:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 816:    *                          containing the delegation principles.  This may be
 817:    *                          {@code null} is authentication is used instead.
 818:    * @return true if the bean is registered.
 819:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
 820:    *                                    is thrown by the server due to a
 821:    *                                    <code>null</code> bean name.
 822:    * @throws SecurityException if the client or delegated subject (if any) does
 823:    *                           not have permission to invoke this operation.
 824:    * @throws IOException if an I/O error occurred in communicating with
 825:    *                     the bean server.
 826:    */
 827:   boolean isRegistered(ObjectName name, Subject delegationSubject)
 828:     throws IOException;
 829: 
 830:   /**
 831:    * <p>
 832:    * Handles {@link
 833:    * MBeanServerConnection#queryMBeans(ObjectName, QueryExp)}.
 834:    * The query expression is wrapped in a {@link MarshalledObject}
 835:    * so that it is deserialised using the bean's classloader.
 836:    * </p>
 837:    * <p>
 838:    * Returns a set of {@link ObjectInstance}s matching the specified
 839:    * criteria.  The full set of beans registered with the server
 840:    * are passed through two filters:
 841:    * </p>
 842:    * <ol>
 843:    * <li>Pattern matching is performed using the supplied
 844:    * {@link ObjectName}.</li>
 845:    * <li>The supplied query expression is applied.</li>
 846:    * </ol>
 847:    * <p>
 848:    * If both the object name and the query expression are <code>null</code>,
 849:    * or the object name has no domain and no key properties,
 850:    * no filtering will be performed and all beans are returned. 
 851:    * </p>
 852:    *
 853:    * @param name an {@link ObjectName} to use as a filter.
 854:    * @param query a query expression to apply to each of the beans that match
 855:    *              the given object name, encapsulated in a
 856:    *              {@link MarshalledObject}.  If a <code>null</code> value is
 857:    *              encapsulated, then the beans will only be filtered using
 858:    *              pattern matching on the supplied {@link ObjectName}.
 859:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 860:    *                          containing the delegation principles.  This may be
 861:    *                          {@code null} is authentication is used instead.
 862:    * @return a set of {@link ObjectInstance}s matching the filtered beans.
 863:    *         This is empty if no beans survived the filters.
 864:    * @throws IOException if an I/O error occurred in communicating with
 865:    *                     the bean server.
 866:    * @throws SecurityException if the client or delegated subject (if any) does
 867:    *                           not have permission to invoke this operation.
 868:    */
 869:   Set<ObjectInstance> queryMBeans(ObjectName name, MarshalledObject query,
 870:                   Subject delegationSubject)
 871:     throws IOException;
 872:   
 873:   /**
 874:    * <p>
 875:    * Handles {@link
 876:    * MBeanServerConnection#queryNames(ObjectName, QueryExp)}.
 877:    * The query expression is wrapped in a {@link MarshalledObject}
 878:    * so that it is deserialised using the bean's classloader.
 879:    * </p>
 880:    * <p>
 881:    * Returns a set of {@link ObjectName}s matching the specified
 882:    * criteria.  The full set of beans registered with the server
 883:    * are passed through two filters:
 884:    * </p>
 885:    * <ol>
 886:    * <li>Pattern matching is performed using the supplied
 887:    * {@link ObjectName}.</li>
 888:    * <li>The supplied query expression is applied.</li>
 889:    * </ol>
 890:    * <p>
 891:    * If both the object name and the query expression are <code>null</code>,
 892:    * or the object name has no domain and no key properties,
 893:    * no filtering will be performed and all beans are returned. 
 894:    * </p>
 895:    *
 896:    * @param name an {@link ObjectName} to use as a filter.
 897:    * @param query a query expression to apply to each of the beans that match
 898:    *              the given object name, encapsulated in a
 899:    *              {@link MarshalledObject}.  If a <code>null</code> value is
 900:    *              encapsulated, then the beans will only be filtered using
 901:    *              pattern matching on the supplied {@link ObjectName}.
 902:    * @param delegationSubject an instance of {@link javax.security.auth.Subject}
 903:    *                          containing the delegation principles.  This may be
 904:    *                          {@code null} is authentication is used instead.
 905:    * @return a set of {@link ObjectName}s matching the filtered beans.
 906:    * @throws SecurityException if the client or delegated subject (if any) does
 907:    *                           not have permission to invoke this operation.
 908:    * @throws IOException if an I/O error occurred in communicating with
 909:    *                     the bean server.
 910:    */
 911:   Set<ObjectName> queryNames(ObjectName name, MarshalledObject query,
 912:                  Subject delegationSubject)
 913:     throws IOException;
 914: 
 915:   /**
 916:    * <p>
 917:    * Handles {@link
 918:    * MBeanServerConnection#removeNotificationListener(ObjectName,
 919:    * ObjectName, NotificationFilter, Object)}. Both the filter and
 920:    * the handback object are wrapped in a {@link MarshalledObject}
 921:    * so that they are deserialised using the bean's classloader.
 922:    * </p>
 923:    * <p>
 924:    * Removes the specified listener from the list of recipients
 925:    * of notifications from the supplied bean.  Only the first instance with
 926:    * the supplied filter and passback object is removed.
 927:    * <code>null</code> is used as a valid value for these parameters,
 928:    * rather than as a way to remove all registration instances for
 929:    * the specified listener; for this behaviour instead, see
 930:    * {@link #removeNotificationListener(ObjectName, NotificationListener)}.
 931:    * </p>
 932:    *
 933:    * @param name the name of the management bean from which the
 934:    *             listener should be removed.
 935:    * @param listener the listener to remove.
 936:    * @param filter a wrapper containing the filter of the listener
 937:    *               to remove.
 938:    * @param passback a wrapper containing the handback object of the
 939:    *                 listener to remove.
 940:    * @param delegationSubject a {@link javax.security.auth.Subject} instance
 941:    *                          containing the delegation principles or
 942:    *                          {@code null} if authentication is used.
 943:    * @throws InstanceNotFoundException if the bean can not be found.
 944:    * @throws ListenerNotFoundException if the specified listener
 945:    *                                   is not registered with the bean.
 946:    * @throws SecurityException if the client or delegated subject (if any) does
 947:    *                           not have permission to invoke this operation.
 948:    * @throws IOException if an I/O error occurred in communicating with
 949:    *                     the bean server.
 950:    * @see #addNotificationListener(ObjectName, NotificationListener,
 951:    *                               MarshalledObject, MarshalledObject, Subject)
 952:    * @see NotificationEmitter#removeNotificationListener(NotificationListener,
 953:    *                                                     NotificationFilter,
 954:    *                                                     Object)
 955:    */
 956:   void removeNotificationListener(ObjectName name,
 957:                   ObjectName listener,
 958:                   MarshalledObject filter,
 959:                   MarshalledObject passback,
 960:                   Subject delegationSubject)
 961:     throws InstanceNotFoundException, ListenerNotFoundException,
 962:        IOException;
 963: 
 964:   /**
 965:    * Handles {@link
 966:    * MBeanServerConnection#removeNotificationListener(ObjectName,
 967:    * ObjectName)} by removing the specified listener from the list
 968:    * of recipients of notifications from the supplied bean.  This
 969:    * includes all combinations of filters and passback objects
 970:    * registered for this listener.  For more specific removal of
 971:    * listeners, see {@link #removeNotificationListener(ObjectName,
 972:    * ObjectName,MarshalledObject,MarshalledObject,Subject)}
 973:    *
 974:    * @param name the name of the management bean from which the
 975:    *             listener should be removed.
 976:    * @param listener the name of the listener to remove.
 977:    * @param delegationSubject a {@link javax.security.auth.Subject} instance
 978:    *                          containing the delegation principles or
 979:    *                          {@code null} if authentication is used.
 980:    * @throws InstanceNotFoundException if a name doesn't match a registered
 981:    *                                   bean.
 982:    * @throws ListenerNotFoundException if the specified listener
 983:    *                                   is not registered with the bean.
 984:    * @throws SecurityException if the client or delegated subject (if any) does
 985:    *                           not have permission to invoke this operation.
 986:    * @throws IOException if an I/O error occurred in communicating with
 987:    *                     the bean server.
 988:    * @see #addNotificationListener(ObjectName, NotificationListener,
 989:    *                               MarshalledObject, MarshalledObject, Subject)
 990:    * @see NotificationBroadcaster#removeNotificationListener(NotificationListener)
 991:    */
 992:   void removeNotificationListener(ObjectName name, ObjectName listener,
 993:                   Subject delegationSubject)
 994:     throws InstanceNotFoundException, ListenerNotFoundException,
 995:        IOException;
 996: 
 997:   /**
 998:    * Removes one or more {@link NotificationListener}s from the specified
 999:    * management bean.  This method corresponds to
1000:    * {@link #addNotificationListeners(ObjectName[], MarshalledObject[],
1001:    * Subject)} and provides a different way of handling
1002:    * MBeanServerConnection#removeNotificationListener(ObjectName,
1003:    * ObjectName)} and
1004:    * {@link MBeanServerConnection#removeNotificationListener(ObjectName,
1005:    * ObjectName, NotificationFilter, Object)} by using the integer
1006:    * identifiers provided by the
1007:    * {@link #addNotificationListeners(ObjectName[], MarshalledObject[],
1008:    * Subject)} method to select the listeners to remove.
1009:    * 
1010:    * @param name the name of the management bean from which the
1011:    *             listeners should be removed.
1012:    * @param listenerIds the identifiers of the listeners to remove.
1013:    * @param delegationSubject a {@link javax.security.auth.Subject} instance
1014:    *                          containing the delegation principles or
1015:    *                          {@code null} if authentication is used.
1016:    * @throws InstanceNotFoundException if a name doesn't match a registered
1017:    *                                   bean.
1018:    * @throws ListenerNotFoundException if the specified listener
1019:    *                                   is not registered with the bean.
1020:    * @throws SecurityException if the client or delegated subject (if any) does
1021:    *                           not have permission to invoke this operation.
1022:    * @throws IOException if an I/O error occurred in communicating with
1023:    *                     the bean server.
1024:    * @throws IllegalArgumentException if either <code>name</code>,
1025:    *                                  <code>listenerIds</code> or an element
1026:    *                                  of <code>listenerIds</code>
1027:    *                                  is <code>null</code>.
1028:    * @see #addNotificationListeners(ObjectName[], MarshalledObject[], Subject)
1029:    */
1030:   void removeNotificationListeners(ObjectName name, Integer[] listenerIds,
1031:                    Subject delegationSubject)
1032:     throws InstanceNotFoundException, ListenerNotFoundException,
1033:        IOException;
1034: 
1035:   /**
1036:    * Handles {@link
1037:    * MBeanServerConnection#setAttribute(ObjectName, Attribute)}
1038:    * by setting the value of the specified attribute of the supplied
1039:    * management bean.  The attribute is wrapped in a
1040:    * {@link MarshalledObject} so that it is deserialised using the
1041:    * bean's classloader.
1042:    *
1043:    * @param name the name of the management bean.
1044:    * @param attribute the attribute to set, encapsulated in a
1045:    *                  {@link MarshalledObject}.
1046:    * @param delegationSubject a {@link javax.security.auth.Subject} instance
1047:    *                          containing the delegation principles or
1048:    *                          {@code null} if authentication is used.
1049:    * @throws InstanceNotFoundException if the bean can not be found.
1050:    * @throws AttributeNotFoundException if the attribute does not
1051:    *                                    correspond to an attribute
1052:    *                                    of the bean.
1053:    * @throws InvalidAttributeValueException if the value is invalid
1054:    *                                        for this particular
1055:    *                                        attribute of the bean.
1056:    * @throws MBeanException if setting the attribute causes
1057:    *                        the bean to throw an exception (which
1058:    *                        becomes the cause of this exception).
1059:    * @throws ReflectionException if an exception occurred in trying
1060:    *                             to use the reflection interface
1061:    *                             to lookup the attribute.  The
1062:    *                             thrown exception is the cause of
1063:    *                             this exception.
1064:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1065:    *                                    is thrown by the server due to a
1066:    *                                    <code>null</code> bean or attribute
1067:    *                                    name.
1068:    * @throws SecurityException if the client or delegated subject (if any) does
1069:    *                           not have permission to invoke this operation.
1070:    * @throws IOException if an I/O error occurred in communicating with
1071:    *                     the bean server.
1072:    * @see #getAttribute(ObjectName, String, Subject)
1073:    * @see javax.management.DynamicMBean#setAttribute(Attribute)
1074:    */
1075:   void setAttribute(ObjectName name, MarshalledObject attribute,
1076:             Subject delegationSubject)
1077:     throws InstanceNotFoundException, AttributeNotFoundException,
1078:        InvalidAttributeValueException, MBeanException,
1079:        ReflectionException, IOException;
1080: 
1081:   /**
1082:    * Handles {@link
1083:    * MBeanServerConnection#setAttributes(ObjectName, AttributeList)}
1084:    * by setting the value of each of the specified attributes
1085:    * of the supplied management bean to that specified by
1086:    * the {@link Attribute} object.  The returned list contains
1087:    * the attributes that were set and their new values.
1088:    * The attribute list is wrapped in a {@link MarshalledObject} so
1089:    * that it is deserialised using the bean's classloader.
1090:    *
1091:    * @param name the name of the management bean.
1092:    * @param attributes the attributes to set, encapsulated in a
1093:    *                   {@link MarshalledObject}.
1094:    * @param delegationSubject a {@link javax.security.auth.Subject} instance
1095:    *                          containing the delegation principles or
1096:    *                          {@code null} if authentication is used.
1097:    * @return a list of the changed attributes.
1098:    * @throws InstanceNotFoundException if the bean can not be found.
1099:    * @throws ReflectionException if an exception occurred in trying
1100:    *                             to use the reflection interface
1101:    *                             to lookup the attribute.  The
1102:    *                             thrown exception is the cause of
1103:    *                             this exception.
1104:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1105:    *                                    is thrown by the server due to a
1106:    *                                    <code>null</code> bean or attribute
1107:    *                                    list.
1108:    * @throws SecurityException if the client or delegated subject (if any) does
1109:    *                           not have permission to invoke this operation.
1110:    * @throws IOException if an I/O error occurred in communicating with
1111:    *                     the bean server.
1112:    * @see #getAttributes(ObjectName, String[])
1113:    * @see DynamicMBean#setAttributes(AttributeList)
1114:    */
1115:   AttributeList setAttributes(ObjectName name, MarshalledObject attributes,
1116:                   Subject delegationSubject)
1117:     throws InstanceNotFoundException, ReflectionException,
1118:        IOException;
1119: 
1120:   /**
1121:    * Handles {@link
1122:    * MBeanServerConnection#unregisterMBean(ObjectName)} by unregistering
1123:    * the specified management bean.  Following this operation,
1124:    * the bean instance is no longer accessible from the server via this
1125:    * name.  Prior to unregistering the bean, the
1126:    * {@link MBeanRegistration#preDeregister()} method will be called if
1127:    * the bean implements the {@link MBeanRegistration} interface.
1128:    *
1129:    * @param name the name of the management bean.
1130:    * @param delegationSubject a {@link javax.security.auth.Subject} instance
1131:    *                          containing the delegation principles or
1132:    *                          {@code null} if authentication is used.
1133:    * @throws InstanceNotFoundException if the bean can not be found.
1134:    * @throws MBeanRegistrationException if an exception occurs in
1135:    *                                    calling the preDeregister
1136:    *                                    method.
1137:    * @throws RuntimeOperationsException if an {@link IllegalArgumentException}
1138:    *                                    is thrown by the server due to a
1139:    *                                    <code>null</code> bean name or a
1140:    *                                    request being made to unregister the
1141:    *                                    {@link MBeanServerDelegate} bean.
1142:    * @throws SecurityException if the client or delegated subject (if any) does
1143:    *                           not have permission to invoke this operation.
1144:    * @throws IOException if an I/O error occurred in communicating with
1145:    *                     the bean server.
1146:    */ 
1147:   void unregisterMBean(ObjectName name, Subject delegationSubject)
1148:     throws InstanceNotFoundException, MBeanRegistrationException,
1149:        IOException;
1150: 
1151: }