diff options
Diffstat (limited to 'libjava/classpath/javax/management/remote/rmi')
| -rw-r--r-- | libjava/classpath/javax/management/remote/rmi/RMIConnection.java | 1161 | ||||
| -rw-r--r-- | libjava/classpath/javax/management/remote/rmi/RMIServer.java | 89 |
2 files changed, 1250 insertions, 0 deletions
diff --git a/libjava/classpath/javax/management/remote/rmi/RMIConnection.java b/libjava/classpath/javax/management/remote/rmi/RMIConnection.java new file mode 100644 index 000000000..434051d58 --- /dev/null +++ b/libjava/classpath/javax/management/remote/rmi/RMIConnection.java @@ -0,0 +1,1161 @@ +/* RMIConnection.java -- RMI object representing a MBean server connection. + Copyright (C) 2007, 2008 Free Software Foundation, Inc. + +This file is part of GNU Classpath. + +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath 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 for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +02110-1301 USA. + +Linking this library statically or dynamically with other modules is +making a combined work based on this library. Thus, the terms and +conditions of the GNU General Public License cover the whole +combination. + +As a special exception, the copyright holders of this library give you +permission to link this library with independent modules to produce an +executable, regardless of the license terms of these independent +modules, and to copy and distribute the resulting executable under +terms of your choice, provided that you also meet, for each linked +independent module, the terms and conditions of the license of that +module. An independent module is a module which is not derived from +or based on this library. If you modify this library, you may extend +this exception to your version of the library, but you are not +obligated to do so. If you do not wish to do so, delete this +exception statement from your version. */ + +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.MBeanInfo; +import javax.management.MBeanException; +import javax.management.MBeanRegistrationException; +import javax.management.NotCompliantMBeanException; +import javax.management.ObjectInstance; +import javax.management.ObjectName; +import javax.management.ReflectionException; + +import javax.management.remote.NotificationResult; + +import javax.security.auth.Subject; + +/** + * <p> + * RMI interface for forwarding requests to a remote + * {@link javax.management.MBeanServer}. This interface + * parallels the {@link javax.management.MBeanServerConnection} + * interface, providing a way of invoking those methods using + * the RMI protocol. When a client wishes to call a method + * of an MBean server using RMI, the method is called on the stub + * on the client side, which serializes the object parameters + * and sends them to the server where they are deserialized and + * an implementation of this interface forwards them to the + * appropriate MBean server. Return values follow the same + * process, only in reverse. Each client obtains its own + * implementation of this interface from an {@link RMIServer} + * instance. + * </p> + * <p> + * Implementations of this interface do more than simply + * forward requests directly to the server. The arguments + * of the server methods are wrapped in {@link MarshalledObject} + * instances, so that the correct classloader can be used to + * deserialize the arguments. When a method is called, the + * implementation must first retrieve the appropriate classloader + * and then use it to deserialize the marshalled object. Unless + * explicitly specified in the documentation for the method, + * a parameter of the type {@link MarshalledObject} or an array + * of that type should not be {@code null}. + * </p> + * <p> + * Security is also handled by this interface, as the methods + * use an additional {@link javax.security.auth.Subject} parameter + * for role delegation. + * </p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.5 + */ +public interface RMIConnection + extends Closeable, Remote +{ + + /** + * Handles {@link + * MBeanServerConnection#addNotificationListener(ObjectName, + * ObjectName, NotificationFilter, Object)} by + * registering the supplied listener with the specified management + * bean. Notifications emitted by the management bean are forwarded + * to the listener via the server, which will convert any MBean + * references in the source to portable {@link ObjectName} + * instances. The notification is otherwise unchanged. The filter + * and handback object are wrapped in a {@link MarshalledObject} + * so that they are deserialised using the bean's classloader. + * + * @param name the name of the management bean with which the listener + * should be registered. + * @param listener the listener which will handle notifications from + * the bean. + * @param filter a wrapper containing a filter to apply to incoming + * notifications, or <code>null</code> if no filtering + * should be applied. + * @param passback a wrapper containing an object to be passed to the + * listener when a notification is emitted. + * @param delegationSubject a {@link javax.security.auth.Subject} instance + * containing the delegation principles or + * {@code null} if authentication is used. + * @throws InstanceNotFoundException if the name of the management bean + * could not be resolved. + * @throws RuntimeOperationsException if the bean associated with the given + * object name is not a + * {@link NotificationListener}. This + * exception wraps an + * {@link IllegalArgumentException}. + * @throws SecurityException if the client or delegated subject (if any) + * does not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see #removeNotificationListener(ObjectName, ObjectName, + * javax.security.auth.Subject) + * @see #removeNotificationListener(ObjectName, ObjectName, + * java.rmi.MarshalledObject, + * java.rmi.MarshalledObject, + * javax.security.auth.Subject) + * @see #removeNotificationListeners(ObjectName, Integer[], + * javax.security.auth.Subject) + * @see NotificationBroadcaster#addNotificationListener(NotificationListener, + * NotificationFilter, + * Object) + */ + @SuppressWarnings("unchecked") + void addNotificationListener(ObjectName name, ObjectName listener, + MarshalledObject filter, MarshalledObject passback, + Subject delegationSubject) + throws InstanceNotFoundException, IOException; + + /** + * Handles {@link + * MBeanServerConnection#addNotificationListener(ObjectName, + * NotificationListener, NotificationFilter, Object)} by + * registering for notifications from the specified management + * beans. The array of filters is assumed to be aligned with + * the array of bean names, so that the notifications from each + * bean are matched against the appropriate filter (or left as + * is if the filter is {@code null}. Notifications emitted by + * the management beans are forwarded to a local listener created + * by this method, via the server, which converts any MBean + * references in the source to portable {@link ObjectName} + * instances. The notification is otherwise unchanged. + * </p> + * <p> + * This local listener buffers the notifications for retrieval by + * {@link #fetchNotifications(long,int,long). This method returns + * an array of listener identifiers which aligns with the supplied + * array of beans so that the appropriate listener can be identified + * by the client, which retains its own listener and handback object. + * The filters are wrapped in {@link MarshalledObject}s so that they are + * deserialised using the bean's classloader. + * </p> + * + * @param names the names of the management bean whose notifications + * should be recorded. + * @param filters an array of wrappers containing filters to apply to + * incoming notifications. An element may be <code>null</code> + * if no filtering should be applied to a bean's notifications. + * @param delegationSubjects an array of {@link javax.security.auth.Subject} + * instances containing the delegation principles for + * each listener. An element may be {@code null} if + * authentication is used instead, or the entire + * argument itself may be {@code null}. In the latter + * case, this is treated as an array of {@code null} + * values. + * @return an array of integers which act as listener identifiers, so that + * notifications retrieved from {@link #fetchNotifications(long,int,long) + * can be matched to the beans they were emitted from. The array is + * aligned against the array of beans supplied to this methods, so that + * the identifier in position 0 represents the bean in position 0 of the + * input array. + * @throws IllegalArgumentException if the {@code names} or {@code filters} array + * is {@code null}, the {@code names} array contains + * a {@code null} value or the three arrays are not + * of the same size. + * @throws ClassCastException if an element of the {@code filters} array unmarshalls + * as a non-null object that is not a {@link NotificationFilter}. + * @throws InstanceNotFoundException if the name of one of the management beans + * could not be resolved. + * @throws SecurityException if, for one of the beans, the client or delegated subject + * (if any) does not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see #removeNotificationListener(ObjectName, ObjectName, + * javax.security.auth.Subject) + * @see #removeNotificationListener(ObjectName, ObjectName, + * java.rmi.MarshalledObject, + * java.rmi.MarshalledObject, + * javax.security.auth.Subject) + * @see #removeNotificationListeners(ObjectName, Integer[], + * javax.security.auth.Subject) + * @see NotificationBroadcaster#addNotificationListener(NotificationListener, + * NotificationFilter, + * Object) + */ + @SuppressWarnings("unchecked") + Integer[] addNotificationListeners(ObjectName[] names, MarshalledObject[] filters, + Subject[] delegationSubjects) + throws InstanceNotFoundException, IOException; + + /** + * Closes the connection and unexports the RMI object implementing this + * interface. Following this call, future method calls to this instance + * will fail. + * + * @throws IOException if there is an I/O error in transmitting the close + * request via RMI, closing the connection, or unexporting + * the RMI object. + */ + void close() + throws IOException; + + /** + * <p> + * Handles {@link + * MBeanServerConnection#createMBean(String, ObjectName, + * Object[], String[])}. The array of parameters is wrapped in + * a {@link MarshalledObject} so that it is deserialised using the + * bean's classloader. + * </p> + * <p> + * Instantiates a new instance of the specified management bean + * using the given constructor and registers it with the server + * under the supplied name. The class is loaded using the + * {@link javax.management.loading.ClassLoaderRepository default + * loader repository} of the server. + * </p> + * <p> + * If the name supplied is <code>null</code>, then the bean is + * expected to implement the {@link MBeanRegistration} interface. + * The {@link MBeanRegistration#preRegister preRegister} method + * of this interface will be used to obtain the name in this case. + * </p> + * + * @param className the class of the management bean, of which + * an instance should be created. + * @param name the name to register the new bean with. This may + * be <code>null</code>. + * @param params the parameters for the bean's constructor, encapsulated + * in a {@link MarshalledObject}. If this parameter is + * <code>null</code>, it will be judged equivalent to an + * empty array. + * @param sig the signature of the constructor to use. If this parameter + * is <code>null</code>, it will be judged equivalent to an + * empty array. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return an {@link ObjectInstance} containing the {@link ObjectName} + * and Java class name of the created instance. + * @throws ReflectionException if an exception occurs in creating + * an instance of the bean. + * @throws InstanceAlreadyExistsException if a matching instance + * already exists. + * @throws MBeanRegistrationException if an exception occurs in + * calling the preRegister + * method. + * @throws MBeanException if the bean's constructor throws an exception. + * @throws NotCompliantMBeanException if the created bean is not + * compliant with the JMX specification. + * @throws RuntimeOperationsException if an {@link IllegalArgumentException} + * is thrown by the server due to a + * <code>null</code> class name or object + * name or if the object name is a pattern. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + */ + @SuppressWarnings("unchecked") + ObjectInstance createMBean(String className, ObjectName name, + MarshalledObject params, String[] sig, + Subject delegationSubject) + throws ReflectionException, InstanceAlreadyExistsException, + MBeanRegistrationException, MBeanException, + NotCompliantMBeanException, IOException; + + /** + * <p> + * Handles {@link + * MBeanServerConnection#createMBean(String, ObjectName, + * ObjectName, Object[], String[])}. The array of parameters is + * wrapped in a {@link MarshalledObject} so that it is deserialised + * using the bean's classloader. + * </p> + * <p> + * Instantiates a new instance of the specified management bean + * using the given constructor and registers it with the server + * under the supplied name. The class is loaded using the + * given class loader. If this argument is <code>null</code>, + * then the same class loader as was used to load the server + * is used. + * </p> + * <p> + * If the name supplied is <code>null</code>, then the bean is + * expected to implement the {@link MBeanRegistration} interface. + * The {@link MBeanRegistration#preRegister preRegister} method + * of this interface will be used to obtain the name in this case. + * </p> + * + * @param className the class of the management bean, of which + * an instance should be created. + * @param name the name to register the new bean with. This may + * be <code>null</code>. + * @param loaderName the name of the class loader. + * @param params the parameters for the bean's constructor, encapsulated + * in a {@link MarshalledObject}. If this parameter is + * <code>null</code>, it will be judged equivalent to an + * empty array. + * @param sig the signature of the constructor to use. If this parameter + * is <code>null</code>, it will be judged equivalent to an + * empty array. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return an {@link ObjectInstance} containing the {@link ObjectName} + * and Java class name of the created instance. + * @throws ReflectionException if an exception occurs in creating + * an instance of the bean. + * @throws InstanceAlreadyExistsException if a matching instance + * already exists. + * @throws MBeanRegistrationException if an exception occurs in + * calling the preRegister + * method. + * @throws MBeanException if the bean's constructor throws an exception. + * @throws NotCompliantMBeanException if the created bean is not + * compliant with the JMX specification. + * @throws InstanceNotFoundException if the specified class loader is not + * registered with the server. + * @throws RuntimeOperationsException if an {@link IllegalArgumentException} + * is thrown by the server due to a + * <code>null</code> class name or object + * name or if the object name is a pattern. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + */ + @SuppressWarnings("unchecked") + ObjectInstance createMBean(String className, ObjectName name, + ObjectName loaderName, MarshalledObject params, + String[] sig, Subject delegationSubject) + throws ReflectionException, InstanceAlreadyExistsException, + MBeanRegistrationException, MBeanException, + NotCompliantMBeanException, InstanceNotFoundException, + IOException; + + /** + * <p> + * Handles {@link + * MBeanServerConnection#createMBean(String, ObjectName, + * ObjectName)} by instantiating a new instance of the specified + * management bean using the default constructor and registering + * it with the server under the supplied name. The class is loaded + * using the given class loader. If this argument is <code>null</code>, + * then the same class loader as was used to load the server + * is used. + * </p> + * <p> + * If the name supplied is <code>null</code>, then the bean is + * expected to implement the {@link MBeanRegistration} interface. + * The {@link MBeanRegistration#preRegister preRegister} method + * of this interface will be used to obtain the name in this case. + * </p> + * <p> + * This method is equivalent to calling {@link + * #createMBean(String, ObjectName, ObjectName, Object[], String) + * <code>createMBean(className, name, loaderName, (Object[]) null, + * (String) null)</code>} with <code>null</code> parameters + * and signature. + * </p> + * + * @param className the class of the management bean, of which + * an instance should be created. + * @param name the name to register the new bean with. This may + * be <code>null</code>. + * @param loaderName the name of the class loader. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return an {@link ObjectInstance} containing the {@link ObjectName} + * and Java class name of the created instance. + * @throws ReflectionException if an exception occurs in creating + * an instance of the bean. + * @throws InstanceAlreadyExistsException if a matching instance + * already exists. + * @throws MBeanRegistrationException if an exception occurs in + * calling the preRegister + * method. + * @throws MBeanException if the bean's constructor throws an exception. + * @throws NotCompliantMBeanException if the created bean is not + * compliant with the JMX specification. + * @throws InstanceNotFoundException if the specified class loader is not + * registered with the server. + * @throws RuntimeOperationsException if an {@link IllegalArgumentException} + * is thrown by the server due to a + * <code>null</code> class name or object + * name or if the object name is a pattern. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see #createMBean(String, ObjectName, ObjectName, MarshalledObject, + * String[], Subject) + */ + ObjectInstance createMBean(String className, ObjectName name, + ObjectName loaderName, Subject delegationSubject) + throws ReflectionException, InstanceAlreadyExistsException, + MBeanRegistrationException, MBeanException, + NotCompliantMBeanException, InstanceNotFoundException, + IOException; + + /** + * <p> + * Handles {@link + * MBeanServerConnection#createMBean(String, ObjectName)} by + * instantiating a new instance of the specified management bean + * using the default constructor and registering it with the server + * under the supplied name. The class is loaded using the + * {@link javax.management.loading.ClassLoaderRepository default + * loader repository} of the server. + * </p> + * <p> + * If the name supplied is <code>null</code>, then the bean is + * expected to implement the {@link MBeanRegistration} interface. + * The {@link MBeanRegistration#preRegister preRegister} method + * of this interface will be used to obtain the name in this case. + * </p> + * <p> + * This method is equivalent to calling {@link + * #createMBean(String, ObjectName, Object[], String[]) + * <code>createMBean(className, name, (Object[]) null, + * (String[]) null)</code>} with <code>null</code> parameters + * and signature. + * </p> + * + * @param className the class of the management bean, of which + * an instance should be created. + * @param name the name to register the new bean with. This may + * be <code>null</code>. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return an {@link ObjectInstance} containing the {@link ObjectName} + * and Java class name of the created instance. + * @throws ReflectionException if an exception occurs in creating + * an instance of the bean. + * @throws InstanceAlreadyExistsException if a matching instance + * already exists. + * @throws MBeanRegistrationException if an exception occurs in + * calling the preRegister + * method. + * @throws MBeanException if the bean's constructor throws an exception. + * @throws NotCompliantMBeanException if the created bean is not + * compliant with the JMX specification. + * @throws RuntimeOperationsException if an {@link IllegalArgumentException} + * is thrown by the server due to a + * <code>null</code> class name or object + * name or if the object name is a pattern. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see #createMBean(String, ObjectName, MarshalledObject, String[], Subject) + */ + ObjectInstance createMBean(String className, ObjectName name, + Subject delegationSubject) + throws ReflectionException, InstanceAlreadyExistsException, + MBeanRegistrationException, MBeanException, + NotCompliantMBeanException, IOException; + + /** + * <p> + * Retrieves any waiting notifications from the server. When notifications + * are requested using the {@link #addNotificationListeners(ObjectName[], + * MarshalledObject[], Subject[])} method, the server sets up an internal + * listener to receive notifications from the bean and buffer them. When + * this method is called, these buffered notifications can be retrieved. + * </p> + * <p> + * The blocking behaviour of this method depends on the timeout value specified. + * If there are no waiting notifications in the buffer, a value of 0 will cause + * the method to return immediately. Conversely, if the value is + * {@link Long#MAX_VALUE}, then it will wait indefinitely until a notification + * arrives. For any other value, it waits until a notification arrives or the + * number of milliseconds specified by the timeout value is exceeded. The + * behaviour for a negative timeout value is undefined. + * </p> + * <p> + * For a notification to be returned, the following criteria must be fulfilled: + * </p> + * <ul> + * <li>the client must have previously requested notifications from at least + * one bean</li> + * <li>a bean from which notifications have been requested must have emitted + * a notification since the last call to this method</li> + * <li>the emitted notification must pass through any filters established + * when notifications were requested</li> + * <li>the sequence number of the notification must be greater than or equal + * to the specified sequence number (if non-negative)</li> + * </ul> + * + * @param sequenceNumber the sequence number of each notification returned + * must be greater than or equal to this value. If + * the number is negative, this is interpreted as + * meaning the sequence number of the next notification + * and so all notifications are allowed through. + * @param maxNotifications the maximum number of notifications to return. + * This does not include any duplicates so the + * number of actual notifications returned may + * be larger. + * @param timeout the number of milliseconds to wait for a notification + * if the buffer is empty. <code>0</code> causes the + * method to return immediately even if there are no + * notifications available (non-blocking behaviour) while + * a value of {@link Long#MAX_VALUE} causes it to wait + * indefinitely (blocking behaviour). The response to + * a negative value is undefined. + * @return a {@link NotificationResult} object containing the buffered + * notifications. + * @throws IOException if an I/O error occurs. + */ + NotificationResult fetchNotifications(long sequenceNumber, + int maxNotifications, + long timeout) + throws IOException; + + /** + * Handles {@link + * MBeanServerConnection#getAttribute(ObjectName, String)}, + * returning the value of the supplied attribute from the specified + * management bean. + * + * @param bean the bean to retrieve the value from. + * @param name the name of the attribute to retrieve. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return the value of the attribute. + * @throws AttributeNotFoundException if the attribute could not be + * accessed from the bean. + * @throws MBeanException if the management bean's accessor throws + * an exception. + * @throws InstanceNotFoundException if the bean can not be found. + * @throws ReflectionException if an exception was thrown in trying + * to invoke the bean's accessor. + * @throws RuntimeOperationsException if an {@link IllegalArgumentException} + * is thrown by the server due to a + * <code>null</code> bean or attribute + * name. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see DynamicMBean#getAttribute(String) + */ + Object getAttribute(ObjectName bean, String name, Subject delegationSubject) + throws MBeanException, AttributeNotFoundException, + InstanceNotFoundException, ReflectionException, + IOException; + + /** + * Handles {@link + * MBeanServerConnection#getAttribute(ObjectName, String)}, + * returning the values of the named attributes from the specified + * management bean. + * + * @param bean the bean to retrieve the value from. + * @param names the names of the attributes to retrieve. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return the values of the attributes. + * @throws InstanceNotFoundException if the bean can not be found. + * @throws ReflectionException if an exception was thrown in trying + * to invoke the bean's accessor. + * @throws RuntimeOperationsException if an {@link IllegalArgumentException} + * is thrown by the server due to a + * <code>null</code> bean or attribute + * name. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see DynamicMBean#getAttributes(String[]) + */ + AttributeList getAttributes(ObjectName bean, String[] names, + Subject delegationSubject) + throws InstanceNotFoundException, ReflectionException, + IOException; + + /** + * Returns the unique identifier for this connection to the RMI + * server. + * + * @return the connection ID. + * @throws IOException if an I/O error occurred. + */ + String getConnectionId() + throws IOException; + + /** + * Handles {@link + * MBeanServerConnection#getDefaultDomain()} by returning the default + * domain this server applies to beans that have no specified domain. + * + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return the default domain. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + */ + String getDefaultDomain(Subject delegationSubject) + throws IOException; + + /** + * Handles {@link + * MBeanServerConnection#getDomains()} by returning an array + * containing all the domains used by beans registered with + * this server. The ordering of the array is undefined. + * + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return the list of domains. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see ObjectName#getDomain() + */ + String[] getDomains(Subject delegationSubject) + throws IOException; + + /** + * Handles {@link + * MBeanServerConnection#getMBeanCount()} by returning the number of + * management beans registered with this server. + * + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return the number of registered beans. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + */ + Integer getMBeanCount(Subject delegationSubject) + throws IOException; + + /** + * Handles {@link + * MBeanServerConnection#getMBeanInfo(ObjectName)} by returning + * information on the given management bean. + * + * @param name the name of the management bean. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return an instance of {@link MBeanInfo} for the bean. + * @throws IntrospectionException if an exception occurs in examining + * the bean. + * @throws InstanceNotFoundException if the bean can not be found. + * @throws ReflectionException if an exception occurs when trying + * to invoke {@link DynamicMBean#getMBeanInfo()} + * on the bean. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see DynamicMBean#getMBeanInfo() + */ + MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject) + throws InstanceNotFoundException, IntrospectionException, + ReflectionException, IOException; + + /** + * Handles {@link + * MBeanServerConnection#getObjectInstance(ObjectName)} by returning + * the {@link ObjectInstance} created for the specified management + * bean on registration. + * + * @param name the name of the bean. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return the corresponding {@link ObjectInstance} instance. + * @throws InstanceNotFoundException if the bean can not be found. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see #createMBean(String, ObjectName, Subject) + */ + ObjectInstance getObjectInstance(ObjectName name, Subject delegationSubject) + throws InstanceNotFoundException, IOException; + + /** + * <p> + * Handles {@link + * MBeanServerConnection#invoke(ObjectName, String, Object[], + * String[])}. The array of parameters is wrapped in a + * {@link MarshalledObject} so that it is deserialised + * using the bean's classloader. + * </p> + * <p> + * Invokes the supplied operation on the specified management + * bean. The class objects specified in the signature are loaded + * using the same class loader as was used for the management bean. + * + * @param bean the management bean whose operation should be invoked. + * @param name the name of the operation to invoke. + * @param params the parameters for the bean's constructor, encapsulated + * in a {@link MarshalledObject}. If this parameter is + * <code>null</code>, it will be judged equivalent to an + * empty array. + * @param sig the signature of the constructor to use. If this parameter + * is <code>null</code>, it will be judged equivalent to an + * empty array. The class objects will be loaded using the + * bean's classloader. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return the return value of the method. + * @throws InstanceNotFoundException if the bean can not be found. + * @throws MBeanException if the method invoked throws an exception. + * @throws ReflectionException if an exception is thrown in invoking the + * method. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see DynamicMBean#invoke(String, Object[], String[]) + */ + @SuppressWarnings("unchecked") + Object invoke(ObjectName bean, String name, MarshalledObject params, + String[] sig, Subject delegationSubject) + throws InstanceNotFoundException, MBeanException, + ReflectionException, IOException; + + /** + * <p> + * Handles {@link + * MBeanServerConnection#isInstanceOf(ObjectName, String) by + * returning true if the specified management bean is an instance + * of the supplied class. + * </p> + * <p> + * A bean, B, is an instance of a class, C, if either of the following + * conditions holds: + * </p> + * <ul> + * <li>The class name in B's {@link MBeanInfo} is equal to the supplied + * name.</li> + * <li>Both the class of B and C were loaded by the same class loader, + * and B is assignable to C.</li> + * </ul> + * + * @param name the name of the management bean. + * @param className the name of the class to test if <code>name</code> is + * an instance of. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return true if either B is directly an instance of the named class, + * or B is assignable to the class, given that both it and B's + * current class were loaded using the same class loader. + * @throws InstanceNotFoundException if the bean can not be found. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + */ + boolean isInstanceOf(ObjectName name, String className, + Subject delegationSubject) + throws InstanceNotFoundException, IOException; + + /** + * Handles {@link + * MBeanServerConnection#isRegistered(ObjectName) by returning + * true if the specified management bean is registered with + * the server. + * + * @param name the name of the management bean. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return true if the bean is registered. + * @throws RuntimeOperationsException if an {@link IllegalArgumentException} + * is thrown by the server due to a + * <code>null</code> bean name. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + */ + boolean isRegistered(ObjectName name, Subject delegationSubject) + throws IOException; + + /** + * <p> + * Handles {@link + * MBeanServerConnection#queryMBeans(ObjectName, QueryExp)}. + * The query expression is wrapped in a {@link MarshalledObject} + * so that it is deserialised using the bean's classloader. + * </p> + * <p> + * Returns a set of {@link ObjectInstance}s matching the specified + * criteria. The full set of beans registered with the server + * are passed through two filters: + * </p> + * <ol> + * <li>Pattern matching is performed using the supplied + * {@link ObjectName}.</li> + * <li>The supplied query expression is applied.</li> + * </ol> + * <p> + * If both the object name and the query expression are <code>null</code>, + * or the object name has no domain and no key properties, + * no filtering will be performed and all beans are returned. + * </p> + * + * @param name an {@link ObjectName} to use as a filter. + * @param query a query expression to apply to each of the beans that match + * the given object name, encapsulated in a + * {@link MarshalledObject}. If a <code>null</code> value is + * encapsulated, then the beans will only be filtered using + * pattern matching on the supplied {@link ObjectName}. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return a set of {@link ObjectInstance}s matching the filtered beans. + * This is empty if no beans survived the filters. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + */ + @SuppressWarnings("unchecked") + Set<ObjectInstance> queryMBeans(ObjectName name, MarshalledObject query, + Subject delegationSubject) + throws IOException; + + /** + * <p> + * Handles {@link + * MBeanServerConnection#queryNames(ObjectName, QueryExp)}. + * The query expression is wrapped in a {@link MarshalledObject} + * so that it is deserialised using the bean's classloader. + * </p> + * <p> + * Returns a set of {@link ObjectName}s matching the specified + * criteria. The full set of beans registered with the server + * are passed through two filters: + * </p> + * <ol> + * <li>Pattern matching is performed using the supplied + * {@link ObjectName}.</li> + * <li>The supplied query expression is applied.</li> + * </ol> + * <p> + * If both the object name and the query expression are <code>null</code>, + * or the object name has no domain and no key properties, + * no filtering will be performed and all beans are returned. + * </p> + * + * @param name an {@link ObjectName} to use as a filter. + * @param query a query expression to apply to each of the beans that match + * the given object name, encapsulated in a + * {@link MarshalledObject}. If a <code>null</code> value is + * encapsulated, then the beans will only be filtered using + * pattern matching on the supplied {@link ObjectName}. + * @param delegationSubject an instance of {@link javax.security.auth.Subject} + * containing the delegation principles. This may be + * {@code null} is authentication is used instead. + * @return a set of {@link ObjectName}s matching the filtered beans. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + */ + @SuppressWarnings("unchecked") + Set<ObjectName> queryNames(ObjectName name, MarshalledObject query, + Subject delegationSubject) + throws IOException; + + /** + * <p> + * Handles {@link + * MBeanServerConnection#removeNotificationListener(ObjectName, + * ObjectName, NotificationFilter, Object)}. Both the filter and + * the handback object are wrapped in a {@link MarshalledObject} + * so that they are deserialised using the bean's classloader. + * </p> + * <p> + * Removes the specified listener from the list of recipients + * of notifications from the supplied bean. Only the first instance with + * the supplied filter and passback object is removed. + * <code>null</code> is used as a valid value for these parameters, + * rather than as a way to remove all registration instances for + * the specified listener; for this behaviour instead, see + * {@link #removeNotificationListener(ObjectName, NotificationListener)}. + * </p> + * + * @param name the name of the management bean from which the + * listener should be removed. + * @param listener the listener to remove. + * @param filter a wrapper containing the filter of the listener + * to remove. + * @param passback a wrapper containing the handback object of the + * listener to remove. + * @param delegationSubject a {@link javax.security.auth.Subject} instance + * containing the delegation principles or + * {@code null} if authentication is used. + * @throws InstanceNotFoundException if the bean can not be found. + * @throws ListenerNotFoundException if the specified listener + * is not registered with the bean. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see #addNotificationListener(ObjectName, NotificationListener, + * MarshalledObject, MarshalledObject, Subject) + * @see NotificationEmitter#removeNotificationListener(NotificationListener, + * NotificationFilter, + * Object) + */ + @SuppressWarnings("unchecked") + void removeNotificationListener(ObjectName name, + ObjectName listener, + MarshalledObject filter, + MarshalledObject passback, + Subject delegationSubject) + throws InstanceNotFoundException, ListenerNotFoundException, + IOException; + + /** + * Handles {@link + * MBeanServerConnection#removeNotificationListener(ObjectName, + * ObjectName)} by removing the specified listener from the list + * of recipients of notifications from the supplied bean. This + * includes all combinations of filters and passback objects + * registered for this listener. For more specific removal of + * listeners, see {@link #removeNotificationListener(ObjectName, + * ObjectName,MarshalledObject,MarshalledObject,Subject)} + * + * @param name the name of the management bean from which the + * listener should be removed. + * @param listener the name of the listener to remove. + * @param delegationSubject a {@link javax.security.auth.Subject} instance + * containing the delegation principles or + * {@code null} if authentication is used. + * @throws InstanceNotFoundException if a name doesn't match a registered + * bean. + * @throws ListenerNotFoundException if the specified listener + * is not registered with the bean. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see #addNotificationListener(ObjectName, NotificationListener, + * MarshalledObject, MarshalledObject, Subject) + * @see NotificationBroadcaster#removeNotificationListener(NotificationListener) + */ + void removeNotificationListener(ObjectName name, ObjectName listener, + Subject delegationSubject) + throws InstanceNotFoundException, ListenerNotFoundException, + IOException; + + /** + * Removes one or more {@link NotificationListener}s from the specified + * management bean. This method corresponds to + * {@link #addNotificationListeners(ObjectName[], MarshalledObject[], + * Subject)} and provides a different way of handling + * MBeanServerConnection#removeNotificationListener(ObjectName, + * ObjectName)} and + * {@link MBeanServerConnection#removeNotificationListener(ObjectName, + * ObjectName, NotificationFilter, Object)} by using the integer + * identifiers provided by the + * {@link #addNotificationListeners(ObjectName[], MarshalledObject[], + * Subject)} method to select the listeners to remove. + * + * @param name the name of the management bean from which the + * listeners should be removed. + * @param listenerIds the identifiers of the listeners to remove. + * @param delegationSubject a {@link javax.security.auth.Subject} instance + * containing the delegation principles or + * {@code null} if authentication is used. + * @throws InstanceNotFoundException if a name doesn't match a registered + * bean. + * @throws ListenerNotFoundException if the specified listener + * is not registered with the bean. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @throws IllegalArgumentException if either <code>name</code>, + * <code>listenerIds</code> or an element + * of <code>listenerIds</code> + * is <code>null</code>. + * @see #addNotificationListeners(ObjectName[], MarshalledObject[], Subject) + */ + void removeNotificationListeners(ObjectName name, Integer[] listenerIds, + Subject delegationSubject) + throws InstanceNotFoundException, ListenerNotFoundException, + IOException; + + /** + * Handles {@link + * MBeanServerConnection#setAttribute(ObjectName, Attribute)} + * by setting the value of the specified attribute of the supplied + * management bean. The attribute is wrapped in a + * {@link MarshalledObject} so that it is deserialised using the + * bean's classloader. + * + * @param name the name of the management bean. + * @param attribute the attribute to set, encapsulated in a + * {@link MarshalledObject}. + * @param delegationSubject a {@link javax.security.auth.Subject} instance + * containing the delegation principles or + * {@code null} if authentication is used. + * @throws InstanceNotFoundException if the bean can not be found. + * @throws AttributeNotFoundException if the attribute does not + * correspond to an attribute + * of the bean. + * @throws InvalidAttributeValueException if the value is invalid + * for this particular + * attribute of the bean. + * @throws MBeanException if setting the attribute causes + * the bean to throw an exception (which + * becomes the cause of this exception). + * @throws ReflectionException if an exception occurred in trying + * to use the reflection interface + * to lookup the attribute. The + * thrown exception is the cause of + * this exception. + * @throws RuntimeOperationsException if an {@link IllegalArgumentException} + * is thrown by the server due to a + * <code>null</code> bean or attribute + * name. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see #getAttribute(ObjectName, String, Subject) + * @see javax.management.DynamicMBean#setAttribute(Attribute) + */ + @SuppressWarnings("unchecked") + void setAttribute(ObjectName name, MarshalledObject attribute, + Subject delegationSubject) + throws InstanceNotFoundException, AttributeNotFoundException, + InvalidAttributeValueException, MBeanException, + ReflectionException, IOException; + + /** + * Handles {@link + * MBeanServerConnection#setAttributes(ObjectName, AttributeList)} + * by setting the value of each of the specified attributes + * of the supplied management bean to that specified by + * the {@link Attribute} object. The returned list contains + * the attributes that were set and their new values. + * The attribute list is wrapped in a {@link MarshalledObject} so + * that it is deserialised using the bean's classloader. + * + * @param name the name of the management bean. + * @param attributes the attributes to set, encapsulated in a + * {@link MarshalledObject}. + * @param delegationSubject a {@link javax.security.auth.Subject} instance + * containing the delegation principles or + * {@code null} if authentication is used. + * @return a list of the changed attributes. + * @throws InstanceNotFoundException if the bean can not be found. + * @throws ReflectionException if an exception occurred in trying + * to use the reflection interface + * to lookup the attribute. The + * thrown exception is the cause of + * this exception. + * @throws RuntimeOperationsException if an {@link IllegalArgumentException} + * is thrown by the server due to a + * <code>null</code> bean or attribute + * list. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + * @see #getAttributes(ObjectName, String[]) + * @see DynamicMBean#setAttributes(AttributeList) + */ + @SuppressWarnings("unchecked") + AttributeList setAttributes(ObjectName name, MarshalledObject attributes, + Subject delegationSubject) + throws InstanceNotFoundException, ReflectionException, + IOException; + + /** + * Handles {@link + * MBeanServerConnection#unregisterMBean(ObjectName)} by unregistering + * the specified management bean. Following this operation, + * the bean instance is no longer accessible from the server via this + * name. Prior to unregistering the bean, the + * {@link MBeanRegistration#preDeregister()} method will be called if + * the bean implements the {@link MBeanRegistration} interface. + * + * @param name the name of the management bean. + * @param delegationSubject a {@link javax.security.auth.Subject} instance + * containing the delegation principles or + * {@code null} if authentication is used. + * @throws InstanceNotFoundException if the bean can not be found. + * @throws MBeanRegistrationException if an exception occurs in + * calling the preDeregister + * method. + * @throws RuntimeOperationsException if an {@link IllegalArgumentException} + * is thrown by the server due to a + * <code>null</code> bean name or a + * request being made to unregister the + * {@link MBeanServerDelegate} bean. + * @throws SecurityException if the client or delegated subject (if any) does + * not have permission to invoke this operation. + * @throws IOException if an I/O error occurred in communicating with + * the bean server. + */ + void unregisterMBean(ObjectName name, Subject delegationSubject) + throws InstanceNotFoundException, MBeanRegistrationException, + IOException; + +} diff --git a/libjava/classpath/javax/management/remote/rmi/RMIServer.java b/libjava/classpath/javax/management/remote/rmi/RMIServer.java new file mode 100644 index 000000000..d862372ac --- /dev/null +++ b/libjava/classpath/javax/management/remote/rmi/RMIServer.java @@ -0,0 +1,89 @@ +/* RMIServer.java -- RMI object for connecting to an RMI JMX connector. + Copyright (C) 2007 Free Software Foundation, Inc. + +This file is part of GNU Classpath. + +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath 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 for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +02110-1301 USA. + +Linking this library statically or dynamically with other modules is +making a combined work based on this library. Thus, the terms and +conditions of the GNU General Public License cover the whole +combination. + +As a special exception, the copyright holders of this library give you +permission to link this library with independent modules to produce an +executable, regardless of the license terms of these independent +modules, and to copy and distribute the resulting executable under +terms of your choice, provided that you also meet, for each linked +independent module, the terms and conditions of the license of that +module. An independent module is a module which is not derived from +or based on this library. If you modify this library, you may extend +this exception to your version of the library, but you are not +obligated to do so. If you do not wish to do so, delete this +exception statement from your version. */ + +package javax.management.remote.rmi; + +import java.io.IOException; + +import java.rmi.Remote; +import java.rmi.RemoteException; + +/** + * RMI interface for obtaining an instance of an + * {@link RMIConnection}. An implementation of this + * interface exists for each RMI connector. + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.5 + */ +public interface RMIServer + extends Remote +{ + + /** + * Returns the version of the RMI connection protocol used + * by this server. The returned string takes the form of + * <emph>protocol-version implementation-name</emph> where + * <emph>protocol-version</emph> is a series of two or more + * non-negative integers, separated by a decimal point (.) + * (currently {@code 1.0}) and <emph>implementation-name</emph> + * is the string {@code "GNU Classpath"} followed by the version + * of GNU Classpath in use. + * + * @return the string specified above. + * @throws RemoteException if there is a problem with the transfer + * of the string via RMI. + */ + String getVersion() + throws RemoteException; + + /** + * Constructs and returns a new RMI connection using the specified + * authentication credentials. Each client calls this method to + * obtain a connection to the server. + * + * @param credentials a user-defined object passed to the server + * to authenticate the client. May be {@code null}. + * @return the new connection. + * @throws IOException if the new connection can not be created or + * exported, or an error occurs in the RMI transmission. + * @throws SecurityException if the client could not be authenticated + * correctly using the supplied credientials. + */ + RMIConnection newClient(Object credentials) + throws IOException; +} |