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 {@link java.net.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.xThis 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-settingwhere 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-settingwhere 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.
@author Sun Microsystems, Inc.
@since 2.0
| |
| |
| |
| |
| |
| |
| |
| |