1. /*

  2.  * @(#)RMIClassLoaderSpi.java	1.14 04/05/05

  3.  *

  4.  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.

  5.  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.

  6.  */

  7. 

  8. package java.rmi.server;

  9. 

  10. import java.net.MalformedURLException;

  11. import java.net.URL;

  12. 

  13. /**

  14.  * <code>RMIClassLoaderSpi</code> is the service provider interface for

  15.  * <code>RMIClassLoader</code>.

  16.  *

  17.  * In particular, an <code>RMIClassLoaderSpi</code> instance provides an

  18.  * implementation of the following static methods of

  19.  * <code>RMIClassLoader</code>:

  20.  *

  21.  * <ul>

  22.  *

  23.  * <li>{@link RMIClassLoader#loadClass(URL,String)}

  24.  * <li>{@link RMIClassLoader#loadClass(String,String)}

  25.  * <li>{@link RMIClassLoader#loadClass(String,String,ClassLoader)}

  26.  * <li>{@link RMIClassLoader#loadProxyClass(String,String[],ClassLoader)}

  27.  * <li>{@link RMIClassLoader#getClassLoader(String)}

  28.  * <li>{@link RMIClassLoader#getClassAnnotation(Class)}

  29.  *

  30.  * </ul>

  31.  *

  32.  * When one of those methods is invoked, its behavior is to delegate

  33.  * to a corresponding method on an instance of this class.

  34.  * The details of how each method delegates to the provider instance is

  35.  * described in the documentation for each particular method.

  36.  * See the documentation for {@link RMIClassLoader} for a description

  37.  * of how a provider instance is chosen.

  38.  *

  39.  * @version	1.14, 04/05/05

  40.  * @author	Peter Jones

  41.  * @author	Laird Dornin

  42.  * @see		RMIClassLoader

  43.  * @since	JDK1.4

  44.  */

  45. public abstract class RMIClassLoaderSpi {

  46. 

  47.     /**

  48.      * Provides the implementation for

  49.      * {@link RMIClassLoader#loadClass(URL,String)},

  50.      * {@link RMIClassLoader#loadClass(String,String)}, and

  51.      * {@link RMIClassLoader#loadClass(String,String,ClassLoader)}.

  52.      *

  53.      * Loads a class from a codebase URL path, optionally using the

  54.      * supplied loader.

  55.      *

  56.      * Typically, a provider implementation will attempt to

  57.      * resolve the named class using the given <code>defaultLoader</code>,

  58.      * if specified, before attempting to resolve the class from the

  59.      * codebase URL path.

  60.      *

  61.      * <p>An implementation of this method must either return a class

  62.      * with the given name or throw an exception.

  63.      *

  64.      * @param	codebase the list of URLs (separated by spaces) to load

  65.      * the class from, or <code>null</code>

  66.      *

  67.      * @param	name the name of the class to load

  68.      *

  69.      * @param	defaultLoader additional contextual class loader

  70.      * to use, or <code>null</code>

  71.      *

  72.      * @return	the <code>Class</code> object representing the loaded class

  73.      *

  74.      * @throws	MalformedURLException if <code>codebase</code> is

  75.      * non-<code>null</code> and contains an invalid URL, or

  76.      * if <code>codebase</code> is <code>null</code> and a provider-specific

  77.      * URL used to load classes is invalid

  78.      *

  79.      * @throws	ClassNotFoundException if a definition for the class

  80.      * could not be found at the specified location

  81.      */

  82.     public abstract Class<?> loadClass(String codebase, String name,

  83. 				       ClassLoader defaultLoader)

  84. 	throws MalformedURLException, ClassNotFoundException;

  85.     

  86.     /**

  87.      * Provides the implementation for

  88.      * {@link RMIClassLoader#loadProxyClass(String,String[],ClassLoader)}.

  89.      *

  90.      * Loads a dynamic proxy class (see {@link java.lang.reflect.Proxy}

  91.      * that implements a set of interfaces with the given names

  92.      * from a codebase URL path, optionally using the supplied loader.

  93.      * 

  94.      * <p>An implementation of this method must either return a proxy

  95.      * class that implements the named interfaces or throw an exception.

  96.      *

  97.      * @param	codebase the list of URLs (space-separated) to load

  98.      * classes from, or <code>null</code>

  99.      *

  100.      * @param	interfaces the names of the interfaces for the proxy class

  101.      * to implement

  102.      *

  103.      * @return	a dynamic proxy class that implements the named interfaces

  104.      *

  105.      * @param	defaultLoader additional contextual class loader

  106.      * to use, or <code>null</code>

  107.      *

  108.      * @throws	MalformedURLException if <code>codebase</code> is

  109.      * non-<code>null</code> and contains an invalid URL, or

  110.      * if <code>codebase</code> is <code>null</code> and a provider-specific

  111.      * URL used to load classes is invalid

  112.      *

  113.      * @throws	ClassNotFoundException if a definition for one of

  114.      * the named interfaces could not be found at the specified location,

  115.      * or if creation of the dynamic proxy class failed (such as if

  116.      * {@link java.lang.reflect.Proxy#getProxyClass(ClassLoader,Class[])}

  117.      * would throw an <code>IllegalArgumentException</code> for the given

  118.      * interface list)

  119.      */

  120.     public abstract Class<?> loadProxyClass(String codebase,

  121. 					    String[] interfaces,

  122. 					    ClassLoader defaultLoader)

  123. 	throws MalformedURLException, ClassNotFoundException;

  124. 

  125.     /**

  126.      * Provides the implementation for

  127.      * {@link RMIClassLoader#getClassLoader(String)}.

  128.      *

  129.      * Returns a class loader that loads classes from the given codebase

  130.      * URL path.

  131.      *

  132.      * <p>If there is a security manger, its <code>checkPermission</code>

  133.      * method will be invoked with a

  134.      * <code>RuntimePermission("getClassLoader")</code> permission;

  135.      * this could result in a <code>SecurityException</code>.

  136.      * The implementation of this method may also perform further security

  137.      * checks to verify that the calling context has permission to connect

  138.      * to all of the URLs in the codebase URL path.

  139.      *

  140.      * @param	codebase the list of URLs (space-separated) from which

  141.      * the returned class loader will load classes from, or <code>null</code>

  142.      *

  143.      * @return a class loader that loads classes from the given codebase URL

  144.      * path

  145.      *

  146.      * @throws	MalformedURLException if <code>codebase</code> is

  147.      * non-<code>null</code> and contains an invalid URL, or

  148.      * if <code>codebase</code> is <code>null</code> and a provider-specific

  149.      * URL used to identify the class loader is invalid

  150.      *

  151.      * @throws	SecurityException if there is a security manager and the

  152.      * invocation of its <code>checkPermission</code> method fails, or

  153.      * if the caller does not have permission to connect to all of the

  154.      * URLs in the codebase URL path

  155.      */

  156.     public abstract ClassLoader getClassLoader(String codebase)

  157. 	throws MalformedURLException; // SecurityException

  158. 

  159.     /**

  160.      * Provides the implementation for

  161.      * {@link RMIClassLoader#getClassAnnotation(Class)}.

  162.      *

  163.      * Returns the annotation string (representing a location for

  164.      * the class definition) that RMI will use to annotate the class

  165.      * descriptor when marshalling objects of the given class.

  166.      *

  167.      * @param	cl the class to obtain the annotation for

  168.      *

  169.      * @return	a string to be used to annotate the given class when

  170.      * it gets marshalled, or <code>null</code>

  171.      *

  172.      * @throws	NullPointerException if <code>cl</code> is <code>null</code>

  173.      */

  174.     public abstract String getClassAnnotation(Class<?> cl);

  175. }