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 }