org.netbeans.api.java.classpath

Class GlobalPathRegistry

java.lang.Object

org.netbeans.api.java.classpath.GlobalPathRegistry

public final class GlobalPathRegistry
extends Object

Maintains a global registry of "interesting" classpaths of various kinds. You may add and remove different kinds of ClassPaths to the registry and listen to changes in them.

It is permitted to register the same classpath more than once; unregistration keeps track of the number of registrations so that the operation is symmetric. However getPaths(java.lang.String) only ever returns one copy of the classpath, and listeners are only notified the first time a given classpath is added to the registry, or the last time it is removed. (ClassPath equality is based on equality of the ClassPathImplementation which by default is based on object identity, so there could be multiple paths returned that at the time share the same list of roots. There may also be several paths which contain some shared roots.)

The registry is not persisted between JVM sessions.

Intended usage patterns:

1. When a project is opened using org.netbeans.spi.project.ui.ProjectOpenedHook it should add any paths it defines, i.e. paths it might return from a ClassPathProvider. When closed it should remove them.

2. The Fast Open feature of the editor and other features which require a global list of relevant sources should use getSourceRoots() or the equivalent.

3. The Javadoc Index Search feature and View → Documentation Indices submenu should operate on open Javadoc paths, meaning that Javadoc corresponding to registered compile and boot classpaths (according to org.netbeans.api.java.queries.JavadocForBinaryQuery).

4. Stack trace hyperlinking can use the global list of source paths to find sources, in case no more specific information about their origin is available. The same would be true of debugging: if the debugger cannot find Java-like sources using more precise means (SourceForBinaryQuery), it can use findResource(java.lang.String) as a fallback.

Since:

org.netbeans.api.java/1 1.4

Method Summary

Modifier and Type	Method and Description
void	addGlobalPathRegistryListener(GlobalPathRegistryListener l) Add a listener to the registry.
FileObject	findResource(String resource) Convenience method to find a particular source file by resource path.
static GlobalPathRegistry	getDefault() Get the singleton instance of the registry.
Set<ClassPath>	getPaths(String id) Find all paths of a certain type.
Set<FileObject>	getSourceRoots() Convenience method to find all relevant source roots.
void	register(String id, ClassPath[] paths) Register some classpaths of a certain type.
void	removeGlobalPathRegistryListener(GlobalPathRegistryListener l) Remove a listener to the registry.
void	unregister(String id, ClassPath[] paths) Unregister some classpaths of a certain type.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getDefault

@NonNull
public static GlobalPathRegistry getDefault()

Get the singleton instance of the registry.

In environments with scoped global lookup don't cache an instance of the GlobalPathRegistry but rather call the getDefault() when the instance is needed.

Returns:

the default instance

getPaths

@NonNull
public Set<ClassPath> getPaths(@NonNull
                                        String id)

Find all paths of a certain type.

Parameters:

id - a classpath type, e.g. ClassPath.SOURCE

Returns:

an immutable set of all registered ClassPaths of that type (may be empty but not null)

register

public void register(@NonNull
                     String id,
                     @NonNull
                     ClassPath[] paths)

Register some classpaths of a certain type.

Parameters:

id - a classpath type, e.g. ClassPath.SOURCE

paths - a list of classpaths to add to the registry

unregister

public void unregister(@NonNull
                       String id,
                       @NonNull
                       ClassPath[] paths)
                throws IllegalArgumentException

Unregister some classpaths of a certain type.

Parameters:

id - a classpath type, e.g. ClassPath.SOURCE

paths - a list of classpaths to remove from the registry

Throws:

IllegalArgumentException - if they had not been registered before

addGlobalPathRegistryListener

public void addGlobalPathRegistryListener(GlobalPathRegistryListener l)

Add a listener to the registry.

Parameters:

l - a listener to add

removeGlobalPathRegistryListener

public void removeGlobalPathRegistryListener(GlobalPathRegistryListener l)

Remove a listener to the registry.

Parameters:

l - a listener to remove

getSourceRoots

public Set<FileObject> getSourceRoots()

Convenience method to find all relevant source roots. This consists of:

1. Roots of all registered ClassPath.SOURCE paths.
2. Sources (according to SourceForBinaryQuery) of all registered ClassPath.COMPILE paths.
3. Sources of all registered ClassPath.BOOT paths.

Order is not significant.

Currently there is no reliable way to listen for changes in the value of this method: while you can listen to changes in the paths mentioned, it is possible for SourceForBinaryQuery results to change. In the future a change listener might be added for the value of the source roots.

Note that this method takes no account of package includes/excludes.

Returns:

an immutable set of FileObject source roots

findResource

public FileObject findResource(String resource)

Convenience method to find a particular source file by resource path. This simply uses getSourceRoots() to find possible roots and looks up the resource among them. In case more than one source root contains the resource, one is chosen arbitrarily. As with ClassPath.findResource(java.lang.String), include/exclude lists can affect the result.

Parameters:

resource - a resource path, e.g. somepkg/Foo.java

Returns:

some file found with that path, or null