1 /* 2 * Copyright (c) 2003, 2015, 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 29 import com.sun.jmx.remote.util.ClassLogger; 30 import com.sun.jmx.remote.util.EnvHelp; 31 32 import java.io.IOException; 33 import java.net.MalformedURLException; 34 import java.util.Collections; 35 import java.util.HashMap; 36 import java.util.Iterator; 37 import java.util.Map; 38 39 import javax.management.MBeanServer; 40 41 /** 42 * <p>Factory to create JMX API connector servers. There 43 * are no instances of this class.</p> 44 * 45 * <p>Each connector server is created by an instance of {@link 46 * JMXConnectorServerProvider}. This instance is found as follows. Suppose 47 * the given {@link JMXServiceURL} looks like 48 * <code>"service:jmx:<em>protocol</em>:<em>remainder</em>"</code>. 49 * Then the factory will attempt to find the appropriate {@link 50 * JMXConnectorServerProvider} for <code><em>protocol</em></code>. Each 51 * occurrence of the character <code>+</code> or <code>-</code> in 52 * <code><em>protocol</em></code> is replaced by <code>.</code> or 53 * <code>_</code>, respectively.</p> 54 * 55 * <p>A <em>provider package list</em> is searched for as follows:</p> 56 * 57 * <ol> 58 * 59 * <li>If the <code>environment</code> parameter to {@link 60 * #newJMXConnectorServer(JMXServiceURL,Map,MBeanServer) 61 * newJMXConnectorServer} contains the key 62 * <code>jmx.remote.protocol.provider.pkgs</code> then the associated 63 * value is the provider package list. 64 * 65 * <li>Otherwise, if the system property 66 * <code>jmx.remote.protocol.provider.pkgs</code> exists, then its value 67 * is the provider package list. 68 * 69 * <li>Otherwise, there is no provider package list. 70 * 71 * </ol> 72 * 73 * <p>The provider package list is a string that is interpreted as a 74 * list of non-empty Java package names separated by vertical bars 75 * (<code>|</code>). If the string is empty, then so is the provider 76 * package list. If the provider package list is not a String, or if 77 * it contains an element that is an empty string, a {@link 78 * JMXProviderException} is thrown.</p> 79 * 80 * <p>If the provider package list exists and is not empty, then for 81 * each element <code><em>pkg</em></code> of the list, the factory 82 * will attempt to load the class 83 * 84 * <blockquote> 85 * <code><em>pkg</em>.<em>protocol</em>.ServerProvider</code> 86 * </blockquote> 87 88 * <p>If the <code>environment</code> parameter to {@link 89 * #newJMXConnectorServer(JMXServiceURL, Map, MBeanServer) 90 * newJMXConnectorServer} contains the key 91 * <code>jmx.remote.protocol.provider.class.loader</code> then the 92 * associated value is the class loader to use to load the provider. 93 * If the associated value is not an instance of {@link 94 * java.lang.ClassLoader}, an {@link 95 * java.lang.IllegalArgumentException} is thrown.</p> 96 * 97 * <p>If the <code>jmx.remote.protocol.provider.class.loader</code> 98 * key is not present in the <code>environment</code> parameter, the 99 * calling thread's context class loader is used.</p> 100 * 101 * <p>If the attempt to load this class produces a {@link 102 * ClassNotFoundException}, the search for a handler continues with 103 * the next element of the list.</p> 104 * 105 * <p>Otherwise, a problem with the provider found is signalled by a 106 * {@link JMXProviderException} whose {@link 107 * JMXProviderException#getCause() <em>cause</em>} indicates the 108 * underlying exception, as follows:</p> 109 * 110 * <ul> 111 * 112 * <li>if the attempt to load the class produces an exception other 113 * than <code>ClassNotFoundException</code>, that is the 114 * <em>cause</em>; 115 * 116 * <li>if {@link Class#newInstance()} for the class produces an 117 * exception, that is the <em>cause</em>. 118 * 119 * </ul> 120 * 121 * <p>If no provider is found by the above steps, including the 122 * default case where there is no provider package list, then the 123 * implementation will use its own provider for 124 * <code><em>protocol</em></code>, or it will throw a 125 * <code>MalformedURLException</code> if there is none. An 126 * implementation may choose to find providers by other means. For 127 * example, it may support the <a 128 * href="{@docRoot}/../technotes/guides/jar/jar.html#Service%20Provider"> 129 * JAR conventions for service providers</a>, where the service 130 * interface is <code>JMXConnectorServerProvider</code>.</p> 131 * 132 * <p>Every implementation must support the RMI connector protocol with 133 * the default RMI transport, specified with string <code>rmi</code>. 134 * </p> 135 * 136 * <p>Once a provider is found, the result of the 137 * <code>newJMXConnectorServer</code> method is the result of calling 138 * {@link 139 * JMXConnectorServerProvider#newJMXConnectorServer(JMXServiceURL, 140 * Map, MBeanServer) newJMXConnectorServer} on the provider.</p> 141 * 142 * <p>The <code>Map</code> parameter passed to the 143 * <code>JMXConnectorServerProvider</code> is a new read-only 144 * <code>Map</code> that contains all the entries that were in the 145 * <code>environment</code> parameter to {@link 146 * #newJMXConnectorServer(JMXServiceURL,Map,MBeanServer) 147 * JMXConnectorServerFactory.newJMXConnectorServer}, if there was one. 148 * Additionally, if the 149 * <code>jmx.remote.protocol.provider.class.loader</code> key is not 150 * present in the <code>environment</code> parameter, it is added to 151 * the new read-only <code>Map</code>. The associated value is the 152 * calling thread's context class loader.</p> 153 * 154 * @since 1.5 155 */ 156 public class JMXConnectorServerFactory { 157 158 /** 159 * <p>Name of the attribute that specifies the default class 160 * loader. This class loader is used to deserialize objects in 161 * requests received from the client, possibly after consulting an 162 * MBean-specific class loader. The value associated with this 163 * attribute is an instance of {@link ClassLoader}.</p> 164 */ 165 public static final String DEFAULT_CLASS_LOADER = 166 JMXConnectorFactory.DEFAULT_CLASS_LOADER; 167 168 /** 169 * <p>Name of the attribute that specifies the default class 170 * loader MBean name. This class loader is used to deserialize objects in 171 * requests received from the client, possibly after consulting an 172 * MBean-specific class loader. The value associated with this 173 * attribute is an instance of {@link javax.management.ObjectName 174 * ObjectName}.</p> 175 */ 176 public static final String DEFAULT_CLASS_LOADER_NAME = 177 "jmx.remote.default.class.loader.name"; 178 179 /** 180 * <p>Name of the attribute that specifies the provider packages 181 * that are consulted when looking for the handler for a protocol. 182 * The value associated with this attribute is a string with 183 * package names separated by vertical bars (<code>|</code>).</p> 184 */ 185 public static final String PROTOCOL_PROVIDER_PACKAGES = 186 "jmx.remote.protocol.provider.pkgs"; 187 188 /** 189 * <p>Name of the attribute that specifies the class 190 * loader for loading protocol providers. 191 * The value associated with this attribute is an instance 192 * of {@link ClassLoader}.</p> 193 */ 194 public static final String PROTOCOL_PROVIDER_CLASS_LOADER = 195 "jmx.remote.protocol.provider.class.loader"; 196 197 private static final String PROTOCOL_PROVIDER_DEFAULT_PACKAGE = 198 "com.sun.jmx.remote.protocol"; 199 200 private static final ClassLogger logger = 201 new ClassLogger("javax.management.remote.misc","JMXConnectorServerFactory"); 202 203 /** There are no instances of this class. */ 204 private JMXConnectorServerFactory() { 205 } 206 207 private static JMXConnectorServer 208 getConnectorServerAsService(ClassLoader loader, 209 JMXServiceURL url, 210 Map<String, ?> map, 211 MBeanServer mbs) 212 throws IOException { 213 Iterator<JMXConnectorServerProvider> providers = 214 JMXConnectorFactory. 215 getProviderIterator(JMXConnectorServerProvider.class, loader); 216 217 IOException exception = null; 218 while (providers.hasNext()) { 219 try { 220 return providers.next().newJMXConnectorServer(url, map, mbs); 221 } catch (JMXProviderException e) { 222 throw e; 223 } catch (Exception e) { 224 if (logger.traceOn()) 225 logger.trace("getConnectorAsService", 226 "URL[" + url + 227 "] Service provider exception: " + e); 228 if (!(e instanceof MalformedURLException)) { 229 if (exception == null) { 230 if (e instanceof IOException) { 231 exception = (IOException) e; 232 } else { 233 exception = EnvHelp.initCause( 234 new IOException(e.getMessage()), e); 235 } 236 } 237 } 238 continue; 239 } 240 } 241 if (exception == null) 242 return null; 243 else 244 throw exception; 245 } 246 247 /** 248 * <p>Creates a connector server at the given address. The 249 * resultant server is not started until its {@link 250 * JMXConnectorServer#start() start} method is called.</p> 251 * 252 * @param serviceURL the address of the new connector server. The 253 * actual address of the new connector server, as returned by its 254 * {@link JMXConnectorServer#getAddress() getAddress} method, will 255 * not necessarily be exactly the same. For example, it might 256 * include a port number if the original address did not. 257 * 258 * @param environment a set of attributes to control the new 259 * connector server's behavior. This parameter can be null. 260 * Keys in this map must be Strings. The appropriate type of each 261 * associated value depends on the attribute. The contents of 262 * <code>environment</code> are not changed by this call. 263 * 264 * @param mbeanServer the MBean server that this connector server 265 * is attached to. Null if this connector server will be attached 266 * to an MBean server by being registered in it. 267 * 268 * @return a <code>JMXConnectorServer</code> representing the new 269 * connector server. Each successful call to this method produces 270 * a different object. 271 * 272 * @exception NullPointerException if <code>serviceURL</code> is null. 273 * 274 * @exception IOException if the connector server cannot be made 275 * because of a communication problem. 276 * 277 * @exception MalformedURLException if there is no provider for the 278 * protocol in <code>serviceURL</code>. 279 * 280 * @exception JMXProviderException if there is a provider for the 281 * protocol in <code>serviceURL</code> but it cannot be used for 282 * some reason. 283 */ 284 public static JMXConnectorServer 285 newJMXConnectorServer(JMXServiceURL serviceURL, 286 Map<String,?> environment, 287 MBeanServer mbeanServer) 288 throws IOException { 289 Map<String, Object> envcopy; 290 if (environment == null) 291 envcopy = new HashMap<String, Object>(); 292 else { 293 EnvHelp.checkAttributes(environment); 294 envcopy = new HashMap<String, Object>(environment); 295 } 296 297 final Class<JMXConnectorServerProvider> targetInterface = 298 JMXConnectorServerProvider.class; 299 final ClassLoader loader = 300 JMXConnectorFactory.resolveClassLoader(envcopy); 301 final String protocol = serviceURL.getProtocol(); 302 final String providerClassName = "ServerProvider"; 303 304 JMXConnectorServerProvider provider = 305 JMXConnectorFactory.getProvider(serviceURL, 306 envcopy, 307 providerClassName, 308 targetInterface, 309 loader); 310 311 IOException exception = null; 312 if (provider == null) { 313 // Loader is null when context class loader is set to null 314 // and no loader has been provided in map. 315 // com.sun.jmx.remote.util.Service class extracted from j2se 316 // provider search algorithm doesn't handle well null classloader. 317 if (loader != null) { 318 try { 319 JMXConnectorServer connection = 320 getConnectorServerAsService(loader, 321 serviceURL, 322 envcopy, 323 mbeanServer); 324 if (connection != null) 325 return connection; 326 } catch (JMXProviderException e) { 327 throw e; 328 } catch (IOException e) { 329 exception = e; 330 } 331 } 332 provider = 333 JMXConnectorFactory.getProvider( 334 protocol, 335 PROTOCOL_PROVIDER_DEFAULT_PACKAGE, 336 JMXConnectorFactory.class.getClassLoader(), 337 providerClassName, 338 targetInterface); 339 } 340 341 if (provider == null) { 342 MalformedURLException e = 343 new MalformedURLException("Unsupported protocol: " + protocol); 344 if (exception == null) { 345 throw e; 346 } else { 347 throw EnvHelp.initCause(e, exception); 348 } 349 } 350 351 envcopy = Collections.unmodifiableMap(envcopy); 352 353 return provider.newJMXConnectorServer(serviceURL, 354 envcopy, 355 mbeanServer); 356 } 357 }