| /* 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; |
| |
| } |