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 ReferenceHelper.addReference(org.netbeans.api.project.ant.AntArtifact) and ReferenceHelper.removeReference(String,String); the lower-level methods such as ReferenceHelper.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

Nested Classes

Modifier and Type	Class and Description
static class	ReferenceHelper.RawReference A raw reference descriptor representing a link to a foreign project and some build artifact used from it.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method and Description
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 ReferenceHelper.addReference(AntArtifact, URI); to check whether reference exist or not use ReferenceHelper.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.
Library	copyLibrary(Library lib) Copy global IDE library to sharable libraries definition associated with this project.
static Library	copyLibrary(Library lib, File librariesLocation) Copy global IDE library to given folder.
String	createExtraForeignFileReferenceAsIs(String path, String property) Create an Ant-interpretable string referring to a file on disk.
String	createForeignFileReference(AntArtifact artifact) Deprecated. use ReferenceHelper.addReference(AntArtifact, URI) instead
String	createForeignFileReference(File file, String expectedArtifactType) Create an Ant-interpretable string referring to a file on disk.
String	createForeignFileReferenceAsIs(String filepath, String expectedArtifactType) Create an Ant-interpretable string referring to a file on disk.
String	createLibraryReference(Library library, String volumeType) Create a reference to one volume of a library.
SubprojectProvider	createSubprojectProvider() Create an object permitting this project to represent subprojects.
void	destroyForeignFileReference(String reference) Deprecated. use ReferenceHelper.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.
Library	findLibrary(String name) Tries to find a library by name in library manager associated with the project.
void	fixReferences(File originalPath) Tries to fix references after copy/rename/move operation on the project.
AntArtifact	getForeignFileReferenceAsArtifact(String reference) Deprecated. use ReferenceHelper.findArtifactAndLocation(java.lang.String) instead
LibraryManager	getProjectLibraryManager() Gets a library manager corresponding to library definition file referred to from this project.
static LibraryManager	getProjectLibraryManager(Project p) Gets a library manager of the given project.
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 ReferenceHelper.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 ReferenceHelper.destroyReference(java.lang.String) instead; was unused anyway
boolean	removeReference(String foreignProjectName, String id) Deprecated. use ReferenceHelper.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 ReferenceHelper.getForeignFileReferenceAsArtifact(java.lang.String), ReferenceHelper.RawReference.toAntArtifact(org.netbeans.spi.project.support.ant.ReferenceHelper), or ReferenceHelper.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

@Deprecated
public boolean addReference(AntArtifact artifact)
                                 throws IllegalArgumentException

Deprecated. to add reference use ReferenceHelper.addReference(AntArtifact, URI); to check whether reference exist or not use ReferenceHelper.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 ReferenceHelper.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 ReferenceHelper.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 ReferenceHelper.getRawReferences() or ReferenceHelper.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

@Deprecated
public boolean removeReference(String foreignProjectName,
                                           String id)

Deprecated. use ReferenceHelper.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

@Deprecated
public boolean removeReference(String fileReference)

Deprecated. use ReferenceHelper.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 ReferenceHelper.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 ReferenceHelper.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

createForeignFileReferenceAsIs

public String createForeignFileReferenceAsIs(String filepath,
                                             String expectedArtifactType)

Create an Ant-interpretable string referring to a file on disk. Compared to ReferenceHelper.createForeignFileReference(java.io.File, java.lang.String) the filepath does not have to be normalized (ie. it can be relative path to project base folder), no relativization or absolutization of path is done and reference to file is always stored in project properties. 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 ReferenceHelper.createForeignFileReference(AntArtifact).

Acquires write access.

Parameters:

path - a file path to refer to (need not currently exist)

expectedArtifactType - the required AntArtifact.getType()

Returns:

a string which can refer to that file somehow

Since:

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

createExtraForeignFileReferenceAsIs

public String createExtraForeignFileReferenceAsIs(String path,
                                                  String property)

Create an Ant-interpretable string referring to a file on disk. Compared to ReferenceHelper.createForeignFileReference(java.io.File, java.lang.String) the file path does not have to be normalized (ie. it can be relative path to project base folder), no relativization or absolutization of path is done and reference to file is always stored in project properties.

Acquires write access.

Parameters:

path - a file path to refer to (need not currently exist)

property - name of the property

Returns:

a string which can refer to that file somehow

Since:

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

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 ignored. 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 ReferenceHelper.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 ReferenceHelper.addExtraBaseDirectory(java.lang.String) method.

Throws:

IllegalArgumentException - if given property is not extra base directory

Since:

1.4

createForeignFileReference

@Deprecated
public String createForeignFileReference(AntArtifact artifact)
                                              throws IllegalArgumentException

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

Create an Ant-interpretable string referring to a known build artifact file. Simply calls ReferenceHelper.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

@Deprecated
public AntArtifact getForeignFileReferenceAsArtifact(String reference)

Deprecated. use ReferenceHelper.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 an array of nulls.

Acquires read access.

Parameters:

reference - a reference string as present in an Ant property and as created by ReferenceHelper.addReference(AntArtifact, URI)

Returns:

always returns array of two items. The items may be both null. First one is instance of AntArtifact and second is instance of URI and is AntArtifact's location

Since:

1.5

destroyForeignFileReference

@Deprecated
public void destroyForeignFileReference(String reference)

Deprecated. use ReferenceHelper.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 ReferenceHelper.destroyReference(java.lang.String) for more information.

Parameters:

reference - an Ant-interpretable foreign file reference as created e.g. by ReferenceHelper.createForeignFileReference(File,String) or by ReferenceHelper.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 ReferenceHelper.addReference(AntArtifact, URI) or file reference created by ReferenceHelper.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 ReferenceHelper.createForeignFileReference(File,String) or by ReferenceHelper.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

createLibraryReference

public String createLibraryReference(Library library,
                                     String volumeType)

Create a reference to one volume of a library.

Parameters:

library - a library

volumeType - a legal volume type for that library

Returns:

substitutable Ant text suitable for inclusion in a properties file when also loading AntProjectHelper.getProjectLibrariesPropertyProvider()

Since:

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

See Also:

ReferenceHelper.findLibrary(java.lang.String)

getProjectLibraryManager

public LibraryManager getProjectLibraryManager()

Gets a library manager corresponding to library definition file referred to from this project. There is no guarantee that the manager is the same object from call to call even if the location remain the same; in particular, it is not guaranteed that the manager match that returned from Library.getManager() for libraries added from ReferenceHelper.createLibraryReference(org.netbeans.api.project.libraries.Library, java.lang.String).

Returns:

a library manager associated with project's libraries or null if project is not shared (will not include LibraryManager.getDefault())

Since:

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

See Also:

ReferenceHelper.createLibraryReference(org.netbeans.api.project.libraries.Library, java.lang.String), ReferenceHelper.findLibrary(java.lang.String)

getProjectLibraryManager

public static LibraryManager getProjectLibraryManager(Project p)

Gets a library manager of the given project. There is no guarantee that the manager is the same object from call to call even if the project is the same; in particular, it is not guaranteed that the manager match that returned from Library.getManager() for libraries added from ReferenceHelper.createLibraryReference(org.netbeans.api.project.libraries.Library, java.lang.String).

Returns:

a library manager associated with project's libraries or null if project is not shared (will not include LibraryManager.getDefault()) LibraryManager.getDefault())

Since:

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

copyLibrary

public Library copyLibrary(Library lib)
                    throws IOException

Copy global IDE library to sharable libraries definition associated with this project. Does nothing if project is not sharable. When a library with same name already exists in sharable location, the new one is copied with generated unique name.

Library creation is done under write access of ProjectManager.mutex().

Parameters:

lib - global library; cannot be null

Returns:

newly created sharable version of library in case of sharable project or given global library in case of non-sharable project

Throws:

IOException - if there was problem copying files

Since:

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

copyLibrary

public static Library copyLibrary(@NonNull
                                  Library lib,
                                  @NonNull
                                  File librariesLocation)
                           throws IOException

Copy global IDE library to given folder. When a library with same name already exists in sharable location, the new one is copied with generated unique name.

Library creation is done under write access of ProjectManager.mutex().

Parameters:

lib - global library; cannot be null

librariesLocation - the location of the libraries definition file to import the library into

Returns:

newly created sharable version of library in case of sharable project or given global library in case of non-sharable project

Throws:

IOException - if there was problem copying files

Since:

1.62

findLibrary

public Library findLibrary(String name)

Tries to find a library by name in library manager associated with the project. It is not guaranteed that any returned library is an identical object to one which passed in to ReferenceHelper.createLibraryReference(org.netbeans.api.project.libraries.Library, java.lang.String).

Parameters:

name - either a bare Library.getName(), or a reference as created by ReferenceHelper.createLibraryReference(org.netbeans.api.project.libraries.Library, java.lang.String)

Returns:

the first library to be found matching that name, or null if not found

Since:

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