javax.management.remote.rmi

Interface RMIConnection

public interface RMIConnection extends Closeable, Remote

RMI interface for forwarding requests to a remote javax.management.MBeanServer. This interface parallels the 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 RMIServer instance.

Implementations of this interface do more than simply forward requests directly to the server. The arguments of the server methods are wrapped in 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 MarshalledObject or an array of that type should not be {@code null}.

Security is also handled by this interface, as the methods use an additional javax.security.auth.Subject parameter for role delegation.

Since: 1.5

Method Summary
voidaddNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject passback, Subject delegationSubject)
Handles MBeanServerConnection#addNotificationListener(ObjectName, ObjectName, NotificationFilter, Object) by registering the supplied listener with the specified management bean.
Integer[]addNotificationListeners(ObjectName[] names, MarshalledObject[] filters, Subject[] delegationSubjects)
Handles MBeanServerConnection#addNotificationListener(ObjectName, NotificationListener, NotificationFilter, Object) by registering for notifications from the specified management beans.
voidclose()
Closes the connection and unexports the RMI object implementing this interface.
ObjectInstancecreateMBean(String className, ObjectName name, MarshalledObject params, String[] sig, Subject delegationSubject)

Handles MBeanServerConnection#createMBean(String, ObjectName, Object[], String[]).

ObjectInstancecreateMBean(String className, ObjectName name, ObjectName loaderName, MarshalledObject params, String[] sig, Subject delegationSubject)

Handles MBeanServerConnection#createMBean(String, ObjectName, ObjectName, Object[], String[]).

ObjectInstancecreateMBean(String className, ObjectName name, ObjectName loaderName, Subject delegationSubject)

Handles 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.

ObjectInstancecreateMBean(String className, ObjectName name, Subject delegationSubject)

Handles 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.

NotificationResultfetchNotifications(long sequenceNumber, int maxNotifications, long timeout)

Retrieves any waiting notifications from the server.

ObjectgetAttribute(ObjectName bean, String name, Subject delegationSubject)
Handles MBeanServerConnection#getAttribute(ObjectName, String), returning the value of the supplied attribute from the specified management bean.
AttributeListgetAttributes(ObjectName bean, String[] names, Subject delegationSubject)
Handles MBeanServerConnection#getAttribute(ObjectName, String), returning the values of the named attributes from the specified management bean.
StringgetConnectionId()
Returns the unique identifier for this connection to the RMI server.
StringgetDefaultDomain(Subject delegationSubject)
Handles MBeanServerConnection#getDefaultDomain() by returning the default domain this server applies to beans that have no specified domain.
String[]getDomains(Subject delegationSubject)
Handles MBeanServerConnection#getDomains() by returning an array containing all the domains used by beans registered with this server.
IntegergetMBeanCount(Subject delegationSubject)
Handles MBeanServerConnection#getMBeanCount() by returning the number of management beans registered with this server.
MBeanInfogetMBeanInfo(ObjectName name, Subject delegationSubject)
Handles MBeanServerConnection#getMBeanInfo(ObjectName) by returning information on the given management bean.
ObjectInstancegetObjectInstance(ObjectName name, Subject delegationSubject)
Handles MBeanServerConnection#getObjectInstance(ObjectName) by returning the ObjectInstance created for the specified management bean on registration.
Objectinvoke(ObjectName bean, String name, MarshalledObject params, String[] sig, Subject delegationSubject)

Handles MBeanServerConnection#invoke(ObjectName, String, Object[], String[]).

booleanisInstanceOf(ObjectName name, String className, Subject delegationSubject)

Handles

booleanisRegistered(ObjectName name, Subject delegationSubject)
Handles
Set<ObjectInstance>queryMBeans(ObjectName name, MarshalledObject query, Subject delegationSubject)

Handles MBeanServerConnection#queryMBeans(ObjectName, QueryExp).

Set<ObjectName>queryNames(ObjectName name, MarshalledObject query, Subject delegationSubject)

Handles MBeanServerConnection#queryNames(ObjectName, QueryExp).

voidremoveNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject passback, Subject delegationSubject)

Handles MBeanServerConnection#removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object).

voidremoveNotificationListener(ObjectName name, ObjectName listener, Subject delegationSubject)
Handles MBeanServerConnection#removeNotificationListener(ObjectName, ObjectName) by removing the specified listener from the list of recipients of notifications from the supplied bean.
voidremoveNotificationListeners(ObjectName name, Integer[] listenerIds, Subject delegationSubject)
Removes one or more NotificationListeners from the specified management bean.
voidsetAttribute(ObjectName name, MarshalledObject attribute, Subject delegationSubject)
Handles MBeanServerConnection#setAttribute(ObjectName, Attribute) by setting the value of the specified attribute of the supplied management bean.
AttributeListsetAttributes(ObjectName name, MarshalledObject attributes, Subject delegationSubject)
Handles MBeanServerConnection#setAttributes(ObjectName, AttributeList) by setting the value of each of the specified attributes of the supplied management bean to that specified by the Attribute object.
voidunregisterMBean(ObjectName name, Subject delegationSubject)
Handles MBeanServerConnection#unregisterMBean(ObjectName) by unregistering the specified management bean.

Method Detail

addNotificationListener

public void addNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject passback, Subject delegationSubject)
Handles 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 ObjectName instances. The notification is otherwise unchanged. The filter and handback object are wrapped in a MarshalledObject so that they are deserialised using the bean's classloader.

Parameters: name the name of the management bean with which the listener should be registered. listener the listener which will handle notifications from the bean. filter a wrapper containing a filter to apply to incoming notifications, or null if no filtering should be applied. passback a wrapper containing an object to be passed to the listener when a notification is emitted. delegationSubject a 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. RuntimeOperationsException if the bean associated with the given object name is not a NotificationListener. This exception wraps an IllegalArgumentException. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: RMIConnection RMIConnection (ObjectName, Integer[], javax.security.auth.Subject) NotificationBroadcaster#addNotificationListener(NotificationListener, NotificationFilter, Object)

addNotificationListeners

public Integer[] addNotificationListeners(ObjectName[] names, MarshalledObject[] filters, Subject[] delegationSubjects)
Handles 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 ObjectName instances. The notification is otherwise unchanged.

This local listener buffers the notifications for retrieval by . 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 MarshalledObjects so that they are deserialised using the bean's classloader.

Parameters: names the names of the management bean whose notifications should be recorded. filters an array of wrappers containing filters to apply to incoming notifications. An element may be null if no filtering should be applied to a bean's notifications. delegationSubjects an array of 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.

Returns: an array of integers which act as listener identifiers, so that notifications retrieved from 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. ClassCastException if an element of the {@code filters} array unmarshalls as a non-null object that is not a NotificationFilter. InstanceNotFoundException if the name of one of the management beans could not be resolved. SecurityException if, for one of the beans, the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: RMIConnection RMIConnection (ObjectName, Integer[], javax.security.auth.Subject) NotificationBroadcaster#addNotificationListener(NotificationListener, NotificationFilter, Object)

close

public void close()
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.

createMBean

public ObjectInstance createMBean(String className, ObjectName name, MarshalledObject params, String[] sig, Subject delegationSubject)

Handles MBeanServerConnection#createMBean(String, ObjectName, Object[], String[]). The array of parameters is wrapped in a MarshalledObject so that it is deserialised using the bean's classloader.

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 javax.management.loading.ClassLoaderRepository default loader repository of the server.

If the name supplied is null, then the bean is expected to implement the MBeanRegistration interface. The MBeanRegistration#preRegister preRegister method of this interface will be used to obtain the name in this case.

Parameters: className the class of the management bean, of which an instance should be created. name the name to register the new bean with. This may be null. params the parameters for the bean's constructor, encapsulated in a MarshalledObject. If this parameter is null, it will be judged equivalent to an empty array. sig the signature of the constructor to use. If this parameter is null, it will be judged equivalent to an empty array. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: an ObjectInstance containing the ObjectName and Java class name of the created instance.

Throws: ReflectionException if an exception occurs in creating an instance of the bean. InstanceAlreadyExistsException if a matching instance already exists. MBeanRegistrationException if an exception occurs in calling the preRegister method. MBeanException if the bean's constructor throws an exception. NotCompliantMBeanException if the created bean is not compliant with the JMX specification. RuntimeOperationsException if an IllegalArgumentException is thrown by the server due to a null class name or object name or if the object name is a pattern. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

createMBean

public ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName, MarshalledObject params, String[] sig, Subject delegationSubject)

Handles MBeanServerConnection#createMBean(String, ObjectName, ObjectName, Object[], String[]). The array of parameters is wrapped in a MarshalledObject so that it is deserialised using the bean's classloader.

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 null, then the same class loader as was used to load the server is used.

If the name supplied is null, then the bean is expected to implement the MBeanRegistration interface. The MBeanRegistration#preRegister preRegister method of this interface will be used to obtain the name in this case.

Parameters: className the class of the management bean, of which an instance should be created. name the name to register the new bean with. This may be null. loaderName the name of the class loader. params the parameters for the bean's constructor, encapsulated in a MarshalledObject. If this parameter is null, it will be judged equivalent to an empty array. sig the signature of the constructor to use. If this parameter is null, it will be judged equivalent to an empty array. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: an ObjectInstance containing the ObjectName and Java class name of the created instance.

Throws: ReflectionException if an exception occurs in creating an instance of the bean. InstanceAlreadyExistsException if a matching instance already exists. MBeanRegistrationException if an exception occurs in calling the preRegister method. MBeanException if the bean's constructor throws an exception. NotCompliantMBeanException if the created bean is not compliant with the JMX specification. InstanceNotFoundException if the specified class loader is not registered with the server. RuntimeOperationsException if an IllegalArgumentException is thrown by the server due to a null class name or object name or if the object name is a pattern. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

createMBean

public ObjectInstance createMBean(String className, ObjectName name, ObjectName loaderName, Subject delegationSubject)

Handles 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 null, then the same class loader as was used to load the server is used.

If the name supplied is null, then the bean is expected to implement the MBeanRegistration interface. The MBeanRegistration#preRegister preRegister method of this interface will be used to obtain the name in this case.

This method is equivalent to calling (String, ObjectName, ObjectName, Object[], String) createMBean(className, name, loaderName, (Object[]) null, (String) null) with null parameters and signature.

Parameters: className the class of the management bean, of which an instance should be created. name the name to register the new bean with. This may be null. loaderName the name of the class loader. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: an ObjectInstance containing the ObjectName and Java class name of the created instance.

Throws: ReflectionException if an exception occurs in creating an instance of the bean. InstanceAlreadyExistsException if a matching instance already exists. MBeanRegistrationException if an exception occurs in calling the preRegister method. MBeanException if the bean's constructor throws an exception. NotCompliantMBeanException if the created bean is not compliant with the JMX specification. InstanceNotFoundException if the specified class loader is not registered with the server. RuntimeOperationsException if an IllegalArgumentException is thrown by the server due to a null class name or object name or if the object name is a pattern. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: (String, ObjectName, ObjectName, MarshalledObject, String[], Subject)

createMBean

public ObjectInstance createMBean(String className, ObjectName name, Subject delegationSubject)

Handles 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 javax.management.loading.ClassLoaderRepository default loader repository of the server.

If the name supplied is null, then the bean is expected to implement the MBeanRegistration interface. The MBeanRegistration#preRegister preRegister method of this interface will be used to obtain the name in this case.

This method is equivalent to calling (String, ObjectName, Object[], String[]) createMBean(className, name, (Object[]) null, (String[]) null) with null parameters and signature.

Parameters: className the class of the management bean, of which an instance should be created. name the name to register the new bean with. This may be null. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: an ObjectInstance containing the ObjectName and Java class name of the created instance.

Throws: ReflectionException if an exception occurs in creating an instance of the bean. InstanceAlreadyExistsException if a matching instance already exists. MBeanRegistrationException if an exception occurs in calling the preRegister method. MBeanException if the bean's constructor throws an exception. NotCompliantMBeanException if the created bean is not compliant with the JMX specification. RuntimeOperationsException if an IllegalArgumentException is thrown by the server due to a null class name or object name or if the object name is a pattern. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: (String, ObjectName, MarshalledObject, String[], Subject)

fetchNotifications

public NotificationResult fetchNotifications(long sequenceNumber, int maxNotifications, long timeout)

Retrieves any waiting notifications from the server. When notifications are requested using the (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.

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 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.

For a notification to be returned, the following criteria must be fulfilled:

Parameters: 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. maxNotifications the maximum number of notifications to return. This does not include any duplicates so the number of actual notifications returned may be larger. timeout the number of milliseconds to wait for a notification if the buffer is empty. 0 causes the method to return immediately even if there are no notifications available (non-blocking behaviour) while a value of Long#MAX_VALUE causes it to wait indefinitely (blocking behaviour). The response to a negative value is undefined.

Returns: a NotificationResult object containing the buffered notifications.

Throws: IOException if an I/O error occurs.

getAttribute

public Object getAttribute(ObjectName bean, String name, Subject delegationSubject)
Handles MBeanServerConnection#getAttribute(ObjectName, String), returning the value of the supplied attribute from the specified management bean.

Parameters: bean the bean to retrieve the value from. name the name of the attribute to retrieve. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: the value of the attribute.

Throws: AttributeNotFoundException if the attribute could not be accessed from the bean. MBeanException if the management bean's accessor throws an exception. InstanceNotFoundException if the bean can not be found. ReflectionException if an exception was thrown in trying to invoke the bean's accessor. RuntimeOperationsException if an IllegalArgumentException is thrown by the server due to a null bean or attribute name. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: DynamicMBean#getAttribute(String)

getAttributes

public AttributeList getAttributes(ObjectName bean, String[] names, Subject delegationSubject)
Handles MBeanServerConnection#getAttribute(ObjectName, String), returning the values of the named attributes from the specified management bean.

Parameters: bean the bean to retrieve the value from. names the names of the attributes to retrieve. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: the values of the attributes.

Throws: InstanceNotFoundException if the bean can not be found. ReflectionException if an exception was thrown in trying to invoke the bean's accessor. RuntimeOperationsException if an IllegalArgumentException is thrown by the server due to a null bean or attribute name. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: DynamicMBean#getAttributes(String[])

getConnectionId

public String getConnectionId()
Returns the unique identifier for this connection to the RMI server.

Returns: the connection ID.

Throws: IOException if an I/O error occurred.

getDefaultDomain

public String getDefaultDomain(Subject delegationSubject)
Handles MBeanServerConnection#getDefaultDomain() by returning the default domain this server applies to beans that have no specified domain.

Parameters: delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: the default domain.

Throws: SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

getDomains

public String[] getDomains(Subject delegationSubject)
Handles MBeanServerConnection#getDomains() by returning an array containing all the domains used by beans registered with this server. The ordering of the array is undefined.

Parameters: delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: the list of domains.

Throws: SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: ObjectName#getDomain()

getMBeanCount

public Integer getMBeanCount(Subject delegationSubject)
Handles MBeanServerConnection#getMBeanCount() by returning the number of management beans registered with this server.

Parameters: delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: the number of registered beans.

Throws: SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

getMBeanInfo

public MBeanInfo getMBeanInfo(ObjectName name, Subject delegationSubject)
Handles MBeanServerConnection#getMBeanInfo(ObjectName) by returning information on the given management bean.

Parameters: name the name of the management bean. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: an instance of MBeanInfo for the bean.

Throws: IntrospectionException if an exception occurs in examining the bean. InstanceNotFoundException if the bean can not be found. ReflectionException if an exception occurs when trying to invoke DynamicMBean#getMBeanInfo() on the bean. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: DynamicMBean#getMBeanInfo()

getObjectInstance

public ObjectInstance getObjectInstance(ObjectName name, Subject delegationSubject)
Handles MBeanServerConnection#getObjectInstance(ObjectName) by returning the ObjectInstance created for the specified management bean on registration.

Parameters: name the name of the bean. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: the corresponding ObjectInstance instance.

Throws: InstanceNotFoundException if the bean can not be found. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: RMIConnection

invoke

public Object invoke(ObjectName bean, String name, MarshalledObject params, String[] sig, Subject delegationSubject)

Handles MBeanServerConnection#invoke(ObjectName, String, Object[], String[]). The array of parameters is wrapped in a MarshalledObject so that it is deserialised using the bean's classloader.

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.

Parameters: bean the management bean whose operation should be invoked. name the name of the operation to invoke. params the parameters for the bean's constructor, encapsulated in a MarshalledObject. If this parameter is null, it will be judged equivalent to an empty array. sig the signature of the constructor to use. If this parameter is null, it will be judged equivalent to an empty array. The class objects will be loaded using the bean's classloader. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: the return value of the method.

Throws: InstanceNotFoundException if the bean can not be found. MBeanException if the method invoked throws an exception. ReflectionException if an exception is thrown in invoking the method. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: DynamicMBean#invoke(String, Object[], String[])

isInstanceOf

public boolean isInstanceOf(ObjectName name, String className, Subject delegationSubject)

Handles MBeanServerConnection#isInstanceOf(ObjectName, String) by returning true if the specified management bean is an instance of the supplied class.

A bean, B, is an instance of a class, C, if either of the following conditions holds:

Parameters: name the name of the management bean. className the name of the class to test if name is an instance of. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: 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. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

isRegistered

public boolean isRegistered(ObjectName name, Subject delegationSubject)
Handles MBeanServerConnection#isRegistered(ObjectName) by returning true if the specified management bean is registered with the server.

Parameters: name the name of the management bean. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: true if the bean is registered.

Throws: RuntimeOperationsException if an IllegalArgumentException is thrown by the server due to a null bean name. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

queryMBeans

public Set<ObjectInstance> queryMBeans(ObjectName name, MarshalledObject query, Subject delegationSubject)

Handles MBeanServerConnection#queryMBeans(ObjectName, QueryExp). The query expression is wrapped in a MarshalledObject so that it is deserialised using the bean's classloader.

Returns a set of ObjectInstances matching the specified criteria. The full set of beans registered with the server are passed through two filters:

  1. Pattern matching is performed using the supplied ObjectName.
  2. The supplied query expression is applied.

If both the object name and the query expression are null, or the object name has no domain and no key properties, no filtering will be performed and all beans are returned.

Parameters: name an ObjectName to use as a filter. query a query expression to apply to each of the beans that match the given object name, encapsulated in a MarshalledObject. If a null value is encapsulated, then the beans will only be filtered using pattern matching on the supplied ObjectName. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: a set of ObjectInstances 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. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation.

queryNames

public Set<ObjectName> queryNames(ObjectName name, MarshalledObject query, Subject delegationSubject)

Handles MBeanServerConnection#queryNames(ObjectName, QueryExp). The query expression is wrapped in a MarshalledObject so that it is deserialised using the bean's classloader.

Returns a set of ObjectNames matching the specified criteria. The full set of beans registered with the server are passed through two filters:

  1. Pattern matching is performed using the supplied ObjectName.
  2. The supplied query expression is applied.

If both the object name and the query expression are null, or the object name has no domain and no key properties, no filtering will be performed and all beans are returned.

Parameters: name an ObjectName to use as a filter. query a query expression to apply to each of the beans that match the given object name, encapsulated in a MarshalledObject. If a null value is encapsulated, then the beans will only be filtered using pattern matching on the supplied ObjectName. delegationSubject an instance of javax.security.auth.Subject containing the delegation principles. This may be {@code null} is authentication is used instead.

Returns: a set of ObjectNames matching the filtered beans.

Throws: SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

removeNotificationListener

public void removeNotificationListener(ObjectName name, ObjectName listener, MarshalledObject filter, MarshalledObject passback, Subject delegationSubject)

Handles MBeanServerConnection#removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object). Both the filter and the handback object are wrapped in a MarshalledObject so that they are deserialised using the bean's classloader.

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. null 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 RMIConnection.

Parameters: name the name of the management bean from which the listener should be removed. listener the listener to remove. filter a wrapper containing the filter of the listener to remove. passback a wrapper containing the handback object of the listener to remove. delegationSubject a 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. ListenerNotFoundException if the specified listener is not registered with the bean. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: RMIConnection NotificationEmitter#removeNotificationListener(NotificationListener, NotificationFilter, Object)

removeNotificationListener

public void removeNotificationListener(ObjectName name, ObjectName listener, Subject delegationSubject)
Handles 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 RMIConnection

Parameters: name the name of the management bean from which the listener should be removed. listener the name of the listener to remove. delegationSubject a 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. ListenerNotFoundException if the specified listener is not registered with the bean. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: RMIConnection NotificationBroadcaster#removeNotificationListener(NotificationListener)

removeNotificationListeners

public void removeNotificationListeners(ObjectName name, Integer[] listenerIds, Subject delegationSubject)
Removes one or more NotificationListeners from the specified management bean. This method corresponds to (ObjectName[], MarshalledObject[], Subject) and provides a different way of handling MBeanServerConnection#removeNotificationListener(ObjectName, ObjectName)} and MBeanServerConnection#removeNotificationListener(ObjectName, ObjectName, NotificationFilter, Object) by using the integer identifiers provided by the (ObjectName[], MarshalledObject[], Subject) method to select the listeners to remove.

Parameters: name the name of the management bean from which the listeners should be removed. listenerIds the identifiers of the listeners to remove. delegationSubject a 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. ListenerNotFoundException if the specified listener is not registered with the bean. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server. IllegalArgumentException if either name, listenerIds or an element of listenerIds is null.

See Also: (ObjectName[], MarshalledObject[], Subject)

setAttribute

public void setAttribute(ObjectName name, MarshalledObject attribute, Subject delegationSubject)
Handles MBeanServerConnection#setAttribute(ObjectName, Attribute) by setting the value of the specified attribute of the supplied management bean. The attribute is wrapped in a MarshalledObject so that it is deserialised using the bean's classloader.

Parameters: name the name of the management bean. attribute the attribute to set, encapsulated in a MarshalledObject. delegationSubject a 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. AttributeNotFoundException if the attribute does not correspond to an attribute of the bean. InvalidAttributeValueException if the value is invalid for this particular attribute of the bean. MBeanException if setting the attribute causes the bean to throw an exception (which becomes the cause of this exception). 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. RuntimeOperationsException if an IllegalArgumentException is thrown by the server due to a null bean or attribute name. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: RMIConnection javax.management.DynamicMBean#setAttribute(Attribute)

setAttributes

public AttributeList setAttributes(ObjectName name, MarshalledObject attributes, Subject delegationSubject)
Handles MBeanServerConnection#setAttributes(ObjectName, AttributeList) by setting the value of each of the specified attributes of the supplied management bean to that specified by the Attribute object. The returned list contains the attributes that were set and their new values. The attribute list is wrapped in a MarshalledObject so that it is deserialised using the bean's classloader.

Parameters: name the name of the management bean. attributes the attributes to set, encapsulated in a MarshalledObject. delegationSubject a javax.security.auth.Subject instance containing the delegation principles or {@code null} if authentication is used.

Returns: a list of the changed attributes.

Throws: InstanceNotFoundException if the bean can not be found. 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. RuntimeOperationsException if an IllegalArgumentException is thrown by the server due to a null bean or attribute list. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.

See Also: (ObjectName, String[]) DynamicMBean#setAttributes(AttributeList)

unregisterMBean

public void unregisterMBean(ObjectName name, Subject delegationSubject)
Handles 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 MBeanRegistration#preDeregister() method will be called if the bean implements the MBeanRegistration interface.

Parameters: name the name of the management bean. delegationSubject a 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. MBeanRegistrationException if an exception occurs in calling the preDeregister method. RuntimeOperationsException if an IllegalArgumentException is thrown by the server due to a null bean name or a request being made to unregister the MBeanServerDelegate bean. SecurityException if the client or delegated subject (if any) does not have permission to invoke this operation. IOException if an I/O error occurred in communicating with the bean server.