|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sun.jdmk.remote.cascading.CascadingAgent
public abstract class CascadingAgent
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.
[...] 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.
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 |
---|
public static final ObjectName MBSDelegateObjectName
Constructor Detail |
---|
protected CascadingAgent(MBeanServerConnectionFactory sourceConnection, ObjectName sourcePattern, QueryExp sourceQuery, String targetPath, MBeanServer targetMBS)
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.
IllegalArgumentException
- if targetPath is
not syntactically valid (e.g. it contains wildcard
characters).Method Detail |
---|
protected void enableConnectionNotifications() throws IOException
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.
IOException
protected void disableConnectionNotifications() throws IOException
JMXConnectionNotification
with the underlying
MBeanServerConnectionFactory
.
Subclasses are expected to call this method as part of the
implementation of the stop()
method.
IOException
enableConnectionNotifications()
public final String getTargetPath()
CascadingAgentMBean
getTargetPath
in interface CascadingAgentMBean
com.sun.jdmk.remote.cascading
public int getCascadedMBeanCount()
CascadingAgentMBean
CascadingAgent
.
This is the number of source MBeans that have been mounted by
this cascading agent in the target MBeanServer.
getCascadedMBeanCount
in interface CascadingAgentMBean
CascadingAgent
.public abstract Set getCascadedMBeans()
CascadingAgentMBean
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.
getCascadedMBeans
in interface CascadingAgentMBean
Set
containing all
ObjectInstances
representing the cascaded
source MBeans.public abstract void start() throws IOException
CascadingAgentMBean
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.
start
in interface CascadingAgentMBean
IOException
- if cascading couldn't be established.CascadingAgentMBean.stop()
,
CascadingAgentMBean.isActive()
public abstract void start(boolean conflictAllowed) throws IOException, InstanceAlreadyExistsException
CascadingAgentMBean
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.
start
in interface CascadingAgentMBean
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.
IOException
- if the connection with the source
MBeanServer fails.
InstanceAlreadyExistsException
- if a name conflict is
detected while starting.CascadingAgentMBean.start(boolean)
public abstract void stop() throws IOException
CascadingAgentMBean
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()
).
stop
in interface CascadingAgentMBean
IOException
- if cascading couldn't be stopped.CascadingAgentMBean.start(boolean)
,
CascadingAgentMBean.isActive()
public abstract boolean isActive()
CascadingAgentMBean
CascadingAgent
is active.
isActive
in interface CascadingAgentMBean
true
if the cascading agent is active.public abstract String getDescription()
CascadingAgentMBean
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:
getDescription
in interface CascadingAgentMBean
protected abstract void handleJMXConnectionNotification(Notification n, Object handback)
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.
public final ObjectName getPattern()
CascadingAgentMBean
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.
getPattern
in interface CascadingAgentMBean
public final QueryExp getQuery()
CascadingAgentMBean
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.
getQuery
in interface CascadingAgentMBean
public void addNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) throws IllegalArgumentException
addNotificationListener
in interface NotificationBroadcaster
IllegalArgumentException
public void removeNotificationListener(NotificationListener listener) throws ListenerNotFoundException
removeNotificationListener
in interface NotificationBroadcaster
ListenerNotFoundException
public void removeNotificationListener(NotificationListener listener, NotificationFilter filter, Object handback) throws ListenerNotFoundException
removeNotificationListener
in interface NotificationEmitter
ListenerNotFoundException
public MBeanNotificationInfo[] getNotificationInfo()
getNotificationInfo
in interface NotificationBroadcaster
protected void sendNotification(Notification notification)
notification
- The notification to send.NotificationBroadcasterSupport.sendNotification(javax.management.Notification)
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);
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.NotificationBroadcasterSupport.handleNotification(javax.management.NotificationListener, javax.management.Notification, java.lang.Object)
public final MBeanServer getTargetMBeanServer()
public ObjectName preRegister(MBeanServer server, ObjectName name) throws Exception
preRegister
in interface MBeanRegistration
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.
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
MBeanRegistration.preRegister(javax.management.MBeanServer, javax.management.ObjectName)
public void postRegister(Boolean registrationDone)
postRegister
in interface MBeanRegistration
public void preDeregister() throws Exception
preDeregister
in interface MBeanRegistration
Exception
public void postDeregister()
postDeregister
in interface MBeanRegistration
public final MBeanServerConnectionFactory getConnectionFactory()
|
Open Source build 02 opendmk-1.0-b02 2007.10.01_19:17:46_MEST |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |