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.

As of 1.24, project.xml or private.xml reads or writes are first validated against any registered XML schemas. You must register a schema using the target namespace http://www.netbeans.org/ns/foo/1 as ProjectXMLCatalog/foo/1.xsd in your layer for it to be found.

Field Summary

Fields

Modifier and Type	Field and Description
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

Modifier and Type	Method and Description
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.
AuxiliaryProperties	createAuxiliaryProperties() Create an object permitting this project to expose AuxiliaryProperties.
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) Deprecated. since 1.47 use AntProjectHelper.createSharabilityQuery2(org.netbeans.spi.project.support.ant.PropertyEvaluator, java.lang.String[], java.lang.String[]) instead
SharabilityQueryImplementation2	createSharabilityQuery2(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.
AntArtifact	createSimpleAntArtifact(String type, String locationProperty, PropertyEvaluator eval, String targetName, String cleanTargetName, String buildScriptProperty) Create a basic implementation of AntArtifact which assumes everything of interest is in a fixed location under a standard Ant-based project.
String	getLibrariesLocation() Returns location of shared libraries associated with this project or null.
Element	getPrimaryConfigurationData(boolean shared) Get the primary configuration data for this project.
FileObject	getProjectDirectory() Get the top-level project directory.
PropertyProvider	getProjectLibrariesPropertyProvider() Creates a property provider which can load definitions of project libraries.
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.
boolean	isSharableProject() Is this project shared with other or not, that is is it using shrared libraries or not.
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 AntProjectHelper.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.
void	setLibrariesLocation(String location) Change project's associated shared libraries location.
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.

Since:

1.8

See Also:

ProjectState.notifyDeleted()

getProperties

public EditableProperties getProperties(@NonNull
                                        String path)

Load a property file from some location in the project. The returned object may be edited but you must call AntProjectHelper.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. AntProjectHelper.PROJECT_PROPERTIES_PATH or AntProjectHelper.PRIVATE_PROPERTIES_PATH

Returns:

a set of properties

putProperties

public void putProperties(@NonNull
                          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 AntProjectHelper.getProperties(java.lang.String), to prevent race conditions.

Parameters:

path - a relative URI in the project directory, e.g. AntProjectHelper.PROJECT_PROPERTIES_PATH or AntProjectHelper.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 AntProjectHelper.getProperties(java.lang.String), and calls to AntProjectHelper.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. AntProjectHelper.PROJECT_PROPERTIES_PATH or AntProjectHelper.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 AntProjectHelper.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 AntProjectHelper.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

createAuxiliaryProperties

public AuxiliaryProperties createAuxiliaryProperties()

Create an object permitting this project to expose AuxiliaryProperties. Would be placed into the project's lookup. This implementation places the properties into AntProjectHelper.PROJECT_PROPERTIES_PATH or AntProjectHelper.PRIVATE_PROPERTIES_PATH (depending on shared value). The properties are prefixed with "auxiliary.".

Returns:

an instance of AuxiliaryProperties suitable for the project lookup

Since:

1.21

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:

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

1. ${build.classes.dir}/*.class
2. ${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. AntProjectHelper.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

createSimpleAntArtifact

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

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. AntProjectHelper.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

buildScriptProperty - an Ant property name giving the project-relative location and name of the build.xml or null if default one (build.xml) should be used; default value is also used if property is given but its value is null

Returns:

an artifact

Since:

org.netbeans.modules.project.ant/1 1.25

createSharabilityQuery2

public SharabilityQueryImplementation2 createSharabilityQuery2(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.

Whether or not you use this method, all files named *-private.properties outside the project are marked unsharable, as are such files inside the project if currently referenced as project libraries. (See AntProjectHelper.getProjectLibrariesPropertyProvider().)

Typical usage would be:

 helper.createSharabilityQuery2(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

Since:

1.47

See Also:

Project.getLookup()

createSharabilityQuery

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

Deprecated. since 1.47 use AntProjectHelper.createSharabilityQuery2(org.netbeans.spi.project.support.ant.PropertyEvaluator, java.lang.String[], java.lang.String[]) instead

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 and ant.core.lib 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...)

getProjectLibrariesPropertyProvider

public PropertyProvider getProjectLibrariesPropertyProvider()

Creates a property provider which can load definitions of project libraries. If this project refers to any project library definition files, they will be included, with ${base} replaced by the appropriate value.

Returns:

a property provider

Since:

org.netbeans.modules.project.ant/1 1.19

See Also:

Schema for project library references

isSharableProject

public boolean isSharableProject()

Is this project shared with other or not, that is is it using shrared libraries or not.

Returns:

true for shared project

Since:

org.netbeans.modules.project.ant/1 1.19

getLibrariesLocation

public String getLibrariesLocation()

Returns location of shared libraries associated with this project or null.

Returns:

relative or absolute OS path or null

Since:

org.netbeans.modules.project.ant/1 1.19

setLibrariesLocation

public void setLibrariesLocation(String location)

Change project's associated shared libraries location. If location is null then project will not have shared libraries and will be considered as not being shared.

Parameters:

location - project relative or absolute OS path or null

Since:

org.netbeans.modules.project.ant/1 1.18

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 AntProjectHelper.PRIVATE_PROPERTIES_PATH is loaded via AntProjectHelper.getPropertyProvider(java.lang.String), then AntProjectHelper.getProjectLibrariesPropertyProvider(), then global definitions from PropertyUtils.globalPropertyProvider() (though these may be overridden using the property user.properties.file in private.properties), then AntProjectHelper.PROJECT_PROPERTIES_PATH.

Returns:

a standard property evaluator

resolveFile

@NonNull
public File resolveFile(@NonNull
                                 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

@CheckForNull
public FileObject resolveFileObject(@NonNull
                                                  String filename)

Same as AntProjectHelper.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

@NonNull
public String resolvePath(@NonNull
                                   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 AntProjectHelper.resolveFile(java.lang.String).

Parameters:

path - an Ant-style abstract path

Returns:

an absolute, locally usable path

toString

public String toString()

Overrides:

toString in class Object