com.sun.jdmk.remote.cascading.proxy
Class CascadingProxy

java.lang.Object
  com.sun.jdmk.remote.cascading.proxy.CascadingProxy

All Implemented Interfaces:

DynamicMBean, MBeanRegistration, NotificationBroadcaster, NotificationEmitter

public class CascadingProxy
extends Object
implements DynamicMBean, MBeanRegistration, NotificationEmitter

This class is used to proxy an MBean residing in a source MBeanServer. Connections to that source MBeanServer are obtained through an MBeanServerConnectionFactory. The CascadingProxy is a DynamicMBean that forwards all the calls it receive to a source MBean, residing in a source MBeanServer. The CascadingProxy also makes it possible for Notification Listeners to register for notifications emitted by the source MBeans.

Since:

Java DMK 5.1

Constructor Summary

CascadingProxy(ObjectName sourceMBeanName, MBeanServerConnectionFactory mbscf)
Creates a new CascadingProxy.

Method Summary

void	addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Adds a listener to the source MBean.
Object	getAttribute(String attribute) Obtain the value of a specific attribute from the source MBean.
AttributeList	getAttributes(String[] attributes) Get the values of several attributes from the source MBean.
MBeanServerConnectionFactory	getConnectionFactory() Returns the MBeanServerConnectionFactory, as passed to this object's constructor.
MBeanInfo	getMBeanInfo() Returns the MBeanInfo of the source MBean.
MBeanNotificationInfo[]	getNotificationInfo() Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.
ObjectName	getSourceMBeanName() The ObjectName of the source MBean, as passed to this Object's constructor.
ObjectName	getTargetName() The ObjectName of this cascading proxy.
Object	invoke(String actionName, Object[] params, String[] signature) Allows an action to be invoked on the source MBean.
void	postDeregister() Allows the MBean to perform any operations needed after having been unregistered in the MBean server.
void	postRegister(Boolean registrationDone) Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed.
void	preDeregister() Allows the MBean to perform any operations it needs before being unregistered by the MBean server.
ObjectName	preRegister(MBeanServer server, ObjectName name) Allows the MBean to perform any operations it needs before being registered in the MBean server.
void	removeNotificationListener(NotificationListener listener) Removes a listener from the source MBean.
void	removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) Removes a listener from the source MBean.
void	setAttribute(Attribute attribute) Set the value of a specific attribute on the source MBean.
AttributeList	setAttributes(AttributeList attributes) Sets the values of several attributes in the source MBean.
protected Notification	translate(Notification notif) Translate the source ObjectName into this CascadingProxy's ObjectName.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CascadingProxy

public CascadingProxy(ObjectName sourceMBeanName,
                      MBeanServerConnectionFactory mbscf)

Creates a new CascadingProxy.

Parameters:

sourceMBeanName - The ObjectName of the source MBean.

mbscf - An MBeanServerConnectionFactory from which connections with the MBeanServer containing the source MBean can be obtained. The CascadingProxy will call mbscf.getMBeanServerConnection() every time it needs to access the subagent.

Method Detail

getAttribute

public Object getAttribute(String attribute)
                    throws AttributeNotFoundException,
                           MBeanException,
                           ReflectionException

Obtain the value of a specific attribute from the source MBean.

Specified by:

getAttribute in interface DynamicMBean

Parameters:

attribute - The name of the attribute to be retrieved

Returns:

The value of the attribute retrieved.

Throws:

AttributeNotFoundException

MBeanException - Wraps a java.lang.Exception thrown by the MBean's getter.

ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the getter.

UndeclaredThrowableException - if an InstanceNotFoundException or an IOException is raised while trying to forward the request to the source MBean.

See Also:

setAttribute(javax.management.Attribute), DynamicMBean.getAttribute(java.lang.String)

setAttribute

public void setAttribute(Attribute attribute)
                  throws AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException

Set the value of a specific attribute on the source MBean.

Specified by:

setAttribute in interface DynamicMBean

Parameters:

attribute - The identification of the attribute to be set and the value it is to be set to.

Throws:

AttributeNotFoundException

InvalidAttributeValueException

MBeanException - Wraps a java.lang.Exception thrown by the MBean's setter.

ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the MBean's setter.

UndeclaredThrowableException - if an InstanceNotFoundException or an IOException is raised while trying to forward the request to the source MBean.

See Also:

getAttribute(java.lang.String), DynamicMBean.setAttribute(javax.management.Attribute)

getAttributes

public AttributeList getAttributes(String[] attributes)

Get the values of several attributes from the source MBean.

Specified by:

getAttributes in interface DynamicMBean

Parameters:

attributes - A list of the attributes to be retrieved.

Returns:

The list of attributes retrieved.

Throws:

UndeclaredThrowableException - if an InstanceNotFoundException, an IOException, or a ReflectionException is raised while trying to forward the request to the source MBean.

See Also:

setAttributes(javax.management.AttributeList), DynamicMBean.getAttributes(java.lang.String[])

setAttributes

public AttributeList setAttributes(AttributeList attributes)

Sets the values of several attributes in the source MBean.

Specified by:

setAttributes in interface DynamicMBean

Parameters:

attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to.

Returns:

The list of attributes that were set, with their new values.

Throws:

UndeclaredThrowableException - if an InstanceNotFoundException, an IOException, or a ReflectionException is raised while trying to forward the request to the source MBean.

See Also:

getAttributes(java.lang.String[]), DynamicMBean.setAttributes(javax.management.AttributeList)

invoke

public Object invoke(String actionName,
                     Object[] params,
                     String[] signature)
              throws MBeanException,
                     ReflectionException

Allows an action to be invoked on the source MBean.

Specified by:

invoke in interface DynamicMBean

Parameters:

actionName - The name of the action to be invoked.

params - An array containing the parameters to be set when the action is invoked.

signature - An array containing the signature of the action.

Returns:

The object returned by the action, which represents the result of invoking the action on the MBean specified.

Throws:

MBeanException - Wraps a java.lang.Exception thrown by the MBean's invoked method.

ReflectionException - Wraps a java.lang.Exception thrown while trying to invoke the method

UndeclaredThrowableException - if an InstanceNotFoundException or an IOException is raised while trying to forward the request to the source MBean.

See Also:

DynamicMBean.invoke(java.lang.String, java.lang.Object[], java.lang.String[])

getMBeanInfo

public MBeanInfo getMBeanInfo()

Returns the MBeanInfo of the source MBean. This MBeanInfo is not cached by the proxy, which could be considered as a suboptimal implementation for those implementations in which it is known that the source MBeanInfo will not change over time.

Subclasses may therefore wish to redefine this method in order to cache the returned MBeanInfo.

Specified by:

getMBeanInfo in interface DynamicMBean

Returns:

The source MBean MBeanInfo.

Throws:

UndeclaredThrowableException - if an InstanceNotFoundException, an IOException, a ReflectionException, or an IntrospectionException is raised while trying to forward the request to the source MBean.

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

Allows the MBean to perform any operations it needs before being registered in the MBean server. This default implementation simply checks that the given name is not null, and cache it in the CascadingProxy. Once the CascadingProxy is registered, its ObjectName can be later obtained by calling getTargetName().

Specified by:

preRegister in interface MBeanRegistration

Parameters:

server - The MBean server in which the MBean will be registered.

name - The object name of the MBean. If name this method throws an IllegalArgumentException.

Returns:

The given name.

Throws:

IllegalArgumentException - if the parameter name is null

Exception

See Also:

MBeanRegistration.preRegister(javax.management.MBeanServer, javax.management.ObjectName)

postRegister

public void postRegister(Boolean registrationDone)

Allows the MBean to perform any operations needed after having been registered in the MBean server or after the registration has failed. This default implementation does nothing.

Specified by:

postRegister in interface MBeanRegistration

Parameters:

registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

See Also:

MBeanRegistration.postRegister(java.lang.Boolean)

preDeregister

public void preDeregister()
                   throws Exception

Allows the MBean to perform any operations it needs before being unregistered by the MBean server. This default implementation does nothing.

Specified by:

preDeregister in interface MBeanRegistration

Throws:

Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException or a RuntimeMBeanException.

See Also:

MBeanRegistration.preDeregister()

postDeregister

public void postDeregister()

Allows the MBean to perform any operations needed after having been unregistered in the MBean server. This default implementation does nothing.

Specified by:

postDeregister in interface MBeanRegistration

getSourceMBeanName

public final ObjectName getSourceMBeanName()

The ObjectName of the source MBean, as passed to this Object's constructor.

getTargetName

public ObjectName getTargetName()

The ObjectName of this cascading proxy. May be null if this object has not been registered in an MBeanServer yet. Otherwise, it is the ObjectName obtained from the preRegister(javax.management.MBeanServer, javax.management.ObjectName) method.

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()

Returns an array indicating, for each notification this MBean may send, the name of the Java class of the notification and the notification type.

This method returns the notification information present in the source MBean's MBeanInfo - if any. Otherwise, it returns an empty array.

It is not illegal for the MBean to send notifications not described in this array. However, some clients of the MBean server may depend on the array being complete for their correct functioning.

Specified by:

getNotificationInfo in interface NotificationBroadcaster

Returns:

the array of possible notifications.

See Also:

NotificationBroadcaster.getNotificationInfo()

addNotificationListener

public void addNotificationListener(NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)

Adds a listener to the source MBean.

Specified by:

addNotificationListener in interface NotificationBroadcaster

Parameters:

listener - The listener object which will handle the notifications emitted by the broadcaster.

filter - The filter object. If filter is null, no filtering will be performed before handling notifications.

handback - An opaque object to be sent back to the listener when a notification is emitted. This object cannot be used by the Notification broadcaster object. It should be resent unchanged with the notification to the listener.

Throws:

IllegalArgumentException - Listener parameter is null.

UndeclaredThrowableException - if an InstanceNotFoundException or an IOException is raised while trying to forward the request to the source MBean.

See Also:

removeNotificationListener(javax.management.NotificationListener), NotificationBroadcaster.addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException

Removes a listener from the source MBean. If the listener has been registered with different handback objects or notification filters, all entries corresponding to the listener will be removed.

Specified by:

removeNotificationListener in interface NotificationBroadcaster

Parameters:

listener - A listener that was previously added to this MBean.

Throws:

ListenerNotFoundException - The listener is not registered with the MBean.

UndeclaredThrowableException - if an InstanceNotFoundException or an IOException is raised while trying to forward the request to the source MBean.

See Also:

addNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object), NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)
                                throws ListenerNotFoundException

Removes a listener from the source MBean. The MBean must have a listener that exactly matches the given listener, filter, and handback parameters. If there is more than one such listener, only one is removed.

The filter and handback parameters may be null if and only if they are null in a listener to be removed.

Specified by:

removeNotificationListener in interface NotificationEmitter

Parameters:

listener - A listener that was previously added to this MBean.

filter - The filter that was specified when the listener was added.

handback - The handback that was specified when the listener was added.

Throws:

ListenerNotFoundException - The listener is not registered with the MBean, or it is not registered with the given filter and handback.

UndeclaredThrowableException - if an InstanceNotFoundException or an IOException is raised while trying to forward the request to the source MBean.

See Also:

NotificationEmitter.removeNotificationListener(javax.management.NotificationListener, javax.management.NotificationFilter, java.lang.Object)

getConnectionFactory

public final MBeanServerConnectionFactory getConnectionFactory()

Returns the MBeanServerConnectionFactory, as passed to this object's constructor.

translate

protected Notification translate(Notification notif)

Translate the source ObjectName into this CascadingProxy's ObjectName. This implementation simply substitute the notification source by this CascadingProxy's ObjectName, iff the source is the ObjectName of the source MBean.

Returns:

notif, after the source has been possibly substituted.