org.netbeans.api.java.classpath

Java Source Code / Java Documentation
1. 6.0 JDK Core
2. 6.0 JDK Modules
3. 6.0 JDK Modules com.sun
4. 6.0 JDK Modules com.sun.java
5. 6.0 JDK Modules sun
6. 6.0 JDK Platform
7. Ajax
8. Apache Harmony Java SE
9. Aspect oriented
10. Authentication Authorization
11. Blogger System
12. Build
13. Byte Code
14. Cache
15. Chart
16. Chat
17. Code Analyzer
18. Collaboration
19. Content Management System
20. Database Client
21. Database DBMS
22. Database JDBC Connection Pool
23. Database ORM
24. Development
25. EJB Server geronimo
26. EJB Server GlassFish
27. EJB Server JBoss 4.2.1
28. EJB Server resin 3.1.5
29. ERP CRM Financial
30. ESB
31. Forum
32. GIS
33. Graphic Library
34. Groupware
35. HTML Parser
36. IDE
37. IDE Eclipse
38. IDE Netbeans
39. Installer
40. Internationalization Localization
41. Inversion of Control
42. Issue Tracking
43. J2EE
44. JBoss
45. JMS
46. JMX
47. Library
48. Mail Clients
49. Net
50. Parser
51. PDF
52. Portal
53. Profiler
54. Project Management
55. Report
56. RSS RDF
57. Rule Engine
58. Science
59. Scripting
60. Search Engine
61. Security
62. Sevlet Container
63. Source Control
64. Swing Library
65. Template Engine
66. Test Coverage
67. Testing
68. UML
69. Web Crawler
70. Web Framework
71. Web Mail
72. Web Server
73. Web Services
74. Web Services apache cxf 2.0.1
75. Web Services AXIS2
76. Wiki Engine
77. Workflow Engines
78. XML
79. XML UI
Java
Java Tutorial
Java Open Source
Jar File Download
Java Articles
Java Products
Java by API
Photoshop Tutorials
Maya Tutorials
Flash Tutorials
3ds-Max Tutorials
Illustrator Tutorials
GIMP Tutorials
C# / C Sharp
C# / CSharp Tutorial
C# / CSharp Open Source
ASP.Net
ASP.NET Tutorial
JavaScript DHTML
JavaScript Tutorial
JavaScript Reference
HTML / CSS
HTML CSS Reference
C / ANSI-C
C Tutorial
C++
C++ Tutorial
Ruby
PHP
Python
Python Tutorial
Python Open Source
SQL Server / T-SQL
SQL Server / T-SQL Tutorial
Oracle PL / SQL
Oracle PL/SQL Tutorial
PostgreSQL
SQL / MySQL
MySQL Tutorial
VB.Net
VB.Net Tutorial
Flash / Flex / ActionScript
VBA / Excel / Access / Word
XML
XML Tutorial
Microsoft Office PowerPoint 2007 Tutorial
Microsoft Office Excel 2007 Tutorial
Microsoft Office Word 2007 Tutorial
Java Source Code / Java Documentation » IDE Netbeans » api » org.netbeans.api.java.classpath 
org.netbeans.api.java.classpath
Representation of Java classpaths, and the ability to find the classpath needed for a particular purpose.

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

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 methodNew 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}

Java Source File NameTypeComment
ClassLoaderSupport.javaClass Classloader for the filesystem pool.
ClassPath.javaClass ClassPath objects should be used to access contents of the ClassPath, searching for resources, objects reachable using the ClassPath at runtime.
ClassPathTest.javaClass
GlobalPathRegistry.javaClass 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 GlobalPathRegistry.getPaths 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.

GlobalPathRegistryEvent.javaClass Event object giving details of a change in the path registry.
GlobalPathRegistryListener.javaInterface Event listener interface for being notified of changes in the set of available paths.
GlobalPathRegistryTest.javaClass Test functionality of GlobalPathRegistry.
www.java2java.com | Contact Us
Copyright 2009 - 12 Demo Source and Support. All rights reserved.
All other trademarks are property of their respective owners.