1 /* 2 * Copyright (c) 2002, 2007, 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.loading; 27 28 import javax.management.MBeanServer; // for Javadoc 29 30 /** 31 * <p>Instances of this interface are used to keep the list of ClassLoaders 32 * registered in an MBean Server. 33 * They provide the necessary methods to load classes using the registered 34 * ClassLoaders.</p> 35 * 36 * <p>The first ClassLoader in a <code>ClassLoaderRepository</code> is 37 * always the MBean Server's own ClassLoader.</p> 38 * 39 * <p>When an MBean is registered in an MBean Server, if it is of a 40 * subclass of {@link java.lang.ClassLoader} and if it does not 41 * implement the interface {@link PrivateClassLoader}, it is added to 42 * the end of the MBean Server's <code>ClassLoaderRepository</code>. 43 * If it is subsequently unregistered from the MBean Server, it is 44 * removed from the <code>ClassLoaderRepository</code>.</p> 45 * 46 * <p>The order of MBeans in the <code>ClassLoaderRepository</code> is 47 * significant. For any two MBeans <em>X</em> and <em>Y</em> in the 48 * <code>ClassLoaderRepository</code>, <em>X</em> must appear before 49 * <em>Y</em> if the registration of <em>X</em> was completed before 50 * the registration of <em>Y</em> started. If <em>X</em> and 51 * <em>Y</em> were registered concurrently, their order is 52 * indeterminate. The registration of an MBean corresponds to the 53 * call to {@link MBeanServer#registerMBean} or one of the {@link 54 * MBeanServer}<code>.createMBean</code> methods.</p> 55 * 56 * @see javax.management.MBeanServerFactory 57 * 58 * @since 1.5 59 */ 60 public interface ClassLoaderRepository { 61 62 /** 63 * <p>Load the given class name through the list of class loaders. 64 * Each ClassLoader in turn from the ClassLoaderRepository is 65 * asked to load the class via its {@link 66 * ClassLoader#loadClass(String)} method. If it successfully 67 * returns a {@link Class} object, that is the result of this 68 * method. If it throws a {@link ClassNotFoundException}, the 69 * search continues with the next ClassLoader. If it throws 70 * another exception, the exception is propagated from this 71 * method. If the end of the list is reached, a {@link 72 * ClassNotFoundException} is thrown.</p> 73 * 74 * @param className The name of the class to be loaded. 75 * 76 * @return the loaded class. 77 * 78 * @exception ClassNotFoundException The specified class could not be 79 * found. 80 */ loadClass(String className)81 public Class<?> loadClass(String className) 82 throws ClassNotFoundException; 83 84 /** 85 * <p>Load the given class name through the list of class loaders, 86 * excluding the given one. Each ClassLoader in turn from the 87 * ClassLoaderRepository, except <code>exclude</code>, is asked to 88 * load the class via its {@link ClassLoader#loadClass(String)} 89 * method. If it successfully returns a {@link Class} object, 90 * that is the result of this method. If it throws a {@link 91 * ClassNotFoundException}, the search continues with the next 92 * ClassLoader. If it throws another exception, the exception is 93 * propagated from this method. If the end of the list is 94 * reached, a {@link ClassNotFoundException} is thrown.</p> 95 * 96 * <p>Be aware that if a ClassLoader in the ClassLoaderRepository 97 * calls this method from its {@link ClassLoader#loadClass(String) 98 * loadClass} method, it exposes itself to a deadlock if another 99 * ClassLoader in the ClassLoaderRepository does the same thing at 100 * the same time. The {@link #loadClassBefore} method is 101 * recommended to avoid the risk of deadlock.</p> 102 * 103 * @param className The name of the class to be loaded. 104 * @param exclude The class loader to be excluded. May be null, 105 * in which case this method is equivalent to {@link #loadClass 106 * loadClass(className)}. 107 * 108 * @return the loaded class. 109 * 110 * @exception ClassNotFoundException The specified class could not 111 * be found. 112 */ loadClassWithout(ClassLoader exclude, String className)113 public Class<?> loadClassWithout(ClassLoader exclude, 114 String className) 115 throws ClassNotFoundException; 116 117 /** 118 * <p>Load the given class name through the list of class loaders, 119 * stopping at the given one. Each ClassLoader in turn from the 120 * ClassLoaderRepository is asked to load the class via its {@link 121 * ClassLoader#loadClass(String)} method. If it successfully 122 * returns a {@link Class} object, that is the result of this 123 * method. If it throws a {@link ClassNotFoundException}, the 124 * search continues with the next ClassLoader. If it throws 125 * another exception, the exception is propagated from this 126 * method. If the search reaches <code>stop</code> or the end of 127 * the list, a {@link ClassNotFoundException} is thrown.</p> 128 * 129 * <p>Typically this method is called from the {@link 130 * ClassLoader#loadClass(String) loadClass} method of 131 * <code>stop</code>, to consult loaders that appear before it 132 * in the <code>ClassLoaderRepository</code>. By stopping the 133 * search as soon as <code>stop</code> is reached, a potential 134 * deadlock with concurrent class loading is avoided.</p> 135 * 136 * @param className The name of the class to be loaded. 137 * @param stop The class loader at which to stop. May be null, in 138 * which case this method is equivalent to {@link #loadClass(String) 139 * loadClass(className)}. 140 * 141 * @return the loaded class. 142 * 143 * @exception ClassNotFoundException The specified class could not 144 * be found. 145 * 146 */ loadClassBefore(ClassLoader stop, String className)147 public Class<?> loadClassBefore(ClassLoader stop, 148 String className) 149 throws ClassNotFoundException; 150 151 } 152