ClassPath objects should be used to access contents of the ClassPath, searching
for resources, objects reachable using the ClassPath at runtime. It is intended
to replace some of the functionality of org.openide.filesystems.Repository.
ClassPath instances should be used to map from Java-style resource names
to FileObject (NetBeans-style resource) and vice versa. It should be also used
whenever the operation requires inspection of development or runtime project
environment instead. The service supports either searching in the classpath
resource space, properly hiding resources as the ClassLoader would do at runtime.
It can effectively say whether a FileObject is within the reach of a ClassPath
or whether it is reachable (visible to a ClassLoader). One can translate
filenames to resource names and vice versa.
A client may obtain a ClassPath instance using
ClassPath.getClassPath(id) static method, where the ID is an
abstract name for the classpath wanted. There are some predefined classpath
names predefined as symbolic constants, following individual types of services
(compiler, debugger, executor). Names are not limited to the listed ones; an extension
module might add its own private classpath type.
entries() Returns list of classpath entries from the ClassPath definition.
The implementation must ensure that modifications done to the List are
banned or at least not reflected in other Lists returned by this ClassPath
instance.
findAllResources(String resourceName) Gives out an ordered collection containing all FileObjects, which correspond
to a given ResourceName; only the first one is seen by the ClassLoader
at runtime or can be linked against.
final public FileObject
findOwnerRoot(FileObject resource) Finds a root in this ClassPath, that owns the given file.
final public FileObject
findResource(String resourceName) Returns a FileObject for the specified resource.
final void
firePropertyChange(String what, Object oldV, Object newV, Object propagationId) Fires a property change event on the specified property, notifying the
old and new values.
getClassPath(FileObject f, String id) Find the classpath of a given type, if any, defined for a given file.
This method may return null, if:
the path type (id parameter) is not recognized
the path type is not defined for the given file object
Generally you may pass either an individual Java file, or the root of
a Java package tree, interchangeably, since in most cases all files
in a given tree will share a single classpath.
Typically classpaths for files are defined by the owning project, but
there may be other ways classpaths are defined.
getResourceName(FileObject f, char dirSep, boolean includeExt) Computes a resource name for the FileObject, which uses `pathSep' character
as a directory separator.
public FileObject[]
getRoots() Retrieves valid roots of ClassPath, in the proper order.
If there's an entry in the ClassPath, which cannot be accessed,
its root is not returned by this method.
final public boolean
isResourceVisible(FileObject resource) Determines if the resource is visible in the classpath,
that is if the file will be reached when a process attempts to
load a resource of that name.
Boot ClassPath of the JDK. This type can be used to learn boot classpath
which should be used for the file in question.
It corresponds to the -Xbootclasspath and -Xext
options to java (the Java launcher): i.e. all compiled
classes in the JRE that will be needed to run the program.
It may also be thought of as corresponding to the classes loadable
by the primordial bootstrap class loader plus the standard
extension and endorsed-library class loaders; i.e. class loaders lying
below the regular application startup loader and any custom loaders.
Generally there ought to be a single boot classpath for the entire
application.
ClassPath for compiling things. This type can be used to learn
compilation time classpath for the file in question.
It corresponds to the -classpath option to javac:
i.e. already-compiled classes which some new sources need to compile against,
besides what is already in the JRE.
Classpath setting for executing things. This type can be used to learn
runtime time classpath for execution of the file in question.
It corresponds to the -classpath option to java
(the Java launcher): i.e. all compiled classes outside the JRE that
will be needed to run the program, or at least to load a certain class.
It may also be thought of as corresponding to the list of URLs in a
URLClassLoader (plus URLs present in parent class loaders
but excluding the bootstrap and extension class loaders).
ClassPath for project sources. This type can be used to learn
package root of the file in question.
It is similar to the -sourcepath option of javac.
For typical source files, the sourcepath will consist of one element:
the package root of the source file. If more than one package root is
to be compiled together, all the sources should share a sourcepath
with multiple roots.
Note that each source file for which editor code completion (and similar
actions) should work should have a classpath of this type.
Checks whether a FileObject lies on this classpath.
FilteringPathResourceImplementation is considered.
true, if the parameter is inside one of the classpath subtrees,false otherwise. Parameters: f - the FileObject to check
Returns list of classpath entries from the ClassPath definition.
The implementation must ensure that modifications done to the List are
banned or at least not reflected in other Lists returned by this ClassPath
instance. Clients must assume that the returned value is immutable.
list of definition entries (Entry instances)
findAllResources
final publicList<FileObject> findAllResources(String resourceName)(Code)
Gives out an ordered collection containing all FileObjects, which correspond
to a given ResourceName; only the first one is seen by the ClassLoader
at runtime or can be linked against. The resource name uses slashes ('/')
as folder separator and must not start with slash.
FilteringPathResourceImplementation may cause an actual file
beneath a registered root to not be returned.
Parameters: resourceName - resource name list of resources identified by the given name.
findOwnerRoot
final public FileObject findOwnerRoot(FileObject resource)(Code)
Finds a root in this ClassPath, that owns the given file. File resources, that
are not reachable (they are hidden by other resources, or
FilteringPathResourceImplementation excluded) are still considered
to be part of the classpath and "owned" by one of its roots.
Note: This implementation assumes that the FileSystem hosting a classpath root
contains the entire classpath subtree rooted at that root folder.
classpath root, which hosts the specified resouce. It can return null,if the resource is not within the ClassPath contents. Parameters: resource - resource to find root for.
findResource
final public FileObject findResource(String resourceName)(Code)
Returns a FileObject for the specified resource. May return null,
if the resource does not exist, or is not reachable through
this ClassPath.
If the resourceName identifies a package, this method will
return the FileObject for the first package fragment
in the ClassPath.
FilteringPathResourceImplementation may cause an actual file
beneath a registered root to not be returned.
Note: do not pass names starting with slash to this method.
Parameters: resourceName - name of the resource as it would be passedto ClassLoader.getResource FileObject for the resource, or null if the resource cannotbe found in this ClassPath.
Fires a property change event on the specified property, notifying the
old and new values.
Parameters: what - name of the property Parameters: oldV - old value Parameters: newV - new value
getClassLoader
final public synchronized ClassLoader getClassLoader(boolean cache)(Code)
Returns a ClassLoader for loading classes from this ClassPath.
If cache is false, then
the method will always return a new class loader. If that parameter is true,
the method may return a loader which survived from a previous call to the same ClassPath.
Parameters: cache - true if it is permissible to cache class loaders between calls class loader which uses the roots in this class path to search for classes and resources since: 1.2.1
Find the classpath of a given type, if any, defined for a given file.
This method may return null, if:
the path type (id parameter) is not recognized
the path type is not defined for the given file object
Generally you may pass either an individual Java file, or the root of
a Java package tree, interchangeably, since in most cases all files
in a given tree will share a single classpath.
Typically classpaths for files are defined by the owning project, but
there may be other ways classpaths are defined. See
ClassPathProvider for more details.
Parameters: f - the file, whose classpath settings should be returned (may not be null as of org.netbeans.modules.gsfpath.api/1 1.4) Parameters: id - the type of the classpath (e.g. ClassPath.COMPILE) classpath of the desired type for the given file object, or null, ifthere is no classpath available See Also:ClassPathProvider
getResourceName
final publicString getResourceName(FileObject f)(Code)
Creates a suitable resource name for the given FileObject within the
classpath. The method will return null if the fileobject
is not underneath any of classpath roots.
The returned name uses uses slashes ('/') as folder separators and
dot ('.') to separate file name and its extension.
Note that if the file object is in the classpath subtree, but is not reachable
(it is hidden by some other resource, or
FilteringPathResourceImplementation excluded ), the resource name is still returned.
Java-style resource name for the given file object (the empty string for the package root itself), or null if notwithin the classpath Parameters: f - FileObject whose resource name is requested
getResourceName
final publicString getResourceName(FileObject f, char dirSep, boolean includeExt)(Code)
Computes a resource name for the FileObject, which uses `pathSep' character
as a directory separator. The resource name can be returned without the file
extension, if desired. Note that parent folder names are always returned with
extension, if they have some.
Parameters: f - FileObject whose resource name is requested. Parameters: dirSep - directory separator character Parameters: includeExt - whether the FileObject's extension should be included in the result resource name for the given FileObject (the empty string for the package root itself) or null
Retrieves valid roots of ClassPath, in the proper order.
If there's an entry in the ClassPath, which cannot be accessed,
its root is not returned by this method. FileObjects returned
are all folders.
Note that this method ignores
FilteringPathResourceImplementation includes and excludes .
array of roots (folders) of the classpath. Never returnsnull.
isResourceVisible
final public boolean isResourceVisible(FileObject resource)(Code)
Determines if the resource is visible in the classpath,
that is if the file will be reached when a process attempts to
load a resource of that name. It will return false when the resource
is not contained in the classpath, or the resource is
FilteringPathResourceImplementation excluded .
Parameters: resource - the resource whose visibility should be tested true, if the resource is contained in the classpath and visible;false otherwise.
