/*
 * Copyright (c) 2002, 2018, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.management.remote;

import com.sun.jmx.mbeanserver.Util;
import java.io.IOException;
import java.io.UncheckedIOException;
import java.net.MalformedURLException;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.ServiceLoader;
import java.util.ServiceLoader.Provider;
import java.util.StringTokenizer;
import java.util.function.Predicate;
import java.util.stream.Stream;
import java.security.AccessController;
import java.security.PrivilegedAction;

import com.sun.jmx.remote.util.ClassLogger;
import com.sun.jmx.remote.util.EnvHelp;
import sun.reflect.misc.ReflectUtil;


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<String,?>).
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:

If the environment parameter to newJMXConnector contains the key jmx.remote.protocol.provider.pkgs then the
associated value is the provider package list.
Otherwise, if the system property
jmx.remote.protocol.provider.pkgs exists, then its value
is the provider package list.
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 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:

if the attempt to load the class produces an exception other
than ClassNotFoundException, that is the
cause;
if 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.
Since:
1.5/**
 * <p>Factory to create JMX API connector clients.  There
 * are no instances of this class.</p>
 *
 * <p>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)}.</p>
 *
 * <p>Each client is created by an instance of {@link
 * JMXConnectorProvider}.  This instance is found as follows.  Suppose
 * the given {@link JMXServiceURL} looks like
 * <code>"service:jmx:<em>protocol</em>:<em>remainder</em>"</code>.
 * Then the factory will attempt to find the appropriate {@link
 * JMXConnectorProvider} for <code><em>protocol</em></code>.  Each
 * occurrence of the character <code>+</code> or <code>-</code> in
 * <code><em>protocol</em></code> is replaced by <code>.</code> or
 * <code>_</code>, respectively.</p>
 *
 * <p>A <em>provider package list</em> is searched for as follows:</p>
 *
 * <ol>
 *
 * <li>If the <code>environment</code> parameter to {@link
 * #newJMXConnector(JMXServiceURL, Map) newJMXConnector} contains the
 * key <code>jmx.remote.protocol.provider.pkgs</code> then the
 * associated value is the provider package list.
 *
 * <li>Otherwise, if the system property
 * <code>jmx.remote.protocol.provider.pkgs</code> exists, then its value
 * is the provider package list.
 *
 * <li>Otherwise, there is no provider package list.
 *
 * </ol>
 *
 * <p>The provider package list is a string that is interpreted as a
 * list of non-empty Java package names separated by vertical bars
 * (<code>|</code>).  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.</p>
 *
 * <p>If the provider package list exists and is not empty, then for
 * each element <code><em>pkg</em></code> of the list, the factory
 * will attempt to load the class
 *
 * <blockquote>
 * <code><em>pkg</em>.<em>protocol</em>.ClientProvider</code>
 * </blockquote>

 * <p>If the <code>environment</code> parameter to {@link
 * #newJMXConnector(JMXServiceURL, Map) newJMXConnector} contains the
 * key <code>jmx.remote.protocol.provider.class.loader</code> 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.</p>
 *
 * <p>If the <code>jmx.remote.protocol.provider.class.loader</code>
 * key is not present in the <code>environment</code> parameter, the
 * calling thread's context class loader is used.</p>
 *
 * <p>If the attempt to load this class produces a {@link
 * ClassNotFoundException}, the search for a handler continues with
 * the next element of the list.</p>
 *
 * <p>Otherwise, a problem with the provider found is signalled by a
 * {@link JMXProviderException} whose {@link
 * JMXProviderException#getCause() <em>cause</em>} indicates the underlying
 * exception, as follows:</p>
 *
 * <ul>
 *
 * <li>if the attempt to load the class produces an exception other
 * than <code>ClassNotFoundException</code>, that is the
 * <em>cause</em>;
 *
 * <li>if {@link Class#newInstance()} for the class produces an
 * exception, that is the <em>cause</em>.
 *
 * </ul>
 *
 * <p>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
 * <code><em>protocol</em></code>, or it will throw a
 * <code>MalformedURLException</code> if there is none.  An
 * implementation may choose to find providers by other means.  For
 * example, it may support <a
 * href="{@docRoot}/java.base/java/util/ServiceLoader.html#developing-service-providers">service providers</a>,
 * where the service interface is <code>JMXConnectorProvider</code>.</p>
 *
 * <p>Every implementation must support the RMI connector protocol with
 * the default RMI transport, specified with string <code>rmi</code>.
 * </p>
 *
 * <p>Once a provider is found, the result of the
 * <code>newJMXConnector</code> method is the result of calling {@link
 * JMXConnectorProvider#newJMXConnector(JMXServiceURL,Map) newJMXConnector}
 * on the provider.</p>
 *
 * <p>The <code>Map</code> parameter passed to the
 * <code>JMXConnectorProvider</code> is a new read-only
 * <code>Map</code> that contains all the entries that were in the
 * <code>environment</code> parameter to {@link
 * #newJMXConnector(JMXServiceURL,Map)
 * JMXConnectorFactory.newJMXConnector}, if there was one.
 * Additionally, if the
 * <code>jmx.remote.protocol.provider.class.loader</code> key is not
 * present in the <code>environment</code> parameter, it is added to
 * the new read-only <code>Map</code>.  The associated value is the
 * calling thread's context class loader.</p>
 *
 * @since 1.5
 */
public class JMXConnectorFactory {

    
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.
/**
     * <p>Name of the attribute that specifies the default class
     * loader. This class loader is used to deserialize return values and
     * exceptions from remote <code>MBeanServerConnection</code>
     * calls.  The value associated with this attribute is an instance
     * of {@link ClassLoader}.</p>
     */
    public static final String DEFAULT_CLASS_LOADER =
        "jmx.remote.default.class.loader";

    
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 (|).
/**
     * <p>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 (<code>|</code>).</p>
     */
    public static final String PROTOCOL_PROVIDER_PACKAGES =
        "jmx.remote.protocol.provider.pkgs";

    
Name of the attribute that specifies the class loader for loading protocol providers. The value associated with this attribute is an instance of ClassLoader.
/**
     * <p>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}.</p>
     */
    public static final String PROTOCOL_PROVIDER_CLASS_LOADER =
        "jmx.remote.protocol.provider.class.loader";

    private static final String PROTOCOL_PROVIDER_DEFAULT_PACKAGE =
        "com.sun.jmx.remote.protocol";

    private static final ClassLogger logger =
        new ClassLogger("javax.management.remote.misc", "JMXConnectorFactory");

    
There are no instances of this class.  /** There are no instances of this class.  */
    private JMXConnectorFactory() {
    }

    
Creates a connection to the connector server at the given
address.
This method is equivalent to connect(serviceURL, null).
Params:
serviceURL – the address of the connector server to
connect to.
Throws:
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.
Returns:
a JMXConnector whose connect method has been called./**
     * <p>Creates a connection to the connector server at the given
     * address.</p>
     *
     * <p>This method is equivalent to {@link
     * #connect(JMXServiceURL,Map) connect(serviceURL, null)}.</p>
     *
     * @param serviceURL the address of the connector server to
     * connect to.
     *
     * @return a <code>JMXConnector</code> whose {@link
     * JMXConnector#connect connect} method has been called.
     *
     * @exception NullPointerException if <code>serviceURL</code> 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.
     */
    public static JMXConnector connect(JMXServiceURL serviceURL)
            throws IOException {
        return connect(serviceURL, null);
    }

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

Params:
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.
Throws:
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.
Returns:
a JMXConnector representing the newly-made
connection.  Each successful call to this method produces a
different object./**
     * <p>Creates a connection to the connector server at the given
     * address.</p>
     *
     * <p>This method is equivalent to:</p>
     *
     * <pre>
     * JMXConnector conn = JMXConnectorFactory.newJMXConnector(serviceURL,
     *                                                         environment);
     * conn.connect(environment);
     * </pre>
     *
     * @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
     * <code>environment</code> are not changed by this call.
     *
     * @return a <code>JMXConnector</code> representing the newly-made
     * connection.  Each successful call to this method produces a
     * different object.
     *
     * @exception NullPointerException if <code>serviceURL</code> 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.
     */
    public static JMXConnector connect(JMXServiceURL serviceURL,
                                       Map<String,?> environment)
            throws IOException {
        if (serviceURL == null)
            throw new NullPointerException("Null JMXServiceURL");
        JMXConnector conn = newJMXConnector(serviceURL, environment);
        conn.connect(environment);
        return conn;
    }

    private static <K,V> Map<K,V> newHashMap() {
        return new HashMap<K,V>();
    }

    private static <K> Map<K,Object> newHashMap(Map<K,?> map) {
        return new HashMap<K,Object>(map);
    }

    
Creates a connector client for the connector server at the given address. The resultant client is not connected until its connect method is called.
Params:
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.
Throws:
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.
Returns:
a JMXConnector representing the new
connector client.  Each successful call to this method produces
a different object./**
     * <p>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.</p>
     *
     * @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
     * <code>environment</code> are not changed by this call.
     *
     * @return a <code>JMXConnector</code> representing the new
     * connector client.  Each successful call to this method produces
     * a different object.
     *
     * @exception NullPointerException if <code>serviceURL</code> 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 <code>serviceURL</code>.
     *
     * @exception JMXProviderException if there is a provider for the
     * protocol in <code>serviceURL</code> but it cannot be used for
     * some reason.
     */
    public static JMXConnector newJMXConnector(JMXServiceURL serviceURL,
                                               Map<String,?> environment)
            throws IOException {

        final Map<String,Object> envcopy;
        if (environment == null)
            envcopy = newHashMap();
        else {
            EnvHelp.checkAttributes(environment);
            envcopy = newHashMap(environment);
        }

        final ClassLoader loader = resolveClassLoader(envcopy);
        final Class<JMXConnectorProvider> targetInterface =
                JMXConnectorProvider.class;
        final String protocol = serviceURL.getProtocol();
        final String providerClassName = "ClientProvider";
        final JMXServiceURL providerURL = serviceURL;

        JMXConnectorProvider provider = getProvider(providerURL, envcopy,
                                               providerClassName,
                                               targetInterface,
                                               loader);

        IOException exception = null;
        if (provider == null) {
            Predicate<Provider<?>> systemProvider =
                    JMXConnectorFactory::isSystemProvider;
            // 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.
            JMXConnector connection = null;
            if (loader != null) {
                try {
                    connection = getConnectorAsService(loader,
                                                       providerURL,
                                                       envcopy,
                                                       systemProvider.negate());
                    if (connection != null) return connection;
                } catch (JMXProviderException e) {
                    throw e;
                } catch (IOException e) {
                    exception = e;
                }
            }
            connection = getConnectorAsService(
                             JMXConnectorFactory.class.getClassLoader(),
                             providerURL,
                             Collections.unmodifiableMap(envcopy),
                             systemProvider);
            if (connection != null) return connection;
        }

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

        final Map<String,Object> fixedenv =
                Collections.unmodifiableMap(envcopy);

        return provider.newJMXConnector(serviceURL, fixedenv);
    }

    private static String resolvePkgs(Map<String, ?> env)
            throws JMXProviderException {

        Object pkgsObject = null;

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

        if (pkgsObject == null)
            pkgsObject =
                AccessController.doPrivileged(new PrivilegedAction<String>() {
                    public String 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().isEmpty())
            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;
    }

    static <T> T getProvider(JMXServiceURL serviceURL,
                             final Map<String, Object> environment,
                             String providerClassName,
                             Class<T> targetInterface,
                             final ClassLoader loader)
            throws IOException {

        final String protocol = serviceURL.getProtocol();

        final String pkgs = resolvePkgs(environment);

        T instance = null;

        if (pkgs != null) {
            instance =
                getProvider(protocol, pkgs, loader, providerClassName,
                            targetInterface);

            if (instance != null) {
                boolean needsWrap = (loader != instance.getClass().getClassLoader());
                environment.put(PROTOCOL_PROVIDER_CLASS_LOADER, needsWrap ? wrap(loader) : loader);
            }
        }

        return instance;
    }

    private static ClassLoader wrap(final ClassLoader parent) {
        return parent != null ? AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() {
            @Override
            public ClassLoader run() {
                return new ClassLoader(parent) {
                    @Override
                    protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundException {
                        ReflectUtil.checkPackageAccess(name);
                        return super.loadClass(name, resolve);
                    }
                };
            }
        }) : null;
    }

    
Checks whether the given provider is our system provider for
the RMI connector.
If providers for additional protocols are added in the future
then the name of their modules may need to be added here.
System providers will be loaded only if no other provider is found.
Params:
provider – the provider to test.
Returns:
true if this provider is a default system provider./**
     * Checks whether the given provider is our system provider for
     * the RMI connector.
     * If providers for additional protocols are added in the future
     * then the name of their modules may need to be added here.
     * System providers will be loaded only if no other provider is found.
     * @param provider the provider to test.
     * @return true if this provider is a default system provider.
     */
    static boolean isSystemProvider(Provider<?> provider) {
        Module providerModule = provider.type().getModule();
        return providerModule.isNamed()
           && providerModule.getName().equals("java.management.rmi");
    }

    
Creates a JMXConnector from the first JMXConnectorProvider service
supporting the given url that can be loaded from the given loader.

Parses the list of JMXConnectorProvider services that can be loaded
from the given loader, only retaining those that satisfy the given filter.
Then for each provider, attempts to create a new JMXConnector.
The first JMXConnector successfully created is returned.

The filter predicate is usually used to either exclude system providers
or only retain system providers (see isSystemProvider(...) above).
Params:
loader – The ClassLoader to use when looking up an implementation
       of the service. If null, then only installed services will be
       considered.
url – The JMXServiceURL of the connector for which a provider is
       requested.
filter – A filter used to exclude or return provider
       implementations. Typically the filter will either exclude
       system services (system default implementations) or only
       retain those.
       This can allow to first look for custom implementations (e.g.
       deployed on the CLASSPATH with META-INF/services) and
       then only default to system implementations.
Throws:
IOException – if no connector could not be instantiated, and at least one provider threw an exception that wasn't a MalformedURLException or a JMProviderException.
JMXProviderException – if a provider for the protocol in
        url was found, but couldn't create the connector
        some reason.
Returns:
an instance of JMXConnector if a provider was found from which one could be instantiated, null otherwise./**
     * Creates a JMXConnector from the first JMXConnectorProvider service
     * supporting the given url that can be loaded from the given loader.
     * <p>
     * Parses the list of JMXConnectorProvider services that can be loaded
     * from the given loader, only retaining those that satisfy the given filter.
     * Then for each provider, attempts to create a new JMXConnector.
     * The first JMXConnector successfully created is returned.
     * <p>
     * The filter predicate is usually used to either exclude system providers
     * or only retain system providers (see isSystemProvider(...) above).
     *
     * @param loader The ClassLoader to use when looking up an implementation
     *        of the service. If null, then only installed services will be
     *        considered.
     *
     * @param url The JMXServiceURL of the connector for which a provider is
     *        requested.
     *
     * @param filter A filter used to exclude or return provider
     *        implementations. Typically the filter will either exclude
     *        system services (system default implementations) or only
     *        retain those.
     *        This can allow to first look for custom implementations (e.g.
     *        deployed on the CLASSPATH with META-INF/services) and
     *        then only default to system implementations.
     *
     * @throws IOException if no connector could not be instantiated, and
     *         at least one provider threw an exception that wasn't a
     *         {@code MalformedURLException} or a {@code JMProviderException}.
     *
     * @throws JMXProviderException if a provider for the protocol in
     *         <code>url</code> was found, but couldn't create the connector
     *         some reason.
     *
     * @return an instance of JMXConnector if a provider was found from
     *         which one could be instantiated, {@code null} otherwise.
     */
    private static JMXConnector getConnectorAsService(ClassLoader loader,
                                                      JMXServiceURL url,
                                                      Map<String, ?> map,
                                                      Predicate<Provider<?>> filter)
        throws IOException {

        final ConnectorFactory<JMXConnectorProvider, JMXConnector> factory =
                (p) -> p.newJMXConnector(url, map);
        return getConnectorAsService(JMXConnectorProvider.class, loader, url,
                                     filter, factory);
    }


    
A factory function that can create a connector from a provider.
The pair (P,C) will be either one of:
a. (JMXConnectorProvider, JMXConnector) or
b. (JMXConnectorServerProvider, JMXConnectorServer)
/**
     * A factory function that can create a connector from a provider.
     * The pair (P,C) will be either one of:
     * a. (JMXConnectorProvider, JMXConnector) or
     * b. (JMXConnectorServerProvider, JMXConnectorServer)
     */
    @FunctionalInterface
    static interface ConnectorFactory<P,C> {
        public C apply(P provider) throws Exception;
    }

    
An instance of ProviderFinder is used to traverse a Stream<Provider<P>> and find the first implementation of P that supports creating a connector C from the given JMXServiceURL. 

The pair (P,C) will be either one of: 

a. (JMXConnectorProvider, JMXConnector) or 

b. (JMXConnectorServerProvider, JMXConnectorServer)

The first connector successfully created while traversing the stream
is stored in the ProviderFinder instance. After that, the
ProviderFinder::test method, if called, will always return false, skipping
the remaining providers.

An instance of ProviderFinder is always expected to be used in conjunction
with Stream::findFirst, so that the stream traversal is stopped as soon
as a matching provider is found.

At the end of the stream traversal, the ProviderFinder::get method can be
used to obtain the connector instance (an instance of C) that was created.
If no connector could be created, and an exception was encountered while
traversing the stream and attempting to create the connector, then that
exception will be thrown by ProviderFinder::get, wrapped, if needed,
inside an IOException.

If any JMXProviderException is encountered while traversing the stream and
attempting to create the connector, that exception will be wrapped in an
UncheckedIOException and thrown immediately within the stream, thus
interrupting the traversal.

If no matching provider was found (no provider found or attempting
factory.apply always returned null or threw a MalformedURLException,
indicating the provider didn't support the protocol asked for by
the JMXServiceURL), then ProviderFinder::get will simply return null.
/**
     * An instance of ProviderFinder is used to traverse a
     * {@code Stream<Provider<P>>} and find the first implementation of P
     * that supports creating a connector C from the given JMXServiceURL.
     * <p>
     * The pair (P,C) will be either one of: <br>
     * a. (JMXConnectorProvider, JMXConnector) or <br>
     * b. (JMXConnectorServerProvider, JMXConnectorServer)
     * <p>
     * The first connector successfully created while traversing the stream
     * is stored in the ProviderFinder instance. After that, the
     * ProviderFinder::test method, if called, will always return false, skipping
     * the remaining providers.
     * <p>
     * An instance of ProviderFinder is always expected to be used in conjunction
     * with Stream::findFirst, so that the stream traversal is stopped as soon
     * as a matching provider is found.
     * <p>
     * At the end of the stream traversal, the ProviderFinder::get method can be
     * used to obtain the connector instance (an instance of C) that was created.
     * If no connector could be created, and an exception was encountered while
     * traversing the stream and attempting to create the connector, then that
     * exception will be thrown by ProviderFinder::get, wrapped, if needed,
     * inside an IOException.
     * <p>
     * If any JMXProviderException is encountered while traversing the stream and
     * attempting to create the connector, that exception will be wrapped in an
     * UncheckedIOException and thrown immediately within the stream, thus
     * interrupting the traversal.
     * <p>
     * If no matching provider was found (no provider found or attempting
     * factory.apply always returned null or threw a MalformedURLException,
     * indicating the provider didn't support the protocol asked for by
     * the JMXServiceURL), then ProviderFinder::get will simply return null.
     */
    private static final class ProviderFinder<P,C> implements Predicate<Provider<P>> {

        final ConnectorFactory<P,C> factory;
        final JMXServiceURL  url;
        private IOException  exception = null;
        private C connection = null;

        ProviderFinder(ConnectorFactory<P,C> factory, JMXServiceURL url) {
            this.factory = factory;
            this.url = url;
        }

        
Returns true for the first provider sp that can be used to obtain an instance of C from the given factory. 
Params:
sp – a candidate provider for instantiating C.
Throws:
UncheckedIOException – if sp throws a JMXProviderException. The JMXProviderException is set as the root cause.
Returns:
true for the first provider sp for which C could be instantiated, false otherwise./**
         * Returns {@code true} for the first provider {@code sp} that can
         * be used to obtain an instance of {@code C} from the given
         * {@code factory}.
         *
         * @param sp a candidate provider for instantiating {@code C}.
         *
         * @throws UncheckedIOException if {@code sp} throws a
         *         JMXProviderException. The JMXProviderException is set as the
         *         root cause.
         *
         * @return {@code true} for the first provider {@code sp} for which
         *         {@code C} could be instantiated, {@code false} otherwise.
         */
        public boolean test(Provider<P> sp) {
            if (connection == null) {
                P provider = sp.get();
                try {
                    connection = factory.apply(provider);
                    return connection != null;
                } catch (JMXProviderException e) {
                    throw new UncheckedIOException(e);
                } catch (Exception e) {
                    if (logger.traceOn())
                        logger.trace("getConnectorAsService",
                             "URL[" + url +
                             "] Service provider exception: " + e);
                    if (!(e instanceof MalformedURLException)) {
                        if (exception == null) {
                            if (e instanceof IOException) {
                                exception = (IOException) e;
                            } else {
                                exception = EnvHelp.initCause(
                                    new IOException(e.getMessage()), e);
                            }
                        }
                    }
                }
            }
            return false;
        }

        
Returns an instance of C if a provider was found from which C could be instantiated. 
Throws:
IOException – if C could not be instantiated, and at least one provider threw an exception that wasn't a MalformedURLException or a JMProviderException.
Returns:
an instance of C if a provider was found from which C could be instantiated, null otherwise./**
         * Returns an instance of {@code C} if a provider was found from
         * which {@code C} could be instantiated.
         *
         * @throws IOException if {@code C} could not be instantiated, and
         *         at least one provider threw an exception that wasn't a
         *         {@code MalformedURLException} or a {@code JMProviderException}.
         *
         * @return an instance of {@code C} if a provider was found from
         *         which {@code C} could be instantiated, {@code null} otherwise.
         */
        C get() throws IOException {
            if (connection != null) return connection;
            else if (exception != null) throw exception;
            else return null;
        }
    }

    
Creates a connector from a provider loaded from the ServiceLoader.

The pair (P,C) will be either one of: 

a. (JMXConnectorProvider, JMXConnector) or 

b. (JMXConnectorServerProvider, JMXConnectorServer)
Params:
providerClass – The service type for which an implementation should be looked up from the ServiceLoader. This will be either JMXConnectorProvider.class or JMXConnectorServerProvider.class
loader – The ClassLoader to use when looking up an implementation
       of the service. If null, then only installed services will be
       considered.
url – The JMXServiceURL of the connector for which a provider is
       requested.
filter – A filter used to exclude or return provider
       implementations. Typically the filter will either exclude
       system services (system default implementations) or only
       retain those.
       This can allow to first look for custom implementations (e.g.
       deployed on the CLASSPATH with META-INF/services) and
       then only default to system implementations.
factory – A functional factory that can attempt to create an instance of connector C from a provider P. Typically, this is a simple wrapper over 
       JMXConnectorProvider::newJMXConnector or 
       JMXConnectorProviderServer::newJMXConnectorServer.
Throws:
IOException – if C could not be instantiated, and at least one provider P threw an exception that wasn't a MalformedURLException or a JMProviderException.
JMXProviderException – if a provider P for the protocol in url was found, but couldn't create the connector C for some reason.
Returns:
an instance of C if a provider P was found from which one could be instantiated, null otherwise./**
     * Creates a connector from a provider loaded from the ServiceLoader.
     * <p>
     * The pair (P,C) will be either one of: <br>
     * a. (JMXConnectorProvider, JMXConnector) or <br>
     * b. (JMXConnectorServerProvider, JMXConnectorServer)
     *
     * @param providerClass The service type for which an implementation
     *        should be looked up from the {@code ServiceLoader}. This will
     *        be either {@code JMXConnectorProvider.class} or
     *        {@code JMXConnectorServerProvider.class}
     *
     * @param loader The ClassLoader to use when looking up an implementation
     *        of the service. If null, then only installed services will be
     *        considered.
     *
     * @param url The JMXServiceURL of the connector for which a provider is
     *        requested.
     *
     * @param filter A filter used to exclude or return provider
     *        implementations. Typically the filter will either exclude
     *        system services (system default implementations) or only
     *        retain those.
     *        This can allow to first look for custom implementations (e.g.
     *        deployed on the CLASSPATH with META-INF/services) and
     *        then only default to system implementations.
     *
     * @param factory A functional factory that can attempt to create an
     *        instance of connector {@code C} from a provider {@code P}.
     *        Typically, this is a simple wrapper over {@code
     *        JMXConnectorProvider::newJMXConnector} or {@code
     *        JMXConnectorProviderServer::newJMXConnectorServer}.
     *
     * @throws IOException if {@code C} could not be instantiated, and
     *         at least one provider {@code P} threw an exception that wasn't a
     *         {@code MalformedURLException} or a {@code JMProviderException}.
     *
     * @throws JMXProviderException if a provider {@code P} for the protocol in
     *         <code>url</code> was found, but couldn't create the connector
     *         {@code C} for some reason.
     *
     * @return an instance of {@code C} if a provider {@code P} was found from
     *         which one could be instantiated, {@code null} otherwise.
     */
    static <P,C> C getConnectorAsService(Class<P> providerClass,
                                         ClassLoader loader,
                                         JMXServiceURL url,
                                         Predicate<Provider<?>> filter,
                                         ConnectorFactory<P,C> factory)
        throws IOException {

        // sanity check
        if (JMXConnectorProvider.class != providerClass
            && JMXConnectorServerProvider.class != providerClass) {
            // should never happen
            throw new InternalError("Unsupported service interface: "
                                    + providerClass.getName());
        }

        ServiceLoader<P> serviceLoader = loader == null
                ? ServiceLoader.loadInstalled(providerClass)
                : ServiceLoader.load(providerClass, loader);
        Stream<Provider<P>> stream = serviceLoader.stream().filter(filter);
        ProviderFinder<P,C> finder = new ProviderFinder<>(factory, url);

        try {
            stream.filter(finder).findFirst();
            return finder.get();
        } catch (UncheckedIOException e) {
            if (e.getCause() instanceof JMXProviderException) {
                throw (JMXProviderException) e.getCause();
            } else {
                throw e;
            }
        }
    }

    static <T> T getProvider(String protocol,
                              String pkgs,
                              ClassLoader loader,
                              String providerClassName,
                              Class<T> targetInterface)
            throws IOException {

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

            // We have just proved that this cast is correct
            Class<? extends T> providerClassT = Util.cast(providerClass);
            try {
                @SuppressWarnings("deprecation")
                T result = providerClassT.newInstance();
                return result;
            } catch (Exception e) {
                final String msg =
                    "Exception when instantiating provider [" + className +
                    "]";
                throw new JMXProviderException(msg, e);
            }
        }

        return null;
    }

    static ClassLoader resolveClassLoader(Map<String, ?> 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 = Thread.currentThread().getContextClassLoader();
        }

        return loader;
    }

    private static String protocol2package(String protocol) {
        return protocol.replace('+', '.').replace('-', '_');
    }
}