ReferenceHelper (NetBeans Ant Project API) - NetBeans API Javadoc 4.1.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 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.

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

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

ReferenceHelper (NetBeans Ant Project API) - NetBeans API Javadoc 4.1.0

org.netbeans.spi.project.support.ant Class ReferenceHelper

ReferenceHelper

addReference

addReference

isReferenced

addRawReference

removeReference

removeReference

removeRawReference

getRawReferences

getRawReference

createForeignFileReference

addExtraBaseDirectory

removeExtraBaseDirectory

createForeignFileReference

getForeignFileReferenceAsArtifact

findArtifactAndLocation

destroyForeignFileReference

destroyReference

createSubprojectProvider

org.netbeans.spi.project.support.ant
Class ReferenceHelper