Please note that this documentation is not final and is subject to change.

javax.management.namespace
Class JMXDomain

java.lang.Object
  javax.management.namespace.JMXNamespace
      javax.management.namespace.JMXDomain

All Implemented Interfaces:

MBeanRegistration, JMXNamespaceMBean

public class JMXDomain
extends JMXNamespace

A special JMXNamespace that can handle part of the MBeanServer local name space.

A JMXDomain makes a domain X of a source MBean server appear in the same domain X of a containing MBeanServer in which the JMXDomain MBean is registered.

The JMX infrastructure of the containing MBeanServer takes care of routing all calls to MBeans whose names have domain X to the source MBean server exported by the JMXDomain MBean in charge of domain X.

The source MBean server of a JMXDomain can, but need not be a regular MBeanServer created through the MBeanServerFactory. It could also be, for instance, an instance of a subclass of MBeanServerSupport, or a custom object implementing the MBeanServer interface.

Differences between JMXNamespace and JMXDomain

A JMXDomain is a special kind of JMXNamespace. A JMXNamespace such as foo// is triggered by an ObjectName that begins with the string foo//, for example foo//bar:type=Baz. A JMXDomain such as foo is triggered by an ObjectName with that exact domain, for example foo:type=Baz. A client can immediately see that an MBean is handled by a JMXNamespace because of the // in the name. A client cannot see whether a name such as foo:type=Baz is an ordinary MBean or is handled by a JMXDomain.

A query on the containing MBeanserver will return all MBeans from the JMXDomain that match the query. In particular, queryNames(null, null) will return all MBeans including those from JMXDomain domains. On the other hand, a query will not include MBeans from a JMXNamespace unless the ObjectName pattern in the query starts with the name of that namespace.

Permission checks

When a JMXDomain MBean is registered in a containing MBean server created through the default MBeanServerBuilder, and if a SecurityManager is present, the containing MBeanServer will check an MBeanPermission before invoking any method on the source MBeanServer of the JMXDomain.

First, if there is no security manager (System.getSecurityManager() is null), that containing MBeanServer is free not to make any checks.

Assuming that there is a security manager, or that the implementation chooses to make checks anyway, the containing MBeanServer will perform MBeanPermission checks for access to the MBeans in domain X handled by a JMXDomain in the same way that it would do for MBeans registered in its own local repository, and as described in the MBeanServer interface, with the following exceptions:

For those permissions that require a className, the className is the string returned by getSourceServer(). getObjectInstance(mbeanName). getClassName(), except for createMBean and registerMBean operations, for which the permission checks are performed as follows:

• For createMBean operations, the className of the permission you need is the className passed as first parameter to createMBean.

• For registerMBean operations, the className of the permission you need is the name of the class of the mbean object, as returned by mbean.getClass().getClassName(), where mbean is the mbean reference passed as first parameter to registerMBean.

• In addition, for createMBean and registerMBean, the permission you need is checked with the object name of the mbean that is passed as second parameter to the createMBean or registerMBean operation.

• Contrarily to what is done for regular MBeans registered in the MBeanServer local repository, the containing MBeanServer will not check the MBeanTrustPermission("register") against the protection domain of the MBean's class. This check can be performed by the source MBean server implementation, if necessary.

If a security check fails, the method throws SecurityException.

For methods that can throw InstanceNotFoundException, this exception is thrown for a non-existent MBean, regardless of permissions. This is because a non-existent MBean has no className.

All these checks are performed by the containing MBeanServer, before accessing the JMXDomain source MBean server. The implementation of the JMXDomain source MBean server is free to make any additional checks. In fact, if the JMXDomain source MBean server is an MBeanServer obtained through the MBeanServerFactory, it will again make permission checks as described in the MBeanServer interface.

See the MBeanServer interface for more details on permission checks.

Since:

1.7

Field Summary

Modifier and Type	Field and Description
static String	TYPE This constant contains the value of the type key used in defining a standard JMXDomain MBean object name.
static String	TYPE_ASSIGNMENT This constant contains the value of the standard key property list string for JMXDomain MBean object names.

Constructor and Description

JMXDomain(MBeanServer virtualServer)
Creates a new instance of JMXDomain.

Method Summary

Modifier and Type	Method and Description
void	addMBeanServerNotificationListener(NotificationListener listener, NotificationFilter filter) This method is called by the JMX framework to register a NotificationListener that will forward mbean server notifications through the delegate of the containing MBeanServer.
String	getDefaultDomain() Return the name of domain handled by this JMXDomain.
static ObjectName	getDomainObjectName(String domain) Return a canonical handler name for the provided local domain name, or null if the provided domain name is null.
String[]	getDomains() Returns a singleton array, containing the only domain handled by this JMXDomain object.
Integer	getMBeanCount() This method returns the number of MBeans in the domain handled by this JMXDomain object.
void	removeMBeanServerNotificationListener(NotificationListener listener) This method is called by the JMX framework to remove the NotificationListener that was added with addMBeanServerNotificationListener.

Methods inherited from class javax.management.namespace.JMXNamespace

getMBeanServer, getObjectName, getSourceServer, getUUID, postDeregister, postRegister, preDeregister, preRegister

Methods inherited from class java.lang.Object

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

Field Detail

TYPE

public static final String TYPE

This constant contains the value of the type key used in defining a standard JMXDomain MBean object name. By definition, a standard JMXDomain MBean object name must be of the form:

 "<domain>:"+"type=JMXDomain"
 

See Also:

Constant Field Values

TYPE_ASSIGNMENT

public static final String TYPE_ASSIGNMENT

This constant contains the value of the standard key property list string for JMXDomain MBean object names. By definition, a standard JMXDomain MBean object name must be of the form:

 <domain>+":"+"type=JMXDomain"
 

See Also:

Constant Field Values

Constructor Detail

JMXDomain

public JMXDomain(MBeanServer virtualServer)

Creates a new instance of JMXDomain. The MBeans contained in this domain are handled by the virtualServer object given to this constructor. Frequently, this will be an instance of MBeanServerSupport.

Parameters:

virtualServer - The virtual server that acts as a container for the MBeans handled by this JMXDomain object. Frequently, this will be an instance of MBeanServerSupport

See Also:

JMXNamespace.JMXNamespace(MBeanServer)

Method Detail

getDefaultDomain

public final String getDefaultDomain()

Return the name of domain handled by this JMXDomain.

Specified by:

getDefaultDomain in interface JMXNamespaceMBean

Overrides:

getDefaultDomain in class JMXNamespace

Returns:

the domain handled by this JMXDomain.

Throws:

IOException - - if the domain cannot be determined, for instance, if the MBean is not registered yet.

See Also:

MBeanServerConnection.getDefaultDomain

getDomains

public final String[] getDomains()

Returns a singleton array, containing the only domain handled by this JMXDomain object. This is new String[] {getDefaultDomain()}.

Specified by:

getDomains in interface JMXNamespaceMBean

Overrides:

getDomains in class JMXNamespace

Returns:

the only domain handled by this JMXDomain.

Throws:

IOException - if the domain cannot be determined, for instance, if the MBean is not registered yet.

See Also:

getDefaultDomain()

getMBeanCount

public Integer getMBeanCount()

This method returns the number of MBeans in the domain handled by this JMXDomain object. The default implementation is:

    getSourceServer().queryNames(
        new ObjectName(getObjectName().getDomain()+":*"), null).size();
 

If this JMXDomain is not yet registered, this method returns 0. Subclasses can override the above behavior and provide a better implementation.

The getMBeanCount() method is called when computing the number of MBeans in the containing MBeanServer.

Specified by:

getMBeanCount in interface JMXNamespaceMBean

Overrides:

getMBeanCount in class JMXNamespace

Returns:

the number of MBeans in this domain, or 0.

See Also:

MBeanServerConnection.getMBeanCount

getDomainObjectName

public static ObjectName getDomainObjectName(String domain)

Return a canonical handler name for the provided local domain name, or null if the provided domain name is null. If not null, the handler name returned will be domain+":type="+TYPE, for example foo:type=JMXDomain.

Parameters:

domain - A domain name

Returns:

a canonical ObjectName for a domain handler.

Throws:

IllegalArgumentException - if the provided domain is not valid - e.g it contains "//".

addMBeanServerNotificationListener

public void addMBeanServerNotificationListener(NotificationListener listener,
                                               NotificationFilter filter)

This method is called by the JMX framework to register a NotificationListener that will forward mbean server notifications through the delegate of the containing MBeanServer. The default implementation of this method is to call

    getSourceServer().addNotificationListener(
           MBeanServerDelegate.DELEGATE_NAME, listener, filter, null);
 

Subclasses can redefine this behavior if needed. In particular, subclasses can send their own instances of MBeanServerNotification by calling listener.handleNotification().

Parameters:

listener - The MBeanServerNotification listener for this domain.

filter - A notification filter.

removeMBeanServerNotificationListener

public void removeMBeanServerNotificationListener(NotificationListener listener)
                                           throws ListenerNotFoundException

This method is called by the JMX framework to remove the NotificationListener that was added with addMBeanServerNotificationListener. The default implementation of this method is to call

    getSourceServer().removeNotificationListener(
           MBeanServerDelegate.DELEGATE_NAME, listener);
 

Subclasses can redefine this behavior if needed.

Parameters:

listener - The MBeanServerNotification listener for this domain.

Throws:

ListenerNotFoundException - if the listener is not found.