1. /*

  2.  * @(#)RMIClassLoaderSpi.java	1.11 03/01/23

  3.  *

  4.  * Copyright 2003 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.11, 03/01/23

  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 the system

  77.      * property <code>java.rmi.server.codebase</code> contains an

  78.      * invalid URL

  79.      *

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

  81.      * could not be found at the specified location

  82.      */

  83.     public abstract Class loadClass(String codebase, String name,

  84. 				    ClassLoader defaultLoader)

  85. 	throws MalformedURLException, ClassNotFoundException;

  86.     

  87.     /**

  88.      * Provides the implementation for

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

  90.      *

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

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

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

  94.      * 

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

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

  97.      *

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

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

  100.      *

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

  102.      * to implement

  103.      *

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

  105.      *

  106.      * @param	defaultLoader additional contextual class loader

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

  108.      *

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

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

  111.      * if <code>codebase</code> is <code>null</code> and the system

  112.      * property <code>java.rmi.server.codebase</code> contains an

  113.      * invalid URL

  114.      *

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

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

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

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

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

  120.      * interface list)

  121.      */

  122.     public abstract Class loadProxyClass(String codebase, String[] interfaces,

  123. 					 ClassLoader defaultLoader)

  124. 	throws MalformedURLException, ClassNotFoundException;

  125. 

  126.     /**

  127.      * Provides the implementation for

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

  129.      *

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

  131.      * URL path.

  132.      *

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

  134.      * method will be invoked with a

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

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

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

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

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

  140.      *

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

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

  143.      *

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

  145.      * path

  146.      *

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

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

  149.      * if <code>codebase</code> is <code>null</code> and the system

  150.      * property <code>java.rmi.server.codebase</code> contains an

  151.      * invalid URL

  152.      *

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

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

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

  156.      * URLs in the codebase URL path

  157.      */

  158.     public abstract ClassLoader getClassLoader(String codebase)

  159. 	throws MalformedURLException; // SecurityException

  160. 

  161.     /**

  162.      * Provides the implementation for

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

  164.      *

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

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

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

  168.      *

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

  170.      *

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

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

  173.      *

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

  175.      */

  176.     public abstract String getClassAnnotation(Class cl);

  177. }