GlobalPathRegistry (NetBeans Java Support APIs) - NetBeans API Javadoc 5.0.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

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 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 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:

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.
The Fast Open feature of the editor and other features which require a global list of relevant sources should use getSourceRoots() or the equivalent.
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).
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 ClassPaths of that type (may be empty but not null)

register

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

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:

Roots of all registered ClassPath.SOURCE paths.
Sources (according to SourceForBinaryQuery) of all registered ClassPath.COMPILE paths.
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