Class JMXUtils

java.lang.Object

org.tquadrat.foundation.mgmt.JMXUtils

@UtilityClass
@ClassVersion(sourceVersion="$Id: JMXUtils.java 1258 2026-06-04 18:33:06Z tquadrat $")
@API(status=STABLE,
     since="0.0.1")
public final class JMXUtils
extends Object

This class provides some utilities that are useful in the context of JMX.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: JMXUtils.java 1258 2026-06-04 18:33:06Z tquadrat $

Since:

0.0.1

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.mgmt.JMXUtils"

⁠

Field Summary

Fields

Modifier and Type	Field	Description
static final String	BIND_NAME	The JNDI name for the exposed MBeanServer: "jmxrmi"
static final String	CONNECTOR_ADDRESS	The property name for the connector address: "com.sun.management.jmxremote.localConnectorAddress".
static final String	JMX_DOMAIN	The name of the JMX domain that is used by all JMX enabled components of the library.
private static final Map<JMXServiceURL, JMXConnectorServer>	m_ConnectorServers	The JMXConnectorServer instance that expose an MBeanServer.
static final String	MBEAN_CLASS	The property name for the class of an MBean: "class".
static final String	MBEAN_FUNCTION	The property name for the function of an MBean: "function".
static final String	MBEAN_LOADER	The property name for the loader of an MBean: "loader".
static final String	MBEAN_NAME	The property name for the name of an MBean: "name".
static final String	MBEAN_TYPE	The property name for the MBean type: "type".

Constructor Summary

Constructors

Modifier	Constructor	Description
private	JMXUtils()	No instance allowed for this class.

Method Summary

Modifier and Type	Method	Description
static ObjectName	composeObjectName(String domainName, String type, String function, Class<?> mbeanClass, NameValuePair<String>... properties)	Composes an object name from the given domain name and the given properties.
static ObjectName	composeObjectName(String domainName, NameValuePair<String>... properties)	Composes an object name from the given domain name and the given properties.
static final JMXServiceURL	composeServiceURL(int registryPort)	Composes an instance of JMXServiceURL as ist is needed to expose an MBean server or to connect to an exposed MBean server.
static final JMXServiceURL	composeServiceURL(String hostName, int registryPort, int dataPort)	Composes an instance of JMXServiceURL as ist is needed to expose an MBean server or to connect to an exposed MBean server.
static final void	disableRemoteAccess(JMXServiceURL serviceURL)	Disables the external access to the MBeanServer for the given service URL.
static final JMXServiceURL	enableRemoteAccess(MBeanServer mbeanServer, int registryPortNumber, Map<String,?> environment)	Enables the external access to the MBeanServer from a process running on the same machine.
static final JMXServiceURL	enableRemoteAccess(MBeanServer mbeanServer, String hostName, int registryPortNumber, int dataPortNumber, Map<String,?> environment)	Makes the MBeanServer accessible for remote machines.
private static final void	enableRemoteAccess(MBeanServer mbeanServer, JMXServiceURL serviceURL, int registryPortNumber, Map<String,?> environment)	Enables the external access to the MBeanServer.
private static final void	startRMIRegistry(int port)	Ensures that an RMI registry is running for given the port.
private static final String	toString(NameValuePair<String> pair)	Converts an instance of NameValuePair to a String.
static void	unregisterQuietly(JMXSupport<?> mbean)	Unregisters the given MBean from the MBeanServer.

Methods inherited from class Object

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

Field Details

BIND_NAME

public static final String BIND_NAME

The JNDI name for the exposed MBeanServer: "jmxrmi"

See Also:

• enableRemoteAccess(MBeanServer,JMXServiceURL,int,Map)
• enableRemoteAccess(MBeanServer,int,Map)
• enableRemoteAccess(MBeanServer,String,int,int,Map)
• disableRemoteAccess(JMXServiceURL)
• Constant Field Values

CONNECTOR_ADDRESS

public static final String CONNECTOR_ADDRESS

The property name for the connector address: "com.sun.management.jmxremote.localConnectorAddress".

See Also:

• Constant Field Values

JMX_DOMAIN

public static final String JMX_DOMAIN

The name of the JMX domain that is used by all JMX enabled components of the library.

See Also:

• Constant Field Values

MBEAN_CLASS

public static final String MBEAN_CLASS

The property name for the class of an MBean: "class".

See Also:

• Constant Field Values

MBEAN_FUNCTION

public static final String MBEAN_FUNCTION

The property name for the function of an MBean: "function".

See Also:

• Constant Field Values

MBEAN_LOADER

public static final String MBEAN_LOADER

The property name for the loader of an MBean: "loader".

See Also:

• Constant Field Values

MBEAN_NAME

public static final String MBEAN_NAME

The property name for the name of an MBean: "name".

See Also:

• Constant Field Values

MBEAN_TYPE

public static final String MBEAN_TYPE

The property name for the MBean type: "type".

See Also:

• Constant Field Values

m_ConnectorServers

private static final Map<JMXServiceURL, JMXConnectorServer> m_ConnectorServers

The JMXConnectorServer instance that expose an MBeanServer.

See Also:

• enableRemoteAccess(MBeanServer,int,Map)

Constructor Details

JMXUtils

private JMXUtils()

No instance allowed for this class.

Method Details

composeObjectName

@SafeVarargs
@API(status=STABLE,
     since="0.0.1")
public static ObjectName composeObjectName(String domainName,
 String type,
 String function,
 Class<?> mbeanClass,
 NameValuePair<String>... properties)
                                    throws MalformedObjectNameException

Composes an object name from the given domain name and the given properties.

The object name has the form

    <Domain>:type=<Type>,function=<Function>[, class=<Class>][,…]

The type is something like a category.

The function is a description for what the MBean does.

The class can be provided, if multiple MBean implementations with the same type and function will be loaded.

Additional properties in the form <name>=<value> can be added as required.

Parameters:

domainName - The domain name.

type - The type of the MBean that will be named with the new object name.

function - The function of the MBean.

mbeanClass - The MBean's class; can be null.

properties - Additional properties as name-value-pairs; can be null.

Returns:

The object name.

Throws:

MalformedObjectNameException - It is not possible to create a valid object name from the given domain name and properties.

composeObjectName

@SafeVarargs
@API(status=STABLE,
     since="0.0.1")
public static ObjectName composeObjectName(String domainName,
 NameValuePair<String>... properties)
                                    throws MalformedObjectNameException

Composes an object name from the given domain name and the given properties.

Parameters:

domainName - The domain name.

properties - The properties as name-value-pairs; at least one property has to be provided.

Returns:

The object name.

Throws:

MalformedObjectNameException - It is not possible to create a valid object name from the given domain name and properties.

composeServiceURL

@API(status=STABLE,
     since="0.25.3")
public static final JMXServiceURL composeServiceURL(int registryPort)

Composes an instance of JMXServiceURL as ist is needed to expose an MBean server or to connect to an exposed MBean server.

This version creates a URL that can be used for local connections (both processes are running on the same machine).

Parameters:

registryPort - The number of the registry port.

Returns:

The service URL.

Since:

0.25.3

See Also:

• BIND_NAME

composeServiceURL

@API(status=STABLE,
     since="0.25.3")
public static final JMXServiceURL composeServiceURL(String hostName,
 int registryPort,
 int dataPort)
                                             throws MalformedURLException

Composes an instance of JMXServiceURL as ist is needed to expose an MBean server or to connect to an exposed MBean server.

This version creates a URL that can be used for remote connections (the processes are running on different machines).

Parameters:

hostName - The host name.

registryPort - The number of the registry port.

dataPort - The number of the data port; can be the same as the registry port.

Returns:

The service URL.

Throws:

MalformedURLException - It is not possible to compose a valid JMXServiceURL with the given hostName.

Since:

0.25.3

See Also:

• BIND_NAME

disableRemoteAccess

@API(status=STABLE,
     since="0.25.3")
public static final void disableRemoteAccess(JMXServiceURL serviceURL)
                                      throws IOException

Disables the external access to the MBeanServer for the given service URL. Nothing happens if there was no NBean server exposed that URL.

Internally, this method deactivates the connector server, that is, stops listening for client connections. Calling this method will also close all client connections that were made by this server. After this method returns, whether normally or with an exception, the connector server will not create any new client connections.

Once a connector server has been stopped, it cannot be started again.

Calling this method when the connector server has already been stopped has also no effect.

If closing a client connection produces an exception, that exception is not thrown from this method. A JMXConnectionNotification with type JMXConnectionNotification.FAILED is emitted from this MBean with the connection ID of the connection that could not be closed.

Closing a connector server is a potentially slow operation. For example, if a client machine with an open connection has crashed, the close operation might have to wait for a network protocol timeout. Callers that do not want to block in a close operation should do it in a separate thread.

This method works for both locally and remotely exposed connector servers.

Parameters:

serviceURL - The URL that is used to connect to the MBean server.

Throws:

IOException - The connection server cannot be closed cleanly. When this exception is thrown, the connection server has already attempted to close all client connections. All client connections are closed except possibly those that generated exceptions when the server attempted to close them.

Since:

0.25.3

enableRemoteAccess

@API(status=INTERNAL,
     since="0.25.3")
private static final void enableRemoteAccess(MBeanServer mbeanServer,
 JMXServiceURL serviceURL,
 int registryPortNumber,
 Map<String,?> environment)
                                      throws IllegalStateException,
IOException,
RemoteException

Enables the external access to the MBeanServer.

enableRemoteAccess(MBeanServer,String,int,int,Map) and enableRemoteAccess(MBeanServer,int,Map) are delegating to this method. See there for details.

Parameters:

mbeanServer - The MBean server that should be exposed.

serviceURL - The service URL.

registryPortNumber - The port number that is used for the registry connection.

environment - The configuration settings for the JMXConnectorServer.

Throws:

RemoteException - The RMI registry cannot be created/exported.

IOException - Failed to create the connection server.

IllegalStateException - The connection server was previously stopped and the attempt to restart it failed.

Since:

0.25.3

enableRemoteAccess

@API(status=STABLE,
     since="0.25.3")
public static final JMXServiceURL enableRemoteAccess(MBeanServer mbeanServer,
 int registryPortNumber,
 Map<String,?> environment)
                                              throws IllegalStateException,
IOException,
RemoteException

Enables the external access to the MBeanServer from a process running on the same machine.

Basically, this method creates a new instance of JMXConnectorServer, registers it to a JNDI registry associated with the given port number, and finally starts it.

If the registry does not exist yet, it will be created first.

The same MBean server can be multiple times, using this method or enableRemoteAccess(MBeanServer,String,int,int,Map), but the given port numbers must be different.

Parameters:

mbeanServer - The MBean server that should be exposed.

registryPortNumber - The port number that is used for the connection.

environment - The configuration settings for the JMXConnectorServer that is used to expose the MBean server. This parameter can be null, although it is recommended to use Map.of() in case no attributes should be provided. The keys in this map must be Strings. The appropriate type of each associated value depends on the attribute. The contents of environment are not changed by this call.

Returns:

The JMXServiceURL that was used to register the MBean server. It has the format service:jmx:rmi:///jndi/rmi://localhost:<port>/jmxrmi.

Throws:

RemoteException - The RMI registry cannot be created/exported.

IOException - Failed to create the connection server.

IllegalStateException - The connection server was previously stopped and the attempt to restart it failed.

Since:

0.25.3

See Also:

• BIND_NAME

enableRemoteAccess

@API(status=STABLE,
     since="0.25.3")
public static final JMXServiceURL enableRemoteAccess(MBeanServer mbeanServer,
 String hostName,
 int registryPortNumber,
 int dataPortNumber,
 Map<String,?> environment)
                                              throws IllegalStateException,
IOException,
RemoteException

Makes the MBeanServer accessible for remote machines.

Basically, this method creates a new instance of JMXConnectorServer, registers it to a JNDI registry associated with the given port number, and finally starts it.

If the registry does not exist yet, it will be created first.

The same MBean server can be multiple times, using this method or enableRemoteAccess(MBeanServer, int, Map), but the given port numbers must be different.

Parameters:

mbeanServer - The MBean server that should be exposed.

hostName - The host name that is used for the connection.

registryPortNumber - The port number that is used for the registry connection.

dataPortNumber - The port number that is used for the data transport.

environment - The configuration settings for the JMXConnectorServer that is used to expose the MBean server. This parameter can be null, although it is recommended to use Map.of() in case no attributes should be provided. The keys in this map must be Strings. The appropriate type of each associated value depends on the attribute. The contents of environment are not changed by this call.

Returns:

The JMXServiceURL that was used to register the MBean server. It has the format service:jmx:rmi://<host>:<dataPort>/jndi/rmi://<host>:<registryPort>/jmxrmi

Throws:

RemoteException - The RMI registry cannot be created/exported.

IOException - Failed to create the connection server.

IllegalStateException - The connection server was previously stopped and the attempt to restart it failed.

MalformedURLException - It is not possible to compose a valid JMXServiceURL with the given hostName.

Since:

0.25.3

See Also:

• BIND_NAME

startRMIRegistry

private static final void startRMIRegistry(int port)
                                    throws RemoteException

Ensures that an RMI registry is running for given the port. If there is no registry, a new one will be started.

Parameters:

port - The registry port.

Throws:

RemoteException - The registry cannot be created.

toString

private static final String toString(NameValuePair<String> pair)

Converts an instance of NameValuePair to a String.

Parameters:

pair - The name-value-pair.

Returns:

The String representation of the name-value-pair.

unregisterQuietly

@API(status=STABLE,
     since="0.0.1")
public static void unregisterQuietly(JMXSupport<?> mbean)

Unregisters the given MBean from the MBeanServer. All exceptions – if any – will be swallowed silently.

Parameters:

mbean - The mbean to unregister; may be null.