Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.netbeans.modules.project.ant/1 1.12.22
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:

  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. `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()

  Overrides:
    `toString` in class `Object`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.netbeans.modules.project.ant/1 1.12.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.