Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.netbeans.api.java/1 1.10.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 `ClassPath`s 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 identity is 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 `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 `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
`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` | `getPaths(String id)` Find all paths of a certain type.
`Set` | `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

    public static GlobalPathRegistry getDefault()

  Get the singleton instance of the registry.

  Returns:
    the default instance

### getPaths

    public Set getPaths(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 `ClassPath`s of that type (may be empty but not null)

### register

    public void register(String id,
                         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(String id,
                           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 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.

  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.

  Parameters:
    `resource` - a resource path, e.g. `somepkg/Foo.java`
  Returns:
    some file found with that path, or null

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.netbeans.api.java/1 1.10.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.