AntProjectHelper (NetBeans Ant Project API) - 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.spi.project.support.ant
Class AntProjectHelper

java.lang.Object
  org.netbeans.spi.project.support.ant.AntProjectHelper

public final class AntProjectHelper
extends Object

Support class for implementing Ant-based projects.

Field Summary

static String PRIVATE_PROPERTIES_PATH
          Relative path from project directory to the customary private properties file.

static String PRIVATE_XML_PATH
          Relative path from project directory to the required private project metadata file.

static String PROJECT_PROPERTIES_PATH
          Relative path from project directory to the customary shared properties file.

static String PROJECT_XML_PATH
          Relative path from project directory to the required shared project metadata file.

Method Summary

void addAntProjectListener(AntProjectListener listener)
          Add a listener to changes in the project configuration.

AuxiliaryConfiguration createAuxiliaryConfiguration()
          Create an object permitting this project to store auxiliary configuration.

CacheDirectoryProvider createCacheDirectoryProvider()
          Create an object permitting this project to expose a cache directory.

FileBuiltQueryImplementation createGlobFileBuiltQuery(PropertyEvaluator eval, String[] from, String[] to)
          Create an implementation of FileBuiltQuery that works with files within the project based on simple glob pattern mappings.

SharabilityQueryImplementation createSharabilityQuery(PropertyEvaluator eval, String[] sourceRoots, String[] buildDirectories)
          Create an implementation of the file sharability query.

AntArtifact createSimpleAntArtifact(String type, String locationProperty, PropertyEvaluator eval, String targetName, String cleanTargetName)
          Create a basic implementation of AntArtifact which assumes everything of interest is in a fixed location under a standard Ant-based project.

Element getPrimaryConfigurationData(boolean shared)
          Get the primary configuration data for this project.

FileObject getProjectDirectory()
          Get the top-level project directory.

EditableProperties getProperties(String path)
          Load a property file from some location in the project.

PropertyProvider getPropertyProvider(String path)
          Get a property provider that works with loadable project properties.

PropertyEvaluator getStandardPropertyEvaluator()
          Get a property evaluator that can evaluate properties according to the default file layout for Ant-based projects.

PropertyProvider getStockPropertyPreprovider()
          Get a property provider which defines basedir according to the project directory and also copies all system properties in the current VM.

void notifyDeleted()
          Notification that this project has been deleted.

void putPrimaryConfigurationData(Element data, boolean shared)
          Store the primary configuration data for this project.

void putProperties(String path, EditableProperties props)
          Store a property file to some location in the project.

void removeAntProjectListener(AntProjectListener listener)
          Remove a listener to changes in the project configuration.

File resolveFile(String filename)
          Find an absolute file path from a possibly project-relative path.

FileObject resolveFileObject(String filename)
          Same as resolveFile(java.lang.String), but produce a FileObject if possible.

String resolvePath(String path)
          Take an Ant-style path specification and convert it to a platform-specific absolute path.

String toString()


Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

PROJECT_PROPERTIES_PATH

public static final String PROJECT_PROPERTIES_PATH

Relative path from project directory to the customary shared properties file.

See Also:: Constant Field Values

PRIVATE_PROPERTIES_PATH

public static final String PRIVATE_PROPERTIES_PATH

Relative path from project directory to the customary private properties file.

See Also:: Constant Field Values

PROJECT_XML_PATH

public static final String PROJECT_XML_PATH

Relative path from project directory to the required shared project metadata file.

See Also:: Constant Field Values

PRIVATE_XML_PATH

public static final String PRIVATE_XML_PATH

Relative path from project directory to the required private project metadata file.

See Also:: Constant Field Values

Method Detail

addAntProjectListener

public void addAntProjectListener(AntProjectListener listener)

Add a listener to changes in the project configuration.

Thread-safe.

Parameters:: listener - a listener to add

removeAntProjectListener

public void removeAntProjectListener(AntProjectListener listener)

Remove a listener to changes in the project configuration.

Thread-safe.

Parameters:: listener - a listener to remove

getProjectDirectory

public FileObject getProjectDirectory()

Get the top-level project directory.

Returns:: the project directory beneath which everything in the project lies

notifyDeleted

public void notifyDeleted()

Notification that this project has been deleted. See org.netbeans.api.projects.ProjectState#notifyDeleted.

Since:: 1.8

getProperties

public EditableProperties getProperties(String path)

Load a property file from some location in the project. The returned object may be edited but you must call putProperties(java.lang.String, org.netbeans.spi.project.support.ant.EditableProperties) to save any changes you make. If the file does not (yet) exist or could not be loaded for whatever reason, an empty properties list is returned instead.

Parameters:: path - a relative URI in the project directory, e.g. PROJECT_PROPERTIES_PATH or PRIVATE_PROPERTIES_PATH
Returns:: a set of properties

putProperties

public void putProperties(String path,
                          EditableProperties props)

Store a property file to some location in the project. A clone will be made of the supplied properties file so as to snapshot it. The new properties are not actually stored to disk immediately, but the project is marked modified so that they will be later. You can store to a path that does not yet exist and the file will be created if and when the project is saved. If the old value is the same as the new, nothing is done. Otherwise an expected properties change event is fired.

Acquires write access from ProjectManager.mutex(). However, you are well advised to explicitly enclose a complete operation within write access, starting with getProperties(java.lang.String), to prevent race conditions.

Parameters:: path - a relative URI in the project directory, e.g. PROJECT_PROPERTIES_PATH or PRIVATE_PROPERTIES_PATH; props - a set of properties to store, or null to delete any existing properties file there

getPropertyProvider

public PropertyProvider getPropertyProvider(String path)

Get a property provider that works with loadable project properties. Its current values should match getProperties(java.lang.String), and calls to putProperties(java.lang.String, org.netbeans.spi.project.support.ant.EditableProperties) should cause it to fire changes.

Parameters:: path - a relative URI in the project directory, e.g. PROJECT_PROPERTIES_PATH or PRIVATE_PROPERTIES_PATH
Returns:: a property provider implementation

getPrimaryConfigurationData

public Element getPrimaryConfigurationData(boolean shared)

Get the primary configuration data for this project. The returned element will be named according to AntBasedProjectType.getPrimaryConfigurationDataElementName(boolean) and AntBasedProjectType.getPrimaryConfigurationDataElementNamespace(boolean). The project may read this document fragment to get custom information from nbproject/project.xml and nbproject/private/private.xml. The fragment will have no parent node and while it may be modified, you must use putPrimaryConfigurationData(org.w3c.dom.Element, boolean) to store any changes.

Parameters:: shared - if true, refers to project.xml, else refers to private.xml
Returns:: the configuration data that is available

putPrimaryConfigurationData

public void putPrimaryConfigurationData(Element data,
                                        boolean shared)
                                 throws IllegalArgumentException

Store the primary configuration data for this project. The supplied element must be named according to AntBasedProjectType.getPrimaryConfigurationDataElementName(boolean) and AntBasedProjectType.getPrimaryConfigurationDataElementNamespace(boolean). The project may save this document fragment to set custom information in nbproject/project.xml and nbproject/private/private.xml. The fragment will be cloned and so further modifications will have no effect.

Acquires write access from ProjectManager.mutex(). However, you are well advised to explicitly enclose a complete operation within write access, starting with getPrimaryConfigurationData(boolean), to prevent race conditions.

Parameters:: data - the desired new configuration data; shared - if true, refers to project.xml, else refers to private.xml
Throws:: IllegalArgumentException - if the element is not correctly named

createAuxiliaryConfiguration

public AuxiliaryConfiguration createAuxiliaryConfiguration()

Create an object permitting this project to store auxiliary configuration. Would be placed into the project's lookup.

Returns:: an auxiliary configuration provider object suitable for the project lookup

createCacheDirectoryProvider

public CacheDirectoryProvider createCacheDirectoryProvider()

Create an object permitting this project to expose a cache directory. Would be placed into the project's lookup.

Returns:: a cache directory provider object suitable for the project lookup

createGlobFileBuiltQuery

public FileBuiltQueryImplementation createGlobFileBuiltQuery(PropertyEvaluator eval,
                                                             String[] from,
                                                             String[] to)
                                                      throws IllegalArgumentException

Create an implementation of FileBuiltQuery that works with files within the project based on simple glob pattern mappings.

It is intended to be placed in Project.getLookup().

It will return status objects for any files in the project matching a source glob pattern - this must include exactly one asterisk (*) representing a variable portion of a source file path (always slash-separated and relative to the project directory) and may include some Ant property references which will be resolved as per the property evaluator. A file is considered out of date if there is no file represented by the matching target pattern (which has the same format), or the target file is older than the source file, or the source file is modified as per DataObject.isModified(). An attempt is made to fire changes from the status object whenever the result should change from one call to the next.

The (evaluated) source and target patterns may be relative, resolved against the project directory (perhaps going outside it), or absolute.

A typical set of source and target patterns would be:

${src.dir}/*.java
${test.src.dir}/*.java

${build.classes.dir}/*.class
${test.build.classes.dir}/*.class

Parameters:: eval - a property evaluator to interpret the patterns with; from - a list of glob patterns for source files; to - a matching list of glob patterns for built files
Returns:: a query implementation
Throws:: IllegalArgumentException - if either from or to patterns have zero or multiple asterisks, or the arrays are not of equal lengths

createSimpleAntArtifact

public AntArtifact createSimpleAntArtifact(String type,
                                           String locationProperty,
                                           PropertyEvaluator eval,
                                           String targetName,
                                           String cleanTargetName)

Create a basic implementation of AntArtifact which assumes everything of interest is in a fixed location under a standard Ant-based project.

Parameters:: type - the type of artifact, e.g. JavaProjectConstants.ARTIFACT_TYPE_JAR; locationProperty - an Ant property name giving the project-relative location of the artifact, e.g. dist.jar; eval - a way to evaluate the location property (e.g. getStandardPropertyEvaluator()); targetName - the name of an Ant target which will build the artifact, e.g. jar; cleanTargetName - the name of an Ant target which will delete the artifact (and maybe other build products), e.g. clean
Returns:: an artifact

createSharabilityQuery

public SharabilityQueryImplementation createSharabilityQuery(PropertyEvaluator eval,
                                                             String[] sourceRoots,
                                                             String[] buildDirectories)

Create an implementation of the file sharability query. You may specify a list of source roots to include that should be considered sharable, as well as a list of build directories that should not be considered sharable.

The project directory itself is automatically included in the list of sharable directories so you need not explicitly specify it. Similarly, the nbproject/private subdirectory is automatically excluded from VCS, so you do not need to explicitly specify it.

Any file (or directory) mentioned (explicitly or implicity) in the source directory list but not in any of the build directory lists, and not containing any build directories inside it, will be given as sharable. If a directory itself is sharable but some directory inside it is not, it will be given as mixed. A file or directory inside some build directory will be listed as not sharable. A file or directory matching neither the source list nor the build directory list will be treated as of unknown status, but in practice such a file should never have been passed to this implementation anyway - SharabilityQuery will normally only call an implementation in project lookup if the file is owned by that project.

Each entry in either list should be a string evaluated first for Ant property escapes (if any), then treated as a file path relative to the project directory (or it may be absolute).

It is permitted, and harmless, to include items that overlap others. For example, you can have both a directory and one of its children in the include list.

Typical usage would be:

 helper.createSharabilityQuery(helper.getStandardPropertyEvaluator(),
                               new String[] {"${src.dir}", "${test.src.dir}"},
                               new String[] {"${build.dir}", "${dist.dir}"})

A quick rule of thumb is that the include list should contain any source directories which might reside outside the project directory; and the exclude list should contain any directories which you would want to add to a .cvsignore file if using CVS (for example).

Note that in this case ${src.dir} and ${test.src.dir} may be relative paths inside the project directory; relative paths pointing outside of the project directory; or absolute paths (generally outside of the project directory). If they refer to locations inside the project directory, including them does nothing but is harmless - since the project directory itself is always treated as sharable. If they refer to external locations, you will need to also make sure that FileOwnerQuery actually maps files in those directories to this project, or else SharabilityQuery will never find this implementation in your project lookup and may return UNKNOWN.

Parameters:: eval - a property evaluator to interpret paths with; sourceRoots - a list of additional paths to treat as sharable; buildDirectories - a list of paths to treat as not sharable
Returns:: a sharability query implementation suitable for the project lookup
See Also:: Project.getLookup()

getStockPropertyPreprovider

public PropertyProvider getStockPropertyPreprovider()

Get a property provider which defines basedir according to the project directory and also copies all system properties in the current VM. It may also define ant.home if it is able.

Returns:: a stock property provider for initial Ant-related definitions
See Also:: PropertyUtils.sequentialPropertyEvaluator(org.netbeans.spi.project.support.ant.PropertyProvider, org.netbeans.spi.project.support.ant.PropertyProvider[])

getStandardPropertyEvaluator

public PropertyEvaluator getStandardPropertyEvaluator()

Get a property evaluator that can evaluate properties according to the default file layout for Ant-based projects. First, stock properties are predefined. Then PRIVATE_PROPERTIES_PATH is loaded via getPropertyProvider(java.lang.String), then global definitions from PropertyUtils.globalPropertyProvider() (though these may be overridden using the property user.properties.file in private.properties), then PROJECT_PROPERTIES_PATH.

Returns:: a standard property evaluator

resolveFile

public File resolveFile(String filename)

Find an absolute file path from a possibly project-relative path.

Parameters:: filename - a pathname which may be project-relative or absolute and may use / or \ as the path separator
Returns:: an absolute file corresponding to it

resolveFileObject

public FileObject resolveFileObject(String filename)

Same as resolveFile(java.lang.String), but produce a FileObject if possible.

Parameters:: filename - a pathname according to Ant conventions
Returns:: a file object it represents, or null if there is no such file object in known filesystems

resolvePath

public String resolvePath(String path)

Take an Ant-style path specification and convert it to a platform-specific absolute path. The path separator characters are converted to the local convention, and individual path components are resolved and cleaned up as for resolveFile(java.lang.String).

Parameters:: path - an Ant-style abstract path
Returns:: an absolute, locally usable path

toString

public String toString()