5.6 The RMIClassLoader Class

The java.rmi.server.RMIClassLoader class provides a set of public static utility methods for supporting network-based class loading in RMI. These methods are called by RMI's internal marshal streams to implement the dynamic class loading of types for RMI parameters and return values, but they also may be called directly by applications in order to mimic RMI's class loading behavior. The RMIClassLoader class has no publicly-accessible constructors and thus cannot be instantiated.

package java.rmi.server;

public class RMIClassLoader {
	public static String getClassAnnotation(Class cl);
	public static ClassLoader getClassLoader(String codebase)
	    throws java.net.MalformedURLException, SecurityException;
	public static Object getSecurityContext(ClassLoader loader);
        public static Class loadClass(String name)
	    throws java.net.MalformedURLException, 
		   ClassNotFoundException;
	public static Class loadClass(String codebase, String name)
	    throws java.net.MalformedURLException, 
		   ClassNotFoundException;
    	public static Class loadClass(URL codebase, String name) 
	    throws java.net.MalformedURLException, 
		   ClassNotFoundException;
}

The getClassAnnotation method returns a String representing the network codebase path that a remote endpoint should use for downloading the definition of the indicated class. The RMI runtime uses String objects returned by this method as the annotations for class descriptors in its marshal streams. The format of this codebase string is a path of codebase URL strings delimited by spaces.

The codebase string returned depends on the class loader of the supplied class:

• If the class loader is one of the following:

then the value of the java.rmi.server.codebase property is returned, or null is returned if that property is not set.

• Otherwise, if the class loader is an instance of the class java.net.URLClassLoader, then the codebase string returned is a space-separated list of the external forms of the URLs returned by invoking the getURLs methods on the class loader. If the URLClassLoader was created by the RMI runtime to service an invocation of one of the RMIClassLoader.loadClass methods, then no permissions are necessary to get the associated codebase string. If it is an arbitrary URLClassLoader instance, the caller must have permission to connect to all of the URLs in the codebase path, as determined by calling openConnection().getPermission() on each URL instance returned by the getURLs method.
• Finally, if the class loader is not an instance of URLClassLoader, then the value of the java.rmi.server.codebase property is returned, or null is returned if that property is not set.

The getClassLoader method returns a class loader that loads classes from the given codebase URL path, a list of space-separated URLs. The class loader returned is the class loader that the loadClass(String,String) method would use to load classes from the given codebase. If a class loader with the same codebase URL path already exists for the RMI runtime, it will be returned; otherwise a new class loader will be created. If the given codebase is null, it returns the class loader used to load classes via the loadClass(String) method. The method throws MalformedURLException if the codebase parameter contains an invalid non-null URL and throws SecurityException if the caller does not have permission to connect to all of the URLs in the codebase URL path.

The getSecurityContext method is deprecated because it is no longer applicable to the Java 2 platform security model; it was used internally in JDK1.1 to implement class loader-based security checks. If the indicated class loader was created by the RMI runtime to service an invocation of one of the RMIClassLoader.loadClass methods, the first URL in the class loader's codebase path is returned; otherwise, null is returned.

The three loadClass methods all attempt to load the class with the specified name using the current thread's context class loader and, if there is a security manager set, an internal URLClassLoader for a particular codebase path (depending on the method):

• The loadClass method that only takes one parameter (the class name) implicitly uses the value of the java.rmi.server.codebase property as the codebase path to use. This version of the loadClass method has been deprecated because this use of the java.rmi.server.codebase property is discouraged; use the following, more general version instead.
• The loadClass method with the String codebase parameter uses it as the codebase path; the codebase string must be a space-separated list of URLs, as would be returned by the getClassAnnotation method.
• The loadClass method with the java.net.URL codebase parameter uses that single URL as the codebase.

For all of the loadClass methods, the codebase path is used in conjunction with the current thread's context class loader (determined by invoking getContextClassLoader on the current thread) to determine the internal class loader instance to attempt to load the class from. The RMI runtime maintains a table of internal class loader instances, keyed by the pair consisting of the parent class loader and the loader's codebase path (an ordered list of URLs). A loadClass method looks in the table for a URLClassLoader instance with the desired codebase path and the current thread's context class loader as its parent. If no such loader exists, then one is created and added to the table. Finally, the loadClass method is called on the chosen class loader with the specified class name.

If there is a security manager set (System.getSecurityManager does not return null), the caller of loadClass must have permission to connect to all of the URLs in the codebase path, or a ClassNotFoundException will be thrown. In order to prevent arbitrary untrusted code from being loaded into a JVM with no security manager, if there is no security manager set, all of the loadClass methods will ignore the particular codebase path and only attempt to load the class with the specified name from the current thread's context class loader.