GigaSpaces XAP 9.0 API

net.jini.loader.pref
Class PreferredClassProvider

java.lang.Object
  extended by java.rmi.server.RMIClassLoaderSpi
      extended by net.jini.loader.pref.PreferredClassProvider
Direct Known Subclasses:
RequireDlPermProvider

public class PreferredClassProvider
extends RMIClassLoaderSpi

An RMIClassLoader provider that supports preferred classes.

See the RMIClassLoader specification for information about how to install and configure the RMIClassLoader service provider.

PreferredClassProvider uses instances of PreferredClassLoader to load classes from codebase URL paths supplied to RMIClassLoader.loadClass methods.

PreferredClassProvider does not enforce DownloadPermission by default, but a subclass can configure it to do so by passing true as the argument to the protected constructor.

By overriding the getClassAnnotation(ClassLoader) method, a subclass can also configure the class annotations to be used for classes defined by the system class loader, its ancestor class loaders, and any class loader that is not an instance of ClassAnnotation or URLClassLoader.

Common Terms and Behaviors

The following section defines terms and describes behaviors common to how PreferredClassProvider implements the abstract methods of RMIClassLoaderSpi. Where applicable, these definitions and descriptions are relative to the instance of PreferredClassProvider on which a method is invoked and the context in which it is invoked.

The annotation string for a class loader is determined by the following procedure:

The annotation URL path for a class loader is the path of URLs obtained by parsing the annotation string for the loader as a list of URLs separated by spaces, where each URL is parsed as with the URL(String) constructor; if such parsing would result in a MalformedURLException, then the annotation URL path for the loader is only defined to the extent that it is not equal to any other path of URLs.

A PreferredClassProvider maintains an internal table of class loader instances indexed by keys that comprise a path of URLs and a parent class loader. The table does not strongly reference the class loader instances, in order to allow them (and the classes they have defined) to be garbage collected when they are not otherwise reachable.

The methods loadClass, loadProxyClass, and getClassLoader, which each have a String parameter named codebase, have the following behaviors in common:

When PreferredClassProvider attempts to load a class (or interface) named N using class loader L, it does so in a manner equivalent to evaluating the following expression:

        Class.forName(N, false, L)
 
In particular, the case of N being the binary name of an array class is supported.

Since:
2.0
Author:
Sun Microsystems, Inc.

Constructor Summary
  PreferredClassProvider()
          Creates a new PreferredClassProvider.
protected PreferredClassProvider(boolean requireDlPerm)
          Creates a new PreferredClassProvider.
 
Method Summary
protected  ClassLoader createClassLoader(URL[] urls, ClassLoader parent, boolean requireDlPerm)
          Creates the class loader for this PreferredClassProvider to use to load classes from the specified path of URLs with the specified delegation parent.
 String getClassAnnotation(Class cl)
          Provides the implementation for RMIClassLoaderSpi.getClassAnnotation(Class).
protected  String getClassAnnotation(ClassLoader loader)
          Returns the annotation string for the specified class loader.
 ClassLoader getClassLoader(String codebase)
          Provides the implementation for RMIClassLoaderSpi.getClassLoader(String).
 Class loadClass(String codebase, String name, ClassLoader defaultLoader)
          Provides the implementation for RMIClassLoaderSpi.loadClass(String,String,ClassLoader).
 Class loadProxyClass(String codebase, String[] interfaceNames, ClassLoader defaultLoader)
          Provides the implementation of RMIClassLoaderSpi.loadProxyClass(String,String[],ClassLoader).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PreferredClassProvider

public PreferredClassProvider()
Creates a new PreferredClassProvider.

This constructor is used by the RMIClassLoader service provider location mechanism when PreferredClassProvider is configured as the RMIClassLoader provider class.

If there is a security manager, its checkCreateClassLoader method is invoked; this could result in a SecurityException.

DownloadPermission is not enforced by the created provider.

Throws:
SecurityException - if there is a security manager and the invocation of its checkCreateClassLoader method fails

PreferredClassProvider

protected PreferredClassProvider(boolean requireDlPerm)
Creates a new PreferredClassProvider.

This constructor is used by subclasses to control whether or not DownloadPermission is enforced.

If there is a security manager, its checkCreateClassLoader method is invoked; this could result in a SecurityException.

Parameters:
requireDlPerm - if true, the class loaders created by the provider will only define classes with a CodeSource that is granted DownloadPermission
Throws:
SecurityException - if there is a security manager and the invocation of its checkCreateClassLoader method fails
Method Detail

loadClass

public Class loadClass(String codebase,
                       String name,
                       ClassLoader defaultLoader)
                throws MalformedURLException,
                       ClassNotFoundException
Provides the implementation for RMIClassLoaderSpi.loadClass(String,String,ClassLoader).

PreferredClassProvider implements this method as follows:

If name is the binary name of an array class (of one or more dimensions) with a primitive element type, this method returns the Class for that array class.

Otherwise, if defaultLoader is not null and any of the following conditions are true:

then this method attempts to load the class with the specified name using defaultLoader. If this attempt succeeds, this method returns the resulting Class; if it throws a ClassNotFoundException, this method proceeds as follows.

Otherwise, this method attempts to load the class with the specified name using the codebase loader, if there is a security manager and the current security context has permission to access the codebase loader, or using the current thread's context class loader otherwise. If this attempt succeeds, this method returns the resulting Class; if it throws a ClassNotFoundException, this method throws a ClassNotFoundException.

Specified by:
loadClass in class RMIClassLoaderSpi
Parameters:
codebase - the codebase URL path as a space-separated list of URLs, or null
name - the binary name of the class to load
defaultLoader - additional contextual class loader to use, or null
Returns:
the Class object representing the loaded class
Throws:
MalformedURLException - if codebase is non-null and contains an invalid URL
ClassNotFoundException - if a definition for the class could not be loaded

getClassAnnotation

public String getClassAnnotation(Class cl)
Provides the implementation for RMIClassLoaderSpi.getClassAnnotation(Class).

PreferredClassProvider implements this method as follows:

If cl is an array class (of one or more dimensions) with a primitive element type, this method returns null.

Otherwise, this method returns the annotation string for the defining class loader of cl, except that if the annotation string would be determined by an invocation of URLClassLoader.getURLs on that loader and the current security context does not have the permissions necessary to connect to each URL returned by that invocation (where the permission to connect to a URL is determined by invoking openConnection().getPermission() on the URL object), this method returns the result of invoking getClassAnnotation(ClassLoader) with the loader instead.

Specified by:
getClassAnnotation in class RMIClassLoaderSpi
Parameters:
cl - the class to obtain the annotation string for
Returns:
the annotation string for the class, or null

getClassAnnotation

protected String getClassAnnotation(ClassLoader loader)
Returns the annotation string for the specified class loader.

This method is invoked in order to determine the annotation string for the system class loader, an ancestor of the system class loader, any class loader that is not an instance of ClassAnnotation or URLClassLoader, or (for an invocation of getClassAnnotation(Class)) a URLClassLoader for which the current security context does not have the permissions necessary to connect to all of its URLs.

PreferredClassProvider implements this method as follows:

This method returns the value of the system property "java.rmi.server.codebase" (or possibly an earlier cached value).

Parameters:
loader - the class loader to obtain the annotation string for
Returns:
the annotation string for the class loader, or null

getClassLoader

public ClassLoader getClassLoader(String codebase)
                           throws MalformedURLException
Provides the implementation for RMIClassLoaderSpi.getClassLoader(String).

PreferredClassProvider implements this method as follows:

If there is a security manager, its checkPermission method is invoked with a RuntimePermission("getClassLoader") permission; this could result in a SecurityException. Also, if there is a security manager, the codebase loader is not the current thread's context class loader, and the current security context does not have permission to access the codebase loader, this method throws a SecurityException.

This method returns the codebase loader if there is a security manager, or the current thread's context class loader otherwise.

Specified by:
getClassLoader in class RMIClassLoaderSpi
Parameters:
codebase - the codebase URL path as a space-separated list of URLs, or null
Returns:
a class loader for the specified codebase URL path
Throws:
MalformedURLException - if codebase is non-null and contains an invalid URL
SecurityException - if there is a security manager and the invocation of its checkPermission method fails, or if the current security context does not have the permissions necessary to connect to all of the URLs in the codebase URL path

loadProxyClass

public Class loadProxyClass(String codebase,
                            String[] interfaceNames,
                            ClassLoader defaultLoader)
                     throws MalformedURLException,
                            ClassNotFoundException
Provides the implementation of RMIClassLoaderSpi.loadProxyClass(String,String[],ClassLoader).

PreferredClassProvider implements this method as follows:

If defaultLoader is not null and any of the following conditions are true:

then this method attempts to load all of the interfaces named by the elements of interfaces using defaultLoader. If all of the interfaces are loaded successfully, then If any of the attempts to load one of the interfaces throws a ClassNotFoundException, this method proceeds as follows.

Otherwise, this method attempts to load all of the interfaces named by the elements of interfaces using the codebase loader, if there is a security manager and the current security context has permission to access the codebase loader, or using the current thread's context class loader otherwise. If all of the interfaces are loaded successfully, then

If any of the attempts to load one of the interfaces throws a ClassNotFoundException, this method throws a ClassNotFoundException.

Specified by:
loadProxyClass in class RMIClassLoaderSpi
Parameters:
codebase - the codebase URL path as a space-separated list of URLs, or null
interfaceNames - the binary names of the interfaces for the proxy class to implement
defaultLoader - additional contextual class loader to use, or null
Returns:
a dynamic proxy class that implements the named interfaces
Throws:
MalformedURLException - if codebase is non-null and contains an invalid URL
ClassNotFoundException - if a definition for one of the named interfaces could not be loaded, or if creation of the dynamic proxy class failed (such as if Proxy.getProxyClass would throw an IllegalArgumentException for the given interface list)

createClassLoader

protected ClassLoader createClassLoader(URL[] urls,
                                        ClassLoader parent,
                                        boolean requireDlPerm)
Creates the class loader for this PreferredClassProvider to use to load classes from the specified path of URLs with the specified delegation parent.

PreferredClassProvider implements this method as follows:

This method creates a new instance of PreferredClassLoader that loads classes and resources from urls, delegates to parent, and enforces DownloadPermission if requireDlPerm is true. The created loader uses a restricted security context to ensure that the URL retrieval operations undertaken by the loader cannot exercise a permission that is not implied by the permissions necessary to access the loader as a codebase loader for the specified path of URLs.

Parameters:
urls - the path of URLs to load classes and resources from
parent - the parent class loader for delegation
requireDlPerm - if true, the loader must only define classes with a CodeSource that is granted DownloadPermission
Returns:
the created class loader
Since:
2.1

GigaSpaces XAP 9.0 API

Copyright © GigaSpaces.