1 /*

     2  * Copyright (c) 2002, 2014, Oracle and/or its affiliates. All rights reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Oracle designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Oracle in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

    22  * or visit www.oracle.com if you need additional information or have any

    23  * questions.

    24  */

    25 

    26 package javax.management.remote;

    27 

    28 import com.sun.jmx.mbeanserver.Util;

    29 import java.io.IOException;

    30 import java.net.MalformedURLException;

    31 import java.util.Collections;

    32 import java.util.HashMap;

    33 import java.util.Map;

    34 import java.util.Iterator;

    35 import java.util.ServiceLoader;

    36 import java.util.StringTokenizer;

    37 import java.security.AccessController;

    38 import java.security.PrivilegedAction;

    39 

    40 import com.sun.jmx.remote.util.ClassLogger;

    41 import com.sun.jmx.remote.util.EnvHelp;

    42 import sun.reflect.misc.ReflectUtil;

    43 

    44 

    45 /**

    46  * <p>Factory to create JMX API connector clients.  There

    47  * are no instances of this class.</p>

    48  *

    49  * <p>Connections are usually made using the {@link

    50  * #connect(JMXServiceURL) connect} method of this class.  More

    51  * advanced applications can separate the creation of the connector

    52  * client, using {@link #newJMXConnector(JMXServiceURL, Map)

    53  * newJMXConnector} and the establishment of the connection itself, using

    54  * {@link JMXConnector#connect(Map)}.</p>

    55  *

    56  * <p>Each client is created by an instance of {@link

    57  * JMXConnectorProvider}.  This instance is found as follows.  Suppose

    58  * the given {@link JMXServiceURL} looks like

    59  * <code>"service:jmx:<em>protocol</em>:<em>remainder</em>"</code>.

    60  * Then the factory will attempt to find the appropriate {@link

    61  * JMXConnectorProvider} for <code><em>protocol</em></code>.  Each

    62  * occurrence of the character <code>+</code> or <code>-</code> in

    63  * <code><em>protocol</em></code> is replaced by <code>.</code> or

    64  * <code>_</code>, respectively.</p>

    65  *

    66  * <p>A <em>provider package list</em> is searched for as follows:</p>

    67  *

    68  * <ol>

    69  *

    70  * <li>If the <code>environment</code> parameter to {@link

    71  * #newJMXConnector(JMXServiceURL, Map) newJMXConnector} contains the

    72  * key <code>jmx.remote.protocol.provider.pkgs</code> then the

    73  * associated value is the provider package list.

    74  *

    75  * <li>Otherwise, if the system property

    76  * <code>jmx.remote.protocol.provider.pkgs</code> exists, then its value

    77  * is the provider package list.

    78  *

    79  * <li>Otherwise, there is no provider package list.

    80  *

    81  * </ol>

    82  *

    83  * <p>The provider package list is a string that is interpreted as a

    84  * list of non-empty Java package names separated by vertical bars

    85  * (<code>|</code>).  If the string is empty, then so is the provider

    86  * package list.  If the provider package list is not a String, or if

    87  * it contains an element that is an empty string, a {@link

    88  * JMXProviderException} is thrown.</p>

    89  *

    90  * <p>If the provider package list exists and is not empty, then for

    91  * each element <code><em>pkg</em></code> of the list, the factory

    92  * will attempt to load the class

    93  *

    94  * <blockquote>

    95  * <code><em>pkg</em>.<em>protocol</em>.ClientProvider</code>

    96  * </blockquote>

    97 

    98  * <p>If the <code>environment</code> parameter to {@link

    99  * #newJMXConnector(JMXServiceURL, Map) newJMXConnector} contains the

   100  * key <code>jmx.remote.protocol.provider.class.loader</code> then the

   101  * associated value is the class loader to use to load the provider.

   102  * If the associated value is not an instance of {@link

   103  * java.lang.ClassLoader}, an {@link

   104  * java.lang.IllegalArgumentException} is thrown.</p>

   105  *

   106  * <p>If the <code>jmx.remote.protocol.provider.class.loader</code>

   107  * key is not present in the <code>environment</code> parameter, the

   108  * calling thread's context class loader is used.</p>

   109  *

   110  * <p>If the attempt to load this class produces a {@link

   111  * ClassNotFoundException}, the search for a handler continues with

   112  * the next element of the list.</p>

   113  *

   114  * <p>Otherwise, a problem with the provider found is signalled by a

   115  * {@link JMXProviderException} whose {@link

   116  * JMXProviderException#getCause() <em>cause</em>} indicates the underlying

   117  * exception, as follows:</p>

   118  *

   119  * <ul>

   120  *

   121  * <li>if the attempt to load the class produces an exception other

   122  * than <code>ClassNotFoundException</code>, that is the

   123  * <em>cause</em>;

   124  *

   125  * <li>if {@link Class#newInstance()} for the class produces an

   126  * exception, that is the <em>cause</em>.

   127  *

   128  * </ul>

   129  *

   130  * <p>If no provider is found by the above steps, including the

   131  * default case where there is no provider package list, then the

   132  * implementation will use its own provider for

   133  * <code><em>protocol</em></code>, or it will throw a

   134  * <code>MalformedURLException</code> if there is none.  An

   135  * implementation may choose to find providers by other means.  For

   136  * example, it may support the <a

   137  * href="{@docRoot}/../technotes/guides/jar/jar.html#Service%20Provider">

   138  * JAR conventions for service providers</a>, where the service

   139  * interface is <code>JMXConnectorProvider</code>.</p>

   140  *

   141  * <p>Every implementation must support the RMI connector protocol with

   142  * the default RMI transport, specified with string <code>rmi</code>.

   143  * An implementation may optionally support the RMI connector protocol

   144  * with the RMI/IIOP transport, specified with the string

   145  * <code>iiop</code>.</p>

   146  *

   147  * <p>Once a provider is found, the result of the

   148  * <code>newJMXConnector</code> method is the result of calling {@link

   149  * JMXConnectorProvider#newJMXConnector(JMXServiceURL,Map) newJMXConnector}

   150  * on the provider.</p>

   151  *

   152  * <p>The <code>Map</code> parameter passed to the

   153  * <code>JMXConnectorProvider</code> is a new read-only

   154  * <code>Map</code> that contains all the entries that were in the

   155  * <code>environment</code> parameter to {@link

   156  * #newJMXConnector(JMXServiceURL,Map)

   157  * JMXConnectorFactory.newJMXConnector}, if there was one.

   158  * Additionally, if the

   159  * <code>jmx.remote.protocol.provider.class.loader</code> key is not

   160  * present in the <code>environment</code> parameter, it is added to

   161  * the new read-only <code>Map</code>.  The associated value is the

   162  * calling thread's context class loader.</p>

   163  *

   164  * @since 1.5

   165  */

   166 public class JMXConnectorFactory {

   167 

   168     /**

   169      * <p>Name of the attribute that specifies the default class

   170      * loader. This class loader is used to deserialize return values and

   171      * exceptions from remote <code>MBeanServerConnection</code>

   172      * calls.  The value associated with this attribute is an instance

   173      * of {@link ClassLoader}.</p>

   174      */

   175     public static final String DEFAULT_CLASS_LOADER =

   176         "jmx.remote.default.class.loader";

   177 

   178     /**

   179      * <p>Name of the attribute that specifies the provider packages

   180      * that are consulted when looking for the handler for a protocol.

   181      * The value associated with this attribute is a string with

   182      * package names separated by vertical bars (<code>|</code>).</p>

   183      */

   184     public static final String PROTOCOL_PROVIDER_PACKAGES =

   185         "jmx.remote.protocol.provider.pkgs";

   186 

   187     /**

   188      * <p>Name of the attribute that specifies the class

   189      * loader for loading protocol providers.

   190      * The value associated with this attribute is an instance

   191      * of {@link ClassLoader}.</p>

   192      */

   193     public static final String PROTOCOL_PROVIDER_CLASS_LOADER =

   194         "jmx.remote.protocol.provider.class.loader";

   195 

   196     private static final String PROTOCOL_PROVIDER_DEFAULT_PACKAGE =

   197         "com.sun.jmx.remote.protocol";

   198 

   199     private static final ClassLogger logger =

   200         new ClassLogger("javax.management.remote.misc", "JMXConnectorFactory");

   201 

   202     /** There are no instances of this class.  */

   203     private JMXConnectorFactory() {

   204     }

   205 

   206     /**

   207      * <p>Creates a connection to the connector server at the given

   208      * address.</p>

   209      *

   210      * <p>This method is equivalent to {@link

   211      * #connect(JMXServiceURL,Map) connect(serviceURL, null)}.</p>

   212      *

   213      * @param serviceURL the address of the connector server to

   214      * connect to.

   215      *

   216      * @return a <code>JMXConnector</code> whose {@link

   217      * JMXConnector#connect connect} method has been called.

   218      *

   219      * @exception NullPointerException if <code>serviceURL</code> is null.

   220      *

   221      * @exception IOException if the connector client or the

   222      * connection cannot be made because of a communication problem.

   223      *

   224      * @exception SecurityException if the connection cannot be made

   225      * for security reasons.

   226      */

   227     public static JMXConnector connect(JMXServiceURL serviceURL)

   228             throws IOException {

   229         return connect(serviceURL, null);

   230     }

   231 

   232     /**

   233      * <p>Creates a connection to the connector server at the given

   234      * address.</p>

   235      *

   236      * <p>This method is equivalent to:</p>

   237      *

   238      * <pre>

   239      * JMXConnector conn = JMXConnectorFactory.newJMXConnector(serviceURL,

   240      *                                                         environment);

   241      * conn.connect(environment);

   242      * </pre>

   243      *

   244      * @param serviceURL the address of the connector server to connect to.

   245      *

   246      * @param environment a set of attributes to determine how the

   247      * connection is made.  This parameter can be null.  Keys in this

   248      * map must be Strings.  The appropriate type of each associated

   249      * value depends on the attribute.  The contents of

   250      * <code>environment</code> are not changed by this call.

   251      *

   252      * @return a <code>JMXConnector</code> representing the newly-made

   253      * connection.  Each successful call to this method produces a

   254      * different object.

   255      *

   256      * @exception NullPointerException if <code>serviceURL</code> is null.

   257      *

   258      * @exception IOException if the connector client or the

   259      * connection cannot be made because of a communication problem.

   260      *

   261      * @exception SecurityException if the connection cannot be made

   262      * for security reasons.

   263      */

   264     public static JMXConnector connect(JMXServiceURL serviceURL,

   265                                        Map<String,?> environment)

   266             throws IOException {

   267         if (serviceURL == null)

   268             throw new NullPointerException("Null JMXServiceURL");

   269         JMXConnector conn = newJMXConnector(serviceURL, environment);

   270         conn.connect(environment);

   271         return conn;

   272     }

   273 

   274     private static <K,V> Map<K,V> newHashMap() {

   275         return new HashMap<K,V>();

   276     }

   277 

   278     private static <K> Map<K,Object> newHashMap(Map<K,?> map) {

   279         return new HashMap<K,Object>(map);

   280     }

   281 

   282     /**

   283      * <p>Creates a connector client for the connector server at the

   284      * given address.  The resultant client is not connected until its

   285      * {@link JMXConnector#connect(Map) connect} method is called.</p>

   286      *

   287      * @param serviceURL the address of the connector server to connect to.

   288      *

   289      * @param environment a set of attributes to determine how the

   290      * connection is made.  This parameter can be null.  Keys in this

   291      * map must be Strings.  The appropriate type of each associated

   292      * value depends on the attribute.  The contents of

   293      * <code>environment</code> are not changed by this call.

   294      *

   295      * @return a <code>JMXConnector</code> representing the new

   296      * connector client.  Each successful call to this method produces

   297      * a different object.

   298      *

   299      * @exception NullPointerException if <code>serviceURL</code> is null.

   300      *

   301      * @exception IOException if the connector client cannot be made

   302      * because of a communication problem.

   303      *

   304      * @exception MalformedURLException if there is no provider for the

   305      * protocol in <code>serviceURL</code>.

   306      *

   307      * @exception JMXProviderException if there is a provider for the

   308      * protocol in <code>serviceURL</code> but it cannot be used for

   309      * some reason.

   310      */

   311     public static JMXConnector newJMXConnector(JMXServiceURL serviceURL,

   312                                                Map<String,?> environment)

   313             throws IOException {

   314 

   315         final Map<String,Object> envcopy;

   316         if (environment == null)

   317             envcopy = newHashMap();

   318         else {

   319             EnvHelp.checkAttributes(environment);

   320             envcopy = newHashMap(environment);

   321         }

   322 

   323         final ClassLoader loader = resolveClassLoader(envcopy);

   324         final Class<JMXConnectorProvider> targetInterface =

   325                 JMXConnectorProvider.class;

   326         final String protocol = serviceURL.getProtocol();

   327         final String providerClassName = "ClientProvider";

   328         final JMXServiceURL providerURL = serviceURL;

   329 

   330         JMXConnectorProvider provider = getProvider(providerURL, envcopy,

   331                                                providerClassName,

   332                                                targetInterface,

   333                                                loader);

   334 

   335         IOException exception = null;

   336         if (provider == null) {

   337             // Loader is null when context class loader is set to null

   338             // and no loader has been provided in map.

   339             // com.sun.jmx.remote.util.Service class extracted from j2se

   340             // provider search algorithm doesn't handle well null classloader.

   341             if (loader != null) {

   342                 try {

   343                     JMXConnector connection =

   344                         getConnectorAsService(loader, providerURL, envcopy);

   345                     if (connection != null)

   346                         return connection;

   347                 } catch (JMXProviderException e) {

   348                     throw e;

   349                 } catch (IOException e) {

   350                     exception = e;

   351                 }

   352             }

   353             provider = getProvider(protocol, PROTOCOL_PROVIDER_DEFAULT_PACKAGE,

   354                             JMXConnectorFactory.class.getClassLoader(),

   355                             providerClassName, targetInterface);

   356         }

   357 

   358         if (provider == null) {

   359             MalformedURLException e =

   360                 new MalformedURLException("Unsupported protocol: " + protocol);

   361             if (exception == null) {

   362                 throw e;

   363             } else {

   364                 throw EnvHelp.initCause(e, exception);

   365             }

   366         }

   367 

   368         final Map<String,Object> fixedenv =

   369                 Collections.unmodifiableMap(envcopy);

   370 

   371         return provider.newJMXConnector(serviceURL, fixedenv);

   372     }

   373 

   374     private static String resolvePkgs(Map<String, ?> env)

   375             throws JMXProviderException {

   376 

   377         Object pkgsObject = null;

   378 

   379         if (env != null)

   380             pkgsObject = env.get(PROTOCOL_PROVIDER_PACKAGES);

   381 

   382         if (pkgsObject == null)

   383             pkgsObject =

   384                 AccessController.doPrivileged(new PrivilegedAction<String>() {

   385                     public String run() {

   386                         return System.getProperty(PROTOCOL_PROVIDER_PACKAGES);

   387                     }

   388                 });

   389 

   390         if (pkgsObject == null)

   391             return null;

   392 

   393         if (!(pkgsObject instanceof String)) {

   394             final String msg = "Value of " + PROTOCOL_PROVIDER_PACKAGES +

   395                 " parameter is not a String: " +

   396                 pkgsObject.getClass().getName();

   397             throw new JMXProviderException(msg);

   398         }

   399 

   400         final String pkgs = (String) pkgsObject;

   401         if (pkgs.trim().equals(""))

   402             return null;

   403 

   404         // pkgs may not contain an empty element

   405         if (pkgs.startsWith("|") || pkgs.endsWith("|") ||

   406             pkgs.indexOf("||") >= 0) {

   407             final String msg = "Value of " + PROTOCOL_PROVIDER_PACKAGES +

   408                 " contains an empty element: " + pkgs;

   409             throw new JMXProviderException(msg);

   410         }

   411 

   412         return pkgs;

   413     }

   414 

   415     static <T> T getProvider(JMXServiceURL serviceURL,

   416                              final Map<String, Object> environment,

   417                              String providerClassName,

   418                              Class<T> targetInterface,

   419                              final ClassLoader loader)

   420             throws IOException {

   421 

   422         final String protocol = serviceURL.getProtocol();

   423 

   424         final String pkgs = resolvePkgs(environment);

   425 

   426         T instance = null;

   427 

   428         if (pkgs != null) {

   429             instance =

   430                 getProvider(protocol, pkgs, loader, providerClassName,

   431                             targetInterface);

   432 

   433             if (instance != null) {

   434                 boolean needsWrap = (loader != instance.getClass().getClassLoader());

   435                 environment.put(PROTOCOL_PROVIDER_CLASS_LOADER, needsWrap ? wrap(loader) : loader);

   436             }

   437         }

   438 

   439         return instance;

   440     }

   441 

   442     static <T> Iterator<T> getProviderIterator(final Class<T> providerClass,

   443                                                final ClassLoader loader) {

   444        ServiceLoader<T> serviceLoader =

   445                 ServiceLoader.load(providerClass, loader);

   446        return serviceLoader.iterator();

   447     }

   448 

   449     private static ClassLoader wrap(final ClassLoader parent) {

   450         return parent != null ? AccessController.doPrivileged(new PrivilegedAction<ClassLoader>() {

   451             @Override

   452             public ClassLoader run() {

   453                 return new ClassLoader(parent) {

   454                     @Override

   455                     protected Class<?> loadClass(String name, boolean resolve) throws ClassNotFoundException {

   456                         ReflectUtil.checkPackageAccess(name);

   457                         return super.loadClass(name, resolve);

   458                     }

   459                 };

   460             }

   461         }) : null;

   462     }

   463 

   464     private static JMXConnector getConnectorAsService(ClassLoader loader,

   465                                                       JMXServiceURL url,

   466                                                       Map<String, ?> map)

   467         throws IOException {

   468 

   469         Iterator<JMXConnectorProvider> providers =

   470                 getProviderIterator(JMXConnectorProvider.class, loader);

   471         JMXConnector connection;

   472         IOException exception = null;

   473         while (providers.hasNext()) {

   474             JMXConnectorProvider provider = providers.next();

   475             try {

   476                 connection = provider.newJMXConnector(url, map);

   477                 return connection;

   478             } catch (JMXProviderException e) {

   479                 throw e;

   480             } catch (Exception e) {

   481                 if (logger.traceOn())

   482                     logger.trace("getConnectorAsService",

   483                                  "URL[" + url +

   484                                  "] Service provider exception: " + e);

   485                 if (!(e instanceof MalformedURLException)) {

   486                     if (exception == null) {

   487                         if (e instanceof IOException) {

   488                             exception = (IOException) e;

   489                         } else {

   490                             exception = EnvHelp.initCause(

   491                                 new IOException(e.getMessage()), e);

   492                         }

   493                     }

   494                 }

   495                 continue;

   496             }

   497         }

   498         if (exception == null)

   499             return null;

   500         else

   501             throw exception;

   502     }

   503 

   504     static <T> T getProvider(String protocol,

   505                               String pkgs,

   506                               ClassLoader loader,

   507                               String providerClassName,

   508                               Class<T> targetInterface)

   509             throws IOException {

   510 

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

   512 

   513         while (tokenizer.hasMoreTokens()) {

   514             String pkg = tokenizer.nextToken();

   515             String className = (pkg + "." + protocol2package(protocol) +

   516                                 "." + providerClassName);

   517             Class<?> providerClass;

   518             try {

   519                 providerClass = Class.forName(className, true, loader);

   520             } catch (ClassNotFoundException e) {

   521                 //Add trace.

   522                 continue;

   523             }

   524 

   525             if (!targetInterface.isAssignableFrom(providerClass)) {

   526                 final String msg =

   527                     "Provider class does not implement " +

   528                     targetInterface.getName() + ": " +

   529                     providerClass.getName();

   530                 throw new JMXProviderException(msg);

   531             }

   532 

   533             // We have just proved that this cast is correct

   534             Class<? extends T> providerClassT = Util.cast(providerClass);

   535             try {

   536                 return providerClassT.newInstance();

   537             } catch (Exception e) {

   538                 final String msg =

   539                     "Exception when instantiating provider [" + className +

   540                     "]";

   541                 throw new JMXProviderException(msg, e);

   542             }

   543         }

   544 

   545         return null;

   546     }

   547 

   548     static ClassLoader resolveClassLoader(Map<String, ?> environment) {

   549         ClassLoader loader = null;

   550 

   551         if (environment != null) {

   552             try {

   553                 loader = (ClassLoader)

   554                     environment.get(PROTOCOL_PROVIDER_CLASS_LOADER);

   555             } catch (ClassCastException e) {

   556                 final String msg =

   557                     "The ClassLoader supplied in the environment map using " +

   558                     "the " + PROTOCOL_PROVIDER_CLASS_LOADER +

   559                     " attribute is not an instance of java.lang.ClassLoader";

   560                 throw new IllegalArgumentException(msg);

   561             }

   562         }

   563 

   564         if (loader == null) {

   565             loader = Thread.currentThread().getContextClassLoader();

   566         }

   567 

   568         return loader;

   569     }

   570 

   571     private static String protocol2package(String protocol) {

   572         return protocol.replace('+', '.').replace('-', '_');

   573     }

   574 }