com.sun.jdmk.remote.cascading
Class CascadingAgent

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

All Implemented Interfaces:

CascadingAgentMBean, MBeanRegistration, NotificationBroadcaster, NotificationEmitter

Direct Known Subclasses:

ProxyCascadingAgent

public abstract class CascadingAgent
extends Object
implements MBeanRegistration, NotificationEmitter, CascadingAgentMBean

This class is an abstract MBean class that provides a basic default implementation for some methods of the CascadingAgentMBean interface.

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.

The Java DMK cascading API introduces the notion of domain path. An ObjectName is thus decomposed into three parts:

 <domain-path><domain-base-name>:<key-property-list>
 

The domain path is a hierarchical name similar to a UNIX path name, and using the character `/' as separator.
The Java DMK cascading API provides the ability to mount MBeans from a source MBeanServer under a target domain path in a target MBeanServer.
For instance, this makes it possible to:

• mount "java.lang:*" MBeans from a subagent 1 under "server1/instance1"
• mount "java.lang:*" MBeans from a subagent 2 under "server1/instance2"

The content of the target MBeanServer as returned by queryNames(null,null) would then appear as:

 [...]
 java.lang:type=Compilation
 java.lang:type=Threading
 [...]
 server1/instance1/java.lang:type=Threading
 server1/instance1/java.lang:type=Compilation
 [...]
 server1/instance2/java.lang:type=Threading
 server1/instance2/java.lang:type=Compilation
 [...]
 

See com.sun.jdmk.remote.cascading for more details.

Since:

Java DMK 5.1

Field Summary

static ObjectName

MBSDelegateObjectName A constant holding the standard ObjectName of the MBeanServerDelegate MBean.

Constructor Summary

protected

CascadingAgent(MBeanServerConnectionFactory sourceConnection, ObjectName sourcePattern, QueryExp sourceQuery, String targetPath, MBeanServer targetMBS) Construct a new CascadingAgent MBean.

Method Summary

void	addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)
protected void	disableConnectionNotifications() This method should only be called by subclasses.
protected void	enableConnectionNotifications() This method should only be called by subclasses.
int	getCascadedMBeanCount() Returns the number of source MBeans cascaded by this CascadingAgent.
abstract Set	getCascadedMBeans() Returns a Set of ObjectInstance representing the source MBeans cascaded by this CascadingAgent.
MBeanServerConnectionFactory	getConnectionFactory() Returns the MBeanServerConnectionFactory, as passed to this object's constructor.
abstract String	getDescription() A human readable string describing this cascading agent.
MBeanNotificationInfo[]	getNotificationInfo()
ObjectName	getPattern() Returns the source ObjectName pattern filter that the source MBean names must satisfy in order to be cascaded.
QueryExp	getQuery() Returns the source QueryExp query filter that the source MBean names must satisfy in order to be cascaded.
MBeanServer	getTargetMBeanServer() The target MBeanServer in which the source MBeans will be mounted under the target path.
String	getTargetPath() Gets the targetPath.
protected abstract void	handleJMXConnectionNotification(Notification n, Object handback) This method is called internally when a JMXConnectionNotification is received through the underlying MBeanServerConnectionFactory.
protected void	handleNotification(NotificationListener listener, Notification notif, Object handback) This method is called by sendNotification for each listener in order to send the notification to that listener.
abstract boolean	isActive() Tests if the CascadingAgent is active.
void	postDeregister()
void	postRegister(Boolean registrationDone)
void	preDeregister()
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)
void	removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback)
protected void	sendNotification(Notification notification) Sends a notification.
abstract void	start() Starts the cascading.
abstract void	start(boolean conflictAllowed) Starts this cascading agent.
abstract void	stop() Stops the cascading.

Methods inherited from class java.lang.Object

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

Field Detail

MBSDelegateObjectName

public static final ObjectName MBSDelegateObjectName

A constant holding the standard ObjectName of the MBeanServerDelegate MBean.

Constructor Detail

CascadingAgent

protected CascadingAgent(MBeanServerConnectionFactory sourceConnection,
                         ObjectName sourcePattern,
                         QueryExp sourceQuery,
                         String targetPath,
                         MBeanServer targetMBS)

Construct a new CascadingAgent MBean.

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.

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

If this parameter is null, the target MBeanServer is the MBeanServer passed through the MBeanRegistration interface at registration time.

Throws:

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

Method Detail

enableConnectionNotifications

protected void enableConnectionNotifications()
                                      throws IOException

This method should only be called by subclasses. Register for JMXConnectionNotification with the underlying MBeanServerConnectionFactory. Calling this method causes the handleJMXConnectionNotification(Notification,Object) method to be called when a JMXConnectionNotification is received through the underlying MBeanServerConnectionFactory. Subclasses are expected to call this method as part of the implementation of the start() method.

Throws:

IOException

disableConnectionNotifications

protected void disableConnectionNotifications()
                                       throws IOException

This method should only be called by subclasses. Deregister for JMXConnectionNotification with the underlying MBeanServerConnectionFactory. Subclasses are expected to call this method as part of the implementation of the stop() method.

Throws:

IOException

See Also:

enableConnectionNotifications()

getTargetPath

public final String getTargetPath()

Description copied from interface: CascadingAgentMBean

Gets the targetPath. This is the domain path under which the source MBeans will be mounted in the target MBeanServer. If this attribute 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.

Specified by:

getTargetPath in interface CascadingAgentMBean

Returns:

The value of the targetPath under which source MBeans are mounted in the target MBeanServer.

See Also:

com.sun.jdmk.remote.cascading

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

Returns:

the number of source MBeans cascaded by this CascadingAgent.

getCascadedMBeans

public abstract 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

Returns:

a Set containing all ObjectInstances representing the cascaded source MBeans.

start

public abstract 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

Throws:

IOException - if cascading couldn't be established.

See Also:

CascadingAgentMBean.stop(), CascadingAgentMBean.isActive()

start

public abstract void start(boolean conflictAllowed)
                    throws IOException,
                           InstanceAlreadyExistsException

Description copied from interface: CascadingAgentMBean

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.

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

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.

InstanceAlreadyExistsException - if a name conflict is detected while starting.

See Also:

CascadingAgentMBean.start(boolean)

stop

public abstract void stop()
                   throws IOException

Description copied from interface: CascadingAgentMBean

Stops the cascading.

When this method completes, the MBeans that were cascaded by this CascadingAgent will no longer be mounted in the cascading MBeanServer. After a successful invocation of stop(), the CascadingAgent becomes inactive (see isActive()).

Specified by:

stop in interface CascadingAgentMBean

Throws:

IOException - if cascading couldn't be stopped.

See Also:

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

isActive

public abstract boolean isActive()

Description copied from interface: CascadingAgentMBean

Tests if the CascadingAgent is active.

Specified by:

isActive in interface CascadingAgentMBean

Returns:

true if the cascading agent is active.

getDescription

public abstract 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

Returns:

A human readable string describing this cascading agent.

handleJMXConnectionNotification

protected abstract void handleJMXConnectionNotification(Notification n,
                                                        Object handback)

This method is called internally when a JMXConnectionNotification is received through the underlying MBeanServerConnectionFactory. This method is called only if reception of JMXConnectionNotifications has been enabled with enableConnectionNotifications(). This method is a callback that should never be called directly by subclasses.

getPattern

public final ObjectName getPattern()

Description copied from interface: CascadingAgentMBean

Returns the source ObjectName pattern filter that the source MBean names must satisfy in order to be cascaded. This pattern is to be evaluated in the context of the source MBeanServer.

Specified by:

getPattern in interface CascadingAgentMBean

Returns:

the source ObjectName pattern filter.

getQuery

public final QueryExp getQuery()

Description copied from interface: CascadingAgentMBean

Returns the source QueryExp query filter that the source MBean names must satisfy in order to be cascaded. This query is to be evaluated in the context of the source MBeanServer.

Specified by:

getQuery in interface CascadingAgentMBean

Returns:

the source QueryExp query filter.

addNotificationListener

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

Specified by:

addNotificationListener in interface NotificationBroadcaster

Throws:

IllegalArgumentException

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException

Specified by:

removeNotificationListener in interface NotificationBroadcaster

Throws:

ListenerNotFoundException

removeNotificationListener

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

Specified by:

removeNotificationListener in interface NotificationEmitter

Throws:

ListenerNotFoundException

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()

Specified by:

getNotificationInfo in interface NotificationBroadcaster

sendNotification

protected void sendNotification(Notification notification)

Sends a notification.

Parameters:

notification - The notification to send.

See Also:

NotificationBroadcasterSupport.sendNotification(javax.management.Notification)

handleNotification

protected void handleNotification(NotificationListener listener,
                                  Notification notif,
                                  Object handback)

This method is called by sendNotification for each listener in order to send the notification to that listener. It can be overridden in subclasses to change the behavior of notification delivery, for instance to deliver the notification in a separate thread.

It is not guaranteed that this method is called by the same thread as the one that called sendNotification.

The default implementation of this method is equivalent to

 listener.handleNotification(notif, handback);
 

Parameters:

listener - the listener to which the notification is being delivered.

notif - the notification being delivered to the listener.

handback - the handback object that was supplied when the listener was added.

See Also:

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

getTargetMBeanServer

public final MBeanServer getTargetMBeanServer()

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

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. Check that the given name is not null. If the target MBeanServer supplied at construction time was null, then server becomes the target MBeanServer.

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, or if no target MBeanServer was specified in the constructor and this object is already registered in an MBeanServer.

Exception

See Also:

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

postRegister

public void postRegister(Boolean registrationDone)

Specified by:

postRegister in interface MBeanRegistration

preDeregister

public void preDeregister()
                   throws Exception

Specified by:

preDeregister in interface MBeanRegistration

Throws:

Exception

postDeregister

public void postDeregister()

Specified by:

postDeregister in interface MBeanRegistration

getConnectionFactory

public final MBeanServerConnectionFactory getConnectionFactory()

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