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

javax.management
Class MBeanServerFactory

java.lang.Object
  javax.management.MBeanServerFactory

public class MBeanServerFactory
extends Object

Provides MBean server references. There are no instances of this class.

Since JMX 1.2 this class makes it possible to replace the default MBeanServer implementation. This is done using the MBeanServerBuilder class. The class of the initial MBeanServerBuilder to be instantiated can be specified through the javax.management.builder.initial system property. The specified class must be a public subclass of MBeanServerBuilder, and must have a public empty constructor.

By default, if no value for that property is specified, an instance of javax.management.MBeanServerBuilder is created. Otherwise, the MBeanServerFactory attempts to load the specified class using Thread.currentThread().getContextClassLoader(), or if that is null, Class.forName(). Then it creates an initial instance of that Class using Class.newInstance(). If any checked exception is raised during this process (e.g. ClassNotFoundException, InstantiationException) the MBeanServerFactory will propagate this exception from within a RuntimeException.

The javax.management.builder.initial system property is consulted every time a new MBeanServer needs to be created, and the class pointed to by that property is loaded. If that class is different from that of the current MBeanServerBuilder, then a new MBeanServerBuilder is created. Otherwise, the MBeanServerFactory may create a new MBeanServerBuilder or reuse the current one.

If the class pointed to by the property cannot be loaded, or does not correspond to a valid subclass of MBeanServerBuilder then an exception is propagated, and no MBeanServer can be created until the javax.management.builder.initial system property is reset to valid value.

The MBeanServerBuilder makes it possible to wrap the MBeanServers returned by the default MBeanServerBuilder implementation, for the purpose of e.g. adding an additional security layer.

Since version 2.0 of the JMX API, when creating an MBeanServer, it is possible to specify an MBean Server name. To create an MBean Server with a name, the MBeanServerFactory provides two new methods:

• createNamedMBeanServer(mbeanServerName, defaultDomain): creates a named MBeanServer and keeps an internal reference to the created object. The MBeanServer can be later retrieved using findMBeanServer(mbeanServerId) or findMBeanServerByName(mbeanServerName), and can be released through releaseMBeanServer(mbeanServer).
• newNamedMBeanServer(mbeanServerName, defaultDomain): creates a named MBeanServer without keeping any internal reference to the named server.

The name of the MBeanServer is stored in the MBean Server delegate MBean and is embedded in its MBeanServerId attribute.

The name of the MBeanServer is particularly useful when MBean permissions are checked: it makes it possible to distinguish between an MBean named "X" in MBeanServer named "M1", and another MBean of the same name "X" in another MBeanServer named "M2".

When naming MBean servers it is recommended to use a name that starts with a Java package name. It is also recommended that the default domain and the MBeanServer name be the same.

Since:

1.5

Field Summary

Modifier and Type	Field and Description
static String	DEFAULT_MBEANSERVER_NAME The MBean Server name that will be checked by a permission you need when checking access to an MBean registered in an MBeanServer for which no MBeanServer name was specified.

Method Summary

Modifier and Type	Method and Description
static MBeanServer	createMBeanServer() Return a new object implementing the MBeanServer interface with a standard default domain name.
static MBeanServer	createMBeanServer(String domain) Return a new object implementing the MBeanServer interface with the specified default domain name.
static MBeanServer	createNamedMBeanServer(String mbeanServerName, String domain) Return a new object implementing the MBeanServer interface with the specified MBean Server name and default domain name.
static ArrayList<MBeanServer>	findMBeanServer(String agentId) Return a list of registered MBeanServer objects.
static List<MBeanServer>	findMBeanServerByName(String mbeanServerName) Returns a list of registered MBeanServer objects with the given name.
static ClassLoaderRepository	getClassLoaderRepository(MBeanServer server) Return the ClassLoaderRepository used by the given MBeanServer.
static String	getMBeanServerName(MBeanServer server) Returns the name of the MBeanServer embedded in the MBeanServerId of the given server.
static MBeanServer	newMBeanServer() Return a new object implementing the MBeanServer interface with a standard default domain name, without keeping an internal reference to this new object.
static MBeanServer	newMBeanServer(String domain) Return a new object implementing the MBeanServer interface with the specified default domain name, without keeping an internal reference to this new object.
static MBeanServer	newNamedMBeanServer(String mbeanServerName, String domain) Return a new object implementing the MBeanServer interface with the specified MBean server name and default domain name, without keeping an internal reference to this new object.
static void	releaseMBeanServer(MBeanServer mbeanServer) Remove internal MBeanServerFactory references to a created MBeanServer.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MBEANSERVER_NAME

public static final String DEFAULT_MBEANSERVER_NAME

The MBean Server name that will be checked by a permission you need when checking access to an MBean registered in an MBeanServer for which no MBeanServer name was specified.

Since:

1.7

See Also:

Constant Field Values

Method Detail

releaseMBeanServer

public static void releaseMBeanServer(MBeanServer mbeanServer)

Remove internal MBeanServerFactory references to a created MBeanServer. This allows the garbage collector to remove the MBeanServer object.

Parameters:

mbeanServer - the MBeanServer object to remove.

Throws:

IllegalArgumentException - if mbeanServer was not generated by one of the createMBeanServer methods, or if releaseMBeanServer was already called on it.

SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("releaseMBeanServer").

createMBeanServer

public static MBeanServer createMBeanServer()

Return a new object implementing the MBeanServer interface with a standard default domain name. The default domain name is used as the domain part in the ObjectName of MBeans when the domain is specified by the user is null.

The standard default domain name is DefaultDomain.

The MBeanServer reference is internally kept. This will allow findMBeanServer to return a reference to this MBeanServer object.

This method is equivalent to createMBeanServer(null).

Returns:

the newly created MBeanServer.

Throws:

SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("createMBeanServer").

JMRuntimeException - if the property javax.management.builder.initial exists but the class it names cannot be instantiated through a public no-argument constructor; or if the instantiated builder returns null from its newMBeanServerDelegate or newMBeanServer methods.

ClassCastException - if the property javax.management.builder.initial exists and can be instantiated but is not assignment compatible with MBeanServerBuilder.

createMBeanServer

public static MBeanServer createMBeanServer(String domain)

Return a new object implementing the MBeanServer interface with the specified default domain name. The given domain name is used as the domain part in the ObjectName of MBeans when the domain is specified by the user is null.

The MBeanServer reference is internally kept. This will allow findMBeanServer to return a reference to this MBeanServer object.

Parameters:

domain - the default domain name for the created MBeanServer. This is the value that will be returned by MBeanServer.getDefaultDomain().

Returns:

the newly created MBeanServer.

Throws:

SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("createMBeanServer").

JMRuntimeException - if the property javax.management.builder.initial exists but the class it names cannot be instantiated through a public no-argument constructor; or if the instantiated builder returns null from its newMBeanServerDelegate or newMBeanServer methods.

ClassCastException - if the property javax.management.builder.initial exists and can be instantiated but is not assignment compatible with MBeanServerBuilder.

See Also:

createNamedMBeanServer(java.lang.String, java.lang.String)

createNamedMBeanServer

public static MBeanServer createNamedMBeanServer(String mbeanServerName,
                                                 String domain)

Return a new object implementing the MBeanServer interface with the specified MBean Server name and default domain name. The given MBean server name is used in security checks, and can also be used to find an MBeanServer by name. The given domain name is used as the domain part in the ObjectName of MBeans when the domain is specified by the user is null.

The MBeanServer reference is internally kept. This will allow findMBeanServer to return a reference to this MBeanServer object.

Parameters:

mbeanServerName - the name for the created MBeanServer. This is the name that will be included in the permission you need when checking MBean Permissions for accessing an MBean registered in the returned MBeanServer. The characters ':' (colon), ';' (semicolon), '*' (star) and '?' are not legal. It is recommended that the mbeanServerName be unique in the context of a JVM, and in the form of a java package identifier. If mbeanServerName is null then the created MBean Server has no name - and "default" is used. Calling createNamedMBeanServer(null,domain) is equivalent to calling createMBeanServer(domain).

domain - the default domain name for the created MBeanServer. This is the value that will be returned by MBeanServer.getDefaultDomain(). If a non null mbeanServerName is given, it is recommended to pass the same value as default domain.

Returns:

the newly created MBeanServer.

Throws:

SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("createMBeanServer").

JMRuntimeException - if the property javax.management.builder.initial exists but the class it names cannot be instantiated through a public no-argument constructor; or if the instantiated builder returns null from its newMBeanServerDelegate or newMBeanServer methods.

ClassCastException - if the property javax.management.builder.initial exists and can be instantiated but is not assignment compatible with MBeanServerBuilder.

IllegalArgumentException - if the specified mbeanServerName is empty, or is "-", or contains a character which is not legal.

UnsupportedOperationException - if the specified mbeanServerName cannot be set.

Since:

1.7

newMBeanServer

public static MBeanServer newMBeanServer()

Return a new object implementing the MBeanServer interface with a standard default domain name, without keeping an internal reference to this new object. The default domain name is used as the domain part in the ObjectName of MBeans when the domain is specified by the user is null.

The standard default domain name is DefaultDomain.

No reference is kept. findMBeanServer will not be able to return a reference to this MBeanServer object, but the garbage collector will be able to remove the MBeanServer object when it is no longer referenced.

This method is equivalent to newMBeanServer(null).

Returns:

the newly created MBeanServer.

Throws:

SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("newMBeanServer").

JMRuntimeException - if the property javax.management.builder.initial exists but the class it names cannot be instantiated through a public no-argument constructor; or if the instantiated builder returns null from its newMBeanServerDelegate or newMBeanServer methods.

ClassCastException - if the property javax.management.builder.initial exists and can be instantiated but is not assignment compatible with MBeanServerBuilder.

newMBeanServer

public static MBeanServer newMBeanServer(String domain)

Return a new object implementing the MBeanServer interface with the specified default domain name, without keeping an internal reference to this new object. The given domain name is used as the domain part in the ObjectName of MBeans when the domain is specified by the user is null.

No reference is kept. findMBeanServer will not be able to return a reference to this MBeanServer object, but the garbage collector will be able to remove the MBeanServer object when it is no longer referenced.

Parameters:

domain - the default domain name for the created MBeanServer. This is the value that will be returned by MBeanServer.getDefaultDomain().

Returns:

the newly created MBeanServer.

Throws:

SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("newMBeanServer").

JMRuntimeException - if the property javax.management.builder.initial exists but the class it names cannot be instantiated through a public no-argument constructor; or if the instantiated builder returns null from its newMBeanServerDelegate or newMBeanServer methods.

ClassCastException - if the property javax.management.builder.initial exists and can be instantiated but is not assignment compatible with MBeanServerBuilder.

newNamedMBeanServer

public static MBeanServer newNamedMBeanServer(String mbeanServerName,
                                              String domain)

Return a new object implementing the MBeanServer interface with the specified MBean server name and default domain name, without keeping an internal reference to this new object. The given MBean server name is used in security checks. The given domain name is used as the domain part in the ObjectName of MBeans when the domain is specified by the user is null.

No reference is kept. findMBeanServer and findMBeanServerByName will not be able to return a reference to this MBeanServer object, but the garbage collector will be able to remove the MBeanServer object when it is no longer referenced.

Parameters:

mbeanServerName - the name for the created MBeanServer. This is the name that will be included in the permission you need when checking MBean Permissions for accessing an MBean registered in the returned MBeanServer. The characters ':' (colon), ';' (semicolon), '*' (star) and '?' are not legal. It is recommended that the mbeanServerName be unique in the context of a JVM, and in the form of a java package identifier. If mbeanServerName is null then the created MBean Server has no name - and "default" is used. Calling newNamedMBeanServer(null,domain) is equivalent to calling newMBeanServer(domain).

domain - the default domain name for the created MBeanServer. This is the value that will be returned by MBeanServer.getDefaultDomain().

Returns:

the newly created MBeanServer.

Throws:

SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("newMBeanServer").

JMRuntimeException - if the property javax.management.builder.initial exists but the class it names cannot be instantiated through a public no-argument constructor; or if the instantiated builder returns null from its newMBeanServerDelegate or newMBeanServer methods.

ClassCastException - if the property javax.management.builder.initial exists and can be instantiated but is not assignment compatible with MBeanServerBuilder.

IllegalArgumentException - if the specified mbeanServerName is empty, or is "-", or contains a character which is not legal.

UnsupportedOperationException - if the specified mbeanServerName cannot be set.

Since:

1.7

findMBeanServer

public static ArrayList<MBeanServer> findMBeanServer(String agentId)

Return a list of registered MBeanServer objects. A registered MBeanServer object is one that was created by one of the createMBeanServer methods and not subsequently released with releaseMBeanServer.

Parameters:

agentId - The agent identifier of the MBeanServer to retrieve. If this parameter is null, all registered MBeanServers in this JVM are returned. Otherwise, only MBeanServers whose id is equal to agentId are returned. The id of an MBeanServer is the MBeanServerId attribute of its delegate MBean.

Returns:

A list of MBeanServer objects.

Throws:

SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("findMBeanServer").

findMBeanServerByName

public static List<MBeanServer> findMBeanServerByName(String mbeanServerName)

Returns a list of registered MBeanServer objects with the given name. A registered MBeanServer object is one that was created by one of the createMBeanServer or createNamedMBeanServer methods and not subsequently released with releaseMBeanServer.

See the section about MBean Server names above.

Parameters:

mbeanServerName - The name of the MBeanServer to retrieve. If this parameter is null, all registered MBeanServers in this JVM are returned. Otherwise, only those MBeanServers that have a name matching mbeanServerName are returned: this parameter can be a pattern, where '*' matches any sequence of characters and '?' matches any character.
The name of an MBeanServer, if specified, is embedded in the MBeanServerId attribute of its delegate MBean: this method will parse the MBeanServerId to get the MBeanServer name. If this parameter is equal to "*" then all registered MBeanServers in this JVM are returned, whether they have a name or not: findMBeanServerByName(null), findMBeanServerByName("*") and findMBeanServer(null), are equivalent. It is also possible to get all MBeanServers for which no name was specified by calling findMBeanServerByName("default").

Returns:

A list of MBeanServer objects.

Throws:

SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanServerPermission("findMBeanServer").

Since:

1.7

See Also:

getMBeanServerName(MBeanServer)

getMBeanServerName

public static String getMBeanServerName(MBeanServer server)

Returns the name of the MBeanServer embedded in the MBeanServerId of the given server. If the given MBeanServerId doesn't contain any name, "default" is returned. The MBeanServerId is expected to be of the form: *[;mbeanServerName=<mbeanServerName>[;*]]
where * denotes any sequence of characters, and [ ] indicate optional parts.

For instance, if an MBeanServer is created using server = MBeanServerFactory.createNamedMBeanServer("com.mycompany.myapp.server1", null) then MBeanServerFactory.getMBeanServerName(server) will return "com.mycompany.myapp.server1" and server.getAttribute(MBeanServerDelegate.DELEGATE_NAME, "MBeanServerId") will return something like "myhost_1213353064145;mbeanServerName=com.mycompany.myapp.server1".

See the section about MBean Server names above.

Parameters:

server - A named (or unnamed) MBeanServer.

Returns:

the name of the MBeanServer if found, or "default" if no name is present in its MBeanServerId, or "*" if its MBeanServerId couldn't be obtained. Returning "*" means that only MBeanPermissions that allow all MBean Server names will apply to this MBean Server.

Since:

1.7

See Also:

MBeanServerDelegate

getClassLoaderRepository

public static ClassLoaderRepository getClassLoaderRepository(MBeanServer server)

Return the ClassLoaderRepository used by the given MBeanServer. This method is equivalent to server.getClassLoaderRepository().

Parameters:

server - The MBeanServer under examination. Since JMX 1.2, if server is null, the result is a NullPointerException. This behavior differs from what was implemented in JMX 1.1 - where the possibility to use null was deprecated.

Returns:

The Class Loader Repository used by the given MBeanServer.

Throws:

SecurityException - if there is a SecurityManager and the caller's permissions do not include or imply MBeanPermission("getClassLoaderRepository").

NullPointerException - if server is null.