org.netbeans.spi.project.support.ant

Class SourcesHelper

java.lang.Object

org.netbeans.spi.project.support.ant.SourcesHelper

public final class SourcesHelper
extends Object

Helper class to work with source roots and typed folders of a project.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	SourcesHelper.SourceRootConfig Helper class for configuring source roots.

Constructor Summary

Constructors

Constructor and Description
SourcesHelper(AntProjectHelper aph, PropertyEvaluator evaluator) Deprecated. Rather use SourcesHelper(Project, AntProjectHelper, PropertyEvaluator).
SourcesHelper(Project project, AntProjectHelper aph, PropertyEvaluator evaluator) Create the helper object, initially configured to recognize only sources contained inside the project directory.

Method Summary

Modifier and Type	Method and Description
void	addNonSourceRoot(String location) Similar to addPrincipalSourceRoot(java.lang.String, java.lang.String, javax.swing.Icon, javax.swing.Icon) but affects only registerExternalRoots(int) and not createSources().
void	addOwnedFile(String location) Add any file that is supposed to be owned by a given project via FileOwnerQuery, affects only registerExternalRoots(int) and not createSources().
void	addPrincipalSourceRoot(String location, String displayName, Icon icon, Icon openedIcon) Deprecated. Use sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.
void	addPrincipalSourceRoot(String location, String includes, String excludes, String displayName, Icon icon, Icon openedIcon) Deprecated. Use sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.
void	addTypedSourceRoot(String location, String type, String displayName, Icon icon, Icon openedIcon) Deprecated. Use sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.
void	addTypedSourceRoot(String location, String includes, String excludes, String type, String displayName, Icon icon, Icon openedIcon) Deprecated. Use sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.
SourceGroupModifierImplementation	createSourceGroupModifierImplementation() Creates new SourceGroupModifierImplementation that can be put into project lookup.
Sources	createSources() Create a source list object.
void	registerExternalRoots(int algorithm) Register all external source or non-source roots using FileOwnerQuery.markExternalOwner(org.openide.filesystems.FileObject, org.netbeans.api.project.Project, int).
void	registerExternalRoots(int algorithm, boolean minimalSubfolders) Register all external source or non-source roots using FileOwnerQuery.markExternalOwner(org.openide.filesystems.FileObject, org.netbeans.api.project.Project, int).
SourcesHelper.SourceRootConfig	sourceRoot(String location) Creates a possible source root configuration.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SourcesHelper

@Deprecated
public SourcesHelper(AntProjectHelper aph,
                                 PropertyEvaluator evaluator)

Deprecated. Rather use SourcesHelper(Project, AntProjectHelper, PropertyEvaluator).

Create the helper object, initially configured to recognize only sources contained inside the project directory.

Parameters:

aph - an Ant project helper

evaluator - a way to evaluate Ant properties used to define source locations

SourcesHelper

public SourcesHelper(Project project,
                     AntProjectHelper aph,
                     PropertyEvaluator evaluator)

Create the helper object, initially configured to recognize only sources contained inside the project directory.

Parameters:

project - the project object (need not yet be registered in ProjectManager)

aph - an Ant project helper

evaluator - a way to evaluate Ant properties used to define source locations

Since:

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

Method Detail

sourceRoot

public SourcesHelper.SourceRootConfig sourceRoot(String location)

Creates a possible source root configuration. Source root is a top-level folder which may contain sources that should be considered part of the project.

If the actual value of the location parameter is inside the project directory and the root is not typed, this is simply ignored; so it safe to configure source roots for any source directory which might be set to use an external path, even if the common location is internal.

Source location need not to exist physically, when hint is specified and SourceGroupModifier created by this helper is added to project lookup, source root can be created on demand.

NOTE: don't forget to call add() method on initialized SourceRootConfig to add it to SourcesHelper. See SourcesHelper.SourceRootConfig for details of usage and other parameters.

Parameters:

location - a project-relative or absolute path giving the location of a source tree; may contain Ant property substitutions

Returns:

source root configuration, that may be added to SourcesHelper

See Also:

for details about location parameter

addPrincipalSourceRoot

@Deprecated
public void addPrincipalSourceRoot(String location,
                                               String displayName,
                                               Icon icon,
                                               Icon openedIcon)
                                        throws IllegalStateException

Deprecated. Use sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.

Add a possible principal source root, or top-level folder which may contain sources that should be considered part of the project.

See sourceRoot(String location) and SourcesHelper.SourceRootConfig for details, consider using them instead of this method for better readability.

Parameters:

location - a project-relative or absolute path giving the location of a source tree; may contain Ant property substitutions

displayName - a display name (for SourceGroup.getDisplayName())

icon - a regular icon for the source root, or null

openedIcon - an opened variant icon for the source root, or null

Throws:

IllegalStateException - if this method is called after either createSources() or registerExternalRoots(int) was called

See Also:

registerExternalRoots(int), Sources.TYPE_GENERIC

addPrincipalSourceRoot

@Deprecated
public void addPrincipalSourceRoot(String location,
                                               String includes,
                                               String excludes,
                                               String displayName,
                                               Icon icon,
                                               Icon openedIcon)
                                        throws IllegalStateException

Deprecated. Use sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.

Add a possible principal source root, or top-level folder which may contain sources that should be considered part of the project, with optional include and exclude lists.

See sourceRoot(String location) and SourcesHelper.SourceRootConfig for details, consider using them instead of this method for better readability.

Parameters:

location - a project-relative or absolute path giving the location of a source tree; may contain Ant property substitutions

includes - Ant-style includes; may contain Ant property substitutions; if not null, only files and folders matching the pattern (or patterns), and not specified in the excludes list, will be included

excludes - Ant-style excludes; may contain Ant property substitutions; if not null, files and folders matching the pattern (or patterns) will not be included, even if specified in the includes list

displayName - a display name (for SourceGroup.getDisplayName())

icon - a regular icon for the source root, or null

openedIcon - an opened variant icon for the source root, or null

Throws:

IllegalStateException - if this method is called after either createSources() or registerExternalRoots(int) was called

Since:

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

See Also:

registerExternalRoots(int), Sources.TYPE_GENERIC

addNonSourceRoot

public void addNonSourceRoot(String location)
                      throws IllegalStateException

Similar to addPrincipalSourceRoot(java.lang.String, java.lang.String, javax.swing.Icon, javax.swing.Icon) but affects only registerExternalRoots(int) and not createSources().

Useful for project type providers which have external paths holding build products. These should not appear in Sources, yet it may be useful for FileOwnerQuery to know the owning project (for example, in order for a project-specific SourceForBinaryQueryImplementation to work).

Parameters:

location - a project-relative or absolute path giving the location of a non-source tree; may contain Ant property substitutions

Throws:

IllegalStateException - if this method is called after registerExternalRoots(int) was called

addOwnedFile

public void addOwnedFile(String location)
                  throws IllegalStateException

Add any file that is supposed to be owned by a given project via FileOwnerQuery, affects only registerExternalRoots(int) and not createSources().

Useful for project type providers which have external paths holding build products. These should not appear in Sources, yet it may be useful for FileOwnerQuery to know the owning project (for example, in order for a project-specific SourceForBinaryQueryImplementation to work).

Parameters:

location - a project-relative or absolute path giving the location of a file; may contain Ant property substitutions

Throws:

IllegalStateException - if this method is called after registerExternalRoots(int) was called

Since:

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

addTypedSourceRoot

@Deprecated
public void addTypedSourceRoot(String location,
                                           String type,
                                           String displayName,
                                           Icon icon,
                                           Icon openedIcon)
                                    throws IllegalStateException

Deprecated. Use sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.

Add a typed source root which will be considered only in certain contexts.

See sourceRoot(String location) and SourcesHelper.SourceRootConfig for details, consider using them instead of this method for better readability.

Parameters:

location - a project-relative or absolute path giving the location of a source tree; may contain Ant property substitutions

type - a source root type such as JavaProjectConstants.SOURCES_TYPE_JAVA

displayName - a display name (for SourceGroup.getDisplayName())

icon - a regular icon for the source root, or null

openedIcon - an opened variant icon for the source root, or null

Throws:

IllegalStateException - if this method is called after either createSources() or registerExternalRoots(int) was called

addTypedSourceRoot

@Deprecated
public void addTypedSourceRoot(String location,
                                           String includes,
                                           String excludes,
                                           String type,
                                           String displayName,
                                           Icon icon,
                                           Icon openedIcon)
                                    throws IllegalStateException

Deprecated. Use sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.

Add a typed source root with optional include and exclude lists.

See sourceRoot(String location) and SourcesHelper.SourceRootConfig for details, consider using them instead of this method for better readability.

Parameters:

location - a project-relative or absolute path giving the location of a source tree; may contain Ant property substitutions

includes - an optional list of Ant-style includes

excludes - an optional list of Ant-style excludes

type - a source root type such as JavaProjectConstants.SOURCES_TYPE_JAVA

displayName - a display name (for SourceGroup.getDisplayName())

icon - a regular icon for the source root, or null

openedIcon - an opened variant icon for the source root, or null

Throws:

IllegalStateException - if this method is called after either createSources() or registerExternalRoots(int) was called

Since:

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

registerExternalRoots

public void registerExternalRoots(int algorithm)
                           throws IllegalArgumentException,
                                  IllegalStateException

Register all external source or non-source roots using FileOwnerQuery.markExternalOwner(org.openide.filesystems.FileObject, org.netbeans.api.project.Project, int).

Only roots added by addPrincipalSourceRoot(java.lang.String, java.lang.String, javax.swing.Icon, javax.swing.Icon) and addNonSourceRoot(java.lang.String) are considered. They are registered if (and only if) they in fact fall outside of the project directory, and of course only if the folders really exist on disk. Currently it is not defined when this file existence check is done (e.g. when this method is first called, or periodically) or whether folders which are created subsequently will be registered, so project type providers are encouraged to create all desired external roots before calling this method.

If the actual value of the location changes (due to changes being fired from the property evaluator), roots which were previously internal and are now external will be registered, and roots which were previously external and are now internal will be unregistered. The (un-)registration will be done using the same algorithm as was used initially.

If an explicit include list is configured for a principal source root, only those subfolders which are included (or folders directly containing included files) will be registered. Note that the source root, or an included subfolder, will be registered even if it contains excluded files or folders beneath it.

Calling this method causes the helper object to hold strong references to the current external roots, which helps a project satisfy the requirements of FileOwnerQuery.EXTERNAL_ALGORITHM_TRANSIENT.

If you used the old constructor form SourcesHelper(AntProjectHelper, PropertyEvaluator) then you may not call this method inside the project's constructor, as it requires the actual project to exist and be registered in ProjectManager; in this case you could still use Mutex.postWriteRequest(java.lang.Runnable) to run it later, if you were creating the helper in your constructor, since the project construction normally occurs in read access. Better to use SourcesHelper(Project, AntProjectHelper, PropertyEvaluator).

Parameters:

algorithm - an external root registration algorithm as per FileOwnerQuery.markExternalOwner(org.openide.filesystems.FileObject, org.netbeans.api.project.Project, int)

Throws:

IllegalArgumentException - if the algorithm is unrecognized

IllegalStateException - if this method is called more than once on a given SourcesHelper object

registerExternalRoots

public void registerExternalRoots(int algorithm,
                                  boolean minimalSubfolders)
                           throws IllegalArgumentException,
                                  IllegalStateException

Register all external source or non-source roots using FileOwnerQuery.markExternalOwner(org.openide.filesystems.FileObject, org.netbeans.api.project.Project, int).

Only roots added by addPrincipalSourceRoot(java.lang.String, java.lang.String, javax.swing.Icon, javax.swing.Icon) and addNonSourceRoot(java.lang.String) are considered. They are registered if (and only if) they in fact fall outside of the project directory, and of course only if the folders really exist on disk. Currently it is not defined when this file existence check is done (e.g. when this method is first called, or periodically) or whether folders which are created subsequently will be registered, so project type providers are encouraged to create all desired external roots before calling this method.

If the actual value of the location changes (due to changes being fired from the property evaluator), roots which were previously internal and are now external will be registered, and roots which were previously external and are now internal will be unregistered. The (un-)registration will be done using the same algorithm as was used initially.

If a minimalSubfolders is true and an explicit include list is configured for a principal source root, only those subfolders which are included (or folders directly containing included files) will be registered, otherwise the whole source root is registered. Note that the source root, or an included subfolder, will be registered even if it contains excluded files or folders beneath it.

Calling this method causes the helper object to hold strong references to the current external roots, which helps a project satisfy the requirements of FileOwnerQuery.EXTERNAL_ALGORITHM_TRANSIENT.

You may not call this method inside the project's constructor, as it requires the actual project to exist and be registered in ProjectManager. Typically you would use Mutex.postWriteRequest(java.lang.Runnable) to run it later, if you were creating the helper in your constructor, since the project construction normally occurs in read access.

Parameters:

algorithm - an external root registration algorithm as per FileOwnerQuery.markExternalOwner(org.openide.filesystems.FileObject, org.netbeans.api.project.Project, int)

minimalSubfolders - controls how the roots having an explicit include list are registered. When true only those subfolders which are included (or folders directly containing included files) will be registered, otherwise the whole source root is registered.

Throws:

IllegalArgumentException - if the algorithm is unrecognized

IllegalStateException - if this method is called more than once on a given SourcesHelper object

Since:

1.26

createSources

public Sources createSources()

Create a source list object.

All principal source roots are listed as Sources.TYPE_GENERIC unless they are inside the project directory. The project directory itself is also listed (with a display name according to ProjectUtils.getInformation(org.netbeans.api.project.Project)), unless it is contained by an explicit principal source root (i.e. ancestor directory). Principal source roots should never overlap; if two configured principal source roots are determined to have the same root folder, the first configured root takes precedence (which only matters in regard to the display name); if one root folder is contained within another, the broader root folder subsumes the narrower one so only the broader root is listed.

Other source groups are listed according to the named typed source roots. There is no check performed that these do not overlap (though a project type provider should for UI reasons avoid this situation).

Any source roots which do not exist on disk are ignored, as if they had not been configured at all. Currently it is not defined when this existence check is performed (e.g. when this method is called, when the source root is first accessed, periodically, etc.), so project type providers are generally encouraged to make sure all desired source folders exist before calling this method, if creating a new project.

Source groups are created according to the semantics described in GenericSources.group(org.netbeans.api.project.Project, org.openide.filesystems.FileObject, java.lang.String, java.lang.String, javax.swing.Icon, javax.swing.Icon). They are listed in the order they were configured (for those roots that are actually used as groups).

You may call this method inside the project's constructor, but Sources.getSourceGroups(java.lang.String) may not be called within the constructor, as it requires the actual project object to exist and be registered in ProjectManager.

Returns:

a source list object suitable for Project.getLookup()

createSourceGroupModifierImplementation

public SourceGroupModifierImplementation createSourceGroupModifierImplementation()

Creates new SourceGroupModifierImplementation that can be put into project lookup.

Only source roots added with a hint can be created with this SourceGroupModifierImplementation.

Returns:

SourceGroupModifierImplementation implementation.

Since:

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

See Also:

sourceRoot(String)