1 /*
   2  * Copyright (c) 2002, 2008, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package javax.management.remote.rmi;
  27 
  28 import java.io.Closeable;
  29 import java.io.IOException;
  30 import java.rmi.MarshalledObject;
  31 import java.rmi.Remote;
  32 import java.util.Set;
  33 
  34 import javax.management.AttributeList;
  35 import javax.management.AttributeNotFoundException;
  36 import javax.management.InstanceAlreadyExistsException;
  37 import javax.management.InstanceNotFoundException;
  38 import javax.management.IntrospectionException;
  39 import javax.management.InvalidAttributeValueException;
  40 import javax.management.ListenerNotFoundException;
  41 import javax.management.MBeanException;
  42 import javax.management.MBeanInfo;
  43 import javax.management.MBeanRegistrationException;
  44 import javax.management.MBeanServerConnection;
  45 import javax.management.NotCompliantMBeanException;
  46 
  47 import javax.management.ObjectInstance;
  48 import javax.management.ObjectName;
  49 import javax.management.ReflectionException;
  50 import javax.management.RuntimeMBeanException;
  51 import javax.management.RuntimeOperationsException;
  52 import javax.management.remote.NotificationResult;
  53 import javax.security.auth.Subject;
  54 
  55 /**
  56  * <p>RMI object used to forward an MBeanServer request from a client
  57  * to its MBeanServer implementation on the server side.  There is one
  58  * Remote object implementing this interface for each remote client
  59  * connected to an RMI connector.</p>
  60  *
  61  * <p>User code does not usually refer to this interface.  It is
  62  * specified as part of the public API so that different
  63  * implementations of that API will interoperate.</p>
  64  *
  65  * <p>To ensure that client parameters will be deserialized at the
  66  * server side with the correct classloader, client parameters such as
  67  * parameters used to invoke a method are wrapped in a {@link
  68  * MarshalledObject}.  An implementation of this interface must first
  69  * get the appropriate class loader for the operation and its target,
  70  * then deserialize the marshalled parameters with this classloader.
  71  * Except as noted, a parameter that is a
  72  * <code>MarshalledObject</code> or <code>MarshalledObject[]</code>
  73  * must not be null; the behavior is unspecified if it is.</p>
  74  *
  75  * <p>Class loading aspects are detailed in the
  76  * <a href="{@docRoot}/../technotes/guides/jmx/JMX_1_4_specification.pdf">
  77  * JMX Specification, version 1.4</a> PDF document.</p>
  78  *
  79  * <p>Most methods in this interface parallel methods in the {@link
  80  * MBeanServerConnection} interface.  Where an aspect of the behavior
  81  * of a method is not specified here, it is the same as in the
  82  * corresponding <code>MBeanServerConnection</code> method.
  83  *
  84  * @since 1.5
  85  */
  86 /*
  87  * Notice that we omit the type parameter from MarshalledObject everywhere,
  88  * even though it would add useful information to the documentation.  The
  89  * reason is that it was only added in Mustang (Java SE 6), whereas versions
  90  * 1.4 and 2.0 of the JMX API must be implementable on Tiger per our
  91  * commitments for JSR 255.  This is also why we suppress rawtypes warnings.
  92  */
  93 @SuppressWarnings("rawtypes")
  94 public interface RMIConnection extends Closeable, Remote {
  95     /**
  96      * <p>Returns the connection ID.  This string is different for
  97      * every open connection to a given RMI connector server.</p>
  98      *
  99      * @return the connection ID
 100      *
 101      * @see RMIConnector#connect RMIConnector.connect
 102      *
 103      * @throws IOException if a general communication exception occurred.
 104      */
 105     public String getConnectionId() throws IOException;
 106 
 107     /**
 108      * <p>Closes this connection.  On return from this method, the RMI
 109      * object implementing this interface is unexported, so further
 110      * remote calls to it will fail.</p>
 111      *
 112      * @throws IOException if the connection could not be closed,
 113      * or the Remote object could not be unexported, or there was a
 114      * communication failure when transmitting the remote close
 115      * request.
 116      */
 117     public void close() throws IOException;
 118 
 119     /**
 120      * Handles the method {@link
 121      * javax.management.MBeanServerConnection#createMBean(String,
 122      * ObjectName)}.
 123      *
 124      * @param className The class name of the MBean to be instantiated.
 125      * @param name The object name of the MBean. May be null.
 126      * @param delegationSubject The <code>Subject</code> containing the
 127      * delegation principals or <code>null</code> if the authentication
 128      * principal is used instead.
 129      *
 130      * @return An <code>ObjectInstance</code>, containing the
 131      * <code>ObjectName</code> and the Java class name of the newly
 132      * instantiated MBean.  If the contained <code>ObjectName</code>
 133      * is <code>n</code>, the contained Java class name is
 134      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
 135      *
 136      * @throws ReflectionException Wraps a
 137      * <code>java.lang.ClassNotFoundException</code> or a
 138      * <code>java.lang.Exception</code> that occurred
 139      * when trying to invoke the MBean's constructor.
 140      * @throws InstanceAlreadyExistsException The MBean is already
 141      * under the control of the MBean server.
 142      * @throws MBeanRegistrationException The
 143      * <code>preRegister</code> (<code>MBeanRegistration</code>
 144      * interface) method of the MBean has thrown an exception. The
 145      * MBean will not be registered.
 146      * @throws MBeanException The constructor of the MBean has
 147      * thrown an exception.
 148      * @throws NotCompliantMBeanException This class is not a JMX
 149      * compliant MBean.
 150      * @throws RuntimeOperationsException Wraps a
 151      * <code>java.lang.IllegalArgumentException</code>: The className
 152      * passed in parameter is null, the <code>ObjectName</code> passed
 153      * in parameter contains a pattern or no <code>ObjectName</code>
 154      * is specified for the MBean.
 155      * @throws SecurityException if the client, or the delegated Subject
 156      * if any, does not have permission to perform this operation.
 157      * @throws IOException if a general communication exception occurred.
 158      */
 159     public ObjectInstance createMBean(String className,
 160                                       ObjectName name,
 161                                       Subject delegationSubject)
 162         throws
 163         ReflectionException,
 164         InstanceAlreadyExistsException,
 165         MBeanRegistrationException,
 166         MBeanException,
 167         NotCompliantMBeanException,
 168         IOException;
 169 
 170     /**
 171      * Handles the method {@link
 172      * javax.management.MBeanServerConnection#createMBean(String,
 173      * ObjectName, ObjectName)}.
 174      *
 175      * @param className The class name of the MBean to be instantiated.
 176      * @param name The object name of the MBean. May be null.
 177      * @param loaderName The object name of the class loader to be used.
 178      * @param delegationSubject The <code>Subject</code> containing the
 179      * delegation principals or <code>null</code> if the authentication
 180      * principal is used instead.
 181      *
 182      * @return An <code>ObjectInstance</code>, containing the
 183      * <code>ObjectName</code> and the Java class name of the newly
 184      * instantiated MBean.  If the contained <code>ObjectName</code>
 185      * is <code>n</code>, the contained Java class name is
 186      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
 187      *
 188      * @throws ReflectionException Wraps a
 189      * <code>java.lang.ClassNotFoundException</code> or a
 190      * <code>java.lang.Exception</code> that occurred when trying to
 191      * invoke the MBean's constructor.
 192      * @throws InstanceAlreadyExistsException The MBean is already
 193      * under the control of the MBean server.
 194      * @throws MBeanRegistrationException The
 195      * <code>preRegister</code> (<code>MBeanRegistration</code>
 196      * interface) method of the MBean has thrown an exception. The
 197      * MBean will not be registered.
 198      * @throws MBeanException The constructor of the MBean has
 199      * thrown an exception.
 200      * @throws NotCompliantMBeanException This class is not a JMX
 201      * compliant MBean.
 202      * @throws InstanceNotFoundException The specified class loader
 203      * is not registered in the MBean server.
 204      * @throws RuntimeOperationsException Wraps a
 205      * <code>java.lang.IllegalArgumentException</code>: The className
 206      * passed in parameter is null, the <code>ObjectName</code> passed
 207      * in parameter contains a pattern or no <code>ObjectName</code>
 208      * is specified for the MBean.
 209      * @throws SecurityException if the client, or the delegated Subject
 210      * if any, does not have permission to perform this operation.
 211      * @throws IOException if a general communication exception occurred.
 212      */
 213     public ObjectInstance createMBean(String className,
 214                                       ObjectName name,
 215                                       ObjectName loaderName,
 216                                       Subject delegationSubject)
 217         throws
 218         ReflectionException,
 219         InstanceAlreadyExistsException,
 220         MBeanRegistrationException,
 221         MBeanException,
 222         NotCompliantMBeanException,
 223         InstanceNotFoundException,
 224         IOException;
 225 
 226     /**
 227      * Handles the method {@link
 228      * javax.management.MBeanServerConnection#createMBean(String,
 229      * ObjectName, Object[], String[])}.  The <code>Object[]</code>
 230      * parameter is wrapped in a <code>MarshalledObject</code>.
 231      *
 232      * @param className The class name of the MBean to be instantiated.
 233      * @param name The object name of the MBean. May be null.
 234      * @param params An array containing the parameters of the
 235      * constructor to be invoked, encapsulated into a
 236      * <code>MarshalledObject</code>.  The encapsulated array can be
 237      * null, equivalent to an empty array.
 238      * @param signature An array containing the signature of the
 239      * constructor to be invoked.  Can be null, equivalent to an empty
 240      * array.
 241      * @param delegationSubject The <code>Subject</code> containing the
 242      * delegation principals or <code>null</code> if the authentication
 243      * principal is used instead.
 244      *
 245      * @return An <code>ObjectInstance</code>, containing the
 246      * <code>ObjectName</code> and the Java class name of the newly
 247      * instantiated MBean.  If the contained <code>ObjectName</code>
 248      * is <code>n</code>, the contained Java class name is
 249      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
 250      *
 251      * @throws ReflectionException Wraps a
 252      * <code>java.lang.ClassNotFoundException</code> or a
 253      * <code>java.lang.Exception</code> that occurred when trying to
 254      * invoke the MBean's constructor.
 255      * @throws InstanceAlreadyExistsException The MBean is already
 256      * under the control of the MBean server.
 257      * @throws MBeanRegistrationException The
 258      * <code>preRegister</code> (<code>MBeanRegistration</code>
 259      * interface) method of the MBean has thrown an exception. The
 260      * MBean will not be registered.
 261      * @throws MBeanException The constructor of the MBean has
 262      * thrown an exception.
 263      * @throws NotCompliantMBeanException This class is not a JMX
 264      * compliant MBean.
 265      * @throws RuntimeOperationsException Wraps a
 266      * <code>java.lang.IllegalArgumentException</code>: The className
 267      * passed in parameter is null, the <code>ObjectName</code> passed
 268      * in parameter contains a pattern, or no <code>ObjectName</code>
 269      * is specified for the MBean.
 270      * @throws SecurityException if the client, or the delegated Subject
 271      * if any, does not have permission to perform this operation.
 272      * @throws IOException if a general communication exception occurred.
 273      */
 274     public ObjectInstance createMBean(String className,
 275                                 ObjectName name,
 276                                 MarshalledObject params,
 277                                 String signature[],
 278                                 Subject delegationSubject)
 279         throws
 280         ReflectionException,
 281         InstanceAlreadyExistsException,
 282         MBeanRegistrationException,
 283         MBeanException,
 284         NotCompliantMBeanException,
 285         IOException;
 286 
 287     /**
 288      * Handles the method {@link
 289      * javax.management.MBeanServerConnection#createMBean(String,
 290      * ObjectName, ObjectName, Object[], String[])}.  The
 291      * <code>Object[]</code> parameter is wrapped in a
 292      * <code>MarshalledObject</code>.
 293      *
 294      * @param className The class name of the MBean to be instantiated.
 295      * @param name The object name of the MBean. May be null.
 296      * @param loaderName The object name of the class loader to be used.
 297      * @param params An array containing the parameters of the
 298      * constructor to be invoked, encapsulated into a
 299      * <code>MarshalledObject</code>.  The encapsulated array can be
 300      * null, equivalent to an empty array.
 301      * @param signature An array containing the signature of the
 302      * constructor to be invoked.  Can be null, equivalent to an empty
 303      * array.
 304      * @param delegationSubject The <code>Subject</code> containing the
 305      * delegation principals or <code>null</code> if the authentication
 306      * principal is used instead.
 307      *
 308      * @return An <code>ObjectInstance</code>, containing the
 309      * <code>ObjectName</code> and the Java class name of the newly
 310      * instantiated MBean.  If the contained <code>ObjectName</code>
 311      * is <code>n</code>, the contained Java class name is
 312      * <code>{@link #getMBeanInfo getMBeanInfo(n)}.getClassName()</code>.
 313      *
 314      * @throws ReflectionException Wraps a
 315      * <code>java.lang.ClassNotFoundException</code> or a
 316      * <code>java.lang.Exception</code> that occurred when trying to
 317      * invoke the MBean's constructor.
 318      * @throws InstanceAlreadyExistsException The MBean is already
 319      * under the control of the MBean server.
 320      * @throws MBeanRegistrationException The
 321      * <code>preRegister</code> (<code>MBeanRegistration</code>
 322      * interface) method of the MBean has thrown an exception. The
 323      * MBean will not be registered.
 324      * @throws MBeanException The constructor of the MBean has
 325      * thrown an exception.
 326      * @throws NotCompliantMBeanException This class is not a JMX
 327      * compliant MBean.
 328      * @throws InstanceNotFoundException The specified class loader
 329      * is not registered in the MBean server.
 330      * @throws RuntimeOperationsException Wraps a
 331      * <code>java.lang.IllegalArgumentException</code>: The className
 332      * passed in parameter is null, the <code>ObjectName</code> passed
 333      * in parameter contains a pattern, or no <code>ObjectName</code>
 334      * is specified for the MBean.
 335      * @throws SecurityException if the client, or the delegated Subject
 336      * if any, does not have permission to perform this operation.
 337      * @throws IOException if a general communication exception occurred.
 338      */
 339     public ObjectInstance createMBean(String className,
 340                                 ObjectName name,
 341                                 ObjectName loaderName,
 342                                 MarshalledObject params,
 343                                 String signature[],
 344                                 Subject delegationSubject)
 345         throws
 346         ReflectionException,
 347         InstanceAlreadyExistsException,
 348         MBeanRegistrationException,
 349         MBeanException,
 350         NotCompliantMBeanException,
 351         InstanceNotFoundException,
 352         IOException;
 353 
 354     /**
 355      * Handles the method
 356      * {@link javax.management.MBeanServerConnection#unregisterMBean(ObjectName)}.
 357      *
 358      * @param name The object name of the MBean to be unregistered.
 359      * @param delegationSubject The <code>Subject</code> containing the
 360      * delegation principals or <code>null</code> if the authentication
 361      * principal is used instead.
 362      *
 363      * @throws InstanceNotFoundException The MBean specified is not
 364      * registered in the MBean server.
 365      * @throws MBeanRegistrationException The preDeregister
 366      * ((<code>MBeanRegistration</code> interface) method of the MBean
 367      * has thrown an exception.
 368      * @throws RuntimeOperationsException Wraps a
 369      * <code>java.lang.IllegalArgumentException</code>: The object
 370      * name in parameter is null or the MBean you are when trying to
 371      * unregister is the {@link javax.management.MBeanServerDelegate
 372      * MBeanServerDelegate} MBean.
 373      * @throws SecurityException if the client, or the delegated Subject
 374      * if any, does not have permission to perform this operation.
 375      * @throws IOException if a general communication exception occurred.
 376      */
 377     public void unregisterMBean(ObjectName name, Subject delegationSubject)
 378         throws
 379         InstanceNotFoundException,
 380         MBeanRegistrationException,
 381         IOException;
 382 
 383     /**
 384      * Handles the method
 385      * {@link javax.management.MBeanServerConnection#getObjectInstance(ObjectName)}.
 386      *
 387      * @param name The object name of the MBean.
 388      * @param delegationSubject The <code>Subject</code> containing the
 389      * delegation principals or <code>null</code> if the authentication
 390      * principal is used instead.
 391      *
 392      * @return The <code>ObjectInstance</code> associated with the MBean
 393      * specified by <var>name</var>.  The contained <code>ObjectName</code>
 394      * is <code>name</code> and the contained class name is
 395      * <code>{@link #getMBeanInfo getMBeanInfo(name)}.getClassName()</code>.
 396      *
 397      * @throws InstanceNotFoundException The MBean specified is not
 398      * registered in the MBean server.
 399      * @throws RuntimeOperationsException Wraps a
 400      * <code>java.lang.IllegalArgumentException</code>: The object
 401      * name in parameter is null.
 402      * @throws SecurityException if the client, or the delegated Subject
 403      * if any, does not have permission to perform this operation.
 404      * @throws IOException if a general communication exception occurred.
 405      */
 406     public ObjectInstance getObjectInstance(ObjectName name,
 407                                             Subject delegationSubject)
 408         throws InstanceNotFoundException, IOException;
 409 
 410     /**
 411      * Handles the method {@link
 412      * javax.management.MBeanServerConnection#queryMBeans(ObjectName,
 413      * QueryExp)}.  The <code>QueryExp</code> is wrapped in a
 414      * <code>MarshalledObject</code>.
 415      *
 416      * @param name The object name pattern identifying the MBeans to
 417      * be retrieved. If null or no domain and key properties are
 418      * specified, all the MBeans registered will be retrieved.
 419      * @param query The query expression to be applied for selecting
 420      * MBeans, encapsulated into a <code>MarshalledObject</code>. If
 421      * the <code>MarshalledObject</code> encapsulates a null value no
 422      * query expression will be applied for selecting MBeans.
 423      * @param delegationSubject The <code>Subject</code> containing the
 424      * delegation principals or <code>null</code> if the authentication
 425      * principal is used instead.
 426      *
 427      * @return A set containing the <code>ObjectInstance</code>
 428      * objects for the selected MBeans.  If no MBean satisfies the
 429      * query an empty list is returned.
 430      *
 431      * @throws SecurityException if the client, or the delegated Subject
 432      * if any, does not have permission to perform this operation.
 433      * @throws IOException if a general communication exception occurred.
 434      */
 435     public Set<ObjectInstance>
 436         queryMBeans(ObjectName name,
 437                     MarshalledObject query,
 438                     Subject delegationSubject)
 439         throws IOException;
 440 
 441     /**
 442      * Handles the method {@link
 443      * javax.management.MBeanServerConnection#queryNames(ObjectName,
 444      * QueryExp)}.  The <code>QueryExp</code> is wrapped in a
 445      * <code>MarshalledObject</code>.
 446      *
 447      * @param name The object name pattern identifying the MBean names
 448      * to be retrieved. If null or no domain and key properties are
 449      * specified, the name of all registered MBeans will be retrieved.
 450      * @param query The query expression to be applied for selecting
 451      * MBeans, encapsulated into a <code>MarshalledObject</code>. If
 452      * the <code>MarshalledObject</code> encapsulates a null value no
 453      * query expression will be applied for selecting MBeans.
 454      * @param delegationSubject The <code>Subject</code> containing the
 455      * delegation principals or <code>null</code> if the authentication
 456      * principal is used instead.
 457      *
 458      * @return A set containing the ObjectNames for the MBeans
 459      * selected.  If no MBean satisfies the query, an empty list is
 460      * returned.
 461      *
 462      * @throws SecurityException if the client, or the delegated Subject
 463      * if any, does not have permission to perform this operation.
 464      * @throws IOException if a general communication exception occurred.
 465      */
 466     public Set<ObjectName>
 467         queryNames(ObjectName name,
 468                    MarshalledObject query,
 469                    Subject delegationSubject)
 470         throws IOException;
 471 
 472     /**
 473      * Handles the method
 474      * {@link javax.management.MBeanServerConnection#isRegistered(ObjectName)}.
 475      *
 476      * @param name The object name of the MBean to be checked.
 477      * @param delegationSubject The <code>Subject</code> containing the
 478      * delegation principals or <code>null</code> if the authentication
 479      * principal is used instead.
 480      *
 481      * @return True if the MBean is already registered in the MBean
 482      * server, false otherwise.
 483      *
 484      * @throws RuntimeOperationsException Wraps a
 485      * <code>java.lang.IllegalArgumentException</code>: The object
 486      * name in parameter is null.
 487      * @throws SecurityException if the client, or the delegated Subject
 488      * if any, does not have permission to perform this operation.
 489      * @throws IOException if a general communication exception occurred.
 490      */
 491     public boolean isRegistered(ObjectName name, Subject delegationSubject)
 492         throws IOException;
 493 
 494     /**
 495      * Handles the method
 496      * {@link javax.management.MBeanServerConnection#getMBeanCount()}.
 497      *
 498      * @param delegationSubject The <code>Subject</code> containing the
 499      * delegation principals or <code>null</code> if the authentication
 500      * principal is used instead.
 501      *
 502      * @return the number of MBeans registered.
 503      *
 504      * @throws SecurityException if the client, or the delegated Subject
 505      * if any, does not have permission to perform this operation.
 506      * @throws IOException if a general communication exception occurred.
 507      */
 508     public Integer getMBeanCount(Subject delegationSubject)
 509         throws IOException;
 510 
 511     /**
 512      * Handles the method {@link
 513      * javax.management.MBeanServerConnection#getAttribute(ObjectName,
 514      * String)}.
 515      *
 516      * @param name The object name of the MBean from which the
 517      * attribute is to be retrieved.
 518      * @param attribute A String specifying the name of the attribute
 519      * to be retrieved.
 520      * @param delegationSubject The <code>Subject</code> containing the
 521      * delegation principals or <code>null</code> if the authentication
 522      * principal is used instead.
 523      *
 524      * @return  The value of the retrieved attribute.
 525      *
 526      * @throws AttributeNotFoundException The attribute specified
 527      * is not accessible in the MBean.
 528      * @throws MBeanException Wraps an exception thrown by the
 529      * MBean's getter.
 530      * @throws InstanceNotFoundException The MBean specified is not
 531      * registered in the MBean server.
 532      * @throws ReflectionException Wraps a
 533      * <code>java.lang.Exception</code> thrown when trying to invoke
 534      * the getter.
 535      * @throws RuntimeOperationsException Wraps a
 536      * <code>java.lang.IllegalArgumentException</code>: The object
 537      * name in parameter is null or the attribute in parameter is
 538      * null.
 539      * @throws RuntimeMBeanException Wraps a runtime exception thrown
 540      * by the MBean's getter.
 541      * @throws SecurityException if the client, or the delegated Subject
 542      * if any, does not have permission to perform this operation.
 543      * @throws IOException if a general communication exception occurred.
 544      *
 545      * @see #setAttribute
 546      */
 547     public Object getAttribute(ObjectName name,
 548                                String attribute,
 549                                Subject delegationSubject)
 550         throws
 551         MBeanException,
 552         AttributeNotFoundException,
 553         InstanceNotFoundException,
 554         ReflectionException,
 555         IOException;
 556 
 557     /**
 558      * Handles the method {@link
 559      * javax.management.MBeanServerConnection#getAttributes(ObjectName,
 560      * String[])}.
 561      *
 562      * @param name The object name of the MBean from which the
 563      * attributes are retrieved.
 564      * @param attributes A list of the attributes to be retrieved.
 565      * @param delegationSubject The <code>Subject</code> containing the
 566      * delegation principals or <code>null</code> if the authentication
 567      * principal is used instead.
 568      *
 569      * @return The list of the retrieved attributes.
 570      *
 571      * @throws InstanceNotFoundException The MBean specified is not
 572      * registered in the MBean server.
 573      * @throws ReflectionException An exception occurred when
 574      * trying to invoke the getAttributes method of a Dynamic MBean.
 575      * @throws RuntimeOperationsException Wrap a
 576      * <code>java.lang.IllegalArgumentException</code>: The object
 577      * name in parameter is null or attributes in parameter is null.
 578      * @throws SecurityException if the client, or the delegated Subject
 579      * if any, does not have permission to perform this operation.
 580      * @throws IOException if a general communication exception occurred.
 581      *
 582      * @see #setAttributes
 583      */
 584     public AttributeList getAttributes(ObjectName name,
 585                                        String[] attributes,
 586                                        Subject delegationSubject)
 587         throws
 588         InstanceNotFoundException,
 589         ReflectionException,
 590         IOException;
 591 
 592     /**
 593      * Handles the method {@link
 594      * javax.management.MBeanServerConnection#setAttribute(ObjectName,
 595      * Attribute)}.  The <code>Attribute</code> parameter is wrapped
 596      * in a <code>MarshalledObject</code>.
 597      *
 598      * @param name The name of the MBean within which the attribute is
 599      * to be set.
 600      * @param attribute The identification of the attribute to be set
 601      * and the value it is to be set to, encapsulated into a
 602      * <code>MarshalledObject</code>.
 603      * @param delegationSubject The <code>Subject</code> containing the
 604      * delegation principals or <code>null</code> if the authentication
 605      * principal is used instead.
 606      *
 607      * @throws InstanceNotFoundException The MBean specified is not
 608      * registered in the MBean server.
 609      * @throws AttributeNotFoundException The attribute specified
 610      * is not accessible in the MBean.
 611      * @throws InvalidAttributeValueException The value specified
 612      * for the attribute is not valid.
 613      * @throws MBeanException Wraps an exception thrown by the
 614      * MBean's setter.
 615      * @throws ReflectionException Wraps a
 616      * <code>java.lang.Exception</code> thrown when trying to invoke
 617      * the setter.
 618      * @throws RuntimeOperationsException Wraps a
 619      * <code>java.lang.IllegalArgumentException</code>: The object
 620      * name in parameter is null or the attribute in parameter is
 621      * null.
 622      * @throws SecurityException if the client, or the delegated Subject
 623      * if any, does not have permission to perform this operation.
 624      * @throws IOException if a general communication exception occurred.
 625      *
 626      * @see #getAttribute
 627      */
 628     public void setAttribute(ObjectName name,
 629                              MarshalledObject attribute,
 630                              Subject delegationSubject)
 631         throws
 632         InstanceNotFoundException,
 633         AttributeNotFoundException,
 634         InvalidAttributeValueException,
 635         MBeanException,
 636         ReflectionException,
 637         IOException;
 638 
 639     /**
 640      * Handles the method {@link
 641      * javax.management.MBeanServerConnection#setAttributes(ObjectName,
 642      * AttributeList)}.  The <code>AttributeList</code> parameter is
 643      * wrapped in a <code>MarshalledObject</code>.
 644      *
 645      * @param name The object name of the MBean within which the
 646      * attributes are to be set.
 647      * @param attributes A list of attributes: The identification of
 648      * the attributes to be set and the values they are to be set to,
 649      * encapsulated into a <code>MarshalledObject</code>.
 650      * @param delegationSubject The <code>Subject</code> containing the
 651      * delegation principals or <code>null</code> if the authentication
 652      * principal is used instead.
 653      *
 654      * @return The list of attributes that were set, with their new
 655      * values.
 656      *
 657      * @throws InstanceNotFoundException The MBean specified is not
 658      * registered in the MBean server.
 659      * @throws ReflectionException An exception occurred when
 660      * trying to invoke the getAttributes method of a Dynamic MBean.
 661      * @throws RuntimeOperationsException Wraps a
 662      * <code>java.lang.IllegalArgumentException</code>: The object
 663      * name in parameter is null or attributes in parameter is null.
 664      * @throws SecurityException if the client, or the delegated Subject
 665      * if any, does not have permission to perform this operation.
 666      * @throws IOException if a general communication exception occurred.
 667      *
 668      * @see #getAttributes
 669      */
 670     public AttributeList setAttributes(ObjectName name,
 671                           MarshalledObject attributes,
 672                           Subject delegationSubject)
 673         throws
 674         InstanceNotFoundException,
 675         ReflectionException,
 676         IOException;
 677 
 678     /**
 679      * Handles the method {@link
 680      * javax.management.MBeanServerConnection#invoke(ObjectName,
 681      * String, Object[], String[])}.  The <code>Object[]</code>
 682      * parameter is wrapped in a <code>MarshalledObject</code>.
 683      *
 684      * @param name The object name of the MBean on which the method is
 685      * to be invoked.
 686      * @param operationName The name of the operation to be invoked.
 687      * @param params An array containing the parameters to be set when
 688      * the operation is invoked, encapsulated into a
 689      * <code>MarshalledObject</code>.  The encapsulated array can be
 690      * null, equivalent to an empty array.
 691      * @param signature An array containing the signature of the
 692      * operation. The class objects will be loaded using the same
 693      * class loader as the one used for loading the MBean on which the
 694      * operation was invoked.  Can be null, equivalent to an empty
 695      * array.
 696      * @param delegationSubject The <code>Subject</code> containing the
 697      * delegation principals or <code>null</code> if the authentication
 698      * principal is used instead.
 699      *
 700      * @return The object returned by the operation, which represents
 701      * the result of invoking the operation on the MBean specified.
 702      *
 703      * @throws InstanceNotFoundException The MBean specified is not
 704      * registered in the MBean server.
 705      * @throws MBeanException Wraps an exception thrown by the
 706      * MBean's invoked method.
 707      * @throws ReflectionException Wraps a
 708      * <code>java.lang.Exception</code> thrown while trying to invoke
 709      * the method.
 710      * @throws SecurityException if the client, or the delegated Subject
 711      * if any, does not have permission to perform this operation.
 712      * @throws IOException if a general communication exception occurred.
 713      * @throws RuntimeOperationsException Wraps an {@link
 714      * IllegalArgumentException} when <code>name</code> or
 715      * <code>operationName</code> is null.
 716      */
 717     public Object invoke(ObjectName name,
 718                          String operationName,
 719                          MarshalledObject params,
 720                          String signature[],
 721                          Subject delegationSubject)
 722         throws
 723         InstanceNotFoundException,
 724         MBeanException,
 725         ReflectionException,
 726         IOException;
 727 
 728     /**
 729      * Handles the method
 730      * {@link javax.management.MBeanServerConnection#getDefaultDomain()}.
 731      *
 732      * @param delegationSubject The <code>Subject</code> containing the
 733      * delegation principals or <code>null</code> if the authentication
 734      * principal is used instead.
 735      *
 736      * @return the default domain.
 737      *
 738      * @throws SecurityException if the client, or the delegated Subject
 739      * if any, does not have permission to perform this operation.
 740      * @throws IOException if a general communication exception occurred.
 741      */
 742     public String getDefaultDomain(Subject delegationSubject)
 743         throws IOException;
 744 
 745     /**
 746      * Handles the method
 747      * {@link javax.management.MBeanServerConnection#getDomains()}.
 748      *
 749      * @param delegationSubject The <code>Subject</code> containing the
 750      * delegation principals or <code>null</code> if the authentication
 751      * principal is used instead.
 752      *
 753      * @return the list of domains.
 754      *
 755      * @throws SecurityException if the client, or the delegated Subject
 756      * if any, does not have permission to perform this operation.
 757      * @throws IOException if a general communication exception occurred.
 758      */
 759     public String[] getDomains(Subject delegationSubject)
 760         throws IOException;
 761 
 762     /**
 763      * Handles the method
 764      * {@link javax.management.MBeanServerConnection#getMBeanInfo(ObjectName)}.
 765      *
 766      * @param name The name of the MBean to analyze
 767      * @param delegationSubject The <code>Subject</code> containing the
 768      * delegation principals or <code>null</code> if the authentication
 769      * principal is used instead.
 770      *
 771      * @return An instance of <code>MBeanInfo</code> allowing the
 772      * retrieval of all attributes and operations of this MBean.
 773      *
 774      * @throws IntrospectionException An exception occurred during
 775      * introspection.
 776      * @throws InstanceNotFoundException The MBean specified was
 777      * not found.
 778      * @throws ReflectionException An exception occurred when
 779      * trying to invoke the getMBeanInfo of a Dynamic MBean.
 780      * @throws SecurityException if the client, or the delegated Subject
 781      * if any, does not have permission to perform this operation.
 782      * @throws IOException if a general communication exception occurred.
 783      * @throws RuntimeOperationsException Wraps a
 784      * <code>java.lang.IllegalArgumentException</code>: The object
 785      * name in parameter is null.
 786      */
 787     public MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject)
 788         throws
 789         InstanceNotFoundException,
 790         IntrospectionException,
 791         ReflectionException,
 792         IOException;
 793 
 794     /**
 795      * Handles the method {@link
 796      * javax.management.MBeanServerConnection#isInstanceOf(ObjectName,
 797      * String)}.
 798      *
 799      * @param name The <code>ObjectName</code> of the MBean.
 800      * @param className The name of the class.
 801      * @param delegationSubject The <code>Subject</code> containing the
 802      * delegation principals or <code>null</code> if the authentication
 803      * principal is used instead.
 804      *
 805      * @return true if the MBean specified is an instance of the
 806      * specified class according to the rules above, false otherwise.
 807      *
 808      * @throws InstanceNotFoundException The MBean specified is not
 809      * registered in the MBean server.
 810      * @throws SecurityException if the client, or the delegated Subject
 811      * if any, does not have permission to perform this operation.
 812      * @throws IOException if a general communication exception occurred.
 813      * @throws RuntimeOperationsException Wraps a
 814      * <code>java.lang.IllegalArgumentException</code>: The object
 815      * name in parameter is null.
 816      */
 817     public boolean isInstanceOf(ObjectName name,
 818                                 String className,
 819                                 Subject delegationSubject)
 820         throws InstanceNotFoundException, IOException;
 821 
 822     /**
 823      * Handles the method {@link
 824      * javax.management.MBeanServerConnection#addNotificationListener(ObjectName,
 825      * ObjectName, NotificationFilter, Object)}.  The
 826      * <code>NotificationFilter</code> parameter is wrapped in a
 827      * <code>MarshalledObject</code>.  The <code>Object</code>
 828      * (handback) parameter is also wrapped in a
 829      * <code>MarshalledObject</code>.
 830      *
 831      * @param name The name of the MBean on which the listener should
 832      * be added.
 833      * @param listener The object name of the listener which will
 834      * handle the notifications emitted by the registered MBean.
 835      * @param filter The filter object, encapsulated into a
 836      * <code>MarshalledObject</code>. If filter encapsulated in the
 837      * <code>MarshalledObject</code> has a null value, no filtering
 838      * will be performed before handling notifications.
 839      * @param handback The context to be sent to the listener when a
 840      * notification is emitted, encapsulated into a
 841      * <code>MarshalledObject</code>.
 842      * @param delegationSubject The <code>Subject</code> containing the
 843      * delegation principals or <code>null</code> if the authentication
 844      * principal is used instead.
 845      *
 846      * @throws InstanceNotFoundException The MBean name of the
 847      * notification listener or of the notification broadcaster does
 848      * not match any of the registered MBeans.
 849      * @throws RuntimeOperationsException Wraps an {@link
 850      * IllegalArgumentException}.  The MBean named by
 851      * <code>listener</code> exists but does not implement the
 852      * {@link javax.management.NotificationListener} interface,
 853      * or <code>name</code> or <code>listener</code> is null.
 854      * @throws SecurityException if the client, or the delegated Subject
 855      * if any, does not have permission to perform this operation.
 856      * @throws IOException if a general communication exception occurred.
 857      *
 858      * @see #removeNotificationListener(ObjectName, ObjectName, Subject)
 859      * @see #removeNotificationListener(ObjectName, ObjectName,
 860      * MarshalledObject, MarshalledObject, Subject)
 861      */
 862     public void addNotificationListener(ObjectName name,
 863                         ObjectName listener,
 864                         MarshalledObject filter,
 865                         MarshalledObject handback,
 866                         Subject delegationSubject)
 867         throws InstanceNotFoundException, IOException;
 868 
 869     /**
 870      * Handles the method {@link
 871      * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,
 872      * ObjectName)}.
 873      *
 874      * @param name The name of the MBean on which the listener should
 875      * be removed.
 876      * @param listener The object name of the listener to be removed.
 877      * @param delegationSubject The <code>Subject</code> containing the
 878      * delegation principals or <code>null</code> if the authentication
 879      * principal is used instead.
 880      *
 881      * @throws InstanceNotFoundException The MBean name provided
 882      * does not match any of the registered MBeans.
 883      * @throws ListenerNotFoundException The listener is not
 884      * registered in the MBean.
 885      * @throws SecurityException if the client, or the delegated Subject
 886      * if any, does not have permission to perform this operation.
 887      * @throws IOException if a general communication exception occurred.
 888      * @throws RuntimeOperationsException Wraps an {@link
 889      * IllegalArgumentException} when <code>name</code> or
 890      * <code>listener</code> is null.
 891      *
 892      * @see #addNotificationListener
 893      */
 894     public void removeNotificationListener(ObjectName name,
 895                                            ObjectName listener,
 896                                            Subject delegationSubject)
 897         throws
 898         InstanceNotFoundException,
 899         ListenerNotFoundException,
 900         IOException;
 901 
 902     /**
 903      * Handles the method {@link
 904      * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,
 905      * ObjectName, NotificationFilter, Object)}.  The
 906      * <code>NotificationFilter</code> parameter is wrapped in a
 907      * <code>MarshalledObject</code>.  The <code>Object</code>
 908      * parameter is also wrapped in a <code>MarshalledObject</code>.
 909      *
 910      * @param name The name of the MBean on which the listener should
 911      * be removed.
 912      * @param listener A listener that was previously added to this
 913      * MBean.
 914      * @param filter The filter that was specified when the listener
 915      * was added, encapsulated into a <code>MarshalledObject</code>.
 916      * @param handback The handback that was specified when the
 917      * listener was added, encapsulated into a <code>MarshalledObject</code>.
 918      * @param delegationSubject The <code>Subject</code> containing the
 919      * delegation principals or <code>null</code> if the authentication
 920      * principal is used instead.
 921      *
 922      * @throws InstanceNotFoundException The MBean name provided
 923      * does not match any of the registered MBeans.
 924      * @throws ListenerNotFoundException The listener is not
 925      * registered in the MBean, or it is not registered with the given
 926      * filter and handback.
 927      * @throws SecurityException if the client, or the delegated Subject
 928      * if any, does not have permission to perform this operation.
 929      * @throws IOException if a general communication exception occurred.
 930      * @throws RuntimeOperationsException Wraps an {@link
 931      * IllegalArgumentException} when <code>name</code> or
 932      * <code>listener</code> is null.
 933      *
 934      * @see #addNotificationListener
 935      */
 936     public void removeNotificationListener(ObjectName name,
 937                       ObjectName listener,
 938                       MarshalledObject filter,
 939                       MarshalledObject handback,
 940                       Subject delegationSubject)
 941         throws
 942         InstanceNotFoundException,
 943         ListenerNotFoundException,
 944         IOException;
 945 
 946     // Special Handling of Notifications -------------------------------------
 947 
 948     /**
 949      * <p>Handles the method {@link
 950      * javax.management.MBeanServerConnection#addNotificationListener(ObjectName,
 951      * NotificationListener, NotificationFilter, Object)}.</p>
 952      *
 953      * <p>Register for notifications from the given MBeans that match
 954      * the given filters.  The remote client can subsequently retrieve
 955      * the notifications using the {@link #fetchNotifications
 956      * fetchNotifications} method.</p>
 957      *
 958      * <p>For each listener, the original
 959      * <code>NotificationListener</code> and <code>handback</code> are
 960      * kept on the client side; in order for the client to be able to
 961      * identify them, the server generates and returns a unique
 962      * <code>listenerID</code>.  This <code>listenerID</code> is
 963      * forwarded with the <code>Notifications</code> to the remote
 964      * client.</p>
 965      *
 966      * <p>If any one of the given (name, filter) pairs cannot be
 967      * registered, then the operation fails with an exception, and no
 968      * names or filters are registered.</p>
 969      *
 970      * @param names the <code>ObjectNames</code> identifying the
 971      * MBeans emitting the Notifications.
 972      * @param filters an array of marshalled representations of the
 973      * <code>NotificationFilters</code>.  Elements of this array can
 974      * be null.
 975      * @param delegationSubjects the <code>Subjects</code> on behalf
 976      * of which the listeners are being added.  Elements of this array
 977      * can be null.  Also, the <code>delegationSubjects</code>
 978      * parameter itself can be null, which is equivalent to an array
 979      * of null values with the same size as the <code>names</code> and
 980      * <code>filters</code> arrays.
 981      *
 982      * @return an array of <code>listenerIDs</code> identifying the
 983      * local listeners.  This array has the same number of elements as
 984      * the parameters.
 985      *
 986      * @throws IllegalArgumentException if <code>names</code> or
 987      * <code>filters</code> is null, or if <code>names</code> contains
 988      * a null element, or if the three arrays do not all have the same
 989      * size.
 990      * @throws ClassCastException if one of the elements of
 991      * <code>filters</code> unmarshalls as a non-null object that is
 992      * not a <code>NotificationFilter</code>.
 993      * @throws InstanceNotFoundException if one of the
 994      * <code>names</code> does not correspond to any registered MBean.
 995      * @throws SecurityException if, for one of the MBeans, the
 996      * client, or the delegated Subject if any, does not have
 997      * permission to add a listener.
 998      * @throws IOException if a general communication exception occurred.
 999      */
1000     public Integer[] addNotificationListeners(ObjectName[] names,
1001                     MarshalledObject[] filters,
1002                     Subject[] delegationSubjects)
1003         throws InstanceNotFoundException, IOException;
1004 
1005     /**
1006      * <p>Handles the
1007      * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener)
1008      * removeNotificationListener(ObjectName, NotificationListener)} and
1009      * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener,NotificationFilter,Object)
1010      * removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)} methods.</p>
1011      *
1012      * <p>This method removes one or more
1013      * <code>NotificationListener</code>s from a given MBean in the
1014      * MBean server.</p>
1015      *
1016      * <p>The <code>NotificationListeners</code> are identified by the
1017      * IDs which were returned by the {@link
1018      * #addNotificationListeners(ObjectName[], MarshalledObject[],
1019      * Subject[])} method.</p>
1020      *
1021      * @param name the <code>ObjectName</code> identifying the MBean
1022      * emitting the Notifications.
1023      * @param listenerIDs the list of the IDs corresponding to the
1024      * listeners to remove.
1025      * @param delegationSubject The <code>Subject</code> containing the
1026      * delegation principals or <code>null</code> if the authentication
1027      * principal is used instead.
1028      *
1029      * @throws InstanceNotFoundException if the given
1030      * <code>name</code> does not correspond to any registered MBean.
1031      * @throws ListenerNotFoundException if one of the listeners was
1032      * not found on the server side.  This exception can happen if the
1033      * MBean discarded a listener for some reason other than a call to
1034      * <code>MBeanServer.removeNotificationListener</code>.
1035      * @throws SecurityException if the client, or the delegated Subject
1036      * if any, does not have permission to remove the listeners.
1037      * @throws IOException if a general communication exception occurred.
1038      * @throws IllegalArgumentException if <code>ObjectName</code> or
1039      * <code>listenerIds</code> is null or if <code>listenerIds</code>
1040      * contains a null element.
1041      */
1042     public void removeNotificationListeners(ObjectName name,
1043                                             Integer[] listenerIDs,
1044                                             Subject delegationSubject)
1045         throws
1046         InstanceNotFoundException,
1047         ListenerNotFoundException,
1048         IOException;
1049 
1050     /**
1051      * <p>Retrieves notifications from the connector server.  This
1052      * method can block until there is at least one notification or
1053      * until the specified timeout is reached.  The method can also
1054      * return at any time with zero notifications.</p>
1055      *
1056      * <p>A notification can be included in the result if its sequence
1057      * number is no less than <code>clientSequenceNumber</code> and
1058      * this client has registered at least one listener for the MBean
1059      * generating the notification, with a filter that accepts the
1060      * notification.  Each listener that is interested in the
1061      * notification is identified by an Integer ID that was returned
1062      * by {@link #addNotificationListeners(ObjectName[],
1063      * MarshalledObject[], Subject[])}.</p>
1064      *
1065      * @param clientSequenceNumber the first sequence number that the
1066      * client is interested in.  If negative, it is interpreted as
1067      * meaning the sequence number that the next notification will
1068      * have.
1069      *
1070      * @param maxNotifications the maximum number of different
1071      * notifications to return.  The <code>TargetedNotification</code>
1072      * array in the returned <code>NotificationResult</code> can have
1073      * more elements than this if the same notification appears more
1074      * than once.  The behavior is unspecified if this parameter is
1075      * negative.
1076      *
1077      * @param timeout the maximum time in milliseconds to wait for a
1078      * notification to arrive.  This can be 0 to indicate that the
1079      * method should not wait if there are no notifications, but
1080      * should return at once.  It can be <code>Long.MAX_VALUE</code>
1081      * to indicate that there is no timeout.  The behavior is
1082      * unspecified if this parameter is negative.
1083      *
1084      * @return A <code>NotificationResult</code>.
1085      *
1086      * @throws IOException if a general communication exception occurred.
1087      */
1088     public NotificationResult fetchNotifications(long clientSequenceNumber,
1089                                                  int maxNotifications,
1090                                                  long timeout)
1091             throws IOException;
1092 }