public final class SourcesHelper extends Object
| Modifier and Type | Class and Description |
|---|---|
class |
SourcesHelper.SourceRootConfig
Helper class for configuring source roots.
|
| Constructor and Description |
|---|
SourcesHelper(AntProjectHelper aph,
PropertyEvaluator evaluator)
Deprecated.
|
SourcesHelper(Project project,
AntProjectHelper aph,
PropertyEvaluator evaluator)
Create the helper object, initially configured to recognize only sources
contained inside the project directory.
|
@Deprecated public SourcesHelper(AntProjectHelper aph, PropertyEvaluator evaluator)
SourcesHelper.SourcesHelper(Project, AntProjectHelper, PropertyEvaluator).aph - an Ant project helperevaluator - a way to evaluate Ant properties used to define source locationspublic SourcesHelper(Project project, AntProjectHelper aph, PropertyEvaluator evaluator)
project - the project object (need not yet be registered in ProjectManager)aph - an Ant project helperevaluator - a way to evaluate Ant properties used to define source locationspublic SourcesHelper.SourceRootConfig sourceRoot(String location)
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.
location - a project-relative or absolute path giving the location
of a source tree; may contain Ant property substitutionsSourcesHelperfor details about location parameter@Deprecated public void addPrincipalSourceRoot(String location, String displayName, Icon icon, Icon openedIcon) throws IllegalStateException
SourcesHelper.sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.
See SourcesHelper.sourceRoot(String location) and SourcesHelper.SourceRootConfig for details,
consider using them instead of this method for better readability.
location - a project-relative or absolute path giving the location
of a source tree; may contain Ant property substitutionsdisplayName - a display name (for SourceGroup.getDisplayName())icon - a regular icon for the source root, or nullopenedIcon - an opened variant icon for the source root, or nullIllegalStateException - if this method is called after either
SourcesHelper.createSources() or SourcesHelper.registerExternalRoots(int)
was calledSourcesHelper.registerExternalRoots(int),
Sources.TYPE_GENERIC@Deprecated public void addPrincipalSourceRoot(String location, String includes, String excludes, String displayName, Icon icon, Icon openedIcon) throws IllegalStateException
SourcesHelper.sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.
See SourcesHelper.sourceRoot(String location) and SourcesHelper.SourceRootConfig for details,
consider using them instead of this method for better readability.
location - a project-relative or absolute path giving the location
of a source tree; may contain Ant property substitutionsincludes - 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 includedexcludes - 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 listdisplayName - a display name (for SourceGroup.getDisplayName())icon - a regular icon for the source root, or nullopenedIcon - an opened variant icon for the source root, or nullIllegalStateException - if this method is called after either
SourcesHelper.createSources() or SourcesHelper.registerExternalRoots(int)
was calledSourcesHelper.registerExternalRoots(int),
Sources.TYPE_GENERICpublic void addNonSourceRoot(String location) throws IllegalStateException
SourcesHelper.addPrincipalSourceRoot(java.lang.String, java.lang.String, javax.swing.Icon, javax.swing.Icon) but affects only
SourcesHelper.registerExternalRoots(int) and not SourcesHelper.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).
location - a project-relative or absolute path giving the location
of a non-source tree; may contain Ant property substitutionsIllegalStateException - if this method is called after
SourcesHelper.registerExternalRoots(int) was calledpublic void addOwnedFile(String location) throws IllegalStateException
SourcesHelper.registerExternalRoots(int)
and not SourcesHelper.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).
location - a project-relative or absolute path giving the location
of a file; may contain Ant property substitutionsIllegalStateException - if this method is called after
SourcesHelper.registerExternalRoots(int) was called@Deprecated public void addTypedSourceRoot(String location, String type, String displayName, Icon icon, Icon openedIcon) throws IllegalStateException
SourcesHelper.sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.
See SourcesHelper.sourceRoot(String location) and SourcesHelper.SourceRootConfig for details,
consider using them instead of this method for better readability.
location - a project-relative or absolute path giving the location
of a source tree; may contain Ant property substitutionstype - a source root type such as JavaProjectConstants.SOURCES_TYPE_JAVAdisplayName - a display name (for SourceGroup.getDisplayName())icon - a regular icon for the source root, or nullopenedIcon - an opened variant icon for the source root, or nullIllegalStateException - if this method is called after either
SourcesHelper.createSources() or SourcesHelper.registerExternalRoots(int)
was called@Deprecated public void addTypedSourceRoot(String location, String includes, String excludes, String type, String displayName, Icon icon, Icon openedIcon) throws IllegalStateException
SourcesHelper.sourceRoot(String location) and SourcesHelper.SourceRootConfig instead.
See SourcesHelper.sourceRoot(String location) and SourcesHelper.SourceRootConfig for details,
consider using them instead of this method for better readability.
location - a project-relative or absolute path giving the location
of a source tree; may contain Ant property substitutionsincludes - an optional list of Ant-style includesexcludes - an optional list of Ant-style excludestype - a source root type such as JavaProjectConstants.SOURCES_TYPE_JAVAdisplayName - a display name (for SourceGroup.getDisplayName())icon - a regular icon for the source root, or nullopenedIcon - an opened variant icon for the source root, or nullIllegalStateException - if this method is called after either
SourcesHelper.createSources() or SourcesHelper.registerExternalRoots(int)
was calledpublic void registerExternalRoots(int algorithm)
throws IllegalArgumentException,
IllegalStateException
FileOwnerQuery.markExternalOwner(org.openide.filesystems.FileObject, org.netbeans.api.project.Project, int).
Only roots added by SourcesHelper.addPrincipalSourceRoot(java.lang.String, java.lang.String, javax.swing.Icon, javax.swing.Icon) and SourcesHelper.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.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.SourcesHelper(Project, AntProjectHelper, PropertyEvaluator).
algorithm - an external root registration algorithm as per
FileOwnerQuery.markExternalOwner(org.openide.filesystems.FileObject, org.netbeans.api.project.Project, int)IllegalArgumentException - if the algorithm is unrecognizedIllegalStateException - if this method is called more than once on a
given SourcesHelper objectpublic void registerExternalRoots(int algorithm,
boolean minimalSubfolders)
throws IllegalArgumentException,
IllegalStateException
FileOwnerQuery.markExternalOwner(org.openide.filesystems.FileObject, org.netbeans.api.project.Project, int).
Only roots added by SourcesHelper.addPrincipalSourceRoot(java.lang.String, java.lang.String, javax.swing.Icon, javax.swing.Icon) and SourcesHelper.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.
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.IllegalArgumentException - if the algorithm is unrecognizedIllegalStateException - if this method is called more than once on a
given SourcesHelper objectpublic Sources createSources()
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.
Project.getLookup()public SourceGroupModifierImplementation createSourceGroupModifierImplementation()
SourceGroupModifierImplementation that can be put into project lookup.
Only source roots added with a hint can be created
with this SourceGroupModifierImplementation.
SourcesHelper.sourceRoot(String)