SourcesHelper (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 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.

Constructor Summary

SourcesHelper(AntProjectHelper project, PropertyEvaluator evaluator)
          Create the helper object, initially configured to recognize only sources contained inside the project directory.

Method Summary

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 addPrincipalSourceRoot(String location, String displayName, Icon icon, Icon openedIcon)
          Add a possible principal source root, or top-level folder which may contain sources that should be considered part of the project.

void addTypedSourceRoot(String location, String type, String displayName, Icon icon, Icon openedIcon)
          Add a typed source root which will be considered only in certain contexts.

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

Methods inherited from class java.lang.Object

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

Constructor Detail

SourcesHelper

public SourcesHelper(AntProjectHelper project,
                     PropertyEvaluator evaluator)

Create the helper object, initially configured to recognize only sources contained inside the project directory.
Parameters:: project - an Ant project helper; evaluator - a way to evaluate Ant properties used to define source locations

Method Detail

addPrincipalSourceRoot

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

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

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

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

addNonSourceRoot

public void addNonSourceRoot(String location)
                      throws IllegalStateException

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

addTypedSourceRoot

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

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

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

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.

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)
Throws:: IllegalArgumentException - if the algorithm is unrecognized; IllegalStateException - if this method is called more than once on a given SourcesHelper object

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