--- old/jdk/src/java.management/share/classes/javax/management/remote/rmi/RMIConnection.java 2017-02-01 16:12:52.000000000 +0000 +++ /dev/null 2017-02-01 16:12:52.000000000 +0000 @@ -1,1092 +0,0 @@ -/* - * Copyright (c) 2002, 2008, Oracle and/or its affiliates. All rights reserved. - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * - * This code is free software; you can redistribute it and/or modify it - * under the terms of the GNU General Public License version 2 only, as - * published by the Free Software Foundation. Oracle designates this - * particular file as subject to the "Classpath" exception as provided - * by Oracle in the LICENSE file that accompanied this code. - * - * This code is distributed in the hope that it will be useful, but WITHOUT - * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or - * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License - * version 2 for more details (a copy is included in the LICENSE file that - * accompanied this code). - * - * You should have received a copy of the GNU General Public License version - * 2 along with this work; if not, write to the Free Software Foundation, - * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. - * - * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA - * or visit www.oracle.com if you need additional information or have any - * questions. - */ - -package javax.management.remote.rmi; - -import java.io.Closeable; -import java.io.IOException; -import java.rmi.MarshalledObject; -import java.rmi.Remote; -import java.util.Set; - -import javax.management.AttributeList; -import javax.management.AttributeNotFoundException; -import javax.management.InstanceAlreadyExistsException; -import javax.management.InstanceNotFoundException; -import javax.management.IntrospectionException; -import javax.management.InvalidAttributeValueException; -import javax.management.ListenerNotFoundException; -import javax.management.MBeanException; -import javax.management.MBeanInfo; -import javax.management.MBeanRegistrationException; -import javax.management.MBeanServerConnection; -import javax.management.NotCompliantMBeanException; - -import javax.management.ObjectInstance; -import javax.management.ObjectName; -import javax.management.ReflectionException; -import javax.management.RuntimeMBeanException; -import javax.management.RuntimeOperationsException; -import javax.management.remote.NotificationResult; -import javax.security.auth.Subject; - -/** - *

RMI object used to forward an MBeanServer request from a client - * to its MBeanServer implementation on the server side. There is one - * Remote object implementing this interface for each remote client - * connected to an RMI connector.

- * - *

User code does not usually refer to this interface. It is - * specified as part of the public API so that different - * implementations of that API will interoperate.

- * - *

To ensure that client parameters will be deserialized at the - * server side with the correct classloader, client parameters such as - * parameters used to invoke a method are wrapped in a {@link - * MarshalledObject}. An implementation of this interface must first - * get the appropriate class loader for the operation and its target, - * then deserialize the marshalled parameters with this classloader. - * Except as noted, a parameter that is a - * MarshalledObject or MarshalledObject[] - * must not be null; the behavior is unspecified if it is.

- * - *

Class loading aspects are detailed in the - * - * JMX Specification, version 1.4 PDF document.

- * - *

Most methods in this interface parallel methods in the {@link - * MBeanServerConnection} interface. Where an aspect of the behavior - * of a method is not specified here, it is the same as in the - * corresponding MBeanServerConnection method. - * - * @since 1.5 - */ -/* - * Notice that we omit the type parameter from MarshalledObject everywhere, - * even though it would add useful information to the documentation. The - * reason is that it was only added in Mustang (Java SE 6), whereas versions - * 1.4 and 2.0 of the JMX API must be implementable on Tiger per our - * commitments for JSR 255. This is also why we suppress rawtypes warnings. - */ -@SuppressWarnings("rawtypes") -public interface RMIConnection extends Closeable, Remote { - /** - *

Returns the connection ID. This string is different for - * every open connection to a given RMI connector server.

- * - * @return the connection ID - * - * @see RMIConnector#connect RMIConnector.connect - * - * @throws IOException if a general communication exception occurred. - */ - public String getConnectionId() throws IOException; - - /** - *

Closes this connection. On return from this method, the RMI - * object implementing this interface is unexported, so further - * remote calls to it will fail.

- * - * @throws IOException if the connection could not be closed, - * or the Remote object could not be unexported, or there was a - * communication failure when transmitting the remote close - * request. - */ - public void close() throws IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#createMBean(String, - * ObjectName)}. - * - * @param className The class name of the MBean to be instantiated. - * @param name The object name of the MBean. May be null. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return An ObjectInstance, containing the - * ObjectName and the Java class name of the newly - * instantiated MBean. If the contained ObjectName - * is n, the contained Java class name is - * {@link #getMBeanInfo getMBeanInfo(n)}.getClassName(). - * - * @throws ReflectionException Wraps a - * java.lang.ClassNotFoundException or a - * java.lang.Exception that occurred - * when trying to invoke the MBean's constructor. - * @throws InstanceAlreadyExistsException The MBean is already - * under the control of the MBean server. - * @throws MBeanRegistrationException The - * preRegister (MBeanRegistration - * interface) method of the MBean has thrown an exception. The - * MBean will not be registered. - * @throws MBeanException The constructor of the MBean has - * thrown an exception. - * @throws NotCompliantMBeanException This class is not a JMX - * compliant MBean. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The className - * passed in parameter is null, the ObjectName passed - * in parameter contains a pattern or no ObjectName - * is specified for the MBean. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public ObjectInstance createMBean(String className, - ObjectName name, - Subject delegationSubject) - throws - ReflectionException, - InstanceAlreadyExistsException, - MBeanRegistrationException, - MBeanException, - NotCompliantMBeanException, - IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#createMBean(String, - * ObjectName, ObjectName)}. - * - * @param className The class name of the MBean to be instantiated. - * @param name The object name of the MBean. May be null. - * @param loaderName The object name of the class loader to be used. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return An ObjectInstance, containing the - * ObjectName and the Java class name of the newly - * instantiated MBean. If the contained ObjectName - * is n, the contained Java class name is - * {@link #getMBeanInfo getMBeanInfo(n)}.getClassName(). - * - * @throws ReflectionException Wraps a - * java.lang.ClassNotFoundException or a - * java.lang.Exception that occurred when trying to - * invoke the MBean's constructor. - * @throws InstanceAlreadyExistsException The MBean is already - * under the control of the MBean server. - * @throws MBeanRegistrationException The - * preRegister (MBeanRegistration - * interface) method of the MBean has thrown an exception. The - * MBean will not be registered. - * @throws MBeanException The constructor of the MBean has - * thrown an exception. - * @throws NotCompliantMBeanException This class is not a JMX - * compliant MBean. - * @throws InstanceNotFoundException The specified class loader - * is not registered in the MBean server. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The className - * passed in parameter is null, the ObjectName passed - * in parameter contains a pattern or no ObjectName - * is specified for the MBean. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public ObjectInstance createMBean(String className, - ObjectName name, - ObjectName loaderName, - Subject delegationSubject) - throws - ReflectionException, - InstanceAlreadyExistsException, - MBeanRegistrationException, - MBeanException, - NotCompliantMBeanException, - InstanceNotFoundException, - IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#createMBean(String, - * ObjectName, Object[], String[])}. The Object[] - * parameter is wrapped in a MarshalledObject. - * - * @param className The class name of the MBean to be instantiated. - * @param name The object name of the MBean. May be null. - * @param params An array containing the parameters of the - * constructor to be invoked, encapsulated into a - * MarshalledObject. The encapsulated array can be - * null, equivalent to an empty array. - * @param signature An array containing the signature of the - * constructor to be invoked. Can be null, equivalent to an empty - * array. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return An ObjectInstance, containing the - * ObjectName and the Java class name of the newly - * instantiated MBean. If the contained ObjectName - * is n, the contained Java class name is - * {@link #getMBeanInfo getMBeanInfo(n)}.getClassName(). - * - * @throws ReflectionException Wraps a - * java.lang.ClassNotFoundException or a - * java.lang.Exception that occurred when trying to - * invoke the MBean's constructor. - * @throws InstanceAlreadyExistsException The MBean is already - * under the control of the MBean server. - * @throws MBeanRegistrationException The - * preRegister (MBeanRegistration - * interface) method of the MBean has thrown an exception. The - * MBean will not be registered. - * @throws MBeanException The constructor of the MBean has - * thrown an exception. - * @throws NotCompliantMBeanException This class is not a JMX - * compliant MBean. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The className - * passed in parameter is null, the ObjectName passed - * in parameter contains a pattern, or no ObjectName - * is specified for the MBean. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public ObjectInstance createMBean(String className, - ObjectName name, - MarshalledObject params, - String signature[], - Subject delegationSubject) - throws - ReflectionException, - InstanceAlreadyExistsException, - MBeanRegistrationException, - MBeanException, - NotCompliantMBeanException, - IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#createMBean(String, - * ObjectName, ObjectName, Object[], String[])}. The - * Object[] parameter is wrapped in a - * MarshalledObject. - * - * @param className The class name of the MBean to be instantiated. - * @param name The object name of the MBean. May be null. - * @param loaderName The object name of the class loader to be used. - * @param params An array containing the parameters of the - * constructor to be invoked, encapsulated into a - * MarshalledObject. The encapsulated array can be - * null, equivalent to an empty array. - * @param signature An array containing the signature of the - * constructor to be invoked. Can be null, equivalent to an empty - * array. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return An ObjectInstance, containing the - * ObjectName and the Java class name of the newly - * instantiated MBean. If the contained ObjectName - * is n, the contained Java class name is - * {@link #getMBeanInfo getMBeanInfo(n)}.getClassName(). - * - * @throws ReflectionException Wraps a - * java.lang.ClassNotFoundException or a - * java.lang.Exception that occurred when trying to - * invoke the MBean's constructor. - * @throws InstanceAlreadyExistsException The MBean is already - * under the control of the MBean server. - * @throws MBeanRegistrationException The - * preRegister (MBeanRegistration - * interface) method of the MBean has thrown an exception. The - * MBean will not be registered. - * @throws MBeanException The constructor of the MBean has - * thrown an exception. - * @throws NotCompliantMBeanException This class is not a JMX - * compliant MBean. - * @throws InstanceNotFoundException The specified class loader - * is not registered in the MBean server. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The className - * passed in parameter is null, the ObjectName passed - * in parameter contains a pattern, or no ObjectName - * is specified for the MBean. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public ObjectInstance createMBean(String className, - ObjectName name, - ObjectName loaderName, - MarshalledObject params, - String signature[], - Subject delegationSubject) - throws - ReflectionException, - InstanceAlreadyExistsException, - MBeanRegistrationException, - MBeanException, - NotCompliantMBeanException, - InstanceNotFoundException, - IOException; - - /** - * Handles the method - * {@link javax.management.MBeanServerConnection#unregisterMBean(ObjectName)}. - * - * @param name The object name of the MBean to be unregistered. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @throws InstanceNotFoundException The MBean specified is not - * registered in the MBean server. - * @throws MBeanRegistrationException The preDeregister - * ((MBeanRegistration interface) method of the MBean - * has thrown an exception. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The object - * name in parameter is null or the MBean you are when trying to - * unregister is the {@link javax.management.MBeanServerDelegate - * MBeanServerDelegate} MBean. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public void unregisterMBean(ObjectName name, Subject delegationSubject) - throws - InstanceNotFoundException, - MBeanRegistrationException, - IOException; - - /** - * Handles the method - * {@link javax.management.MBeanServerConnection#getObjectInstance(ObjectName)}. - * - * @param name The object name of the MBean. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return The ObjectInstance associated with the MBean - * specified by name. The contained ObjectName - * is name and the contained class name is - * {@link #getMBeanInfo getMBeanInfo(name)}.getClassName(). - * - * @throws InstanceNotFoundException The MBean specified is not - * registered in the MBean server. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The object - * name in parameter is null. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public ObjectInstance getObjectInstance(ObjectName name, - Subject delegationSubject) - throws InstanceNotFoundException, IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#queryMBeans(ObjectName, - * QueryExp)}. The QueryExp is wrapped in a - * MarshalledObject. - * - * @param name The object name pattern identifying the MBeans to - * be retrieved. If null or no domain and key properties are - * specified, all the MBeans registered will be retrieved. - * @param query The query expression to be applied for selecting - * MBeans, encapsulated into a MarshalledObject. If - * the MarshalledObject encapsulates a null value no - * query expression will be applied for selecting MBeans. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return A set containing the ObjectInstance - * objects for the selected MBeans. If no MBean satisfies the - * query an empty list is returned. - * - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public Set - queryMBeans(ObjectName name, - MarshalledObject query, - Subject delegationSubject) - throws IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#queryNames(ObjectName, - * QueryExp)}. The QueryExp is wrapped in a - * MarshalledObject. - * - * @param name The object name pattern identifying the MBean names - * to be retrieved. If null or no domain and key properties are - * specified, the name of all registered MBeans will be retrieved. - * @param query The query expression to be applied for selecting - * MBeans, encapsulated into a MarshalledObject. If - * the MarshalledObject encapsulates a null value no - * query expression will be applied for selecting MBeans. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return A set containing the ObjectNames for the MBeans - * selected. If no MBean satisfies the query, an empty list is - * returned. - * - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public Set - queryNames(ObjectName name, - MarshalledObject query, - Subject delegationSubject) - throws IOException; - - /** - * Handles the method - * {@link javax.management.MBeanServerConnection#isRegistered(ObjectName)}. - * - * @param name The object name of the MBean to be checked. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return True if the MBean is already registered in the MBean - * server, false otherwise. - * - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The object - * name in parameter is null. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public boolean isRegistered(ObjectName name, Subject delegationSubject) - throws IOException; - - /** - * Handles the method - * {@link javax.management.MBeanServerConnection#getMBeanCount()}. - * - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return the number of MBeans registered. - * - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public Integer getMBeanCount(Subject delegationSubject) - throws IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#getAttribute(ObjectName, - * String)}. - * - * @param name The object name of the MBean from which the - * attribute is to be retrieved. - * @param attribute A String specifying the name of the attribute - * to be retrieved. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return The value of the retrieved attribute. - * - * @throws AttributeNotFoundException The attribute specified - * is not accessible in the MBean. - * @throws MBeanException Wraps an exception thrown by the - * MBean's getter. - * @throws InstanceNotFoundException The MBean specified is not - * registered in the MBean server. - * @throws ReflectionException Wraps a - * java.lang.Exception thrown when trying to invoke - * the getter. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The object - * name in parameter is null or the attribute in parameter is - * null. - * @throws RuntimeMBeanException Wraps a runtime exception thrown - * by the MBean's getter. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - * - * @see #setAttribute - */ - public Object getAttribute(ObjectName name, - String attribute, - Subject delegationSubject) - throws - MBeanException, - AttributeNotFoundException, - InstanceNotFoundException, - ReflectionException, - IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#getAttributes(ObjectName, - * String[])}. - * - * @param name The object name of the MBean from which the - * attributes are retrieved. - * @param attributes A list of the attributes to be retrieved. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return The list of the retrieved attributes. - * - * @throws InstanceNotFoundException The MBean specified is not - * registered in the MBean server. - * @throws ReflectionException An exception occurred when - * trying to invoke the getAttributes method of a Dynamic MBean. - * @throws RuntimeOperationsException Wrap a - * java.lang.IllegalArgumentException: The object - * name in parameter is null or attributes in parameter is null. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - * - * @see #setAttributes - */ - public AttributeList getAttributes(ObjectName name, - String[] attributes, - Subject delegationSubject) - throws - InstanceNotFoundException, - ReflectionException, - IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#setAttribute(ObjectName, - * Attribute)}. The Attribute parameter is wrapped - * in a MarshalledObject. - * - * @param name The name of the MBean within which the attribute is - * to be set. - * @param attribute The identification of the attribute to be set - * and the value it is to be set to, encapsulated into a - * MarshalledObject. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @throws InstanceNotFoundException The MBean specified is not - * registered in the MBean server. - * @throws AttributeNotFoundException The attribute specified - * is not accessible in the MBean. - * @throws InvalidAttributeValueException The value specified - * for the attribute is not valid. - * @throws MBeanException Wraps an exception thrown by the - * MBean's setter. - * @throws ReflectionException Wraps a - * java.lang.Exception thrown when trying to invoke - * the setter. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The object - * name in parameter is null or the attribute in parameter is - * null. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - * - * @see #getAttribute - */ - public void setAttribute(ObjectName name, - MarshalledObject attribute, - Subject delegationSubject) - throws - InstanceNotFoundException, - AttributeNotFoundException, - InvalidAttributeValueException, - MBeanException, - ReflectionException, - IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#setAttributes(ObjectName, - * AttributeList)}. The AttributeList parameter is - * wrapped in a MarshalledObject. - * - * @param name The object name of the MBean within which the - * attributes are to be set. - * @param attributes A list of attributes: The identification of - * the attributes to be set and the values they are to be set to, - * encapsulated into a MarshalledObject. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return The list of attributes that were set, with their new - * values. - * - * @throws InstanceNotFoundException The MBean specified is not - * registered in the MBean server. - * @throws ReflectionException An exception occurred when - * trying to invoke the getAttributes method of a Dynamic MBean. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The object - * name in parameter is null or attributes in parameter is null. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - * - * @see #getAttributes - */ - public AttributeList setAttributes(ObjectName name, - MarshalledObject attributes, - Subject delegationSubject) - throws - InstanceNotFoundException, - ReflectionException, - IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#invoke(ObjectName, - * String, Object[], String[])}. The Object[] - * parameter is wrapped in a MarshalledObject. - * - * @param name The object name of the MBean on which the method is - * to be invoked. - * @param operationName The name of the operation to be invoked. - * @param params An array containing the parameters to be set when - * the operation is invoked, encapsulated into a - * MarshalledObject. The encapsulated array can be - * null, equivalent to an empty array. - * @param signature An array containing the signature of the - * operation. The class objects will be loaded using the same - * class loader as the one used for loading the MBean on which the - * operation was invoked. Can be null, equivalent to an empty - * array. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return The object returned by the operation, which represents - * the result of invoking the operation on the MBean specified. - * - * @throws InstanceNotFoundException The MBean specified is not - * registered in the MBean server. - * @throws MBeanException Wraps an exception thrown by the - * MBean's invoked method. - * @throws ReflectionException Wraps a - * java.lang.Exception thrown while trying to invoke - * the method. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - * @throws RuntimeOperationsException Wraps an {@link - * IllegalArgumentException} when name or - * operationName is null. - */ - public Object invoke(ObjectName name, - String operationName, - MarshalledObject params, - String signature[], - Subject delegationSubject) - throws - InstanceNotFoundException, - MBeanException, - ReflectionException, - IOException; - - /** - * Handles the method - * {@link javax.management.MBeanServerConnection#getDefaultDomain()}. - * - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return the default domain. - * - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public String getDefaultDomain(Subject delegationSubject) - throws IOException; - - /** - * Handles the method - * {@link javax.management.MBeanServerConnection#getDomains()}. - * - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return the list of domains. - * - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - */ - public String[] getDomains(Subject delegationSubject) - throws IOException; - - /** - * Handles the method - * {@link javax.management.MBeanServerConnection#getMBeanInfo(ObjectName)}. - * - * @param name The name of the MBean to analyze - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return An instance of MBeanInfo allowing the - * retrieval of all attributes and operations of this MBean. - * - * @throws IntrospectionException An exception occurred during - * introspection. - * @throws InstanceNotFoundException The MBean specified was - * not found. - * @throws ReflectionException An exception occurred when - * trying to invoke the getMBeanInfo of a Dynamic MBean. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The object - * name in parameter is null. - */ - public MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject) - throws - InstanceNotFoundException, - IntrospectionException, - ReflectionException, - IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#isInstanceOf(ObjectName, - * String)}. - * - * @param name The ObjectName of the MBean. - * @param className The name of the class. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @return true if the MBean specified is an instance of the - * specified class according to the rules above, false otherwise. - * - * @throws InstanceNotFoundException The MBean specified is not - * registered in the MBean server. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - * @throws RuntimeOperationsException Wraps a - * java.lang.IllegalArgumentException: The object - * name in parameter is null. - */ - public boolean isInstanceOf(ObjectName name, - String className, - Subject delegationSubject) - throws InstanceNotFoundException, IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#addNotificationListener(ObjectName, - * ObjectName, NotificationFilter, Object)}. The - * NotificationFilter parameter is wrapped in a - * MarshalledObject. The Object - * (handback) parameter is also wrapped in a - * MarshalledObject. - * - * @param name The name of the MBean on which the listener should - * be added. - * @param listener The object name of the listener which will - * handle the notifications emitted by the registered MBean. - * @param filter The filter object, encapsulated into a - * MarshalledObject. If filter encapsulated in the - * MarshalledObject has a null value, no filtering - * will be performed before handling notifications. - * @param handback The context to be sent to the listener when a - * notification is emitted, encapsulated into a - * MarshalledObject. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @throws InstanceNotFoundException The MBean name of the - * notification listener or of the notification broadcaster does - * not match any of the registered MBeans. - * @throws RuntimeOperationsException Wraps an {@link - * IllegalArgumentException}. The MBean named by - * listener exists but does not implement the - * {@link javax.management.NotificationListener} interface, - * or name or listener is null. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - * - * @see #removeNotificationListener(ObjectName, ObjectName, Subject) - * @see #removeNotificationListener(ObjectName, ObjectName, - * MarshalledObject, MarshalledObject, Subject) - */ - public void addNotificationListener(ObjectName name, - ObjectName listener, - MarshalledObject filter, - MarshalledObject handback, - Subject delegationSubject) - throws InstanceNotFoundException, IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName, - * ObjectName)}. - * - * @param name The name of the MBean on which the listener should - * be removed. - * @param listener The object name of the listener to be removed. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @throws InstanceNotFoundException The MBean name provided - * does not match any of the registered MBeans. - * @throws ListenerNotFoundException The listener is not - * registered in the MBean. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - * @throws RuntimeOperationsException Wraps an {@link - * IllegalArgumentException} when name or - * listener is null. - * - * @see #addNotificationListener - */ - public void removeNotificationListener(ObjectName name, - ObjectName listener, - Subject delegationSubject) - throws - InstanceNotFoundException, - ListenerNotFoundException, - IOException; - - /** - * Handles the method {@link - * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName, - * ObjectName, NotificationFilter, Object)}. The - * NotificationFilter parameter is wrapped in a - * MarshalledObject. The Object - * parameter is also wrapped in a MarshalledObject. - * - * @param name The name of the MBean on which the listener should - * be removed. - * @param listener A listener that was previously added to this - * MBean. - * @param filter The filter that was specified when the listener - * was added, encapsulated into a MarshalledObject. - * @param handback The handback that was specified when the - * listener was added, encapsulated into a MarshalledObject. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @throws InstanceNotFoundException The MBean name provided - * does not match any of the registered MBeans. - * @throws ListenerNotFoundException The listener is not - * registered in the MBean, or it is not registered with the given - * filter and handback. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to perform this operation. - * @throws IOException if a general communication exception occurred. - * @throws RuntimeOperationsException Wraps an {@link - * IllegalArgumentException} when name or - * listener is null. - * - * @see #addNotificationListener - */ - public void removeNotificationListener(ObjectName name, - ObjectName listener, - MarshalledObject filter, - MarshalledObject handback, - Subject delegationSubject) - throws - InstanceNotFoundException, - ListenerNotFoundException, - IOException; - - // Special Handling of Notifications ------------------------------------- - - /** - *

Handles the method {@link - * javax.management.MBeanServerConnection#addNotificationListener(ObjectName, - * NotificationListener, NotificationFilter, Object)}.

- * - *

Register for notifications from the given MBeans that match - * the given filters. The remote client can subsequently retrieve - * the notifications using the {@link #fetchNotifications - * fetchNotifications} method.

- * - *

For each listener, the original - * NotificationListener and handback are - * kept on the client side; in order for the client to be able to - * identify them, the server generates and returns a unique - * listenerID. This listenerID is - * forwarded with the Notifications to the remote - * client.

- * - *

If any one of the given (name, filter) pairs cannot be - * registered, then the operation fails with an exception, and no - * names or filters are registered.

- * - * @param names the ObjectNames identifying the - * MBeans emitting the Notifications. - * @param filters an array of marshalled representations of the - * NotificationFilters. Elements of this array can - * be null. - * @param delegationSubjects the Subjects on behalf - * of which the listeners are being added. Elements of this array - * can be null. Also, the delegationSubjects - * parameter itself can be null, which is equivalent to an array - * of null values with the same size as the names and - * filters arrays. - * - * @return an array of listenerIDs identifying the - * local listeners. This array has the same number of elements as - * the parameters. - * - * @throws IllegalArgumentException if names or - * filters is null, or if names contains - * a null element, or if the three arrays do not all have the same - * size. - * @throws ClassCastException if one of the elements of - * filters unmarshalls as a non-null object that is - * not a NotificationFilter. - * @throws InstanceNotFoundException if one of the - * names does not correspond to any registered MBean. - * @throws SecurityException if, for one of the MBeans, the - * client, or the delegated Subject if any, does not have - * permission to add a listener. - * @throws IOException if a general communication exception occurred. - */ - public Integer[] addNotificationListeners(ObjectName[] names, - MarshalledObject[] filters, - Subject[] delegationSubjects) - throws InstanceNotFoundException, IOException; - - /** - *

Handles the - * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener) - * removeNotificationListener(ObjectName, NotificationListener)} and - * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener,NotificationFilter,Object) - * removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)} methods.

- * - *

This method removes one or more - * NotificationListeners from a given MBean in the - * MBean server.

- * - *

The NotificationListeners are identified by the - * IDs which were returned by the {@link - * #addNotificationListeners(ObjectName[], MarshalledObject[], - * Subject[])} method.

- * - * @param name the ObjectName identifying the MBean - * emitting the Notifications. - * @param listenerIDs the list of the IDs corresponding to the - * listeners to remove. - * @param delegationSubject The Subject containing the - * delegation principals or null if the authentication - * principal is used instead. - * - * @throws InstanceNotFoundException if the given - * name does not correspond to any registered MBean. - * @throws ListenerNotFoundException if one of the listeners was - * not found on the server side. This exception can happen if the - * MBean discarded a listener for some reason other than a call to - * MBeanServer.removeNotificationListener. - * @throws SecurityException if the client, or the delegated Subject - * if any, does not have permission to remove the listeners. - * @throws IOException if a general communication exception occurred. - * @throws IllegalArgumentException if ObjectName or - * listenerIds is null or if listenerIds - * contains a null element. - */ - public void removeNotificationListeners(ObjectName name, - Integer[] listenerIDs, - Subject delegationSubject) - throws - InstanceNotFoundException, - ListenerNotFoundException, - IOException; - - /** - *

Retrieves notifications from the connector server. This - * method can block until there is at least one notification or - * until the specified timeout is reached. The method can also - * return at any time with zero notifications.

- * - *

A notification can be included in the result if its sequence - * number is no less than clientSequenceNumber and - * this client has registered at least one listener for the MBean - * generating the notification, with a filter that accepts the - * notification. Each listener that is interested in the - * notification is identified by an Integer ID that was returned - * by {@link #addNotificationListeners(ObjectName[], - * MarshalledObject[], Subject[])}.

- * - * @param clientSequenceNumber the first sequence number that the - * client is interested in. If negative, it is interpreted as - * meaning the sequence number that the next notification will - * have. - * - * @param maxNotifications the maximum number of different - * notifications to return. The TargetedNotification - * array in the returned NotificationResult can have - * more elements than this if the same notification appears more - * than once. The behavior is unspecified if this parameter is - * negative. - * - * @param timeout the maximum time in milliseconds to wait for a - * notification to arrive. This can be 0 to indicate that the - * method should not wait if there are no notifications, but - * should return at once. It can be Long.MAX_VALUE - * to indicate that there is no timeout. The behavior is - * unspecified if this parameter is negative. - * - * @return A NotificationResult. - * - * @throws IOException if a general communication exception occurred. - */ - public NotificationResult fetchNotifications(long clientSequenceNumber, - int maxNotifications, - long timeout) - throws IOException; -} --- /dev/null 2017-02-01 16:12:52.000000000 +0000 +++ new/jdk/src/java.management.rmi/share/classes/javax/management/remote/rmi/RMIConnection.java 2017-02-01 16:12:51.000000000 +0000 @@ -0,0 +1,1092 @@ +/* + * Copyright (c) 2002, 2008, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +package javax.management.remote.rmi; + +import java.io.Closeable; +import java.io.IOException; +import java.rmi.MarshalledObject; +import java.rmi.Remote; +import java.util.Set; + +import javax.management.AttributeList; +import javax.management.AttributeNotFoundException; +import javax.management.InstanceAlreadyExistsException; +import javax.management.InstanceNotFoundException; +import javax.management.IntrospectionException; +import javax.management.InvalidAttributeValueException; +import javax.management.ListenerNotFoundException; +import javax.management.MBeanException; +import javax.management.MBeanInfo; +import javax.management.MBeanRegistrationException; +import javax.management.MBeanServerConnection; +import javax.management.NotCompliantMBeanException; + +import javax.management.ObjectInstance; +import javax.management.ObjectName; +import javax.management.ReflectionException; +import javax.management.RuntimeMBeanException; +import javax.management.RuntimeOperationsException; +import javax.management.remote.NotificationResult; +import javax.security.auth.Subject; + +/** + *

RMI object used to forward an MBeanServer request from a client + * to its MBeanServer implementation on the server side. There is one + * Remote object implementing this interface for each remote client + * connected to an RMI connector.

+ * + *

User code does not usually refer to this interface. It is + * specified as part of the public API so that different + * implementations of that API will interoperate.

+ * + *

To ensure that client parameters will be deserialized at the + * server side with the correct classloader, client parameters such as + * parameters used to invoke a method are wrapped in a {@link + * MarshalledObject}. An implementation of this interface must first + * get the appropriate class loader for the operation and its target, + * then deserialize the marshalled parameters with this classloader. + * Except as noted, a parameter that is a + * MarshalledObject or MarshalledObject[] + * must not be null; the behavior is unspecified if it is.

+ * + *

Class loading aspects are detailed in the + * + * JMX Specification, version 1.4 PDF document.

+ * + *

Most methods in this interface parallel methods in the {@link + * MBeanServerConnection} interface. Where an aspect of the behavior + * of a method is not specified here, it is the same as in the + * corresponding MBeanServerConnection method. + * + * @since 1.5 + */ +/* + * Notice that we omit the type parameter from MarshalledObject everywhere, + * even though it would add useful information to the documentation. The + * reason is that it was only added in Mustang (Java SE 6), whereas versions + * 1.4 and 2.0 of the JMX API must be implementable on Tiger per our + * commitments for JSR 255. This is also why we suppress rawtypes warnings. + */ +@SuppressWarnings("rawtypes") +public interface RMIConnection extends Closeable, Remote { + /** + *

Returns the connection ID. This string is different for + * every open connection to a given RMI connector server.

+ * + * @return the connection ID + * + * @see RMIConnector#connect RMIConnector.connect + * + * @throws IOException if a general communication exception occurred. + */ + public String getConnectionId() throws IOException; + + /** + *

Closes this connection. On return from this method, the RMI + * object implementing this interface is unexported, so further + * remote calls to it will fail.

+ * + * @throws IOException if the connection could not be closed, + * or the Remote object could not be unexported, or there was a + * communication failure when transmitting the remote close + * request. + */ + public void close() throws IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#createMBean(String, + * ObjectName)}. + * + * @param className The class name of the MBean to be instantiated. + * @param name The object name of the MBean. May be null. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return An ObjectInstance, containing the + * ObjectName and the Java class name of the newly + * instantiated MBean. If the contained ObjectName + * is n, the contained Java class name is + * {@link #getMBeanInfo getMBeanInfo(n)}.getClassName(). + * + * @throws ReflectionException Wraps a + * java.lang.ClassNotFoundException or a + * java.lang.Exception that occurred + * when trying to invoke the MBean's constructor. + * @throws InstanceAlreadyExistsException The MBean is already + * under the control of the MBean server. + * @throws MBeanRegistrationException The + * preRegister (MBeanRegistration + * interface) method of the MBean has thrown an exception. The + * MBean will not be registered. + * @throws MBeanException The constructor of the MBean has + * thrown an exception. + * @throws NotCompliantMBeanException This class is not a JMX + * compliant MBean. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The className + * passed in parameter is null, the ObjectName passed + * in parameter contains a pattern or no ObjectName + * is specified for the MBean. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public ObjectInstance createMBean(String className, + ObjectName name, + Subject delegationSubject) + throws + ReflectionException, + InstanceAlreadyExistsException, + MBeanRegistrationException, + MBeanException, + NotCompliantMBeanException, + IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#createMBean(String, + * ObjectName, ObjectName)}. + * + * @param className The class name of the MBean to be instantiated. + * @param name The object name of the MBean. May be null. + * @param loaderName The object name of the class loader to be used. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return An ObjectInstance, containing the + * ObjectName and the Java class name of the newly + * instantiated MBean. If the contained ObjectName + * is n, the contained Java class name is + * {@link #getMBeanInfo getMBeanInfo(n)}.getClassName(). + * + * @throws ReflectionException Wraps a + * java.lang.ClassNotFoundException or a + * java.lang.Exception that occurred when trying to + * invoke the MBean's constructor. + * @throws InstanceAlreadyExistsException The MBean is already + * under the control of the MBean server. + * @throws MBeanRegistrationException The + * preRegister (MBeanRegistration + * interface) method of the MBean has thrown an exception. The + * MBean will not be registered. + * @throws MBeanException The constructor of the MBean has + * thrown an exception. + * @throws NotCompliantMBeanException This class is not a JMX + * compliant MBean. + * @throws InstanceNotFoundException The specified class loader + * is not registered in the MBean server. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The className + * passed in parameter is null, the ObjectName passed + * in parameter contains a pattern or no ObjectName + * is specified for the MBean. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public ObjectInstance createMBean(String className, + ObjectName name, + ObjectName loaderName, + Subject delegationSubject) + throws + ReflectionException, + InstanceAlreadyExistsException, + MBeanRegistrationException, + MBeanException, + NotCompliantMBeanException, + InstanceNotFoundException, + IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#createMBean(String, + * ObjectName, Object[], String[])}. The Object[] + * parameter is wrapped in a MarshalledObject. + * + * @param className The class name of the MBean to be instantiated. + * @param name The object name of the MBean. May be null. + * @param params An array containing the parameters of the + * constructor to be invoked, encapsulated into a + * MarshalledObject. The encapsulated array can be + * null, equivalent to an empty array. + * @param signature An array containing the signature of the + * constructor to be invoked. Can be null, equivalent to an empty + * array. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return An ObjectInstance, containing the + * ObjectName and the Java class name of the newly + * instantiated MBean. If the contained ObjectName + * is n, the contained Java class name is + * {@link #getMBeanInfo getMBeanInfo(n)}.getClassName(). + * + * @throws ReflectionException Wraps a + * java.lang.ClassNotFoundException or a + * java.lang.Exception that occurred when trying to + * invoke the MBean's constructor. + * @throws InstanceAlreadyExistsException The MBean is already + * under the control of the MBean server. + * @throws MBeanRegistrationException The + * preRegister (MBeanRegistration + * interface) method of the MBean has thrown an exception. The + * MBean will not be registered. + * @throws MBeanException The constructor of the MBean has + * thrown an exception. + * @throws NotCompliantMBeanException This class is not a JMX + * compliant MBean. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The className + * passed in parameter is null, the ObjectName passed + * in parameter contains a pattern, or no ObjectName + * is specified for the MBean. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public ObjectInstance createMBean(String className, + ObjectName name, + MarshalledObject params, + String signature[], + Subject delegationSubject) + throws + ReflectionException, + InstanceAlreadyExistsException, + MBeanRegistrationException, + MBeanException, + NotCompliantMBeanException, + IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#createMBean(String, + * ObjectName, ObjectName, Object[], String[])}. The + * Object[] parameter is wrapped in a + * MarshalledObject. + * + * @param className The class name of the MBean to be instantiated. + * @param name The object name of the MBean. May be null. + * @param loaderName The object name of the class loader to be used. + * @param params An array containing the parameters of the + * constructor to be invoked, encapsulated into a + * MarshalledObject. The encapsulated array can be + * null, equivalent to an empty array. + * @param signature An array containing the signature of the + * constructor to be invoked. Can be null, equivalent to an empty + * array. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return An ObjectInstance, containing the + * ObjectName and the Java class name of the newly + * instantiated MBean. If the contained ObjectName + * is n, the contained Java class name is + * {@link #getMBeanInfo getMBeanInfo(n)}.getClassName(). + * + * @throws ReflectionException Wraps a + * java.lang.ClassNotFoundException or a + * java.lang.Exception that occurred when trying to + * invoke the MBean's constructor. + * @throws InstanceAlreadyExistsException The MBean is already + * under the control of the MBean server. + * @throws MBeanRegistrationException The + * preRegister (MBeanRegistration + * interface) method of the MBean has thrown an exception. The + * MBean will not be registered. + * @throws MBeanException The constructor of the MBean has + * thrown an exception. + * @throws NotCompliantMBeanException This class is not a JMX + * compliant MBean. + * @throws InstanceNotFoundException The specified class loader + * is not registered in the MBean server. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The className + * passed in parameter is null, the ObjectName passed + * in parameter contains a pattern, or no ObjectName + * is specified for the MBean. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public ObjectInstance createMBean(String className, + ObjectName name, + ObjectName loaderName, + MarshalledObject params, + String signature[], + Subject delegationSubject) + throws + ReflectionException, + InstanceAlreadyExistsException, + MBeanRegistrationException, + MBeanException, + NotCompliantMBeanException, + InstanceNotFoundException, + IOException; + + /** + * Handles the method + * {@link javax.management.MBeanServerConnection#unregisterMBean(ObjectName)}. + * + * @param name The object name of the MBean to be unregistered. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @throws InstanceNotFoundException The MBean specified is not + * registered in the MBean server. + * @throws MBeanRegistrationException The preDeregister + * ((MBeanRegistration interface) method of the MBean + * has thrown an exception. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The object + * name in parameter is null or the MBean you are when trying to + * unregister is the {@link javax.management.MBeanServerDelegate + * MBeanServerDelegate} MBean. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public void unregisterMBean(ObjectName name, Subject delegationSubject) + throws + InstanceNotFoundException, + MBeanRegistrationException, + IOException; + + /** + * Handles the method + * {@link javax.management.MBeanServerConnection#getObjectInstance(ObjectName)}. + * + * @param name The object name of the MBean. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return The ObjectInstance associated with the MBean + * specified by name. The contained ObjectName + * is name and the contained class name is + * {@link #getMBeanInfo getMBeanInfo(name)}.getClassName(). + * + * @throws InstanceNotFoundException The MBean specified is not + * registered in the MBean server. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The object + * name in parameter is null. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public ObjectInstance getObjectInstance(ObjectName name, + Subject delegationSubject) + throws InstanceNotFoundException, IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#queryMBeans(ObjectName, + * QueryExp)}. The QueryExp is wrapped in a + * MarshalledObject. + * + * @param name The object name pattern identifying the MBeans to + * be retrieved. If null or no domain and key properties are + * specified, all the MBeans registered will be retrieved. + * @param query The query expression to be applied for selecting + * MBeans, encapsulated into a MarshalledObject. If + * the MarshalledObject encapsulates a null value no + * query expression will be applied for selecting MBeans. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return A set containing the ObjectInstance + * objects for the selected MBeans. If no MBean satisfies the + * query an empty list is returned. + * + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public Set + queryMBeans(ObjectName name, + MarshalledObject query, + Subject delegationSubject) + throws IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#queryNames(ObjectName, + * QueryExp)}. The QueryExp is wrapped in a + * MarshalledObject. + * + * @param name The object name pattern identifying the MBean names + * to be retrieved. If null or no domain and key properties are + * specified, the name of all registered MBeans will be retrieved. + * @param query The query expression to be applied for selecting + * MBeans, encapsulated into a MarshalledObject. If + * the MarshalledObject encapsulates a null value no + * query expression will be applied for selecting MBeans. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return A set containing the ObjectNames for the MBeans + * selected. If no MBean satisfies the query, an empty list is + * returned. + * + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public Set + queryNames(ObjectName name, + MarshalledObject query, + Subject delegationSubject) + throws IOException; + + /** + * Handles the method + * {@link javax.management.MBeanServerConnection#isRegistered(ObjectName)}. + * + * @param name The object name of the MBean to be checked. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return True if the MBean is already registered in the MBean + * server, false otherwise. + * + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The object + * name in parameter is null. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public boolean isRegistered(ObjectName name, Subject delegationSubject) + throws IOException; + + /** + * Handles the method + * {@link javax.management.MBeanServerConnection#getMBeanCount()}. + * + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return the number of MBeans registered. + * + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public Integer getMBeanCount(Subject delegationSubject) + throws IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#getAttribute(ObjectName, + * String)}. + * + * @param name The object name of the MBean from which the + * attribute is to be retrieved. + * @param attribute A String specifying the name of the attribute + * to be retrieved. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return The value of the retrieved attribute. + * + * @throws AttributeNotFoundException The attribute specified + * is not accessible in the MBean. + * @throws MBeanException Wraps an exception thrown by the + * MBean's getter. + * @throws InstanceNotFoundException The MBean specified is not + * registered in the MBean server. + * @throws ReflectionException Wraps a + * java.lang.Exception thrown when trying to invoke + * the getter. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The object + * name in parameter is null or the attribute in parameter is + * null. + * @throws RuntimeMBeanException Wraps a runtime exception thrown + * by the MBean's getter. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + * + * @see #setAttribute + */ + public Object getAttribute(ObjectName name, + String attribute, + Subject delegationSubject) + throws + MBeanException, + AttributeNotFoundException, + InstanceNotFoundException, + ReflectionException, + IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#getAttributes(ObjectName, + * String[])}. + * + * @param name The object name of the MBean from which the + * attributes are retrieved. + * @param attributes A list of the attributes to be retrieved. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return The list of the retrieved attributes. + * + * @throws InstanceNotFoundException The MBean specified is not + * registered in the MBean server. + * @throws ReflectionException An exception occurred when + * trying to invoke the getAttributes method of a Dynamic MBean. + * @throws RuntimeOperationsException Wrap a + * java.lang.IllegalArgumentException: The object + * name in parameter is null or attributes in parameter is null. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + * + * @see #setAttributes + */ + public AttributeList getAttributes(ObjectName name, + String[] attributes, + Subject delegationSubject) + throws + InstanceNotFoundException, + ReflectionException, + IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#setAttribute(ObjectName, + * Attribute)}. The Attribute parameter is wrapped + * in a MarshalledObject. + * + * @param name The name of the MBean within which the attribute is + * to be set. + * @param attribute The identification of the attribute to be set + * and the value it is to be set to, encapsulated into a + * MarshalledObject. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @throws InstanceNotFoundException The MBean specified is not + * registered in the MBean server. + * @throws AttributeNotFoundException The attribute specified + * is not accessible in the MBean. + * @throws InvalidAttributeValueException The value specified + * for the attribute is not valid. + * @throws MBeanException Wraps an exception thrown by the + * MBean's setter. + * @throws ReflectionException Wraps a + * java.lang.Exception thrown when trying to invoke + * the setter. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The object + * name in parameter is null or the attribute in parameter is + * null. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + * + * @see #getAttribute + */ + public void setAttribute(ObjectName name, + MarshalledObject attribute, + Subject delegationSubject) + throws + InstanceNotFoundException, + AttributeNotFoundException, + InvalidAttributeValueException, + MBeanException, + ReflectionException, + IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#setAttributes(ObjectName, + * AttributeList)}. The AttributeList parameter is + * wrapped in a MarshalledObject. + * + * @param name The object name of the MBean within which the + * attributes are to be set. + * @param attributes A list of attributes: The identification of + * the attributes to be set and the values they are to be set to, + * encapsulated into a MarshalledObject. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return The list of attributes that were set, with their new + * values. + * + * @throws InstanceNotFoundException The MBean specified is not + * registered in the MBean server. + * @throws ReflectionException An exception occurred when + * trying to invoke the getAttributes method of a Dynamic MBean. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The object + * name in parameter is null or attributes in parameter is null. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + * + * @see #getAttributes + */ + public AttributeList setAttributes(ObjectName name, + MarshalledObject attributes, + Subject delegationSubject) + throws + InstanceNotFoundException, + ReflectionException, + IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#invoke(ObjectName, + * String, Object[], String[])}. The Object[] + * parameter is wrapped in a MarshalledObject. + * + * @param name The object name of the MBean on which the method is + * to be invoked. + * @param operationName The name of the operation to be invoked. + * @param params An array containing the parameters to be set when + * the operation is invoked, encapsulated into a + * MarshalledObject. The encapsulated array can be + * null, equivalent to an empty array. + * @param signature An array containing the signature of the + * operation. The class objects will be loaded using the same + * class loader as the one used for loading the MBean on which the + * operation was invoked. Can be null, equivalent to an empty + * array. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return The object returned by the operation, which represents + * the result of invoking the operation on the MBean specified. + * + * @throws InstanceNotFoundException The MBean specified is not + * registered in the MBean server. + * @throws MBeanException Wraps an exception thrown by the + * MBean's invoked method. + * @throws ReflectionException Wraps a + * java.lang.Exception thrown while trying to invoke + * the method. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + * @throws RuntimeOperationsException Wraps an {@link + * IllegalArgumentException} when name or + * operationName is null. + */ + public Object invoke(ObjectName name, + String operationName, + MarshalledObject params, + String signature[], + Subject delegationSubject) + throws + InstanceNotFoundException, + MBeanException, + ReflectionException, + IOException; + + /** + * Handles the method + * {@link javax.management.MBeanServerConnection#getDefaultDomain()}. + * + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return the default domain. + * + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public String getDefaultDomain(Subject delegationSubject) + throws IOException; + + /** + * Handles the method + * {@link javax.management.MBeanServerConnection#getDomains()}. + * + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return the list of domains. + * + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + */ + public String[] getDomains(Subject delegationSubject) + throws IOException; + + /** + * Handles the method + * {@link javax.management.MBeanServerConnection#getMBeanInfo(ObjectName)}. + * + * @param name The name of the MBean to analyze + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return An instance of MBeanInfo allowing the + * retrieval of all attributes and operations of this MBean. + * + * @throws IntrospectionException An exception occurred during + * introspection. + * @throws InstanceNotFoundException The MBean specified was + * not found. + * @throws ReflectionException An exception occurred when + * trying to invoke the getMBeanInfo of a Dynamic MBean. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The object + * name in parameter is null. + */ + public MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject) + throws + InstanceNotFoundException, + IntrospectionException, + ReflectionException, + IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#isInstanceOf(ObjectName, + * String)}. + * + * @param name The ObjectName of the MBean. + * @param className The name of the class. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @return true if the MBean specified is an instance of the + * specified class according to the rules above, false otherwise. + * + * @throws InstanceNotFoundException The MBean specified is not + * registered in the MBean server. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + * @throws RuntimeOperationsException Wraps a + * java.lang.IllegalArgumentException: The object + * name in parameter is null. + */ + public boolean isInstanceOf(ObjectName name, + String className, + Subject delegationSubject) + throws InstanceNotFoundException, IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#addNotificationListener(ObjectName, + * ObjectName, NotificationFilter, Object)}. The + * NotificationFilter parameter is wrapped in a + * MarshalledObject. The Object + * (handback) parameter is also wrapped in a + * MarshalledObject. + * + * @param name The name of the MBean on which the listener should + * be added. + * @param listener The object name of the listener which will + * handle the notifications emitted by the registered MBean. + * @param filter The filter object, encapsulated into a + * MarshalledObject. If filter encapsulated in the + * MarshalledObject has a null value, no filtering + * will be performed before handling notifications. + * @param handback The context to be sent to the listener when a + * notification is emitted, encapsulated into a + * MarshalledObject. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @throws InstanceNotFoundException The MBean name of the + * notification listener or of the notification broadcaster does + * not match any of the registered MBeans. + * @throws RuntimeOperationsException Wraps an {@link + * IllegalArgumentException}. The MBean named by + * listener exists but does not implement the + * {@link javax.management.NotificationListener} interface, + * or name or listener is null. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + * + * @see #removeNotificationListener(ObjectName, ObjectName, Subject) + * @see #removeNotificationListener(ObjectName, ObjectName, + * MarshalledObject, MarshalledObject, Subject) + */ + public void addNotificationListener(ObjectName name, + ObjectName listener, + MarshalledObject filter, + MarshalledObject handback, + Subject delegationSubject) + throws InstanceNotFoundException, IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName, + * ObjectName)}. + * + * @param name The name of the MBean on which the listener should + * be removed. + * @param listener The object name of the listener to be removed. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @throws InstanceNotFoundException The MBean name provided + * does not match any of the registered MBeans. + * @throws ListenerNotFoundException The listener is not + * registered in the MBean. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + * @throws RuntimeOperationsException Wraps an {@link + * IllegalArgumentException} when name or + * listener is null. + * + * @see #addNotificationListener + */ + public void removeNotificationListener(ObjectName name, + ObjectName listener, + Subject delegationSubject) + throws + InstanceNotFoundException, + ListenerNotFoundException, + IOException; + + /** + * Handles the method {@link + * javax.management.MBeanServerConnection#removeNotificationListener(ObjectName, + * ObjectName, NotificationFilter, Object)}. The + * NotificationFilter parameter is wrapped in a + * MarshalledObject. The Object + * parameter is also wrapped in a MarshalledObject. + * + * @param name The name of the MBean on which the listener should + * be removed. + * @param listener A listener that was previously added to this + * MBean. + * @param filter The filter that was specified when the listener + * was added, encapsulated into a MarshalledObject. + * @param handback The handback that was specified when the + * listener was added, encapsulated into a MarshalledObject. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @throws InstanceNotFoundException The MBean name provided + * does not match any of the registered MBeans. + * @throws ListenerNotFoundException The listener is not + * registered in the MBean, or it is not registered with the given + * filter and handback. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to perform this operation. + * @throws IOException if a general communication exception occurred. + * @throws RuntimeOperationsException Wraps an {@link + * IllegalArgumentException} when name or + * listener is null. + * + * @see #addNotificationListener + */ + public void removeNotificationListener(ObjectName name, + ObjectName listener, + MarshalledObject filter, + MarshalledObject handback, + Subject delegationSubject) + throws + InstanceNotFoundException, + ListenerNotFoundException, + IOException; + + // Special Handling of Notifications ------------------------------------- + + /** + *

Handles the method {@link + * javax.management.MBeanServerConnection#addNotificationListener(ObjectName, + * NotificationListener, NotificationFilter, Object)}.

+ * + *

Register for notifications from the given MBeans that match + * the given filters. The remote client can subsequently retrieve + * the notifications using the {@link #fetchNotifications + * fetchNotifications} method.

+ * + *

For each listener, the original + * NotificationListener and handback are + * kept on the client side; in order for the client to be able to + * identify them, the server generates and returns a unique + * listenerID. This listenerID is + * forwarded with the Notifications to the remote + * client.

+ * + *

If any one of the given (name, filter) pairs cannot be + * registered, then the operation fails with an exception, and no + * names or filters are registered.

+ * + * @param names the ObjectNames identifying the + * MBeans emitting the Notifications. + * @param filters an array of marshalled representations of the + * NotificationFilters. Elements of this array can + * be null. + * @param delegationSubjects the Subjects on behalf + * of which the listeners are being added. Elements of this array + * can be null. Also, the delegationSubjects + * parameter itself can be null, which is equivalent to an array + * of null values with the same size as the names and + * filters arrays. + * + * @return an array of listenerIDs identifying the + * local listeners. This array has the same number of elements as + * the parameters. + * + * @throws IllegalArgumentException if names or + * filters is null, or if names contains + * a null element, or if the three arrays do not all have the same + * size. + * @throws ClassCastException if one of the elements of + * filters unmarshalls as a non-null object that is + * not a NotificationFilter. + * @throws InstanceNotFoundException if one of the + * names does not correspond to any registered MBean. + * @throws SecurityException if, for one of the MBeans, the + * client, or the delegated Subject if any, does not have + * permission to add a listener. + * @throws IOException if a general communication exception occurred. + */ + public Integer[] addNotificationListeners(ObjectName[] names, + MarshalledObject[] filters, + Subject[] delegationSubjects) + throws InstanceNotFoundException, IOException; + + /** + *

Handles the + * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener) + * removeNotificationListener(ObjectName, NotificationListener)} and + * {@link javax.management.MBeanServerConnection#removeNotificationListener(ObjectName,NotificationListener,NotificationFilter,Object) + * removeNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object)} methods.

+ * + *

This method removes one or more + * NotificationListeners from a given MBean in the + * MBean server.

+ * + *

The NotificationListeners are identified by the + * IDs which were returned by the {@link + * #addNotificationListeners(ObjectName[], MarshalledObject[], + * Subject[])} method.

+ * + * @param name the ObjectName identifying the MBean + * emitting the Notifications. + * @param listenerIDs the list of the IDs corresponding to the + * listeners to remove. + * @param delegationSubject The Subject containing the + * delegation principals or null if the authentication + * principal is used instead. + * + * @throws InstanceNotFoundException if the given + * name does not correspond to any registered MBean. + * @throws ListenerNotFoundException if one of the listeners was + * not found on the server side. This exception can happen if the + * MBean discarded a listener for some reason other than a call to + * MBeanServer.removeNotificationListener. + * @throws SecurityException if the client, or the delegated Subject + * if any, does not have permission to remove the listeners. + * @throws IOException if a general communication exception occurred. + * @throws IllegalArgumentException if ObjectName or + * listenerIds is null or if listenerIds + * contains a null element. + */ + public void removeNotificationListeners(ObjectName name, + Integer[] listenerIDs, + Subject delegationSubject) + throws + InstanceNotFoundException, + ListenerNotFoundException, + IOException; + + /** + *

Retrieves notifications from the connector server. This + * method can block until there is at least one notification or + * until the specified timeout is reached. The method can also + * return at any time with zero notifications.

+ * + *

A notification can be included in the result if its sequence + * number is no less than clientSequenceNumber and + * this client has registered at least one listener for the MBean + * generating the notification, with a filter that accepts the + * notification. Each listener that is interested in the + * notification is identified by an Integer ID that was returned + * by {@link #addNotificationListeners(ObjectName[], + * MarshalledObject[], Subject[])}.

+ * + * @param clientSequenceNumber the first sequence number that the + * client is interested in. If negative, it is interpreted as + * meaning the sequence number that the next notification will + * have. + * + * @param maxNotifications the maximum number of different + * notifications to return. The TargetedNotification + * array in the returned NotificationResult can have + * more elements than this if the same notification appears more + * than once. The behavior is unspecified if this parameter is + * negative. + * + * @param timeout the maximum time in milliseconds to wait for a + * notification to arrive. This can be 0 to indicate that the + * method should not wait if there are no notifications, but + * should return at once. It can be Long.MAX_VALUE + * to indicate that there is no timeout. The behavior is + * unspecified if this parameter is negative. + * + * @return A NotificationResult. + * + * @throws IOException if a general communication exception occurred. + */ + public NotificationResult fetchNotifications(long clientSequenceNumber, + int maxNotifications, + long timeout) + throws IOException; +}