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

java.lang.Object
  com.sun.jdmk.remote.cascading.CascadingAgent
      com.sun.jdmk.remote.cascading.proxy.ProxyCascadingAgent

All Implemented Interfaces:

CascadingAgentMBean, MBeanRegistration, NotificationBroadcaster, NotificationEmitter

public class ProxyCascadingAgent
extends CascadingAgent

This class is an implementation of CascadingAgent that relies on MBean proxying.

Using this class directly is discouraged. You should envisage using the CascadingService instead.

A CascadingAgent is an MBean that is able to mount a partial view of a source MBeanServer into a target MBeanServer. The source MBeanServer is also sometimes called the cascaded MBeanServer, while the target MBeanServer is called the cascading MBeanServer.

For each MBean cascaded from the source MBeanServer, the ProxyCascadingAgent will register a CascadingProxy in the target MBeanServer.

See CascadingAgent and com.sun.jdmk.remote.cascading for more details on the cascading concepts.

Since:

Java DMK 5.1

Field Summary

Fields inherited from class com.sun.jdmk.remote.cascading.CascadingAgent

MBSDelegateObjectName

Constructor Summary

ProxyCascadingAgent(MBeanServerConnectionFactory sourceConnection, ObjectName sourcePattern, QueryExp sourceQuery, String description)
Creates a new ProxyCascadingAgent - Using this constructor is discouraged.

ProxyCascadingAgent(MBeanServerConnectionFactory sourceConnection, ObjectName sourcePattern, QueryExp sourceQuery, String targetPath, MBeanServer targetMBS, String description)
Creates a ProxyCascadingAgent that will mount MBeans from a source MBeanServer under the given targetPath.

Method Summary

protected Object	createProxy(ObjectName sourceName, MBeanServerConnectionFactory cf) Creates a new proxy for the specified source MBean.
int	getCascadedMBeanCount() Returns the number of source MBeans cascaded by this CascadingAgent.
Set	getCascadedMBeans() Returns a Set of ObjectInstance representing the source MBeans cascaded by this CascadingAgent.
String	getDescription() A human readable string describing this cascading agent.
protected void	handleJMXConnectionNotification(Notification n, Object handback) This method is called internally when a JMXConnectionNotification is received through the underlying source MBeanServerConnectionFactory.
protected void	handleMBeanServerNotification(Notification notification, Object handback) This method is called internally when a MBeanServerNotification is received from the source (cascaded) MBeanServer.
boolean	isActive() Tests if the CascadingAgent is active.
protected boolean	mustCascade(ObjectName sourceName) Returns true if the given source MBean name is the name of an MBean that must be cascaded.
protected long	newSequenceNumber() Increments and returns this object's notification sequence number.
void	preDeregister() Allows the MBean to perform any operations it needs before being unregistered by the MBean server.
void	start() Starts the cascading.
void	start(boolean conflictAllowed) Starts this cascading agent.
void	stop() Stops this CascadingAgent.
void	update() Update the proxies managed by this CascadingAgent by comparing the list of currently linked proxies in the target MBeanServer with the list of source MBeans in the source MBeanServer.

Methods inherited from class com.sun.jdmk.remote.cascading.CascadingAgent

addNotificationListener, disableConnectionNotifications, enableConnectionNotifications, getConnectionFactory, getNotificationInfo, getPattern, getQuery, getTargetMBeanServer, getTargetPath, handleNotification, postDeregister, postRegister, preRegister, removeNotificationListener, removeNotificationListener, sendNotification

Methods inherited from class java.lang.Object

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

Constructor Detail

ProxyCascadingAgent

public ProxyCascadingAgent(MBeanServerConnectionFactory sourceConnection,
                           ObjectName sourcePattern,
                           QueryExp sourceQuery,
                           String targetPath,
                           MBeanServer targetMBS,
                           String description)

Creates a ProxyCascadingAgent that will mount MBeans from a source MBeanServer under the given targetPath.

Parameters:

sourceConnection - An MBeanServerConnectionFactory providing connections to the source (cascaded) MBeanServer.

The CascadingAgent will call sourceConnection.getMBeanServerConnection() every time it needs to access the subagent.

sourcePattern - An ObjectName pattern that must be satisfied by the ObjectNames of the source MBeans.

The sourcePattern is evaluated in the context of the source MBeanServer. The source pattern is used to perform a partial mount of the source MBeanServer in the target MBeanServer. Only those MBeans that satisfy the pattern will be mounted. The source pattern is thus a filter element. A null sourcePattern is equivalent to the wildcard "*:*".

sourceQuery - A QueryExp that must be satisfied by the source MBeans.

The sourceQuery is evaluated in the context of the source MBeanServer. Using this functionality is discouraged. It is recommended to always pass a null parameter. If however, you chose to pass a non null sourceQuery, the given QueryExp should not involve any properties or attributes that vary over time. The evaluation of the sourceQuery against a given MBean should be guaranteed to always consistently yield the same result. Our implementation does not enforce this constraint, but the behavior of the CascadingAgent in the case where this constraint were not respected is unspecified and could be unpredictable.

targetPath - The domain path under which the source MBeans will be mounted in the target MBeanServer.

If this parameter is not null, all source MBean names will be transformed in the target MBeanServer by prefixing their domain name with the string targetPath+"/". An MBean whose name is "D:k1=v1,k2=v2" will thus be mounted as "targetPath/D:k1=v1,k2=v2".

A null targetPath means that MBeans are mounted directly at the root of the hierarchy, that is, as if they were local MBeans. Using a null targetPath is thus highly discouraged, as it could cause name conflicts in the target MBeanServer.

Similarly, MBeans from different sources should not be mounted under the same targetPath. Moreover, an application should not attempt to mount source MBeans under a targetPath that already contain MBeans in the target MBeanServer.

However, our implementation does not enforce these rules: It is the responsibility of the application creating the CascadingAgent to ensure the consistency of the mounting strategy.

Note: A zero-length targetPath is treated as a null targetPath.

description - A human readable string describing this CascadingAgent.

Throws:

IllegalArgumentException - if targetPath is not syntactically valid (e.g. it contains wildcard characters).

ProxyCascadingAgent

public ProxyCascadingAgent(MBeanServerConnectionFactory sourceConnection,
                           ObjectName sourcePattern,
                           QueryExp sourceQuery,
                           String description)

Creates a new ProxyCascadingAgent - Using this constructor is discouraged.

Creates a ProxyCascadingAgent that will mount MBeans from a source MBeanServer at the root of the domain hierarchy. This is equivalent to mounting MBeans from a source MBeanServer to a target MBeanServer under a null targetPath.

A null targetPath means that MBeans are mounted directly at the root of the hierarchy, that is, as if they were local MBeans. Using a null targetPath is thus highly discouraged, as it could cause name conflicts in the target MBeanServer.

When using this constructor, the target MBeanServer is the MBeanServer in which this CascadingAgent is registered.

You should consider using the constructor that takes a targetPath and a target MBeanServer instead.

See com.sun.jdmk.remote.cascading description and CascadingAgent.

Parameters:

sourceConnection - An MBeanServerConnectionFactory providing connections to the source (cascaded) MBeanServer.

The CascadingAgent will call sourceConnection.getMBeanServerConnection() every time it needs to access the subagent.

sourcePattern - An ObjectName pattern that must be satisfied by the ObjectNames of the source MBeans.

The sourcePattern is evaluated in the context of the source MBeanServer. The source pattern is used to perform a partial mount of the source MBeanServer in the target MBeanServer. Only those MBeans that satisfy the pattern will be mounted. The source pattern is thus a filter element. A null sourcePattern is equivalent to the wildcard "*:*".

sourceQuery - A QueryExp that must be satisfied by the source MBeans.

The sourceQuery is evaluated in the context of the source MBeanServer. Using this functionality is discouraged. It is recommended to always pass a null parameter. If however, you chose to pass a non null sourceQuery, the given QueryExp should not involve any properties or attributes that vary over time. The evaluation of the sourceQuery against a given MBean should be guaranteed to always consistently yield the same result. Our implementation does not enforce this constraint, but the behavior of the CascadingAgent in the case where this constraint were not respected is unspecified and could be unpredictable.

description - A human readable string describing this CascadingAgent.

Method Detail

start

public void start()
           throws IOException

Description copied from interface: CascadingAgentMBean

Starts the cascading.

This is equivalent to calling start(true)

When this method successfully completes, the source MBeans from the source (cascaded) MBeanServer which satisfy the source ObjectName pattern filter and the source QueryExp query filter will have been mounted in the target (cascading) MBeanServer under the specified targetPath.
After a successful invocation of start(), the CascadingAgent becomes active (see isActive()).

CascadingAgents may be started and stopped multiple times, long as their underlying MBeanServerConnectionFactory is able to return valid MBeanServerConnections.

If this method raises an exception, then no MBeans will have been cascaded as a result of this invocation.

Specified by:

start in interface CascadingAgentMBean

Specified by:

start in class CascadingAgent

Throws:

IOException - if cascading couldn't be established.

See Also:

CascadingAgentMBean.stop(), CascadingAgentMBean.isActive()

start

public void start(boolean conflictAllowed)
           throws IOException,
                  InstanceAlreadyExistsException

Starts this cascading agent.

When this method successfully completes, the source MBeans from the source (cascaded) MBeanServer which satisfy the source ObjectName pattern filter and the source QueryExp query filter will have been mounted in the target (cascading) MBeanServer under the specified targetPath.
After a successful invocation of start(), the CascadingAgent becomes active (see isActive()).

CascadingAgents may be started and stopped multiple times, long as their underlying MBeanServerConnectionFactory is able to return valid MBeanServerConnections.

If conflictAllowed is false, and a name conflict is detected, this method will throw an InstanceAlreadyExistsException. Otherwise, conflicting names are simply skipped - no proxy is created for the names in conflict. Using a wildcard pattern/query and setting this parameter to false with no targetPath will always result in throwing an InstanceAlreadyExistsException.

For each cascaded MBean found in the source MBeanServer, this method will register a proxy MBean as returned by createProxy(javax.management.ObjectName, com.sun.jdmk.remote.cascading.MBeanServerConnectionFactory) in the target MBeanServer. The ProxyCascadingAgent is responsible for the life cycle of these proxies. The application should not attempt to unregister MBean proxies which are under the responsibility of a ProxyCascadingAgent. Our implementation does not enforce this rule, but unpredictable behavior may occur if it is broken - that is: deleted proxies may suddenly reappear at unpredictable time, when the ProxyCascadingAgent attempts to update its view of the source MBeanServer.

If this method raises an exception, then no MBeans will have been cascaded as a result of this invocation.

Proxy MBeans will be later deleted by the ProxyCascadingAgent on one of these three condition:

• The stop() method is called, in which case all proxies managed by this cascading agent are unregistered from the target MBeanServer.
• An external event - e.g reception of a JMXConnectionNotification.NOTIFS_LOST Notification - makes the ProxyCascadingAgent update its view of source MBeanServer. As a result proxies for which cascaded MBeans no longer exists in the source MBeanServer will be removed from the target MBeanServer.
• The ProxyCascadingAgent receives a MBeanServerNotification.UNREGISTRATION_NOTIFICATION for one of the cascaded MBean. In which case the proxy corresponding to that source MBean will be removed from the target MBeanServer.

Specified by:

start in interface CascadingAgentMBean

Specified by:

start in class CascadingAgent

Parameters:

conflictAllowed - if true the cascading agent will ignore name conflicts. if false, the cascading agent will throw an InstanceAlreadyExistsException if it detects a name conflict while starting. After the CascadingAgent has started, name conflicts are always ignored: MBeans from the source MBeanServer whose name would cause a conflict in the target MBeanServer are simply not cascaded.

Throws:

IOException - if the connection with the source MBeanServer fails.

IllegalStateException - if this cascading agent is not stopped, or if the target MBeanServer can't be obtained (e.g. the CascadingAgent MBean was not registered).

InstanceAlreadyExistsException - if a name conflict is detected while starting.

See Also:

CascadingAgentMBean.start(boolean), mustCascade(javax.management.ObjectName), handleMBeanServerNotification(javax.management.Notification, java.lang.Object), CascadingAgent.preRegister(javax.management.MBeanServer, javax.management.ObjectName)

stop

public void stop()
          throws IOException

Stops this CascadingAgent. Does nothing if the CascadingAgent is already stopped. Deregisters from the target MBeanServer all proxies corresponding to source MBeans.

Specified by:

stop in interface CascadingAgentMBean

Specified by:

stop in class CascadingAgent

Throws:

IOException - not thrown in this default implementation.

IllegalStateException - if the CascadingAgent is not started.

See Also:

CascadingAgentMBean.start(boolean), CascadingAgentMBean.isActive()

getCascadedMBeanCount

public int getCascadedMBeanCount()

Description copied from interface: CascadingAgentMBean

Returns the number of source MBeans cascaded by this CascadingAgent. This is the number of source MBeans that have been mounted by this cascading agent in the target MBeanServer.

Specified by:

getCascadedMBeanCount in interface CascadingAgentMBean

Overrides:

getCascadedMBeanCount in class CascadingAgent

Returns:

the number of source MBeans cascaded by this CascadingAgent.

getCascadedMBeans

public Set getCascadedMBeans()

Description copied from interface: CascadingAgentMBean

Returns a Set of ObjectInstance representing the source MBeans cascaded by this CascadingAgent. The ObjectInstance objects returned are to be interpreted in the context of the source MBeanServer: the ObjectNames correspond to the ObjectNames of the source MBeans in the source MBeanServer.

Specified by:

getCascadedMBeans in interface CascadingAgentMBean

Specified by:

getCascadedMBeans in class CascadingAgent

Returns:

a Set containing all ObjectInstances representing the cascaded source MBeans.

getDescription

public String getDescription()

Description copied from interface: CascadingAgentMBean

A human readable string describing this cascading agent.

Whenever possible, this description string should identify the source MBeanServer which is cascaded by this CascadingAgent, and the semantics of this cascading agent.
For instance, if the cascaded agent has a human readable JMXServiceURL (i.e. not the form containing the encoded stub), then the source agent could be identified by that URL, and that URL could be used in this description string.
Alternatively, if the cascaded agent connector was retrieved from a naming service, then the JMX Agent Name of the cascaded agent could be used to identify it.

A valid description could be e.g:

"mount service:jmx:jmxmp://localhost:9876 java.lang:* null server1/instance1"

Specified by:

getDescription in interface CascadingAgentMBean

Specified by:

getDescription in class CascadingAgent

Returns:

A human readable string describing this cascading agent.

isActive

public boolean isActive()

Description copied from interface: CascadingAgentMBean

Tests if the CascadingAgent is active.

Specified by:

isActive in interface CascadingAgentMBean

Specified by:

isActive in class CascadingAgent

Returns:

true if the cascading agent is active.

update

public void update()
            throws IOException

Update the proxies managed by this CascadingAgent by comparing the list of currently linked proxies in the target MBeanServer with the list of source MBeans in the source MBeanServer. This makes it possible to recover from a potential MBeanServerNotification loss.

Throws:

IOException - if the connection with the cascaded MBeanServer fails.

preDeregister

public void preDeregister()
                   throws Exception

Allows the MBean to perform any operations it needs before being unregistered by the MBean server. This implementation throws an IllegalStateException if the ProxyCascadingAgent is active.

Specified by:

preDeregister in interface MBeanRegistration

Overrides:

preDeregister in class CascadingAgent

Throws:

IllegalStateException - if the ProxyCascadingAgent is not stopped.

Exception

See Also:

CascadingAgent.preDeregister()

createProxy

protected Object createProxy(ObjectName sourceName,
                             MBeanServerConnectionFactory cf)

Creates a new proxy for the specified source MBean. This default implementation returns a new instance of CascadingProxy. Subclasses can redefine this method in order to return other types of proxy. The returned object must simply be a valid MBean that can be registered in the target MBeanServer.

Parameters:

sourceName - The name of the source MBean.

cf - The MBeanServerConnectionFactory used to obtain connections with the source MBeanServer.

Returns:

A new cascading proxy for the given source MBean.

handleJMXConnectionNotification

protected void handleJMXConnectionNotification(Notification n,
                                               Object handback)

This method is called internally when a JMXConnectionNotification is received through the underlying source MBeanServerConnectionFactory. This method is called only after start() was called. This method is a callback that should never be called directly by subclasses.

It proceeds as follows:

JMXConnectionNotification.OPENED and JMXConnectionNotification.NOTIFS_LOST trigger an update() operation.

JMXConnectionNotification.CLOSED makes the CascadingAgent attempt to reopen the underlying connection by calling getConnectionFactory(). getMBeanServerConection().getDefaultDomain().
If this call fails, the CascadingAgent assumes that the underlying connection is broken and proceeds as if the JMXConnectionNotification.FAILED were received.

JMXConnectionNotification.FAILED makes the CascadingAgent stop - proxies are removed and the CascadingAgent becomes inactive.

In all cases, a similar notification is re-emitted to this object's listeners by calling CascadingAgent.sendNotification(javax.management.Notification):

• The source is changed to this,
• The sequenceNumber is reset to this object's sequenceNumber,
• All other fields are imported from the original notification.

Specified by:

handleJMXConnectionNotification in class CascadingAgent

handleMBeanServerNotification

protected void handleMBeanServerNotification(Notification notification,
                                             Object handback)

This method is called internally when a MBeanServerNotification is received from the source (cascaded) MBeanServer. This method is called only after start() was called. This method is a callback that should never be called directly by subclasses.

Parameters:

notification - The notification.

handback - An opaque object which helps the listener to associate information regarding the MBean emitter. This object is passed to the MBean during the addListener call and resent, without modification, to the listener. In this implementation, the handback is null.

See Also:

NotificationListener.handleNotification(javax.management.Notification, java.lang.Object)

mustCascade

protected boolean mustCascade(ObjectName sourceName)

Returns true if the given source MBean name is the name of an MBean that must be cascaded.

This method is called when a MBeanServerNotification.REGISTRATION_NOTIFICATION is received. This default implementation checks that the given source name satisfies the source ObjectName pattern of this cascading agent, that the source MBean satisfies the query filter of this cascading agent, and that this cascading agent has the permission to access the source MBean in the subagent.

Parameters:

sourceName - The source MBean name.

Returns:

true if the source MBean name is the name of an MBean that must be cascaded.

newSequenceNumber

protected final long newSequenceNumber()

Increments and returns this object's notification sequence number.