Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.netbeans.modules.project.ant/1 1.12.22
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

  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

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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| org.netbeans.modules.project.ant/1 1.12.22
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Built on December 7 2006. | Portions Copyright 1997-2005 Sun Microsystems, Inc. All rights reserved.