ClassPath (Classpath APIs)

java.lang.Object
- org.netbeans.api.java.classpath.ClassPath

```
public final class ClassPath
extends Object
```
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.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`ClassPath.Entry` Represents an individual entry in the ClassPath.
`static class`	`ClassPath.Flag` ClassPath's flags.
`static class`	`ClassPath.PathConversionMode` Policy for handling path items which cannot be converted into the desired format.
`static class`	`ClassPath.PathEmbeddingMode` Policy for handling in archive path.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`BOOT` Boot ClassPath of the JDK.
`static String`	`COMPILE` ClassPath for compiling things.
`static String`	`DEBUG` Deprecated. Probably useless.
`static ClassPath`	`EMPTY` The empty ClassPath.
`static String`	`EXECUTE` Classpath setting for executing things.
`static String`	`PROP_ENTRIES` Name of the "entries" property
`static String`	`PROP_FLAGS` Name of the "flags" property
`static String`	`PROP_INCLUDES` Property to be fired when include/exclude set changes.
`static String`	`PROP_ROOTS` Name of the "roots" property
`static String`	`SOURCE` ClassPath for project sources.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addPropertyChangeListener(PropertyChangeListener l)` Adds a property change listener to the bean.
`boolean`	`contains(FileObject f)` Checks whether a FileObject lies on this classpath.
`List<ClassPath.Entry>`	`entries()` Returns list of classpath entries from the ClassPath definition.
`boolean`	`equals(Object obj)`
`List<FileObject>`	`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.
`FileObject`	`findOwnerRoot(FileObject resource)` Finds a root in this ClassPath, that owns the given file.
`FileObject`	`findResource(String resourceName)` Returns a FileObject for the specified resource.
`ClassLoader`	`getClassLoader(boolean cache)` Returns a ClassLoader for loading classes from this ClassPath.
`static ClassPath`	`getClassPath(FileObject f, String id)` Find the classpath of a given type, if any, defined for a given file.
`Set<ClassPath.Flag>`	`getFlags()` Returns the `ClassPath`'s flags.
`String`	`getResourceName(FileObject f)` Creates a suitable resource name for the given FileObject within the classpath.
`String`	`getResourceName(FileObject f, char dirSep, boolean includeExt)` Computes a resource name for the FileObject, which uses `pathSep' character as a directory separator.
`FileObject[]`	`getRoots()` Retrieves valid roots of ClassPath, in the proper order.
`int`	`hashCode()`
`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.
`void`	`removePropertyChangeListener(PropertyChangeListener l)` Removes the listener registered by `addPropertyChangeListener`.
`String`	`toString()` Calls `ClassPath.toString(ClassPath.PathConversionMode)` with `ClassPath.PathConversionMode.PRINT`.
`String`	`toString(ClassPath.PathConversionMode conversionMode)` Render this classpath in the conventional format used by the Java launcher.
`String`	`toString(ClassPath.PathConversionMode conversionMode, ClassPath.PathEmbeddingMode pathEmbeddingMode)` Render this classpath in the conventional format used by the Java launcher.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - EXECUTE
```
public static final String EXECUTE
```
    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).
    
    See Also:
    
    Constant Field Values
  - DEBUG
```
@Deprecated
public static final String DEBUG
```
    Deprecated. Probably useless.
    
    Classpath for debugging things
    
    See Also:
    
    Constant Field Values
  - COMPILE
```
public static final String COMPILE
```
    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.
    
    See Also:
    
    Constant Field Values
  - SOURCE
```
public static final String SOURCE
```
    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.
    
    Since:
    
    org.netbeans.api.java/1 1.4
    
    See Also:
    
    Constant Field Values
  - BOOT
```
public static final String BOOT
```
    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.
    
    Since:
    
    org.netbeans.api.java/1 1.4
    
    See Also:
    
    Constant Field Values
  - PROP_ROOTS
```
public static final String PROP_ROOTS
```
    Name of the "roots" property
    
    See Also:
    
    Constant Field Values
  - PROP_ENTRIES
```
public static final String PROP_ENTRIES
```
    Name of the "entries" property
    
    See Also:
    
    Constant Field Values
  - PROP_FLAGS
```
public static final String PROP_FLAGS
```
    Name of the "flags" property
    
    Since:
    
    1.43
    
    See Also:
    
    Constant Field Values
  - PROP_INCLUDES
```
public static final String PROP_INCLUDES
```
    Property to be fired when include/exclude set changes.
    
    Since:
    
    org.netbeans.api.java/1 1.13
    
    See Also:
    
    FilteringPathResourceImplementation, Constant Field Values
  - EMPTY
```
public static final ClassPath EMPTY
```
    The empty ClassPath. Contains no entries and never fires events.
    
    Since:
    
    1.24
- Method Detail
  - getRoots
```
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. FileObjects returned are all folders. Note that this method ignores includes and excludes.
    
    Returns:
    
    array of roots (folders) of the classpath. Never returns null.
  - entries
```
public List<ClassPath.Entry> 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. Clients must assume that the returned value is immutable.
    
    Returns:
    
    list of definition entries (Entry instances)
  - findResource
```
public final FileObject findResource(String resourceName)
```
    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 passed to ClassLoader.getResource(java.lang.String)
    
    Returns:
    
    FileObject for the resource, or null if the resource cannot be found in this ClassPath.
  - findAllResources
```
public final List<FileObject> 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. 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
    
    Returns:
    
    list of resources identified by the given name.
  - getResourceName
```
public final String getResourceName(FileObject f)
```
    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 excluded), the resource name is still returned.
    
    Parameters:
    
    f - FileObject whose resource name is requested
    
    Returns:
    
    Java-style resource name for the given file object (the empty string for the package root itself), or null if not within the classpath
  - getResourceName
```
public final String getResourceName(FileObject f,
                                    char dirSep,
                                    boolean includeExt)
```
    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.
    
    dirSep - directory separator character
    
    includeExt - whether the FileObject's extension should be included in the result
    
    Returns:
    
    resource name for the given FileObject (the empty string for the package root itself) or null
  - findOwnerRoot
```
@CheckForNull
public final FileObject findOwnerRoot(FileObject resource)
```
    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.
    
    Parameters:
    
    resource - resource to find root for.
    
    Returns:
    
    classpath root, which hosts the specified resouce. It can return null, if the resource is not within the ClassPath contents.
  - contains
```
public final boolean contains(FileObject f)
```
    Checks whether a FileObject lies on this classpath. FilteringPathResourceImplementation is considered.
    
    Parameters:
    
    f - the FileObject to check
    
    Returns:
    
    true, if the parameter is inside one of the classpath subtrees, false otherwise.
  - isResourceVisible
```
public final 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. It will return false when the resource is not contained in the classpath, or the resource is excluded.
    
    Parameters:
    
    resource - the resource whose visibility should be tested
    
    Returns:
    
    true, if the resource is contained in the classpath and visible; false otherwise.
  - addPropertyChangeListener
```
public final void addPropertyChangeListener(PropertyChangeListener l)
```
    Adds a property change listener to the bean.
    
    Parameters:
    
    l - a listener to add
  - removePropertyChangeListener
```
public final void removePropertyChangeListener(PropertyChangeListener l)
```
    Removes the listener registered by addPropertyChangeListener.
    
    Parameters:
    
    l - a listener to remove
  - getFlags
```
@NonNull
public Set<ClassPath.Flag> getFlags()
```
    Returns the ClassPath's flags.
    
    Returns:
    
    the ClassPath.Flags
    
    Since:
    
    1.44
  - getClassPath
```
@CheckForNull
public static ClassPath getClassPath(@NonNull
                                                   FileObject f,
                                                   @NonNull
                                                   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. See ClassPathProvider for more details.
    Parameters:
    
    f - the file, whose classpath settings should be returned (may not be null as of org.netbeans.api.java/1 1.4)
    
    id - the type of the classpath (e.g. ClassPath.COMPILE)
    
    Returns:
    
    classpath of the desired type for the given file object, or null, if there is no classpath available
    
    See Also:
    
    ClassPathProvider
  - toString
```
@NonNull
public String toString(@NonNull
                                ClassPath.PathConversionMode conversionMode,
                                @NonNull
                                ClassPath.PathEmbeddingMode pathEmbeddingMode)
```
    Render this classpath in the conventional format used by the Java launcher.
    
    Parameters:
    
    conversionMode - policy for converting unusual entries
    
    pathEmbeddingMode - policy for handling in archive path
    
    Returns:
    
    a conventionally-formatted representation of the classpath
    
    Since:
    
    1.52
    
    See Also:
    
    File.pathSeparator, FileUtil.archiveOrDirForURL(java.net.URL), ClassPathSupport.createClassPath(String)
  - toString
```
@NonNull
public String toString(@NonNull
                                ClassPath.PathConversionMode conversionMode)
```
    Render this classpath in the conventional format used by the Java launcher.
    
    Parameters:
    
    conversionMode - policy for converting unusual entries
    
    Returns:
    
    a conventionally-formatted representation of the classpath
    
    Since:
    
    org.netbeans.api.java/1 1.15
    
    See Also:
    
    File.pathSeparator, FileUtil.archiveOrDirForURL(java.net.URL), ClassPathSupport.createClassPath(String)
  - toString
```
@NonNull
public String toString()
```
    Calls ClassPath.toString(ClassPath.PathConversionMode) with ClassPath.PathConversionMode.PRINT.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    a classpath suitable for logging or debugging
  - equals
```
public boolean equals(Object obj)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object
  - getClassLoader
```
public final ClassLoader getClassLoader(boolean cache)
```
    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
    
    Returns:
    
    class loader which uses the roots in this class path to search for classes and resources
    
    Since:
    
    1.2.1

Class ClassPath

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

EXECUTE

DEBUG

COMPILE

SOURCE

BOOT

PROP_ROOTS

PROP_ENTRIES

PROP_FLAGS

PROP_INCLUDES

EMPTY

Method Detail

getRoots

entries

findResource

findAllResources

getResourceName

getResourceName

findOwnerRoot

contains

isResourceVisible

addPropertyChangeListener

removePropertyChangeListener

getFlags

getClassPath

toString

toString

toString

equals

hashCode

getClassLoader