public class PreferredClassLoader extends URLClassLoader implements ClassAnnotation
A preferred class is a class that is to be loaded by a class loader without the loader delegating to its parent class loader first. Resources may also be preferred.
Like URLClassLoader, PreferredClassLoader loads classes and
resources from a search path of URLs. If a URL in the path ends with a '/', it is
assumed to refer to a directory; otherwise, the URL is assumed to refer to a JAR file.
The location of the first URL in the path can contain a preferred list for the entire
path. A preferred list declares names of certain classes and other resources throughout the path
as being preferred or not. When a PreferredClassLoader is asked to load a
class or resource that is preferred (according to the preferred list) and the class or resource
exists in the loader's path of URLs, the loader will not delegate first to its parent class
loader as it otherwise would do; instead, it will attempt to load the class or resource from its
own path of URLs only.
The preferred list for a path of URLs, if one exists, is located relative to the first URL in
the path. If the first URL refers to a JAR file, then the preferred list is the contents of the
file named "META-INF/PREFERRED.LIST" within that JAR file. If the first URL refers
to a directory, then the preferred list is the contents of the file at the location
"META-INF/PREFERRED.LIST" relative to that directory URL. If there is no preferred
list at the required location, then no classes or resources are preferred for the path of URLs. A
preferred list at any other location (such as relative to one of the other URLs in the path) is
ignored.
Note that a class or resource is only considered to be preferred if the preferred list declares the name of the class or resource as being preferred and the class or resource actually exists in the path of URLs.
'#', the line is a comment and is
equivalent to a blank line.
The first line of a preferred list must contain a version number in the following format:
PreferredResources-Version: 1.x
This specification defines only version 1.0, but PreferredClassLoader will parse any
version 1.x, x>=0 with the format and semantics specified here.
After the version number line, a preferred list comprises an optional default preferred entry followed by zero or more named preferred entries. A preferred list must contain either a default preferred entry or at least one named preferred entry. Blank lines are allowed before and after preferred entries, as well as between the lines of a named preferred entry.
A default preferred entry is a single line in the following format:
Preferred: preferred-setting
where preferred-setting is a non-empty sequence of characters. If
preferred-setting equals "true" (case insensitive), then resource names not
matched by any of the named preferred entries are by default preferred; otherwise, resource names
not matched by any of the named preferred entries are by default not preferred. If there is no
default preferred entry, then resource names are by default not preferred.
A named preferred entry is two lines in the following format:
Name: name-expression
Preferred: preferred-setting
where name-expression and preferred-setting are non-empty sequences of characters.
If preferred-setting equals "true" (case insensitive), then resource names
that are matched by name-expression (and not any more specific named preferred entries)
are preferred; otherwise, resource names that are matched by name-expression (and not any
more specific named preferred entries) are not preferred.
If name-expression ends with ".class", it matches a class whose binary
name is name-expression without the ".class" suffix and with each
'/' character replaced with a '.'. It also matches any class whose
binary name starts with that same value followed by a '$'; this rule is intended to
match nested classes that have an enclosing class of that name, so that the preferred settings of
a class and all of its nested classes are the same by default. It is possible, but strongly
discouraged, to override the preferred setting of a nested class with a named preferred entry
that explicitly matches the nested class's binary name.
name-expression may match arbitrary resource names as well as class names, with path
elements separated by '/' characters.
If name-expression ends with "/" or "/*", then the entry is a
directory wildcard entry that matches all resources (including classes) in the named directory.
If name-expression ends with "/-", then the entry is a namespace wildcard
entry that matches all resources (including classes) in the named directory and all of its
subdirectories.
When more than one named preferred entry matches a class or resource name, then the most specific entry takes precedence. A non-wildcard entry is more specific than a wildcard entry. A directory wildcard entry is more specific than a namespace wildcard entry. A namespace wildcard entry with more path elements is more specific than a namespace wildcard entry with fewer path elements. Given two non-wildcard entries, the entry with the longer name-expression is more specific (this rule is only significant when matching a class). The order of named preferred entries is insignificant.
Following is an example preferred list:
PreferredResources-Version: 1.0
Preferred: false
Name: com/foo/FooBar.class
Preferred: true
Name: com/foo/*
Preferred: false
Name: com/foo/-
Preferred: true
Name: image-files/*
Preferred: mumble
The class com.foo.FooBar is preferred, as well as any nested classes that have it
as an enclosing class. All other classes in the com.foo package are not preferred
because of the directory wildcard entry. Classes in subpackages of com.foo are
preferred because of the namespace wildcard entry. Resources in the directory
"com/foo/" are not preferred, and resources in subdirectories of
"com/foo/" are preferred. Resources in the directory "image-files/"
are not preferred because preferred settings other than "true" are interpreted as
false. Classes that are in a package named com.bar are not preferred because of the
default preferred entry.
| Constructor and Description |
|---|
PreferredClassLoader(URL[] urls,
ClassLoader parent,
String exportAnnotation,
boolean requireDlPerm)
Creates a new
PreferredClassLoader that loads classes and resources from the
specified path of URLs and delegates to the specified parent class loader. |
PreferredClassLoader(URL[] urls,
ClassLoader parent,
String exportAnnotation,
boolean requireDlPerm,
URLStreamHandlerFactory factory)
Creates a new
PreferredClassLoader that loads classes and resources from the
specified path of URLs, delegates to the specified parent class loader, and uses the
specified URLStreamHandlerFactory when creating new URL objects. |
| Modifier and Type | Method and Description |
|---|---|
protected Package |
definePackage(String name,
String specTitle,
String specVersion,
String specVendor,
String implTitle,
String implVersion,
String implVendor,
URL sealBase) |
String |
getClassAnnotation()
Returns the class annotation string for classes defined by this class loader.
|
protected PermissionCollection |
getPermissions(CodeSource codeSource)
Returns the static permissions to be automatically granted to classes loaded from the
specified
CodeSource and defined by this class loader. |
URL |
getResource(String name)
Gets a resource with the specified name.
|
protected boolean |
isPreferredResource(String name,
boolean isClass)
Returns
true if a class or resource with the specified name is preferred for
this class loader, and false if a class or resource with the specified name is
not preferred for this loader. |
protected Class |
loadClass(String name,
boolean resolve)
Loads a class with the specified name.
|
static PreferredClassLoader |
newInstance(URL[] urls,
ClassLoader parent,
String exportAnnotation,
boolean requireDlPerm)
Creates a new instance of
PreferredClassLoader that loads classes and resources
from the specified path of URLs and delegates to the specified parent class loader. |
String |
toString()
Returns a string representation of this class loader.
|
addURL, close, definePackage, findClass, findResource, findResources, getResourceAsStream, getURLs, newInstance, newInstancedefineClass, defineClassclearAssertionStatus, defineClass, defineClass, defineClass, defineClass, findLibrary, findLoadedClass, findSystemClass, getClassLoadingLock, getPackage, getPackages, getParent, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, registerAsParallelCapable, resolveClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSignerspublic PreferredClassLoader(URL[] urls, ClassLoader parent, String exportAnnotation, boolean requireDlPerm)
PreferredClassLoader that loads classes and resources from the
specified path of URLs and delegates to the specified parent class loader.
If exportAnnotation is not null, then it will be used as the
return value of the loader's getClassAnnotation method. If
exportAnnotation is null, the loader's
getClassAnnotation method will return a space-separated list of the URLs in the
specified path. The exportAnnotation parameter can be used to specify so-called
"export" URLs, from which other parties should load classes defined by the loader and which
are different from the "import" URLs that the classes are actually loaded from.
If requireDlPerm is true, the loader's getPermissions method will require that the CodeSource of any class defined by the
loader is granted DownloadPermission.
urls - the path of URLs to load classes and resources fromparent - the parent class loader for delegationexportAnnotation - the export class annotation string to use for classes defined by this
loader, or nullrequireDlPerm - if true, the loader will only define classes with a
CodeSource that is granted DownloadPermissionSecurityException - if there is a security manager and an invocation of its checkCreateClassLoader
method failspublic PreferredClassLoader(URL[] urls, ClassLoader parent, String exportAnnotation, boolean requireDlPerm, URLStreamHandlerFactory factory)
PreferredClassLoader that loads classes and resources from the
specified path of URLs, delegates to the specified parent class loader, and uses the
specified URLStreamHandlerFactory when creating new URL objects. This constructor
passes factory to the superclass constructor that has a
URLStreamHandlerFactory parameter.
If exportAnnotation is not null, then it will be used as the
return value of the loader's getClassAnnotation method. If
exportAnnotation is null, the loader's
getClassAnnotation method will return a space-separated list of the URLs in the
specified path. The exportAnnotation parameter can be used to specify so-called
"export" URLs, from which other parties should load classes defined by the loader and which
are different from the "import" URLs that the classes are actually loaded from.
If requireDlPerm is true, the loader's getPermissions method will require that the CodeSource of any class defined by the
loader is granted DownloadPermission.
urls - the path of URLs to load classes and resources fromparent - the parent class loader for delegationexportAnnotation - the export class annotation string to use for classes defined by this
loader, or nullrequireDlPerm - if true, the loader will only define classes with a
CodeSource that is granted DownloadPermissionfactory - the URLStreamHandlerFactory to use when creating new URL
objects, or nullSecurityException - if there is a security manager and an invocation of its checkCreateClassLoader
method failspublic static PreferredClassLoader newInstance(URL[] urls, ClassLoader parent, String exportAnnotation, boolean requireDlPerm)
PreferredClassLoader that loads classes and resources
from the specified path of URLs and delegates to the specified parent class loader.
The exportAnnotation and requireDlPerm parameters have the same
semantics as they do for the constructors.
The loadClass method of the returned PreferredClassLoader
will, if there is a security manager, invoke its checkPackageAccess method with the package name of the class to load before attempting to
load the class; this could result in a SecurityException being thrown from
loadClass.
urls - the path of URLs to load classes and resources fromparent - the parent class loader for delegationexportAnnotation - the export class annotation string to use for classes defined by this
loader, or nullrequireDlPerm - if true, the loader will only define classes with a
CodeSource that is granted DownloadPermissionPreferredClassLoader instanceSecurityException - if the current security context does not have the permissions
necessary to connect to all of the URLs in urlsprotected boolean isPreferredResource(String name, boolean isClass) throws IOException
true if a class or resource with the specified name is preferred for
this class loader, and false if a class or resource with the specified name is
not preferred for this loader.
If isClass is true, then name is interpreted as the
binary name of a class; otherwise, name is interpreted as the full path of a
resource.
This method only returns true if a class or resource with the specified name
exists in the this loader's path of URLs and the name is preferred in the preferred list.
This method returns false if the name is not preferred in the preferred list or
if the name is preferred with the default preferred entry or a wildcard preferred entry and
the class or resource does not exist in the path of URLs.
name - the name of the class or resourceisClass - true if name is a binary class name, and
false if name is the full path of a resourcetrue if a class or resource named name is preferred for
this loader, and false if a class or resource named name is not
preferred for this loaderIOException - if the preferred list cannot definitely be determined to exist or not
exist, or if the preferred list contains a syntax error, or if the name
is preferred with the default preferred entry or a wildcard preferred
entry and the class or resource cannot definitely be determined to exist
or not exist in the path of URLs, or if the name is preferred with a
non-wildcard entry and the class or resource does not exist or cannot
definitely be determined to exist in the path of URLsprotected Class loadClass(String name, boolean resolve) throws ClassNotFoundException
PreferredClassLoader implements this method as follows:
This method first invokes findLoadedClass with name;
if findLoadedClass returns a non-null Class, then this
method returns that Class.
Otherwise, this method invokes isPreferredResource with
name as the first argument and true as the second argument:
isPreferredResource throws an IOException, then this method
throws a ClassNotFoundException containing the IOException as its
cause.
isPreferredResource returns true, then this method invokes
findClass with name. If findClass throws an
exception, then this method throws that exception. Otherwise, this method returns the
Class returned by findClass, and if resolve is
true, resolveClass is invoked with the Class
before returning.
isPreferredResource returns false, then this method invokes
the superclass implementation of loadClass
with name and resolve and returns the result. If the superclass's
loadClass throws an exception, then this method throws that exception.
loadClass in class ClassLoadername - the binary name of the class to loadresolve - if true, then resolveClass will be invoked
with the loaded class before returningClassNotFoundException - if the class could not be foundpublic URL getResource(String name)
PreferredClassLoader implements this method as follows:
This method invokes isPreferredResource with
name as the first argument and false as the second argument:
isPreferredResource throws an IOException, then this method
returns null.
isPreferredResource returns true, then this method invokes
findResource with name and returns the result.
isPreferredResource returns false, then this method invokes
the superclass implementation of getResource with
name and returns the result.
getResource in class ClassLoadername - the name of the resource to getURL for the resource, or null if the resource could not
be foundprotected Package definePackage(String name, String specTitle, String specVersion, String specVendor, String implTitle, String implVersion, String implVendor, URL sealBase)
definePackage in class ClassLoaderpublic String getClassAnnotation()
null.
PreferredClassLoader implements this method as follows:
If this PreferredClassLoader was constructed with a non-null
export class annotation string, then this method returns that string. Otherwise, this method
returns a space-separated list of this loader's path of URLs.
getClassAnnotation in interface ClassAnnotationnullprotected PermissionCollection getPermissions(CodeSource codeSource)
CodeSource and defined by this class loader.
PreferredClassLoader implements this method as follows:
If there is a security manager and this PreferredClassLoader was constructed
to enforce DownloadPermission, then this method checks that the current security
policy grants the specified CodeSource the permission
DownloadPermission("permit"); if that check fails, then this method throws a
SecurityException.
Then this method invokes the superclass implementation of getPermissions and returns the result.
getPermissions in class URLClassLoadercodeSource - the CodeSource to return the permissions to be granted toCodeSourceSecurityException - if there is a security manager, this PreferredClassLoader
was constructed to enforce DownloadPermission, and the
current security policy does not grant the specified
CodeSource the permission DownloadPermission("permit")Copyright © GigaSpaces.