rmiclassloader.java

Actual Java RMI implementation

/*
 * @(#)RMIClassLoader.java	1.34 01/12/03
 *
 * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package java.rmi.server;

import java.net.MalformedURLException;
import java.net.URL;

import java.util.Iterator;

import sun.misc.Service;

/**
 * <code>RMIClassLoader</code> comprises static methods to support
 * dynamic class loading with RMI.  Included are methods for loading
 * classes from a network location (one or more URLs) and obtaining
 * the location from which an existing class should be loaded by
 * remote parties.  These methods are used by the RMI runtime when
 * marshalling and unmarshalling classes contained in the arguments
 * and return values of remote method calls, and they also may be
 * invoked directly by applications in order to mimic RMI's dynamic
 * class loading behavior.
 *
 * <p>The implementation of the following static methods
 *
 * <ul>
 *
 * <li>{@link #loadClass(URL,String)}
 * <li>{@link #loadClass(String,String)}
 * <li>{@link #loadClass(String,String,ClassLoader)}
 * <li>{@link #loadProxyClass(String,String[],ClassLoader)}
 * <li>{@link #getClassLoader(String)}
 * <li>{@link #getClassAnnotation(Class)}
 *
 * </ul>
 *
 * is provided by an instance of {@link RMIClassLoaderSpi}, the
 * service provider interface for those methods.  When one of the
 * methods is invoked, its behavior is to delegate to a corresponding
 * method on the service provider instance.  The details of how each
 * method delegates to the provider instance is described in the
 * documentation for each particular method.
 *
 * <p>The service provider instance is chosen as follows:
 *
 * <ul>
 *
 * <li>If the system property
 * <code>java.rmi.server.RMIClassLoaderSpi</code> is defined, then if
 * its value equals the string <code>"default"</code>, the provider
 * instance will be the value returned by an invocation of the {@link
 * #getDefaultProviderInstance()} method, and for any other value, if
 * a class named with the value of the property can be loaded by the
 * system class loader (see {@link ClassLoader#getSystemClassLoader})
 * and that class is assignable to {@link RMIClassLoaderSpi} and has a
 * public no-argument constructor, then that constructor will be
 * invoked to create the provider instance.  If the property is
 * defined but any other of those conditions are not true, then an
 * unspecified <code>Error</code> will be thrown to code that attempts
 * to use <code>RMIClassLoader</code>, indicating the failure to
 * obtain a provider instance.
 *
 * <li>If a resource named
 * <code>META-INF/services/java.rmi.server.RMIClassLoaderSpi</code> is
 * visible to the system class loader, then the contents of that
 * resource are interpreted as a provider-configuration file, and the
 * first class name specified in that file is used as the provider
 * class name.  If a class with that name can be loaded by the system
 * class loader and that class is assignable to {@link
 * RMIClassLoaderSpi} and has a public no-argument constructor, then
 * that constructor will be invoked to create the provider instance.
 * If the resource is found but a provider cannot be instantiated as
 * described, then an unspecified <code>Error</code> will be thrown to
 * code that attempts to use <code>RMIClassLoader</code>, indicating
 * the failure to obtain a provider instance.
 *
 * <li>Otherwise, the provider instance will be the value returned by
 * an invocation of the {@link #getDefaultProviderInstance()} method.
 *
 * </ul>
 *
 * @version	1.34, 01/12/03
 * @author	Ann Wollrath
 * @author	Peter Jones
 * @author	Laird Dornin
 * @see		RMIClassLoaderSpi
 * @since	JDK1.1
 */
public class RMIClassLoader {

    /** "default" provider instance */
    private static final RMIClassLoaderSpi defaultProvider =
	newDefaultProviderInstance();

    /** provider instance */
    private static final RMIClassLoaderSpi provider =
	(RMIClassLoaderSpi) java.security.AccessController.doPrivileged(
	new java.security.PrivilegedAction() {
	    public Object run() { return initializeProvider(); }
	});

    /*
     * Disallow anyone from creating one of these.
     */
    private RMIClassLoader() {}

    /**
     * Loads a class from the codebase URL path specified by the
     * <code>java.rmi.server.codebase</code> property.
     *
     * <p>This method delegates to {@link #loadClass(String,String)},
     * passing <code>null</code> as the first argument and
     * <code>name</code> as the second argument.
     *
     * @param	name the name of the class to load
     *
     * @return	the <code>Class</code> object representing the loaded class
     *
     * @throws	MalformedURLException if the system property
     * <code>java.rmi.server.codebase</code> contains an invalid URL
     *
     * @throws	ClassNotFoundException if a definition for the class
     * could not be found at the codebase location
     *
     * @deprecated replaced by <code>loadClass(String,String)</code> method
     * @see #loadClass(String,String)
     */
    public static Class loadClass(String name)
	throws MalformedURLException, ClassNotFoundException
    {
	return loadClass((String) null, name);
    }

    /**
     * Loads a class from a codebase URL.
     *
     * If <code>codebase</code> is <code>null</code>, then this method
     * will behave the same as {@link #loadClass(String,String)} with a
     * <code>null</code> <code>codebase</code> and the given class name.
     *
     * <p>This method delegates to the
     * {@link RMIClassLoaderSpi#loadClass(String,String,ClassLoader)}
     * method of the provider instance, passing the result of invoking
     * {@link URL#toString} on the given URL (or <code>null</code> if
     * <code>codebase</code> is null) as the first argument,
     * <code>name</code> as the second argument,
     * and <code>null</code> as the third argument.
     *
     * @param	codebase the URL to load the class from, or <code>null</code>
     *
     * @param	name the name of the class to load
     *
     * @return	the <code>Class</code> object representing the loaded class
     *
     * @throws	MalformedURLException if <code>codebase</code> is
     * <code>null</code> and the system property
     * <code>java.rmi.server.codebase</code> contains an invalid URL
     *
     * @throws	ClassNotFoundException if a definition for the class
     * could not be found at the specified URL
     */
    public static Class loadClass(URL codebase, String name)
	throws MalformedURLException, ClassNotFoundException
    {
	return provider.loadClass(
	    codebase != null ? codebase.toString() : null, name, null);
    }

    /**
     * Loads a class from a codebase URL path.
     *
     * If <code>codebase</code> is <code>null</code>, then the value of
     * the system property <code>java.rmi.server.codebase</code> is used
     * as the URL path.
     *
     * <p>This method delegates to the
     * {@link RMIClassLoaderSpi#loadClass(String,String,ClassLoader)}
     * method of the provider instance, passing <code>codebase</code>
     * as the first argument, <code>name</code> as the second argument,
     * and <code>null</code> as the third argument.
     *
     * @param	codebase the list of URLs (separated by spaces) to load
     * the class from, or <code>null</code>
     *
     * @param	name the name of the class to load
     *
     * @return	the <code>Class</code> object representing the loaded class
     *
     * @throws	MalformedURLException if <code>codebase</code> is
     * non-<code>null</code> and contains an invalid URL, or
     * if <code>codebase</code> is <code>null</code> and the system
     * property <code>java.rmi.server.codebase</code> contains an
     * invalid URL
     *
     * @throws	ClassNotFoundException if a definition for the class
     * could not be found at the specified location
     *
     * @since	1.2
     */
    public static Class loadClass(String codebase, String name)
	throws MalformedURLException, ClassNotFoundException
    {
	return provider.loadClass(codebase, name, null);
    }

    /**
     * Loads a class from a codebase URL path, optionally using the
     * supplied loader.
     *
     * If <code>codebase</code> is <code>null</code>, then the value of
     * the system property <code>java.rmi.server.codebase</code> is used
     * as the URL path.
     *
     * This method should be used when the caller would like to make
     * available to the provider implementation an additional contextual
     * class loader to consider, such as the loader of a caller on the
     * stack.  Typically, a provider implementation will attempt to
     * resolve the named class using the given <code>defaultLoader</code>,
     * if specified, before attempting to resolve the class from the
     * codebase URL path.
     *
     * <p>This method delegates to the
     * {@link RMIClassLoaderSpi#loadClass(String,String,ClassLoader)}
     * method of the provider instance, passing <code>codebase</code>
     * as the first argument, <code>name</code> as the second argument,
     * and <code>defaultLoader</code> as the third argument.
     *
     * @param	codebase the list of URLs (separated by spaces) to load
     * the class from, or <code>null</code>
     *
     * @param	name the name of the class to load
     *
     * @param	defaultLoader additional contextual class loader
     * to use, or <code>null</code>
     *
     * @return	the <code>Class</code> object representing the loaded class
     *
     * @throws	MalformedURLException if <code>codebase</code> is
     * non-<code>null</code> and contains an invalid URL, or
     * if <code>codebase</code> is <code>null</code> and the system
     * property <code>java.rmi.server.codebase</code> contains an
     * invalid URL
     *
     * @throws	ClassNotFoundException if a definition for the class
     * could not be found at the specified location
     *
     * @since	1.4
     */
    public static Class loadClass(String codebase, String name,
				  ClassLoader defaultLoader)
	throws MalformedURLException, ClassNotFoundException
    {
	return provider.loadClass(codebase, name, defaultLoader);
    }

    /**
     * Loads a dynamic proxy class (see {@link java.lang.reflect.Proxy})
     * that implements a set of interfaces with the given names
     * from a codebase URL path.
     *
     * If <code>codebase</code> is <code>null</code>, then the value of
     * the system property <code>java.rmi.server.codebase</code> is used
     * as the URL path.
     *
     * <p>The interfaces will be resolved similar to classes loaded via
     * the {@link #loadClass(String,String)} method using the given
     * <code>codebase</code>.
     *
     * <p>This method delegates to the
     * {@link RMIClassLoaderSpi#loadProxyClass(String,String[],ClassLoader)}
     * method of the provider instance, passing <code>codebase</code>
     * as the first argument, <code>interfaces</code> as the second argument,
     * and <code>defaultLoader</code> as the third argument.
     *
     * @param	codebase the list of URLs (space-separated) to load
     * classes from, or <code>null</code>
     *
     * @param	interfaces the names of the interfaces for the proxy class
     * to implement
     *
     * @param	defaultLoader additional contextual class loader
     * to use, or <code>null</code>
     *
     * @return	a dynamic proxy class that implements the named interfaces
     *
     * @throws	MalformedURLException if <code>codebase</code> is
     * non-<code>null</code> and contains an invalid URL, or
     * if <code>codebase</code> is <code>null</code> and the system
     * property <code>java.rmi.server.codebase</code> contains an
     * invalid URL
     *
     * @throws	ClassNotFoundException if a definition for one of
     * the named interfaces could not be found at the specified location,
     * or if creation of the dynamic proxy class failed (such as if
     * {@link java.lang.reflect.Proxy#getProxyClass(ClassLoader,Class[])}
     * would throw an <code>IllegalArgumentException</code> for the given
     * interface list)
     *
     * @since	1.4
     */
    public static Class loadProxyClass(String codebase, String[] interfaces,
				       ClassLoader defaultLoader)
	throws ClassNotFoundException, MalformedURLException
    {
	return provider.loadProxyClass(codebase, interfaces, defaultLoader);
    }
  
    /**
     * Returns a class loader that loads classes from the given codebase
     * URL path.
     *
     * <p>The class loader returned is the class loader that the
     * {@link #loadClass(String,String)} method would use to load classes
     * for the same <code>codebase</code> argument.
     * 
     * <p>This method delegates to the
     * {@link RMIClassLoaderSpi#getClassLoader(String)} method
     * of the provider instance, passing <code>codebase</code> as the argument.
     *
     * <p>If there is a security manger, its <code>checkPermission</code>
     * method will be invoked with a
     * <code>RuntimePermission("getClassLoader")</code> permission;
     * this could result in a <code>SecurityException</code>.
     * The provider implementation of this method may also perform further
     * security checks to verify that the calling context has permission to
     * connect to all of the URLs in the codebase URL path.
     *
     * @param	codebase the list of URLs (space-separated) from which
     * the returned class loader will load classes from, or <code>null</code>
     *
     * @return a class loader that loads classes from the given codebase URL
     * path
     *
     * @throws	MalformedURLException if <code>codebase</code> is
     * non-<code>null</code> and contains an invalid URL, or
     * if <code>codebase</code> is <code>null</code> and the system
     * property <code>java.rmi.server.codebase</code> contains an
     * invalid URL
     *
     * @throws	SecurityException if there is a security manager and the
     * invocation of its <code>checkPermission</code> method fails, or
     * if the caller does not have permission to connect to all of the
     * URLs in the codebase URL path
     *
     * @since	1.3
     */
    public static ClassLoader getClassLoader(String codebase)
	throws MalformedURLException, SecurityException
    {
	return provider.getClassLoader(codebase);
    }