Using the Classpath API you can look up the classpath used for a certain purpose (such as compilation or running) on a certain file.

Contents

• Overview
• How to obtain a ClassPath
• Roots and the definition of the ClassPath
• Resource names and FileObjects
• Listening to classpath changes
• Replacements of FileSystems API methods

ClassPath API

Overview

At runtime, there's often only a single Classpath available through the application classloader. The application is often developed against a set of APIs, with some implementation provided at runtime. For example, if using JDBC, the application is compiled against JDBC API only and the proper driver is added to the runtime classpath. To avoid unintentional dependencies on implementation, the implementation classes are often stripped off the compilation path. Another case is debugging with special implementation libraries that - for example - perform special sanity checks or logging. Again, the classpath is different from those used during build or application's execution.

Since the IDE supports the whole development cycle, it needs to provide different classpaths for each of the purposes mentioned, and maybe for others, too. See {@link java.lang.ClassLoader}.

Obtaining ClassPath

The ClassPath API uses concept similar to Services to categorize ClassPaths. Instead of the class, a string token is used to name a service type. Various types such as {@link org.netbeans.api.java.classpath.ClassPath#COMPILE} are defined.

In addition to different services, the API also permits different files to have different classpaths configured for them. In addition to the desired classpath type, clients are required to pass in a FileObject of the user file, which is the "starting point" for the classpath search.

To obtain a ClassPath instance for the given FileObject and intended usage, you want to call {@link org.netbeans.api.java.classpath.ClassPath#getClassPath} as in this example for getting compilation classpath:

FileObject f = getSomeJavaSourceFile();
ClassPath cp = ClassPath.getClassPath(f, ClassPath.COMPILE);
System.err.println(cp);

Roots and definition of the classpath

The classpath is formed from one or more roots. JRE itself supports at least two types of of them: a root can be either a directory or an archive (.jar or .zip file). The definition of the classpath cannot maintain integrity with the root folders or archives. If one of them is renamed, deleted or otherwise changed, its entry in the classpath becomes invalid and does not contribute to the contents of the classpath. Note that the entry cannot be removed automagically, since an archive can disappear (for example) because of the compilation products in a subproject. Note that regardless of where the classpath entry is an archive, or a folder, the root returned for it will be always a folder. For archive files, it will be the root folder of the archive filesystem.

For most purposes, working with only those roots which are valid, is sufficient enough. The error condition can be detected when a required resource is missing, for example. For some tasks checking for validity of individual classpath entries may be appropriate, the build process being a notable example. For others, like searches or parsing, such behaviour is hihgly undesirable.

If you don't need to notify the user that the definition of classpath is not correct (there are other ways or another, more appropriate, time to notify the user), you can use {@link org.netbeans.api.java.classpath.ClassPath#getRoots} to find out what folders are the roots:

ClassPath cp = ClassPath.getClassPath(myClassFile, ClassPath.EXECUTE);
FileObject[] roots = cp.getRoots();
for (int i = 0; i < roots.length; i++) {
    System.err.print(roots[i] + ":");
}

Clients who need to find out whether the environment is set up well, may work more thoroughly using {@link org.netbeans.api.java.classpath.ClassPath.Entry} objects:

ClassPath cp = ClassPath.getClassPath(myClassObject, ClassPath.EXECUTE);
List entries = cp.entries();
for (Iterator it = entries.iterator(); it.hasNext(); ) {
    ClassPath.Entry en = (ClassPath.Entry)it.next();
    if (!en.isValid()) {
        IOException x = en.getError();
        // Report the error somehow, perhaps using org.openide.ErrorManager.
    } else {
        FileObject root = en.getRoot();
        // Do something with the root folder
    }
}

Resource Names and FileObjects

The resource name is essentially a file name, relative to the root of classpath. If the classpath has more roots (it's a classpath forest rather than a single tree), they are combined and merged together to give one "logical" tree. The merge operation has one subtle property, resource hiding: when there are several resources of the same name in the classpath forest, the order of the roots that define the classpath matters and the only the first resource encountered (in that order) is visible for the ClassLoader.

Often a FileObject is viewed as a resource to the application being developed. It's the most used view for Java sources, as they are required to appear in an appropriate folder in the source tree, but for other objects as well. For example, the IDE support for images need to record the resource name of the image so that it can be loaded at runtime using {@link java.lang.ClassLoader#getResourceAsStream}. If you need to obtain a name for FileObject, which is relative to the classpath, you first have to think about for which service do you need it. For resource bundles, for example, it will be mostly the execution service. Then you will get the appropriate {@link org.netbeans.api.java.classpath.ClassPath} instance and ask it to compute the name for you:

FileObject f = bundleDataObject.getPrimaryFile();
ClassPath cp = ClassPath.getClassPath(theSourceDataObject.getPrimaryFile(), ClassPath.EXECUTE);
String bundleResource = cp.getResourceName(f);

To check whether a resource (FileObject) is visible or not to the service, you may want to call {@link org.netbeans.api.java.classpath.ClassPath#isResourceVisible}. You may want to do just the opposite, to get a FileObject for a resource name you have. Since there may be more resources of that name, the API supports {@link org.netbeans.api.java.classpath.ClassPath#findResource} to get the visible one, or {@link org.netbeans.api.java.classpath.ClassPath#findAllResources} to get a collection of all resources matching the name.

Listening to changes in ClassPath

The ClassPath interface supports listening to either root folder set changes or entry set changes. Changes in root folder set can be observed by property change listeners, they are reported as additions, deletions or changes to the order of roots. For example, to watch out for new compile-time dependencies, you may do:

FileObject f; // some interesting FileObject.
ClassPath cp = ClassPath.getClassPath(f, ClassPath.COMPILE);
cp.addPropertyChangeListener(new PropertyChangeListener() {
    public void propertyChange(PropertyChangeEvent evt) {
        if (ClassPath.PROP_ROOTS.equals(evt.getPropertyName())) {
            // Update your stuff, because classpath roots have changed.
        }
    }
});

You may also listen entries property. Note that the root folder set may change even though the entry set did not change, as a result of some entry becoming (in)valid.

Replacements of FileSystems API methods

The now-deprecated way how to obtain a resource name for a file object was to call {@link org.openide.filesystems.FileObject#getPackageNameExt}. But the getPackageNameExt() method gives a name of the file within the FileSystem rather than its relative path from some classpath root point. Therefore it is no longer recommended to use the {@link org.openide.filesystems Filesystems API} to obtain classpaths.

As the {@link org.openide.filesystems.Repository} searches through FileSystems without regard to the intended usage for individual services, {@link org.openide.filesystems.Repository#findResource} and {@link org.openide.filesystems.Repository#findAllResources} should not be used at all. {@link org.netbeans.api.java.classpath.GlobalPathRegistry} may be used to find certain kinds of files that are available among open projects in the GUI, but this should be used only as a last resort if there is no other possible source of information about where a file might be located according to specific classpaths. The usage of the class {@link org.openide.filesystems.FileSystemCapability} is deprecated; you should use methods of {@link org.netbeans.api.java.classpath.ClassPath} instead of that.

Old method	New method
{@link org.openide.filesystems.FileObject#getPackageName} and {@link org.openide.filesystems.FileObject#getPackageName}	{@link org.netbeans.api.java.classpath.ClassPath#getResourceName}
{@link org.openide.filesystems.FileSystemCapability#findResource}	{@link org.netbeans.api.java.classpath.ClassPath#findResource}
{@link org.openide.filesystems.FileSystemCapability#findAllResources}	{@link org.netbeans.api.java.classpath.ClassPath#findAllResources}
{@link org.openide.filesystems.FileSystemCapability#fileSystems}	{@link org.netbeans.api.java.classpath.ClassPath#getRoots}
{@link org.openide.filesystems.Repository#findResource}	{@link org.netbeans.api.java.classpath.GlobalPathRegistry#findResource}
{@link org.openide.filesystems.Repository#findAllResources}	{@link org.netbeans.api.java.classpath.GlobalPathRegistry#getSourceRoots}

{@link org.netbeans.api.java.queries.SourceForBinaryQuery} lets you find the sources used to compile some Java classfiles you know about.

The usual usecase goes like this:

ProgressHandle handle = ProgressHandleFactory.createHandle("My custom task");
...
// we have 100 workunits
// at this point the task appears in status bar.
handle.start(100);
...
handle.progress(10);
...
handle.progress(50);
...
// at this point the task is finished and removed from status bar
handle.finish();

• task with unknown duration or with hard to show progress steps.
• task with known scaled steps
• task with known steps and also with a time estimate for completion

Note: The APIs in the package resemble the APIs from the main package but are separate.
There are the same visualization options as with the regular progress indication, with additional customization options provided.

• There are multiple, possibly independent sources of task's progress.
• These progress sources (contributors) can be added even during the task's run.
• The infrastructure assures that the progressbar never steps back but recalculates the remaining space among the running contributors.
• It's possible to monitor the progress from a central place.

This package contains ActionFactory class which is factory of all built-in widget-actions provided by the library.

Widget-actions are defined by WidgetAction interface. Also there is an adapter (WidgetAction.Adapter) and special lock-aware version (WidgetAction.LockedAdapter).

Factories requires various input parameter:

• *Provider interfaces are used for providing a action logic or for notifying about state of actions.
• *Decorator interfaces are used for supplying the look of visual element e.g. the style of align-with guide-lines.
• *Strategy interfaces are used for filtering data e.g. snap-to-grid movement strategy.
• *Editor interfaces are used for providing particular in-place editors.

Built-in implementation of those interfaces can be found in ActionFactory class too.

This package contains Anchor interface which is used by ConnectionWidget for defining its source and target point. Built-in anchor implementations can be obtained using AnchorFactory class.

The package also contains AnchorShape interface which is used for defining a shape of a ConnectionWidget. Built-in anchor shape implementations can be obtained using AnchorShapeFactory class or using static field: AnchorShape.NONE, AnchorShape.TRIANGLE_HOLLOW, AnchorShape.TRIANGLE_FILLED and AnchorShape.TRIANGLE_OUT.

This package contains SceneAnimator classes which is used for controlling animations on a scene. Also you can supply your own animator by implementing Animator class. Also you can listen on each animator using AnimatorListener interface.

This package contains Border interface which is used for supplying a border graphics for a widget. Built-in border implementations can be created using BorderFactory class.

This package contains built-in graph-oriented models. They are based on a ObjectScene class.

The GraphScene provides a model with nodes and edges. An edge can have a source and target node specified.

The GraphPinScene providers a model with nodes, pins and edges. A pin is always assigned to a node and an edge can have a source and target pin specified.

This package contains built-in graph-oriented layout algorithms. This layout is not related with widget-oriented layout in org.netbeans.api.visual.layout package. There is GraphLayout class which is used for defining a graph layout. The layout implementation does not have be based this class but it would make its integration with the rest of the library easier.

This package contains LookFeel class with style definition for colors and borders. Default style can be created by LookFeel.createDefaultLookFeel method.

This package contains Layout interface which defines a widget-layout. Widget-layout is similar to Swing-layout. It defines how children widgets should layed out. This layout is not related with graph-oriented layout in org.netbeans.api.visual.graph.layout package.

This package contains ObjectScene class which is a scene with ability to register model-objects with widgets on the scene. Also it holds information about selected, hightlighted, focused and hovered objects. Everything is object-oriented (not widget-oriented).

This package contains Router interface which defines a router for ConnectionWidget. The router has to resolve list of control points for a connection. Then ConnectionWidget uses it as a path for rendering, hit-checking, ...

Built-in router implementations can be created using RouterFactory class.

This package contains a VMD visualization style. The VMD stands for Visual Mobile Designer and is targeted to be used for graph-oriented model based on GraphPinScene. The VMD package providers an integrated set of widgets.

All classes can be used together or standalone except that the VMDNodeWidget expect to have VMDPinWidget added a special way using VMDNodeWidget.attachPinWidget method.

This package contains Widget class. Widget is a small reusable piece of a scene. This defines appearance. Widgets can also has widget-actions assigned. This defines behaviour.

The package contains a set of low-level widgets. E.g.:

• Widget - base/abstract widget - similar to JComponent in Swing
• Scene - widget which represents and holds whole scene - similar to JFrame in Swing
• LayerWidget - special transparent widget used for overlays - similar JGlassPane in Swing
• ConnectionWidget - specific widget which represents path defined by control-points
• LabelWidget - widget with a single-line text - similar to simple version of JLabel in Swing
• ImageWidget - widget with an image - similar to simple version of JLabel in Swing
• ScrollWidget - widget with scrollable viewport - similar to simple version of JScrollPane in Swing
• SwingScrollWidget - widget with scroolable viewport which is using JScrollBars
• ComponentWidget - widget used for integration of Swing component into a scene

This package contains general high-level widgets.

XML Tools Cookies API

No UI Interaction Pattern

Plans

XML Tools Parser APIs

XML Tools Service APIs

This API will typically be used by modules that provide data objects, wizards, editors, etc. for files used in J2EE web module (JSP, Html, deployment descriptor, etc.). It will be also used by web framework clients and implementors.

This API will typically be used by modules that implement project types for J2EE web module (various implementations of web module project, web module with web services, portlets, etc.). It can be also used for implementation of web module that is not based on Projects API. Another use case is implementing support for web frameworks such as Struts or JSF.

A module that implements this API needs to expose an implementation of {@link org.netbeans.modules.web.spi.webmodule.WebModuleProvider} either in the project lookup (for implementations based on the Projects API) or in the global lookup. The module will implement {@link org.netbeans.modules.web.spi.webmodule.WebModuleImplementation} and use {@link org.netbeans.modules.web.spi.webmodule.WebModuleFactory} to create a {@link org.netbeans.modules.web.api.webmodule.WebModule}.

A module wanting to provide support for a web framework needs to implement {@link org.netbeans.modules.web.spi.webmodule.WebFrameworkProvider} and usually also {@link org.netbeans.modules.web.spi.webmodule.WebModuleExtender}.

{@link org.netbeans.spi.java.classpath.ClassPathProvider}s can be registered to default lookup in order to associate information about classpaths with files. For example, a Java-oriented project type would normally indicate that its Java sources have a certain classpath associated with them.
For a source file the ClassPathProvider has to return a {@link org.netbeans.api.java.classpath.ClassPath} of the following ClassPath types:

• ClassPath.SOURCE - the classpath contains the source roots of the project
• ClassPath.BOOT - the classpath contains the jdk runtime libraries
• ClassPath.COMPILE - the classpath contains the project compile libraries (compile classpath)

• ClassPath.BOOT - the classpath contains the jdk runtime libraries
• ClassPath.COMPILE - the classpath contains the project compile libraries (compile classpath)
• ClassPath.EXEC - the classpath contains the build output folder

{@link org.netbeans.spi.java.classpath.ClassPathFactory} may be used to create new {@link org.netbeans.api.java.classpath.ClassPath} instances.

{@link org.netbeans.spi.java.classpath.support.ClassPathSupport} provides various ways to create {@link org.netbeans.api.java.classpath.ClassPath} objects beyond what the plain SPI provides.

{@link org.netbeans.spi.java.classpath.support.PathResourceBase} and {@link org.netbeans.spi.java.classpath.support.CompositePathResourceBase} can be used to define parts of a classpath in a controlled way.

XML Tools Cookies SPI

Requirements

• directly useful for common cases (XML is primary file)
• customizable for special cases

DataObject Supports

Other Supports