1. /*
  2. * @(#)ClassLoaderRepository.java 1.18 03/12/19
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.management.loading;
  8. import javax.management.MBeanServer; // for Javadoc
  9. /**
  10. * <p>Instances of this interface are used to keep the list of ClassLoaders
  11. * registered in an MBean Server.
  12. * They provide the necessary methods to load classes using the registered
  13. * ClassLoaders.</p>
  14. *
  15. * <p>The first ClassLoader in a <code>ClassLoaderRepository</code> is
  16. * always the MBean Server's own ClassLoader.</p>
  17. *
  18. * <p>When an MBean is registered in an MBean Server, if it is of a
  19. * subclass of {@link java.lang.ClassLoader} and if it does not
  20. * implement the interface {@link PrivateClassLoader}, it is added to
  21. * the end of the MBean Server's <code>ClassLoaderRepository</code>.
  22. * If it is subsequently unregistered from the MBean Server, it is
  23. * removed from the <code>ClassLoaderRepository</code>.</p>
  24. *
  25. * <p>The order of MBeans in the <code>ClassLoaderRepository</code> is
  26. * significant. For any two MBeans <em>X</em> and <em>Y</em> in the
  27. * <code>ClassLoaderRepository</code>, <em>X</em> must appear before
  28. * <em>Y</em> if the registration of <em>X</em> was completed before
  29. * the registration of <em>Y</em> started. If <em>X</em> and
  30. * <em>Y</em> were registered concurrently, their order is
  31. * indeterminate. The registration of an MBean corresponds to the
  32. * call to {@link MBeanServer#registerMBean} or one of the {@link
  33. * MBeanServer}<code>.createMBean</code> methods.</p>
  34. *
  35. * @see javax.management.MBeanServerFactory
  36. *
  37. * @since 1.5
  38. * @since.unbundled JMX 1.1
  39. */
  40. public interface ClassLoaderRepository {
  41. /**
  42. * <p>Load the given class name through the list of class loaders.
  43. * Each ClassLoader in turn from the ClassLoaderRepository is
  44. * asked to load the class via its {@link
  45. * ClassLoader#loadClass(String)} method. If it successfully
  46. * returns a {@link Class} object, that is the result of this
  47. * method. If it throws a {@link ClassNotFoundException}, the
  48. * search continues with the next ClassLoader. If it throws
  49. * another exception, the exception is propagated from this
  50. * method. If the end of the list is reached, a {@link
  51. * ClassNotFoundException} is thrown.</p>
  52. *
  53. * @param className The name of the class to be loaded.
  54. *
  55. * @return the loaded class.
  56. *
  57. * @exception ClassNotFoundException The specified class could not be
  58. * found.
  59. */
  60. public Class loadClass(String className)
  61. throws ClassNotFoundException;
  62. /**
  63. * <p>Load the given class name through the list of class loaders,
  64. * excluding the given one. Each ClassLoader in turn from the
  65. * ClassLoaderRepository, except <code>exclude</code>, is asked to
  66. * load the class via its {@link ClassLoader#loadClass(String)}
  67. * method. If it successfully returns a {@link Class} object,
  68. * that is the result of this method. If it throws a {@link
  69. * ClassNotFoundException}, the search continues with the next
  70. * ClassLoader. If it throws another exception, the exception is
  71. * propagated from this method. If the end of the list is
  72. * reached, a {@link ClassNotFoundException} is thrown.</p>
  73. *
  74. * <p>Be aware that if a ClassLoader in the ClassLoaderRepository
  75. * calls this method from its {@link ClassLoader#loadClass(String)
  76. * loadClass} method, it exposes itself to a deadlock if another
  77. * ClassLoader in the ClassLoaderRepository does the same thing at
  78. * the same time. The {@link #loadClassBefore} method is
  79. * recommended to avoid the risk of deadlock.</p>
  80. *
  81. * @param className The name of the class to be loaded.
  82. * @param exclude The class loader to be excluded. May be null,
  83. * in which case this method is equivalent to {@link #loadClass
  84. * loadClass(className)}.
  85. *
  86. * @return the loaded class.
  87. *
  88. * @exception ClassNotFoundException The specified class could not
  89. * be found.
  90. */
  91. public Class loadClassWithout(ClassLoader exclude,
  92. String className)
  93. throws ClassNotFoundException;
  94. /**
  95. * <p>Load the given class name through the list of class loaders,
  96. * stopping at the given one. Each ClassLoader in turn from the
  97. * ClassLoaderRepository is asked to load the class via its {@link
  98. * ClassLoader#loadClass(String)} method. If it successfully
  99. * returns a {@link Class} object, that is the result of this
  100. * method. If it throws a {@link ClassNotFoundException}, the
  101. * search continues with the next ClassLoader. If it throws
  102. * another exception, the exception is propagated from this
  103. * method. If the search reaches <code>stop</code> or the end of
  104. * the list, a {@link ClassNotFoundException} is thrown.</p>
  105. *
  106. * <p>Typically this method is called from the {@link
  107. * ClassLoader#loadClass(String) loadClass} method of
  108. * <code>stop</code>, to consult loaders that appear before it
  109. * in the <code>ClassLoaderRepository</code>. By stopping the
  110. * search as soon as <code>stop</code> is reached, a potential
  111. * deadlock with concurrent class loading is avoided.</p>
  112. *
  113. * @param className The name of the class to be loaded.
  114. * @param stop The class loader at which to stop. May be null, in
  115. * which case this method is equivalent to {@link #loadClass(String)
  116. * loadClass(className)}.
  117. *
  118. * @return the loaded class.
  119. *
  120. * @exception ClassNotFoundException The specified class could not
  121. * be found.
  122. *
  123. * @since.unbundled JMX 1.2
  124. */
  125. public Class loadClassBefore(ClassLoader stop,
  126. String className)
  127. throws ClassNotFoundException;
  128. }