com.sun.jdmk.remote.cascading
Interface CascadingAgentMBean

All Known Implementing Classes:

CascadingAgent, ProxyCascadingAgent

public interface CascadingAgentMBean

Describes the management interface of the cascading agent MBean.

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.

See CascadingAgent for more details.

Since:

Java DMK 5.1

Method Summary

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.
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.
String	getTargetPath() Gets the targetPath.
boolean	isActive() Tests if the CascadingAgent is active.
void	start() Starts the cascading.
void	start(boolean conflictAllowed) Starts this cascading agent.
void	stop() Stops the cascading.

Method Detail

getCascadedMBeanCount

int getCascadedMBeanCount()

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.

Returns:

the number of source MBeans cascaded by this CascadingAgent.

getCascadedMBeans

Set getCascadedMBeans()

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.

Returns:

a Set containing all ObjectInstances representing the cascaded source MBeans.

getPattern

ObjectName getPattern()

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.

Returns:

the source ObjectName pattern filter.

getQuery

QueryExp getQuery()

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.

Returns:

the source QueryExp query filter.

start

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.

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

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:

start(boolean)

start

void start()
           throws IOException

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.

Throws:

IOException - if cascading couldn't be established.

IllegalStateException - if this cascading agent is not in a state where it can be started (for instance, a stop operation is still in progress). The exact cases where IllegalStateException can be thrown is implementation dependent.

See Also:

stop(), isActive()

stop

void stop()
          throws IOException

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

Throws:

IOException - if cascading couldn't be stopped.

IllegalStateException - if this cascading agent is not in a state where it can be stopped (for instance, a start operation is still in progress). The exact cases where IllegalStateException can be thrown is implementation dependent.

See Also:

start(boolean), isActive()

isActive

boolean isActive()

Tests if the CascadingAgent is active.

Returns:

true if the cascading agent is active.

getDescription

String getDescription()

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"

Returns:

A human readable string describing this cascading agent.

getTargetPath

String getTargetPath()

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.

Returns:

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

See Also:

com.sun.jdmk.remote.cascading