This is an API change, not a bug, so it is not possible for D.
Currently it does what it is supposed to: create relative paths when
it can (when they would be collocated with the project dir), otherwise
absolute paths.

What you want, perhaps, is to be able to configure the RH with a list
of Ant property names which are to be treated as alternate basedirs
that the file might be collocated with, in which case the reference
would be created as shared and of the form
${some.known.property}/some/path. Proposed API would look something like

public void ReferenceHelper.addAvailableBaseDirectoryProperty(String
propertyName);

That would work, although I would be happy if it worked just with the
external folders which are displayed in the physical view. I would
actually found that more natural then passing the same set of folders
again.

Can't "just work" with the folders in the Physical View because (1)
these are defined with a SourcesHelper, which the ReferencesHelper
knows nothing of, (2) it needs to know the Ant property name (or
expression) used to define the external source root.

Amend the proposed API to read

public void ReferenceHelper.addAvailableBaseDirectory(String
text);

where text can be any string possibly containing Ant property references.

Usecase: user added external source root and after that added a jar
(lying below this external source root) to project's classpath.
RH.createForeignFileReference() correctly created property based on
the already defined external source root property. Later, user removed
external source root.

What should happen? 

Solution1: external source root property cannot be simply removed in
this case because it is being used by some other property. Perhaps
there could exist helper method <code>boolean
PropertyUtils.isPropertyReferenced(String propertyName,
EditableProperties props)</code>. The disadvantage is that if user
removes the jar from project's classpath then external source property
will never be removed although it is not used anymore.

Solution2: any usages of external source root property must be
replaced with its value and after that it can be safely removed.
Solves the disadvantage mentioned in S1. Again there could he helper
method <code>boolean PropertyUtils.removePropertySafely(String
propertyName, String propertyValue, EditableProperties props)</code>
which would do the replace and return true if a substitution occured.

In both cases it would be project type responsibility to impl above
solutions as part of external source root removal.


Other issue is that project type must be able to unregister external
source roots from RH. So instead of suggested
addAvailableBaseDirectory() method I would rather define 

public void ReferenceHelper.setAvailableBaseDirectory(Set
propertyNames);

Btw. Jesse, what was your motivation for moving from "String
propertyName" param to "String text".

I would like to ask for review of simple API addition.

ReferenceHelper class is used for creating references to files used by
project. The class uses project's base directory as base for files
whenever possible. Some projects might have additional external base
folders (for which there already exist a reference) and this issue
requests that files lying under an external base folder take advantage
of the external folder and reuse its reference. The solution is to add
two new methods to ReferenceHelper which allows to add/remove property
names which value is the external folder and which will be used by
ReferenceHelper for creation references based on them.

I will attach source code diff which includes everything needed.

The new API is not used by J2SE project because its external base
folders are packages roots and it is not expected that project would
need to reference any files below these. The request came from Web
team which I believe has more generic external base folders.

Created attachment 19230 [details]
patch

Sorry I did not look at this issue at all, I was too busy. Will attach
some comments shortly.

Re. moving from String propertyName (e.g. "externalRoot") to String
text (e.g. "${externalRoot}") - in case the project defines the
external dir using something other than a plain property dereference.
Compare various other ant/project SPI methods which accept a string
with possible fixed text and/or multiple property dereferences. But
this is probably not the case in practice, since we are dealing with
entire roots of directory trees, so I don't care much, esp. if it is
easier to implement as propertyName.

Re. addExtraBaseDirectory impl: do not use assertions to check the
validity of arguments passed into an API method, use exceptions, which
should be mentioned in the Javadoc (whether checked or unchecked).

Should not be using Java language synchronization (monitors); should
be using ProjectManager.mutex() in read or write mode as appropriate.

Don't forget to use the date of the actual commit in apichanges.xml.

Otherwise looks fine to me. Pavel, you have been silent about the
proposed change - will it in fact suffice for web projects?

Could somebody from web team comment whether this is what you wanted
or not? Thanks.

Davide, this looks good for our needs. Thanks!

Checked in:
apichanges.xml;
new revision: 1.3; previous revision: 1.2
manifest.mf;
new revision: 1.7; previous revision: 1.6
src/org/netbeans/spi/project/support/ant/ReferenceHelper.java;
new revision: 1.21; previous revision: 1.20
test/unit/src/org/netbeans/spi/project/support/ant/ReferenceHelperTest.java;
new revision: 1.14; previous revision: 1.13