A {@link org.netbeans.api.project.Project} is a representation of a folder which may contain various kinds of development artifacts and/or metadata. Projects can be loaded, saved, etc. using {@link org.netbeans.api.project.ProjectManager}.

{@link org.netbeans.api.project.FileOwnerQuery} is a simple way to associate a file or folder with a project. Typically, all files beneath a project's folder are considered "owned" by that project. A given file can be owned by at most one project.

An {@link org.netbeans.api.project.ant.AntArtifact} is a representation of a build product created from a (somehow Ant-based) project. Rather than relying on details of how another project arranges its builds, a parent project can use {@link org.netbeans.api.project.ant.AntArtifactQuery} to find Ant artifacts from another project (or, perhaps, arbitrary source not formally contained in a project). Using artifact information it is possible to tell what build product (file or directory) will be created and what general sort it is (e.g. JAR vs. Javadoc); which Ant script and target to run to create that build product; and how to request that it be cleaned. This information suffices to create an Ant build script in the parent project that can run sub-builds.

Representation of a library, and the ability to find the installed libraries.

Contents

• Overview
• How to obtain a list of installed libraries
• Managing libraries
• Library definition format

Libraries API

Overview

The libraries API provides a client API of the Libraries framework. The Library itself is a typed set of volumes. The volume is a ordered list of resources. The type of library implies the volumes contained in it. For example the Java SE library contains three volumes (sources, classpath and javadoc). The resource is a valid URL of the physical resource.

How to obtain a list of installed libraries or given library

To obtain a list of installed libraries you want to call {@link org.netbeans.api.project.libraries.LibraryManager#getLibraries} as in the following example for listing the names of installed libraries.

Library[] libraries = LibraryManager.getDefault().getLibraries ();
for (int i = 0; i< libraries.length; i++) {
    System.out.println(libraries[i].getName()+" : "+libraries[i].getType());
}

Library library = LibraryManager.getDefault().getLibrary ("Ant");
if (library != null) {
    System.out.println(library.getName()+" : "+libraries[i].getType());
}

Managing libraries

To open the graphical libraries manager you need to call {@link org.netbeans.api.project.libraries.LibrariesCustomizer#showCustomizer} method.

Library definition format

A module is able to register the predefined library. For example the junit module installs the junit library. The library definition is placed in the org-netbeans-api-project-libraries/Libraries folder on the system filesystem.

The library format is given by the following DTD.

<?xml version="1.0" encoding="UTF-8"?>

<!--
  Root element of library definition descriptor.
-->
<!ELEMENT library (name, type, description?, localizing-bundle?, volume*) >

<!-- The version attribute specifies the version of the library -->

<!ATTLIST library version CDATA #FIXED "1.0" >

<!--- Library unique identifier - a string.

 In the case when the localizing-bundle element presents the name value is used 
 as a key into bundle to locate the display name. Otherwise the name value is 
 used as a display name-->
<!ELEMENT name (#PCDATA) >

<!--Short description of given library - a string.
 In the case when the localizing-bundle element presents the description value
 is used as a key into bundle to locate the localized description. Otherwise
 the description value is used.-->
<!ELEMENT description (#PCDATA) >

<!-- The resource name of base bundle without an extension - a string.
 The bundle used to lookup the localized strings.
 The bundle is looked up by NbBundle.getBundle (String) method.
 Example of localizing bundle: org.netbeans.modules.junit.resources.Bundle -->
<!ELEMENT localizing-bundle (#PCDATA)>

<!--- Volume is typed list of resources -->
<!ELEMENT volume (type, resource*) >

<!--- Volume type of a library volume - a string 
 For example the Java SE library supports the following types of volume:

 classpath, javadoc and src -->
<!ELEMENT type (#PCDATA) >

<!--- Volume resource coded as an URL
 In the case of URL with nbinst protocol the URL is resolved from the NetBeans installation
 dircetory.
 If the URL points to an archive file, the URL must have the jar protocol.
 Example:
 jar:file:///usr/lib/java/xerces.jar!/ is resolved to /usr/lib/java/xerces.jar/
 jar:nbinst://org.netbeans.modules.junit/modules/ext/junit.jar!/ is resolved to ${netbeans.home}/modules/ext/junit.jar

 -->
<!ELEMENT resource (#PCDATA) >

Each kind of project in the system needs to be loaded by a {@link org.netbeans.spi.project.ProjectFactory}, which defines how to recognize projects on disk, load their metadata into memory, and save their metadata back to disk. {@link org.netbeans.spi.project.ProjectState} is used to let the factory mark a project as being modified in memory.

Projects will normally put implementations of several interfaces such as {@link org.netbeans.spi.project.ActionProvider} into their lookup.

An {@link org.netbeans.api.project.ant.AntArtifact} can be used to represent a build product of a sub-project, typically used as a dependency in a parent project. {@link org.netbeans.spi.project.ant.AntArtifactProvider} can be used to enumerate artifacts (i.e. targets creating some files) which are recommended for export to parent projects.

A typical project based on Ant follows a standard pattern of having a project folder containing:

build.xml

A top-level editable build script.

various folders such as src

Development files.

various folders such as build

Build products. Not sharable in a VCS.

nbproject/build-impl.xml

Main logic for the build; regenerated from nbproject/project.xml but sharable.

nbproject/project.xml

General project metadata, including a declaration of the type of project, its name, some structural parameters relating to the build, a list of subprojects, etc.

nbproject/project.properties

Sharable build configuration for the project.

nbproject/private/private.xml

Per-user (or per-checkout) project metadata, if any.

nbproject/private/private.properties

Per-user build configuration for the project.

nbproject/private/cache

Cache directory containing disposable files that might speed up various operations.

Note that since Ant is not aware of the NetBeans Filesystems API, all these files must be physically present on disk, not e.g. in an archive or remote filesystem.

There may also be a file named build.properties located in the NetBeans user directory which can supply additional definitions needed for a build: e.g. the locations of Java platforms and libraries. A typical build-impl.xml loads property definitions from this global properties file as well as the project's nbproject/project.properties and nbproject/private/private.properties.

The basic operations commonly performed on an Ant-based project are:

• Creation from wizard, including build.xml.

• Loading metadata from disk.

• Modifying metadata and build properties in memory, and subsequently saving to disk.

• Regenerating nbproject/build-impl.xml, typically based on transforming nbproject/project.xml with an XSLT stylesheet.

• Running a build target of a well-known name in build.xml using Ant.

• Enumerating important build outputs ("artifacts").

• Adding dependencies on "subprojects" by getting information about their artifacts and storing references to them.

• Interpreting values of Ant properties found on disk, to be used in providing information to the IDE about various development files (e.g. when implementing queries).

A new category of Ant-based project can be registered in the system by adding an implementation of {@link org.netbeans.spi.project.support.ant.AntBasedProjectType} to the default lookup. This will get an instance of {@link org.netbeans.spi.project.support.ant.AntProjectHelper} for every project it creates; the helper does a lot of the work required to interact with the file structure outlined above.

To run Ant targets, use ActionUtils.

{@link org.netbeans.spi.project.support.ant.ReferenceHelper}s can also be created by an Ant-based project and used to manage references to subprojects and their artifacts in a high-level manner.

{@link org.netbeans.spi.project.support.ant.ProjectGenerator} provides the easiest way to create a new Ant-based project on disk. Use {@link org.netbeans.spi.project.support.ant.GeneratedFilesHelper} to make build scripts and {@link org.netbeans.spi.project.support.ant.ProjectXmlSavedHook} to be told when to recreate them.

To allow third-party extensions to build scripts, use {@link org.netbeans.spi.project.ant.AntBuildExtenderImplementation} and {@link org.netbeans.spi.project.support.ant.AntBuildExtenderFactory}.

{@link org.netbeans.spi.project.support.ant.EditableProperties} is a VCS-friendly alternative to {@link java.util.Properties}. {@link org.netbeans.spi.project.support.ant.PropertyUtils} also provides various methods for working with Ant concepts such as relative file paths, property substitution, etc.

Normally a project type provider will supply some special UI representation of the project making use of domain-specific features. {@link org.netbeans.spi.project.ui.LogicalViewProvider} permits a project to display itself however it likes in the Projects Explorer tab. {@link org.netbeans.spi.project.ui.CustomizerProvider} permits the project to be customized in an arbitrary way, typically opening a GUI dialog.

{@link org.netbeans.spi.project.ui.ProjectOpenedHook} may be used by projects wishing to take some special action upon being opened in the GUI.

Mainly deals with project-related actions.

Project types may declare the templates for projects in the folder Templates/Projects on the system filesystem using a module XML layer file. Registering project type templates is similar to registering file templates described below. The wizard for a project can return {@link org.openide.loaders.DataObject}s or {@link org.openide.loaders.FileObject}s corresponding to the project directories of created files and/or files to be selected in newly created projects. The {@link org.openide.WizardDescriptor} may also have a property defined on it called setAsMain, which may be {@link Boolean#TRUE} (the default) or {@link Boolean#FALSE}, according to whether the (first returned) new project should be set as the main project or not.

Each project can also declare own file templates to be exposed it in New File... wizard. This permits users to create new files, which are of types supported by given project type. The project may also provide own iterator for project-specific customization of given file type.

The project type has to declare its file templates in the module's layer file in folder the Templates. The declaration should look as follows:

<folder name="Templates">
  <folder name="JSP_Servlet">
    <file name="JSP.jsp" url="templates/JSP.template">
      <attr name="SystemFileSystem.localizingBundle" stringvalue="org.netbeans.modules.web.core.Bundle"/>
      <attr name="template" boolvalue="true"/>
      <attr name="instantiatingWizardURL" urlvalue="nbresloc:/org/netbeans/modules/web/core/resources/JSP.html"/>
      <attr name="instantiatingIterator" methodvalue="org.netbeans.modules.web.dd.wizards.PageIterator.createJspIterator"/>
      <attr name="templateCategory" stringvalue="web-types"/>
    </file>
  </folder>
</folder>


The mandatory file's attributes are:

Note: a project type can declare own custom iterator with some project-specific customization, it's recommended to use the standardized target chooser exposed in {@link org.netbeans.spi.project.ui.templates.support.Templates#createSimpleTargetChooser(org.netbeans.api.project.Project,org.netbeans.api.project.SourceGroup[]) Templates.createSimpleTargetChooser(...)}, a similar target chooser offers JavaTemplates.createPackageChooser(...) for Java-oriented projects. The project type also can use a InstantiatingIterator published by other module, i.e. JavaTemplates.createJavaTemplateIterator() useful for Java-oriented templates in case of no needs to own customization. The last possibility is declaration no iterator, in this case will be used a generic iterator useful for simple file types without any specific needs, i.e. properties file.
For project templates the instantiate() method should return a Set of FileObjects. FileObjects representing project directories will automatically be opened in the project and files tab. Other FileObjects (e.g. Java classes created by the wizard) will be opened in the editor area. Path of coresponding nodes will be expanded in the project or files tab.
For file templates the instantiate() method should return Set of FileObjects which will then automaticaly opened in the editor. Path of coresponding nodes will be expanded in the project or files tab.

There are two importatnt interfaces affecting the behavior of the templates. Implementation of these interfaces should reside in the project's lookup.

The first one is {@link org.netbeans.spi.project.ui.PrivilegedTemplates}. It is used for the initial content of the popup menu of New File.... It simply should return names of file tempolates from system filesystem which should be contained in the popup menu. Example implementation follows:

private static final class PrivilegedTemplatesImpl implements PrivilegedTemplates {

    private static final String[] PRIVILEGED_NAMES = new String[] {
        "Templates/Classes/Class.java",
        "Templates/Classes/Package",
        "Templates/Classes/Interface.java",
        "Templates/GUIForms/JPanel.java",
        "Templates/GUIForms/JFrame.java",
    };

    public String[] getPrivilegedTemplates() {
        return PRIVILEGED_NAMES;
    }

}

The second interface is {@link org.netbeans.spi.project.ui.RecommendedTemplates}, which infulences the apperance of templates in the New File wizard according to project types. The implementation of the interface has to return array of Strings which corresponds to names of template categories listed in the templateCategory attribute of template files. All templates which list at least one recommended category in the templateCategory attribute will be listed for given project type.
Note: if no templateCategory is declared then this template will be visible for each project regardless its type.

Example implementation of RecommendedTemplates interface:

private static final class RecommendedTemplatesImpl implements RecommendedTemplates {
    
    // List of primarily supported templates categories
    private static final String[] TYPES = new String[] { 
        "java-classes",         
        "java-main-class",      
        "java-forms",           
        "gui-java-application", 
        "java-beans",           
        "oasis-XML-catalogs",   
        "XML",                  
        "ant-script",           
        "ant-task",             
        "junit",                
        "simple-files"          
    };

    public String[] getRecommendedTypes() {
        return TYPES;
    }

}

Supported File Types in Projects Matrix

Projects:

• JA - Java Application
• JL - Java Library
• JP - Java Project with Existing Sources
• WA - Web Application
• WP - Web Project with Existing Sources

* - supported file type