public class JMXConnectorFactory extends Object
Factory to create JMX API connector clients. There are no instances of this class.
Connections are usually made using the connect
method of this class. More advanced applications can separate the creation of the connector client, using newJMXConnector
and the establishment of the connection itself, using JMXConnector.connect(Map)
.
Each client is created by an instance of JMXConnectorProvider
. This instance is found as follows. Suppose the given JMXServiceURL
looks like "service:jmx:protocol:remainder"
. Then the factory will attempt to find the appropriate JMXConnectorProvider
for protocol
. Each occurrence of the character +
or -
in protocol
is replaced by .
or _
, respectively.
A provider package list is searched for as follows:
environment
parameter to newJMXConnector
contains the key jmx.remote.protocol.provider.pkgs
then the associated value is the provider package list. jmx.remote.protocol.provider.pkgs
exists, then its value is the provider package list. The provider package list is a string that is interpreted as a list of non-empty Java package names separated by vertical bars (|
). If the string is empty, then so is the provider package list. If the provider package list is not a String, or if it contains an element that is an empty string, a JMXProviderException
is thrown.
If the provider package list exists and is not empty, then for each element pkg
of the list, the factory will attempt to load the class
pkg.protocol.ClientProvider
If the environment
parameter to newJMXConnector
contains the key jmx.remote.protocol.provider.class.loader
then the associated value is the class loader to use to load the provider. If the associated value is not an instance of ClassLoader
, an IllegalArgumentException
is thrown.
If the jmx.remote.protocol.provider.class.loader
key is not present in the environment
parameter, the calling thread's context class loader is used.
If the attempt to load this class produces a ClassNotFoundException
, the search for a handler continues with the next element of the list.
Otherwise, a problem with the provider found is signalled by a JMXProviderException
whose cause
indicates the underlying exception, as follows:
ClassNotFoundException
, that is the cause; Class.newInstance()
for the class produces an exception, that is the cause. If no provider is found by the above steps, including the default case where there is no provider package list, then the implementation will use its own provider for protocol
, or it will throw a MalformedURLException
if there is none. An implementation may choose to find providers by other means. For example, it may support service providers, where the service interface is JMXConnectorProvider
.
Every implementation must support the RMI connector protocol with the default RMI transport, specified with string rmi
.
Once a provider is found, the result of the newJMXConnector
method is the result of calling newJMXConnector
on the provider.
The Map
parameter passed to the JMXConnectorProvider
is a new read-only Map
that contains all the entries that were in the environment
parameter to JMXConnectorFactory.newJMXConnector
, if there was one. Additionally, if the jmx.remote.protocol.provider.class.loader
key is not present in the environment
parameter, it is added to the new read-only Map
. The associated value is the calling thread's context class loader.
Modifier and Type | Field | Description |
---|---|---|
static final String |
DEFAULT_CLASS_LOADER |
Name of the attribute that specifies the default class loader. |
static final String |
PROTOCOL_PROVIDER_CLASS_LOADER |
Name of the attribute that specifies the class loader for loading protocol providers. |
static final String |
PROTOCOL_PROVIDER_PACKAGES |
Name of the attribute that specifies the provider packages that are consulted when looking for the handler for a protocol. |
Modifier and Type | Method | Description |
---|---|---|
static JMXConnector |
connect |
Creates a connection to the connector server at the given address. |
static JMXConnector |
connect |
Creates a connection to the connector server at the given address. |
static JMXConnector |
newJMXConnector |
Creates a connector client for the connector server at the given address. |
public static final String DEFAULT_CLASS_LOADER
Name of the attribute that specifies the default class loader. This class loader is used to deserialize return values and exceptions from remote MBeanServerConnection
calls. The value associated with this attribute is an instance of ClassLoader
.
public static final String PROTOCOL_PROVIDER_PACKAGES
Name of the attribute that specifies the provider packages that are consulted when looking for the handler for a protocol. The value associated with this attribute is a string with package names separated by vertical bars (|
).
public static final String PROTOCOL_PROVIDER_CLASS_LOADER
Name of the attribute that specifies the class loader for loading protocol providers. The value associated with this attribute is an instance of ClassLoader
.
public static JMXConnector connect(JMXServiceURL serviceURL) throws IOException
Creates a connection to the connector server at the given address.
This method is equivalent to connect(serviceURL, null)
.
serviceURL
- the address of the connector server to connect to.JMXConnector
whose connect
method has been called.NullPointerException
- if serviceURL
is null.IOException
- if the connector client or the connection cannot be made because of a communication problem.SecurityException
- if the connection cannot be made for security reasons.public static JMXConnector connect(JMXServiceURL serviceURL, Map<String,?> environment) throws IOException
Creates a connection to the connector server at the given address.
This method is equivalent to:
JMXConnector conn = JMXConnectorFactory.newJMXConnector(serviceURL, environment); conn.connect(environment);
serviceURL
- the address of the connector server to connect to.environment
- a set of attributes to determine how the connection is made. This parameter can be null. 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.JMXConnector
representing the newly-made connection. Each successful call to this method produces a different object.NullPointerException
- if serviceURL
is null.IOException
- if the connector client or the connection cannot be made because of a communication problem.SecurityException
- if the connection cannot be made for security reasons.public static JMXConnector newJMXConnector(JMXServiceURL serviceURL, Map<String,?> environment) throws IOException
Creates a connector client for the connector server at the given address. The resultant client is not connected until its connect
method is called.
serviceURL
- the address of the connector server to connect to.environment
- a set of attributes to determine how the connection is made. This parameter can be null. 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.JMXConnector
representing the new connector client. Each successful call to this method produces a different object.NullPointerException
- if serviceURL
is null.IOException
- if the connector client cannot be made because of a communication problem.MalformedURLException
- if there is no provider for the protocol in serviceURL
.JMXProviderException
- if there is a provider for the protocol in serviceURL
but it cannot be used for some reason.
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.management/javax/management/remote/JMXConnectorFactory.html