org.netbeans.spi.project.support.ant (NetBeans Ant Project API) - NetBeans API Javadoc 5.0.0

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV PACKAGE NEXT PACKAGE

FRAMES NO FRAMES

Package org.netbeans.spi.project.support.ant

Principal package for implementing typical Ant-based projects.

See:
Description

Interface Summary

AntBasedProjectType Plugin for an Ant project type.

AntProjectListener Listener for changes in Ant project metadata.

PropertyEvaluator A way of mapping property names to values.

PropertyProvider Provides a set of Ant property definitions that might be evaluated in some context.

Class Summary

AntProjectEvent Event object corresponding to a change made in an Ant project's metadata.

AntProjectHelper Support class for implementing Ant-based projects.

EditableProperties Similar to Properties but designed to retain additional information needed for safe hand-editing.

GeneratedFilesHelper Helps a project type (re-)generate, and manage the state and versioning of, build.xml and build-impl.xml.

ProjectGenerator Utilities to create new Ant-based projects on disk.

ProjectXmlSavedHook Hook run when nbproject/project.xml is saved.

PropertyUtils Support for working with Ant properties and property files.

ReferenceHelper Helps manage inter-project references.

ReferenceHelper.RawReference A raw reference descriptor representing a link to a foreign project and some build artifact used from it.

SourcesHelper Helper class to work with source roots and typed folders of a project.

Package org.netbeans.spi.project.support.ant Description

Principal package for implementing typical Ant-based 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 AntBasedProjectType to the default lookup. This will get an instance of AntProjectHelper for every project it creates; the helper does a lot of the work required to interact with the file structure outlined above.

ant.ActionHelper provides a number of utilities which make it easy to run Ant targets.

ReferenceHelpers can also be created by an Ant-based project and used to manage references to subprojects and their artifacts in a high-level manner.

ProjectGenerator provides the easiest way to create a new Ant-based project on disk. Use GeneratedFilesHelper to make build scripts and ProjectXmlSavedHook to be told when to recreate them.

EditableProperties is a VCS-friendly alternative to Properties. PropertyUtils also provides various methods for working with Ant concepts such as relative file paths, property substitution, etc.