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

javax.management.namespace
Class JMXNamespace

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

All Implemented Interfaces:

MBeanRegistration, JMXNamespaceMBean

Direct Known Subclasses:

JMXDomain, JMXRemoteNamespace

public class JMXNamespace
extends Object
implements JMXNamespaceMBean, MBeanRegistration

MBean Servers can be federated into a single hierarchical name space: A JMXNamespace is an MBean that handles a sub name space in that hierarchical name space.

A name space is created simply by registering a JMXNamespace MBean in the MBean Server. The name of the created name space is defined by the name of the JMXNamespace that handles it. A name space is equivalent to an MBean Server within an MBean Server. When creating a JMXNamespace, the MBean Server within is passed to the constructor.

The JMXNamespace class is the base class for implementing all name space handlers. All name space handlers must be instances of JMXNamespace or a subclass of it.

A concrete example of a JMXNamespace MBean subclass is the JMXRemoteNamespace MBean which is able to mirror all MBeans contained in a remote MBean server known by its JMXServiceURL.

You can create a local namespace by supplying a newly created MBean Server to an instance of JMXNamespace. For instance:

 final String namespace = "foo";
 final ObjectName namespaceName = JMXNamespaces.getNamespaceObjectName(namespace);
 server.registerMBean(new JMXNamespace(MBeanServerFactory.newMBeanServer()),
                      namespaceName);
 

Note: A JMXNamespace MBean cannot be registered simultaneously in two different MBean servers, or indeed in the same MBean Server with two different names. It is however possible to give the same MBeanServer instance to two different JMXNamespace MBeans, and thus create a graph rather than a tree.

To view the content of a namespace, you will usually use an instance of JMXNamespaceView. For instance, given the namespace "foo" created above, you would do:

 final JMXNamespaceView view = new JMXNamespaceView(server);
 System.out.println("List of namespaces: "+Arrays.toString(view.list()));

 final JMXNamespaceView foo  = view.down("foo");
 System.out.println(foo.where()+" contains: " +
        foo.getMBeanServerConnection().queryNames(null,null));
 

JMX Namespace Permission Checks

A special JMXNamespacePermission is defined to check access to MBean within namespaces.

When a JMXNamespace MBean is registered in an MBean server created through the default MBeanServerBuilder, and if a SecurityManager is present, the MBeanServer will check a JMXNamespacePermission before invoking any method on the source MBeanServer of the JMXNamespace. JMX Namespace Permissions are similar to MBean Permissions, except that you usually cannot specify an MBean class name. You can however specify object name patterns - which will allow you for example to only grant permissions for MBeans having a specific type=<MBeanType> key in their object name.

Another difference is that JMXNamespacePermission also specifies from which namespace and which MBean server the permission is granted.

In the rest of this document, the following terms are used:

• server name is the name of the MBeanServer in which the permission is granted. The name of an MBeanServer can be obtained by calling MBeanServerFactory.getMBeanServerName(mbeanServer)

• namespace is the name of the namespace in the named MBean server for which the permission is granted. It doesn't contain any namespace separator.

• mbean is the name of the MBean in that namespace. This is the name of the MBean in the namespace's source mbean server. It might contain no, one, or several namespace separators.

For instance let's assume that some piece of code calls:

     final MBeanServer mbeanServer = ...;
     final ObjectName  name   = new ObjectName("a//b//c//D:k=v");
     mbeanServer.getAttribute(name,"Foo");
 

Assuming that there is a security manager, or that the implementation chooses to make checks anyway, the checks that will be made in that case are:

1. JMXNamespacePermission(mbeanServerName, "Foo", "a//b//c//D:k=v", "getAttribute") (where mbeanServerName=MBeanServerFactory.getMBeanServerName(mbeanServer), namespace="a", and mbean="b//c//D:k=v")
2. and in addition if namespace "a" is local, JMXNamespacePermission(aSourceServerName,"Foo","b//c//D:k=v", "getAttribute")} (where aSourceServerName=MBeanServerFactory.getMBeanServerName(sourceServer(a)), namespace="b", and mbean="c//D:k=v"),
3. and in addition if namespace "b" is also local, JMXNamespacePermission(bSourceServerName,"Foo","c//D:k=v", "getAttribute")} (where bSourceServerName=MBeanServerFactory.getMBeanServerName(sourceServer(b)), namespace="c", and mbean="D:k=v"),
4. and in addition if the source mbean server of namespace "c" is a also a local MBeanServer in this JVM, MBeanPermission(cSourceServerName,<className(D:k=v)>,"Foo","D:k=v","getAttrinute"), (where cSourceServerName=MBeanServerFactory.getMBeanServerName(sourceServer(c))).

For any of these MBean servers, if no name was supplied when creating that MBeanServer the JMXNamespacePermission is created with an mbeanServerName equal to "default".

If the namespace a is in fact a remote MBeanServer, for instance because namespace a is implemented by a JMXRemoteNamespace pointing to a distant MBeanServer located in another JMX agent, then checks 2, 3, and 4 will not be performed in the local JVM. They might or might not be performed in the remote agent, depending on how access control and permission checking are configured in the remote agent, and how authentication is configured in the connector used by the JMXRemoteNamespace.

In all cases, JMX Namespace Permissions are checked as follows:

First, if there is no security manager (System.getSecurityManager() is null), then an implementation of of MBeanServer that supports JMX namespaces is free not to make any checks.

Assuming that there is a security manager, or that the implementation chooses to make checks anyway, the checks are made as detailed below.

If a security check fails, the method throws SecurityException.

• For the invoke method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, <operation name>, <namespace>//<mbean>, "invoke"), where mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which the action is performed, in that namespace.

• For the getAttribute method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, <attribute>, <namespace>//<mbean>, "getAttribute").

• For the getAttributes method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, <null>, <namespace>//<mbean>, "getAttribute"), where mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which the action is performed, in that namespace. Additionally, for each attribute att in the AttributeList, if the caller's permissions do not imply JMXNamespacePermission(<mbean server name>, att, <namespace>//<mbean>, "getAttribute"), the MBean server will behave as if that attribute had not been in the supplied list.

• For the setAttribute method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, <attrName>, <namespace>//<mbean>, "setAttribute"), where mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which the action is performed, in that namespace, and attrName is attribute.getName().

• For the setAttributes method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, null, <namespace>//<mbean>, "setAttribute"), where mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which the action is performed, in that namespace. Additionally, for each attribute att in the AttributeList, if the caller's permissions do not imply JMXNamespacePermission(<mbean server name>, att, <namespace>//<mbean>, "setAttribute"), the MBean server will behave as if that attribute had not been in the supplied list.

• For the addNotificationListener methods, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, null, <namespace>//<mbean>, "addNotificationListener"), where mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which the action is performed, in that namespace.

• For the removeNotificationListener methods, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, null, <namespace>//<mbean>, "removeNotificationListener"), where mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which the action is performed, in that namespace.

• For the getMBeanInfo method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, null, <namespace>//<mbean>, "getMBeanInfo"), where mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which the action is performed, in that namespace.

• For the getObjectInstance method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, null, <namespace>//<mbean>, "getObjectInstance"), where mbean server name/a> is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which the action is performed, in that namespace.

• For the isInstanceOf method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, null, <namespace>//<mbean>, "isInstanceOf"), where mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which the action is performed, in that namespace.

• For the queryMBeans method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, null, null, "queryMBeans"). Additionally, for each MBean mbean that matches pattern, if the caller's permissions do not imply JMXNamespacePermission(<mbean server name>, null, <namespace>//<mbean>, "queryMBeans"), the MBean server will behave as if that MBean did not exist.

  Certain query elements perform operations on the MBean server. However these operations are usually performed by the MBeanServer at the bottom of the namespace path, and therefore, do not involve any JMXNamespacePermission permission check. They might involve MBeanPermission checks depending on how security in the JVM in which the bottom MBeanServer resides is implemented. See MBeanServer for more details.

• For the queryNames method, the checks are the same as for queryMBeans except that "queryNames" is used instead of "queryMBeans" in the JMXNamespacePermission objects. Note that a "queryMBeans" permission implies the corresponding "queryNames" permission.

• For the getClassLoader method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, null, <namespace>//<loaderName>, "getClassLoader"), where mbean server name/a> is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and loaderName is the name of the ClassLoader MBean which is accessed, in that namespace.

• For the getClassLoaderFor method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, null, <namespace>//<mbean>, "getClassLoaderFor"), where mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which the action is performed, in that namespace.

• For the registerMBean method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, <class name>, <namespace>//<mbean>, "registerMBean"). Here class name is the string returned by obj.getClass().getName() where obj is the mbean reference, is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean which is being registered, relative to that namespace.

• For the createMBean methods, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, <class name>, <namespace>//<mbean>, "instantiate") and JMXNamespacePermission#JMXNamespacePermission(String,String,ObjectName,String) JMXNamespacePermission(<mbean server name>, <class name>, <namespace>//<mbean>, "registerMBean")}, where class name is the string passed as first argument to the createMBean method, mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean which is being created, relative to that namespace.

• For the unregisterMBean method, the caller's permissions must imply JMXNamespacePermission(<mbean server name>, null, <namespace>//<mbean>, "unregisterMBean"), where mbean server name is the name of the MBeanServer in which the JMXNamespace MBean in charge of namespace is registered, and mbean is the name of the MBean on which is being unregistered, relative to that namespace.

It must be noted that if all namespaces are local, and all local namespaces are implemented by regular MBean servers, that is, there are no Virtual Namespaces, then simple MBean Permission checks might be enough to secure an application. In that case, it is possible to specify the following JMXNamespacePermission permission in the policy file, which implies all other JMX namespace permissions:

     permission javax.management.namespace.JMXNamespacePermission "*::*[]", "*";
 

Since:

1.7

Field Summary

Modifier and Type	Field and Description
static String	TYPE The standard value of the type property key that must be used to construct valid JMXNamespaceMBean ObjectNames. This is "JMXNamespace".
static String	TYPE_ASSIGNMENT The keyPropertyListString that must be used to construct valid JMXNamespaceMBean ObjectNames. This is "type=JMXNamespace".

Constructor and Description

JMXNamespace(MBeanServer sourceServer)
Creates a new JMXNamespace implemented by means of an MBean Server.

Method Summary

Modifier and Type	Method and Description
String	getDefaultDomain() In this class, this method returns getSourceServer().getDefaultDomain().
String[]	getDomains() In this class, this method returns getSourceServer().getDomains().
Integer	getMBeanCount() In this class, this method returns getSourceServer().getMBeanCount().
MBeanServer	getMBeanServer() Returns the MBeanServer in which this MBean is registered, or null.
ObjectName	getObjectName() Returns the ObjectName with which this MBean was registered, or null.
MBeanServer	getSourceServer() Returns the MBeanServer that contains or emulates the source namespace.
String	getUUID() Returns a UUID string which uniquely identifies this JMXNamespace MBean.
void	postDeregister() This method is part of the MBeanRegistration interface.
void	postRegister(Boolean registrationDone) This method is part of the MBeanRegistration interface.
void	preDeregister() This method is part of the MBeanRegistration interface.
ObjectName	preRegister(MBeanServer server, ObjectName name) This method is part of the MBeanRegistration interface.

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

The standard value of the type property key that must be used to construct valid JMXNamespaceMBean ObjectNames.
This is "JMXNamespace".

See Also:

Constant Field Values

TYPE_ASSIGNMENT

public static final String TYPE_ASSIGNMENT

The keyPropertyListString that must be used to construct valid JMXNamespaceMBean ObjectNames.
This is "type=JMXNamespace".

See Also:

Constant Field Values

Constructor Detail

JMXNamespace

public JMXNamespace(MBeanServer sourceServer)

Creates a new JMXNamespace implemented by means of an MBean Server. A namespace is equivalent to an MBeanServer within an MBean Server. The sourceServer provided to this constructor is the MBean Server within.

Parameters:

sourceServer - the MBean server that implemented by this namespace.

See Also:

getSourceServer()

Method Detail

preRegister

public ObjectName preRegister(MBeanServer server,
                              ObjectName name)
                       throws Exception

This method is part of the MBeanRegistration interface. The JMXNamespace class uses the MBeanRegistration interface in order to get a reference to the MBean server in which it is registered. It also checks the validity of its own ObjectName.

This method is called by the MBean server. Application classes should never call this method directly.

If this method is overridden, the overriding method should call super.preRegister(server,name).

Specified by:

preRegister in interface MBeanRegistration

Parameters:

name - The object name of the MBean. name must be a syntactically valid JMXNamespace name, as returned by getNamespaceObjectName(namespace).

server - The MBean Server in which the MBean will be registered.

Returns:

The name under which the MBean is to be registered.

Throws:

IllegalArgumentException - if the name supplied is not valid.

Exception - can be thrown by subclasses.

See Also:

MBeanRegistration, getNamespaceObjectName

postRegister

public void postRegister(Boolean registrationDone)

This method is part of the MBeanRegistration interface. The JMXNamespace class uses the MBeanRegistration interface in order to get a reference to the MBean server in which it is registered.

This method is called by the MBean server. Application classes should not call this method directly. Subclasses are free to override this method with their own specific behavior - but the overriding method shoud still call super.postRegister(registrationDone).

Specified by:

postRegister in interface MBeanRegistration

Parameters:

registrationDone - Indicates whether or not the MBean has been successfully registered in the MBean server. The value false means that the registration phase has failed.

See Also:

MBeanRegistration

preDeregister

public void preDeregister()
                   throws Exception

This method is part of the MBeanRegistration interface. The JMXNamespace class uses the MBeanRegistration interface in order to get a reference to the MBean server in which it is registered.

This method is called by the MBean server. Application classes should not call this method directly. Subclasses are free to override this method with their own specific behavior - but the overriding method shoud still call super.preDeregister().

Specified by:

preDeregister in interface MBeanRegistration

Throws:

Exception - This exception will be caught by the MBean server and re-thrown as an MBeanRegistrationException.

See Also:

MBeanRegistration

postDeregister

public void postDeregister()

This method is part of the MBeanRegistration interface. It allows the JMXNamespace MBean to perform any operations needed after having been unregistered in the MBean server.

This method is called by the MBean server. Application classes should not call this method directly. If a subclass overrides this method, the overriding method shoud call super.postDeregister().

Specified by:

postDeregister in interface MBeanRegistration

See Also:

MBeanRegistration

getMBeanServer

public final MBeanServer getMBeanServer()

Returns the MBeanServer in which this MBean is registered, or null. Chiefly of interest for subclasses.

Returns:

the MBeanServer supplied to preRegister(javax.management.MBeanServer, javax.management.ObjectName).

getSourceServer

public MBeanServer getSourceServer()

Returns the MBeanServer that contains or emulates the source namespace. When a JMXNamespace MBean is registered in an MBean server created through the default MBeanServerBuilder, the MBeanServer will check JMXNamespacePermission before invoking any method on the source MBeanServer of the JMXNamespace. See JMX Namespace Permission Checks above.

Returns:

an MBeanServer view of the source namespace

getObjectName

public final ObjectName getObjectName()

Returns the ObjectName with which this MBean was registered, or null. Chiefly of interest for subclasses.

Returns:

the ObjectName supplied to preRegister(javax.management.MBeanServer, javax.management.ObjectName).

getMBeanCount

public Integer getMBeanCount()
                      throws IOException

In this class, this method returns getSourceServer().getMBeanCount().
This default behaviour may be redefined in subclasses.

Specified by:

getMBeanCount in interface JMXNamespaceMBean

Returns:

the number of MBeans registered in the name space handled by this JMXNamespace.

Throws:

IOException - can be thrown by subclasses.

See Also:

MBeanServerConnection.getMBeanCount

getDomains

public String[] getDomains()
                    throws IOException

In this class, this method returns getSourceServer().getDomains().
This default behaviour may be redefined in subclasses.

Specified by:

getDomains in interface JMXNamespaceMBean

Returns:

the list of domains currently implemented in the name space handled by this JMXNamespace.

Throws:

IOException - can be thrown by subclasses.

See Also:

MBeanServerConnection.getDomains

getDefaultDomain

public String getDefaultDomain()
                        throws IOException

In this class, this method returns getSourceServer().getDefaultDomain().
This default behaviour may be redefined in subclasses.

Specified by:

getDefaultDomain in interface JMXNamespaceMBean

Returns:

the default domain for the name space handled by this JMXNamespace.

Throws:

IOException - can be thrown by subclasses.

See Also:

MBeanServerConnection.getDefaultDomain

getUUID

public final String getUUID()

Description copied from interface: JMXNamespaceMBean

Returns a UUID string which uniquely identifies this JMXNamespace MBean. This information can be used to detect loops in the JMX name space graph.

Specified by:

getUUID in interface JMXNamespaceMBean

Returns:

A unique ID identifying this MBean.