FileDocCategorySizeDatePackage
JMXConnectorFactory.javaAPI DocJava SE 6 API20336Tue Jun 10 00:26:18 BST 2008javax.management.remote

JMXConnectorFactory

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 {@link #connect(JMXServiceURL) connect} method of this class. More advanced applications can separate the creation of the connector client, using {@link #newJMXConnector(JMXServiceURL, Map) newJMXConnector} and the establishment of the connection itself, using {@link JMXConnector#connect(Map)}.

Each client is created by an instance of {@link JMXConnectorProvider}. This instance is found as follows. Suppose the given {@link JMXServiceURL} looks like "service:jmx:protocol:remainder". Then the factory will attempt to find the appropriate {@link 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:

  1. If the environment parameter to {@link #newJMXConnector(JMXServiceURL, Map) newJMXConnector} contains the key jmx.remote.protocol.provider.pkgs then the associated value is the provider package list.
  2. Otherwise, if the system property jmx.remote.protocol.provider.pkgs exists, then its value is the provider package list.
  3. Otherwise, there is no 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 {@link 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 {@link #newJMXConnector(JMXServiceURL, Map) 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 {@link java.lang.ClassLoader}, an {@link java.lang.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 {@link 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 {@link JMXProviderException} whose {@link JMXProviderException#getCause() cause} indicates the underlying exception, as follows:

  • if the attempt to load the class produces an exception other than ClassNotFoundException, that is the cause;
  • if {@link 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 the JAR conventions for service providers, where the service interface is JMXConnectorProvider.

Every implementation must support the RMI connector protocols, specified with the string rmi or iiop.

Once a provider is found, the result of the newJMXConnector method is the result of calling {@link JMXConnectorProvider#newJMXConnector(JMXServiceURL,Map) 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 {@link #newJMXConnector(JMXServiceURL,Map) 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.

since
1.5
since.unbundled
1.0

Fields Summary
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 {@link 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 {@link ClassLoader}.

private static final String
PROTOCOL_PROVIDER_DEFAULT_PACKAGE
private static final ClassLogger
logger
Constructors Summary
private JMXConnectorFactory()
There are no instances of this class.
Methods Summary
public static javax.management.remote.JMXConnectorconnect(javax.management.remote.JMXServiceURL serviceURL)

Creates a connection to the connector server at the given address.

This method is equivalent to {@link #connect(JMXServiceURL,Map) connect(serviceURL, null)}.

param
serviceURL the address of the connector server to connect to.
return
a JMXConnector whose {@link JMXConnector#connect connect} method has been called.
exception
NullPointerException if serviceURL is null.
exception
IOException if the connector client or the connection cannot be made because of a communication problem.
exception
SecurityException if the connection cannot be made for security reasons.

        return connect(serviceURL, null);
public static javax.management.remote.JMXConnectorconnect(javax.management.remote.JMXServiceURL serviceURL, java.util.Map environment)

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);

param
serviceURL the address of the connector server to connect to.
param
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.
return
a JMXConnector representing the newly-made connection. Each successful call to this method produces a different object.
exception
NullPointerException if serviceURL is null.
exception
IOException if the connector client or the connection cannot be made because of a communication problem.
exception
SecurityException if the connection cannot be made for security reasons.

        if (serviceURL == null)
            throw new NullPointerException("Null JMXServiceURL");
        JMXConnector conn = newJMXConnector(serviceURL, environment);
        conn.connect(environment);
        return conn;
private static javax.management.remote.JMXConnectorgetConnectorAsService(java.lang.ClassLoader loader, javax.management.remote.JMXServiceURL url, java.util.Map map)


        Iterator providers = getProviderIterator(JMXConnectorProvider.class,
                                                 loader);
        JMXConnectorProvider provider = null;
        JMXConnector connection = null;
        IOException exception = null;
        while (providers.hasNext()) {
            provider = (JMXConnectorProvider) providers.next();
            try {
                connection = provider.newJMXConnector(url, map);
                return connection;
            } catch (JMXProviderException e) {
                throw e;
            } catch (Exception e) {
                if (logger.traceOn())
                    logger.trace("getConnectorAsService",
                                 "URL[" + url +
                                 "] Service provider exception: " + e);
                if (!(e instanceof MalformedURLException)) {
                    if (exception == null) {
                        if (exception instanceof IOException) {
                            exception = (IOException) e;
                        } else {
                            exception = EnvHelp.initCause(
                                new IOException(e.getMessage()), e);
                        }
                    }
                }
                continue;
            }
        }
        if (exception == null)
            return null;
        else
            throw exception;
static java.lang.ObjectgetProvider(javax.management.remote.JMXServiceURL serviceURL, java.util.Map environment, java.lang.String providerClassName, java.lang.Class targetInterface, java.lang.ClassLoader loader)


        final String protocol = serviceURL.getProtocol();
        
        final String pkgs = resolvePkgs(environment);

        Object instance = null;
        
        if (pkgs != null) {
            environment.put(PROTOCOL_PROVIDER_CLASS_LOADER, loader);
            
            instance =
                getProvider(protocol, pkgs, loader, providerClassName,
                            targetInterface);
        }

        return instance;
static java.lang.ObjectgetProvider(java.lang.String protocol, java.lang.String pkgs, java.lang.ClassLoader loader, java.lang.String providerClassName, java.lang.Class targetInterface)


        StringTokenizer tokenizer = new StringTokenizer(pkgs, "|");

        while (tokenizer.hasMoreTokens()) {
            String pkg = tokenizer.nextToken();
            String className = (pkg + "." + protocol2package(protocol) +
                                "." + providerClassName);
            Class providerClass;
            try {
                providerClass = Class.forName(className, true, loader);
            } catch (ClassNotFoundException e) {
                //Add trace.
                continue;
            }

            if (!targetInterface.isAssignableFrom(providerClass)) {
                final String msg =
                    "Provider class does not implement " +
                    targetInterface.getName() + ": " +
                    providerClass.getName();
                throw new JMXProviderException(msg);
            }

            try {
                return providerClass.newInstance();
            } catch (Exception e) {
                final String msg =
                    "Exception when instantiating provider [" + className +
                    "]";
                throw new JMXProviderException(msg, e);
            }
        }

        return null;
static java.util.IteratorgetProviderIterator(java.lang.Class providerClass, java.lang.ClassLoader loader)

        PrivilegedAction action = new PrivilegedAction() {
                public Object run() {
                    return Service.providers(providerClass, loader);
                }
            };
        return (Iterator) AccessController.doPrivileged(action);
public static javax.management.remote.JMXConnectornewJMXConnector(javax.management.remote.JMXServiceURL serviceURL, java.util.Map environment)

Creates a connector client for the connector server at the given address. The resultant client is not connected until its {@link JMXConnector#connect(Map) connect} method is called.

param
serviceURL the address of the connector server to connect to.
param
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.
return
a JMXConnector representing the new connector client. Each successful call to this method produces a different object.
exception
NullPointerException if serviceURL is null.
exception
IOException if the connector client cannot be made because of a communication problem.
exception
MalformedURLException if there is no provider for the protocol in serviceURL.
exception
JMXProviderException if there is a provider for the protocol in serviceURL but it cannot be used for some reason.

        if (environment == null)
            environment = new HashMap();
        else {
            EnvHelp.checkAttributes(environment);
            environment = new HashMap(environment);
        }
        
        final ClassLoader loader = resolveClassLoader(environment);
        final Class targetInterface = JMXConnectorProvider.class;
        final String protocol = serviceURL.getProtocol();
        final String providerClassName = "ClientProvider";
        
        JMXConnectorProvider provider =
            (JMXConnectorProvider) getProvider(serviceURL, environment,
                                               providerClassName,
                                               targetInterface,
                                               loader);

        IOException exception = null;
        if (provider == null) {
            // Loader is null when context class loader is set to null
            // and no loader has been provided in map.
            // com.sun.jmx.remote.util.Service class extracted from j2se
            // provider search algorithm doesn't handle well null classloader.
            if (loader != null) {
                try {
                    JMXConnector connection =
                        getConnectorAsService(loader, serviceURL, environment);
                    if (connection != null)
                        return connection;
                } catch (JMXProviderException e) {
                    throw e;
                } catch (IOException e) {
                    exception = e;
                }
            }
            provider = (JMXConnectorProvider)
                getProvider(protocol, PROTOCOL_PROVIDER_DEFAULT_PACKAGE,
                            JMXConnectorFactory.class.getClassLoader(),
                            providerClassName, targetInterface);
        }

        if (provider == null) {
            MalformedURLException e =
                new MalformedURLException("Unsupported protocol: " + protocol);
            if (exception == null) {
                throw e;
            } else {
                throw EnvHelp.initCause(e, exception);
            }
        }

        environment = Collections.unmodifiableMap(environment);

        return provider.newJMXConnector(serviceURL, environment);
private static java.lang.Stringprotocol2package(java.lang.String protocol)

        return protocol.replace('+", '.").replace('-", '_");
static java.lang.ClassLoaderresolveClassLoader(java.util.Map environment)

        ClassLoader loader = null;

        if (environment != null) {
            try {
                loader = (ClassLoader)
                    environment.get(PROTOCOL_PROVIDER_CLASS_LOADER);
            } catch (ClassCastException e) {
                final String msg =
                    "The ClassLoader supplied in the environment map using " +
                    "the " + PROTOCOL_PROVIDER_CLASS_LOADER +
                    " attribute is not an instance of java.lang.ClassLoader";
                throw new IllegalArgumentException(msg); 
            }
        }

        if (loader == null)
            loader = (ClassLoader)
                AccessController.doPrivileged(new PrivilegedAction() {
                        public Object run() {
                            return
                                Thread.currentThread().getContextClassLoader();
                        }
                    });

        return loader;
private static java.lang.StringresolvePkgs(java.util.Map env)


        Object pkgsObject = null;

        if (env != null)
            pkgsObject = env.get(PROTOCOL_PROVIDER_PACKAGES);

        if (pkgsObject == null)
            pkgsObject =
                AccessController.doPrivileged(new PrivilegedAction() {
                    public Object run() {
                        return System.getProperty(PROTOCOL_PROVIDER_PACKAGES);
                    }
                });

        if (pkgsObject == null)
            return null;

        if (!(pkgsObject instanceof String)) {
            final String msg = "Value of " + PROTOCOL_PROVIDER_PACKAGES +
                " parameter is not a String: " +
                pkgsObject.getClass().getName();
            throw new JMXProviderException(msg);
        }

        final String pkgs = (String) pkgsObject;
        if (pkgs.trim().equals(""))
            return null;

        // pkgs may not contain an empty element
        if (pkgs.startsWith("|") || pkgs.endsWith("|") ||
            pkgs.indexOf("||") >= 0) {
            final String msg = "Value of " + PROTOCOL_PROVIDER_PACKAGES +
                " contains an empty element: " + pkgs;
            throw new JMXProviderException(msg);
        }

        return pkgs;