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 ReferenceHelper

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

    public final class ReferenceHelper

extends Object

Helps manage inter-project references. Normally you would create an instance of this object and keep it in your project object in order to support `SubprojectProvider` and various operations that change settings which might refer to build artifacts from other projects: e.g. when changing the classpath for a Java-based project you would want to use this helper to scan potential classpath entries for JARs coming from other projects that you would like to be able to build as dependencies before your project is built.

You probably only need the higher-level methods such as `addReference(org.netbeans.api.project.ant.AntArtifact)` and `removeReference(String,String)`; the lower-level methods such as `addRawReference(org.netbeans.spi.project.support.ant.ReferenceHelper.RawReference)` are provided for completeness, but typical client code should not need them.

Only deals with references needed to support build artifacts coming from foreign projects. If for some reason you wish to store other kinds of references to foreign projects, you do not need this class; just store them however you wish, and be sure to create an appropriate `SubprojectProvider`.

Modification methods (add, remove) mark the project as modified but do not save it.

Nested Class Summary
`static class` | `ReferenceHelper.RawReference` A raw reference descriptor representing a link to a foreign project and some build artifact used from it.

Constructor Summary
`ReferenceHelper(AntProjectHelper helper, AuxiliaryConfiguration aux, PropertyEvaluator eval)` Create a new reference helper.

Method Summary
`void` | `addExtraBaseDirectory(String propertyName)` Add extra folder which can be used as base directory (in addition to project base folder) for creating references.
`boolean` | `addRawReference(ReferenceHelper.RawReference ref)` Add a raw reference to a foreign project artifact.
`boolean` | `addReference(AntArtifact artifact)` Deprecated. to add reference use `addReference(AntArtifact, URI)`; to check whether reference exist or not use `isReferenced(AntArtifact, URI)`. This method creates reference for the first artifact location only.
`String` | `addReference(AntArtifact artifact, URI location)` Add a reference to an artifact's location coming from a foreign project.
`String` | `createForeignFileReference(AntArtifact artifact)` Deprecated. use `addReference(AntArtifact, URI)` instead
`String` | `createForeignFileReference(File file, String expectedArtifactType)` Create an Ant-interpretable string referring to a file on disk.
`SubprojectProvider` | `createSubprojectProvider()` Create an object permitting this project to represent subprojects.
`void` | `destroyForeignFileReference(String reference)` Deprecated. use `destroyReference(java.lang.String)` instead which does exactly the same but has more appropriate name
`boolean` | `destroyReference(String reference)` Remove a reference to a foreign file from the project.
`Object[]` | `findArtifactAndLocation(String reference)` Try to find an `AntArtifact` object and location corresponding to a given reference.
`void` | `fixReferences(File originalPath)` Tries to fix references after copy/rename/move operation on the project.
`AntArtifact` | `getForeignFileReferenceAsArtifact(String reference)` Deprecated. use `findArtifactAndLocation(java.lang.String)` instead
`ReferenceHelper.RawReference` | `getRawReference(String foreignProjectName, String id)` Get a particular raw reference from this project to another.
`ReferenceHelper.RawReference[]` | `getRawReferences()` Get a list of raw references from this project to others.
`boolean` | `isReferenced(AntArtifact artifact, URI location)` Tests whether reference for artifact's location was already created by `addReference(AntArtifact, URI)` for this project or not.
`void` | `removeExtraBaseDirectory(String propertyName)` Remove extra base directory.
`boolean` | `removeRawReference(String foreignProjectName, String id)` Remove a raw reference to an artifact coming from a foreign project.
`boolean` | `removeReference(String fileReference)` Deprecated. use `destroyReference(java.lang.String)` instead; was unused anyway
`boolean` | `removeReference(String foreignProjectName, String id)` Deprecated. use `destroyReference(java.lang.String)` instead; was unused anyway

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### ReferenceHelper

    public ReferenceHelper(AntProjectHelper helper,
                           AuxiliaryConfiguration aux,
                           PropertyEvaluator eval)

  Create a new reference helper. It needs an `AntProjectHelper` object in order to update references in `project.xml`, as well as set project or private properties referring to the locations of foreign projects on disk.

  The property evaluator may be used in `getForeignFileReferenceAsArtifact(java.lang.String)`, `ReferenceHelper.RawReference.toAntArtifact(org.netbeans.spi.project.support.ant.ReferenceHelper)`, or `createSubprojectProvider()`. Typically this would be `AntProjectHelper.getStandardPropertyEvaluator()`. You can substitute a custom evaluator but be warned that this helper class assumes that `AntProjectHelper.PROJECT_PROPERTIES_PATH` and `AntProjectHelper.PRIVATE_PROPERTIES_PATH` have their customary meanings; specifically that they are both used when evaluating properties (such as the location of a foreign project) and that private properties can override public properties.

  Parameters:
    `helper` - an Ant project helper object representing this project's configuration
    `aux` - an auxiliary configuration provider needed to store references
    `eval` - a property evaluator

Method Detail

### addReference

    public boolean addReference(AntArtifact artifact)
                         throws IllegalArgumentException

  Deprecated. to add reference use `addReference(AntArtifact, URI)`; to check whether reference exist or not use `isReferenced(AntArtifact, URI)`. This method creates reference for the first artifact location only.

  Add a reference to an artifact coming from a foreign project.

  For more info see `addReference(AntArtifact, URI)`.

  Parameters:
    `artifact` - the artifact to add
  Returns:
    true if a reference or some property was actually added or modified, false if everything already existed and was not modified
  Throws:
    `IllegalArgumentException` - if the artifact is not associated with a project

### addReference

    public String addReference(AntArtifact artifact,
                               URI location)
                        throws IllegalArgumentException

  Add a reference to an artifact's location coming from a foreign project.

  Records the name of the foreign project. Normally the foreign project name is that project's code name, but it may be uniquified if that name is already taken to refer to a different project with the same code name.

  Adds a project property if necessary to refer to its location of the foreign project - a shared property if the foreign project is `collocated` with this one, else a private property. This property is named `project.foreignProjectName`. Example: `project.mylib=../mylib`

  Adds a project property to refer to the artifact's location. This property is named `reference.foreignProjectName.targetName` and will use `${project.foreignProjectName}` and be a shared property - unless the artifact location is an absolute URI, in which case the property will also be private. Example: `reference.mylib.jar=${project.mylib}/dist/mylib.jar`

  Also records the artifact type, (relative) script path, and build and clean target names.

  If the reference already exists (keyed by foreign project object and target name), nothing is done, unless some other field (script location, clean target name, or artifact type) needed to be updated, in which case the new information replaces the old. Similarly, the artifact location property is updated if necessary.

  Acquires write access.

  Parameters:
    `artifact` - the artifact to add
    `location` - the artifact's location to create reference to
  Returns:
    name of reference which was created or already existed
  Throws:
    `IllegalArgumentException` - if the artifact is not associated with a project or if the location is not artifact's location
  Since:
    1.5

### isReferenced

    public boolean isReferenced(AntArtifact artifact,
                                URI location)
                         throws IllegalArgumentException

  Tests whether reference for artifact's location was already created by `addReference(AntArtifact, URI)` for this project or not. This method returns false also in case when reference exist but needs to be updated.

  Acquires read access.

  Parameters:
    `artifact` - the artifact to add
    `location` - the artifact's location to create reference to
  Returns:
    true if already referenced
  Throws:
    `IllegalArgumentException` - if the artifact is not associated with a project or if the location is not artifact's location
  Since:
    1.5

### addRawReference

    public boolean addRawReference(ReferenceHelper.RawReference ref)

  Add a raw reference to a foreign project artifact. Does not check if such a project already exists; does not create a project property to refer to it; does not do any backreference usage notifications.

  If the reference already exists (keyed by foreign project name and target name), nothing is done, unless some other field (script location, clean target name, or artifact type) needed to be updated, in which case the new information replaces the old.

  Note that since `ReferenceHelper.RawReference` is just a descriptor, it is not guaranteed that after adding one `getRawReferences()` or `getRawReference(java.lang.String, java.lang.String)` would return the identical object.

  Acquires write access.

  Parameters:
    `ref` - a raw reference descriptor
  Returns:
    true if a reference was actually added or modified, false if it already existed and was not modified

### removeReference

    public boolean removeReference(String foreignProjectName,
                                   String id)

  Deprecated. use `destroyReference(java.lang.String)` instead; was unused anyway

  Remove a reference to an artifact coming from a foreign project.

  The property giving the location of the artifact is removed if it existed.

  If this was the last reference to the foreign project, its location property is removed as well.

  If the reference does not exist, nothing is done.

  Acquires write access.

  Parameters:
    `foreignProjectName` - the local name of the foreign project (usually its code name)
    `id` - the ID of the build artifact (usually build target name)
  Returns:
    true if a reference or some property was actually removed, false if the reference was not there and no property was removed

### removeReference

    public boolean removeReference(String fileReference)

  Deprecated. use `destroyReference(java.lang.String)` instead; was unused anyway

  Remove reference to a file.

  If the reference does not exist, nothing is done.

  Acquires write access.

  Parameters:
    `fileReference` - file reference as created by `createForeignFileReference(File, String)`
  Returns:
    true if the reference was actually removed; otherwise false

### removeRawReference

    public boolean removeRawReference(String foreignProjectName,
                                      String id)

  Remove a raw reference to an artifact coming from a foreign project. Does not attempt to manipulate backreferences in the foreign project nor project properties.

  If the reference does not exist, nothing is done.

  Acquires write access.

  Parameters:
    `foreignProjectName` - the local name of the foreign project (usually its code name)
    `id` - the ID of the build artifact (usually build target name)
  Returns:
    true if a reference was actually removed, false if it was not there

### getRawReferences

    public ReferenceHelper.RawReference[] getRawReferences()

  Get a list of raw references from this project to others. If necessary, you may use `ReferenceHelper.RawReference.toAntArtifact(org.netbeans.spi.project.support.ant.ReferenceHelper)` to get live information from each reference, such as its associated project.

  Acquires read access.

  Returns:
    a (possibly empty) list of raw references from this project

### getRawReference

    public ReferenceHelper.RawReference getRawReference(String foreignProjectName,
                                                        String id)

  Get a particular raw reference from this project to another. If necessary, you may use `ReferenceHelper.RawReference.toAntArtifact(org.netbeans.spi.project.support.ant.ReferenceHelper)` to get live information from each reference, such as its associated project.

  Acquires read access.

  Parameters:
    `foreignProjectName` - the local name of the foreign project (usually its code name)
    `id` - the ID of the build artifact (usually the build target name)
  Returns:
    the specified raw reference from this project, or null if none such could be found

### createForeignFileReference

    public String createForeignFileReference(File file,
                                             String expectedArtifactType)

  Create an Ant-interpretable string referring to a file on disk. If the file refers to a known Ant artifact according to `AntArtifactQuery.findArtifactFromFile(java.io.File)`, of the expected type and associated with a particular project, the behavior is identical to `createForeignFileReference(AntArtifact)`. Otherwise, a reference for the file is created. The file path will be relative in case `CollocationQuery.areCollocated(java.io.File, java.io.File)` says that the file is collocated with this project's main directory, else it will be an absolute path.

  Acquires write access.

  Parameters:
    `file` - a file to refer to (need not currently exist)
    `expectedArtifactType` - the required `AntArtifact.getType()`
  Returns:
    a string which can refer to that file somehow

### addExtraBaseDirectory

    public void addExtraBaseDirectory(String propertyName)

  Add extra folder which can be used as base directory (in addition to project base folder) for creating references. Duplicate property names are not allowed. Any newly created reference to a file lying under an extra base directory will be based on that property and will be stored in shared project properties.

  Acquires write access.

  Parameters:
    `propertyName` - property name which value is path to folder which can be used as alternative project's base directory; cannot be null; property must exist
  Throws:
    `IllegalArgumentException` - if propertyName is null or such a property does not exist
  Since:
    1.4

### removeExtraBaseDirectory

    public void removeExtraBaseDirectory(String propertyName)

  Remove extra base directory. The base directory property had to be added by `addExtraBaseDirectory(java.lang.String)` method call. At the time when this method is called the property must still exist and must be valid. This method will replace all references of the extra base directory property with its current value and if needed it may move such a property from shared project properties into the private properties.

  Acquires write access.

  Parameters:
    `propertyName` - property name which was added by `addExtraBaseDirectory(java.lang.String)` method.
  Throws:
    `IllegalArgumentException` - if given property is not extra base directory
  Since:
    1.4

### createForeignFileReference

    public String createForeignFileReference(AntArtifact artifact)
                                      throws IllegalArgumentException

  Deprecated. use `addReference(AntArtifact, URI)` instead

  Create an Ant-interpretable string referring to a known build artifact file. Simply calls `addReference(org.netbeans.api.project.ant.AntArtifact)` and returns an Ant string which will refer to that artifact correctly.

  Acquires write access.

  Parameters:
    `artifact` - a known build artifact to refer to
  Returns:
    a string which can refer to that artifact file somehow
  Throws:
    `IllegalArgumentException` - if the artifact is not associated with a project

### getForeignFileReferenceAsArtifact

    public AntArtifact getForeignFileReferenceAsArtifact(String reference)

  Deprecated. use `findArtifactAndLocation(java.lang.String)` instead

  Try to find an `AntArtifact` object corresponding to a given foreign file reference. If the supplied string is not a recognized reference to a build artifact, returns null.

  Acquires read access.

  Parameters:
    `reference` - a reference string as present in an Ant property
  Returns:
    a corresponding Ant artifact object if there is one, else null

### findArtifactAndLocation

    public Object[] findArtifactAndLocation(String reference)

  Try to find an `AntArtifact` object and location corresponding to a given reference. If the supplied string is not a recognized reference to a build artifact, returns null.

  Acquires read access.

  Parameters:
    `reference` - a reference string as present in an Ant property and as created by `addReference(AntArtifact, URI)`
  Returns:
    always returns array of two items. The items may be null. First one is instance of AntArtifact and second is instance of URI and is AntArtifact's location
  Since:
    1.5

### destroyForeignFileReference

    public void destroyForeignFileReference(String reference)

  Deprecated. use `destroyReference(java.lang.String)` instead which does exactly the same but has more appropriate name

  Remove a reference to a foreign file from the project. See `destroyReference(java.lang.String)` for more information.

  Parameters:
    `reference` - an Ant-interpretable foreign file reference as created e.g. by `createForeignFileReference(File,String)` or by `createForeignFileReference(AntArtifact)`

### destroyReference

    public boolean destroyReference(String reference)

  Remove a reference to a foreign file from the project. If the passed string consists of an Ant property reference corresponding to a known inter-project reference created by `addReference(AntArtifact, URI)` or file reference created by `createForeignFileReference(File, String)`, that reference is removed. Since this would break any other identical foreign file references present in the project, you should first confirm that this reference was the last one of its kind (by string match).

  If the passed string is anything else (i.e. a plain file path, relative or absolute), nothing is done.

  Acquires write access.

  Parameters:
    `reference` - an Ant-interpretable foreign file reference as created e.g. by `createForeignFileReference(File,String)` or by `createForeignFileReference(AntArtifact)`
  Returns:
    true if reference was really destroyed or not
  Since:
    1.5

### createSubprojectProvider

    public SubprojectProvider createSubprojectProvider()

  Create an object permitting this project to represent subprojects. Would be placed into the project's lookup.

  Returns:
    a subproject provider object suitable for the project lookup
  See Also:
    `Project.getLookup()`

### fixReferences

    public void fixReferences(File originalPath)

  Tries to fix references after copy/rename/move operation on the project. Handles relative/absolute paths.

  Parameters:
    `originalPath` - the project folder of the original project
  Since:
    1.9
  See Also:
    `CopyOperationImplementation`, `MoveOperationImplementation`

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.