org.eclipse.wst.jsdt.core

## Interface IIncludePathEntry

    public interface IIncludePathEntry

An entry on a JavaScript project includepath identifying one or more package fragment roots. A includepath entry has a content kind (either source, `IPackageFragmentRoot.K_SOURCE`, or binary, `IPackageFragmentRoot.K_BINARY`), which is inherited by each package fragment root and package fragment associated with the entry.

A includepath entry can refer to any of the following:

- Source code in the current project. In this case, the entry identifies a root folder in the current project containing package fragments and source files with one of the `JavaScript-like extensions`. The root folder itself represents a default package, subfolders represent package fragments, and files with a JavaScript-like extension (e.g. `.js` files) represent javaScript files. All javaScript files will be compiled when the project is built. The includepath entry must specify the absolute path to the root folder. Entries of this kind are associated with the `CPE_SOURCE` constant. Source includepath entries can carry inclusion and exclusion patterns for selecting which source files appear as javaScript units and get compiled when the project is built.
- A binary library in the current project, in another project, or in the external file system. In this case the entry identifies non-editable files. Entries of this kind are associated with the `CPE_LIBRARY` constant.
- A required project. In this case the entry identifies another project in the workspace. When performing other "development" operations - such as code assist, code resolve, type hierarchy creation, etc. - the source code of the project is referred to. Thus, development is performed against a required project's source code. The includepath entry must specify the absolute path to the project. Entries of this kind are associated with the `CPE_PROJECT` constant. Note: referencing a required project with a includepath entry refers to the source code or associated `.class` files located in its output location. It will also automatically include any other libraries or projects that the required project's includepath refers to, iff the corresponding includepath entries are tagged as being exported (`isExported()`). Unless exporting some includepath entries, includepaths are not chained by default - each project must specify its own includepath in its entirety.
- A path beginning in a includepath variable defined globally to the workspace. Entries of this kind are associated with the `CPE_VARIABLE` constant. Includepath variables are created using `JavaScriptCore#setIncludepathVariable(String, IPath, org.eclipse.core.runtime.IProgressMonitor)`, and gets resolved, to either a project or library entry, using `JavaScriptCore.getResolvedIncludepathEntry(IIncludePathEntry)`. It is also possible to register an automatic initializer (`JsGlobalScopeVariableInitializer`), which will be invoked through the extension point "org.eclipse.wst.jsdt.core.JsGlobalScopeVariableInitializer". After resolution, a includepath variable entry may either correspond to a project or a library entry.
- A named includepath container identified by its container path. A includepath container provides a way to indirectly reference a set of includepath entries through a includepath entry of kind `CPE_CONTAINER`. Typically, a includepath container can be used to describe a complex library composed of multiple files, projects or includepath variables, considering also that containers can be mapped differently on each project. Several projects can reference the same generic container path, but have each of them actually bound to a different container object. The container path is a formed by a first ID segment followed with extra segments, which can be used as additional hints for resolving this container reference. If no container was ever recorded for this container path onto this project (using `JavaScriptCore.setJsGlobalScopeContainer(IPath, org.eclipse.wst.jsdt.core.IJavaScriptProject[], org.eclipse.wst.jsdt.core.IJsGlobalScopeContainer[], IProgressMonitor)`, then a `JsGlobalScopeContainerInitializer` will be activated if any was registered for this container ID onto the extension point "org.eclipse.wst.jsdt.core.JsGlobalScopeContainerInitializer". A includepath container entry can be resolved explicitly using `JavaScriptCore.getJsGlobalScopeContainer(IPath, org.eclipse.wst.jsdt.core.IJavaScriptProject)` and the resulting container entries can contain any non-container entry. In particular, it may contain variable entries, which in turn needs to be resolved before being directly used.
  Also note that the container resolution APIs include an IJavaScriptProject argument, so as to allow the same container path to be interpreted in different ways for different projects.

The result of `IJavaScriptProject#getResolvedClasspath` will have all entries of type `CPE_VARIABLE` and `CPE_CONTAINER` resolved to a set of `CPE_SOURCE`, `CPE_LIBRARY` or `CPE_PROJECT` includepath entries.

Any includepath entry other than a source folder (kind `CPE_SOURCE`) can be marked as being exported. Exported entries are automatically contributed to dependent projects, along with the project's default output folder, which is implicitly exported, and any auxiliary output folders specified on source includepath entries. The project's output folder(s) are always listed first, followed by the any exported entries.

This interface is not intended to be implemented by clients. Includepath entries can be created via methods on `JavaScriptCore`.

See Also:
  `JavaScriptCore#newLibraryEntry(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath)`, `JavaScriptCore#newProjectEntry(org.eclipse.core.runtime.IPath)`, `JavaScriptCore#newSourceEntry(org.eclipse.core.runtime.IPath)`, `JavaScriptCore#newVariableEntry(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath)`, `JavaScriptCore#newContainerEntry(org.eclipse.core.runtime.IPath)`, `JsGlobalScopeVariableInitializer`, `Provisional API: This class/interface is part of an interim API that is still under development and expected to change significantly before reaching stability. It is being made available at this early stage to solicit feedback from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken (repeatedly) as the API evolves.`

### Field Summary

Fields
`static int` `CPE_CONTAINER` Entry kind constant describing a includepath entry representing a name includepath container.
`static int` `CPE_LIBRARY` Entry kind constant describing a includepath entry identifying a library.
`static int` `CPE_PROJECT` Entry kind constant describing a includepath entry identifying a required project.
`static int` `CPE_SOURCE` Entry kind constant describing a includepath entry identifying a folder containing package fragments with source code to be validated.
`static int` `CPE_VARIABLE` Entry kind constant describing a includepath entry defined using a path that begins with a includepath variable reference.

### Method Summary

All Methods Instance Methods Abstract Methods
`boolean` `combineAccessRules()` Returns whether the access rules of the project's exported entries should be combined with this entry's access rules.
`IAccessRule[]` `getAccessRules()` Returns the possibly empty list of access rules for this entry.
`int` `getContentKind()` Returns the kind of files found in the package fragments identified by this includepath entry.
`int` `getEntryKind()` Returns the kind of this includepath entry.
`IPath[]` `getExclusionPatterns()` Returns the set of patterns used to exclude resources or classes associated with this includepath entry.
`IIncludePathAttribute[]` `getExtraAttributes()` Returns the extra includepath attributes for this includepath entry.
`IPath[]` `getInclusionPatterns()` Returns the set of patterns used to explicitly define resources to be included with this includepath entry.
`IPath` `getPath()` Returns the path of this includepath entry.
`IPath` `getSourceAttachmentPath()` Returns the path to the source archive or folder associated with this includepath entry, or `null` if this includepath entry has no source attachment.
`IPath` `getSourceAttachmentRootPath()` Returns the path within the source archive or folder where package fragments are located.
`boolean` `isExported()` Returns whether this entry is exported to dependent projects.

### Field Detail

#### CPE_LIBRARY

    static final int CPE_LIBRARY

Entry kind constant describing a includepath entry identifying a library.

See Also:
  Constant Field Values

#### CPE_PROJECT

    static final int CPE_PROJECT

Entry kind constant describing a includepath entry identifying a required project.

See Also:
  Constant Field Values

#### CPE_SOURCE

    static final int CPE_SOURCE

Entry kind constant describing a includepath entry identifying a folder containing package fragments with source code to be validated.

See Also:
  Constant Field Values

#### CPE_VARIABLE

    static final int CPE_VARIABLE

Entry kind constant describing a includepath entry defined using a path that begins with a includepath variable reference.

See Also:
  Constant Field Values

#### CPE_CONTAINER

    static final int CPE_CONTAINER

Entry kind constant describing a includepath entry representing a name includepath container.

See Also:
  Constant Field Values

### Method Detail

#### combineAccessRules

    boolean combineAccessRules()

Returns whether the access rules of the project's exported entries should be combined with this entry's access rules. Returns true for container entries. Returns false otherwise.

Returns:
  whether the access rules of the project's exported entries should be combined with this entry's access rules

#### getAccessRules

    IAccessRule[] getAccessRules()

Returns the possibly empty list of access rules for this entry.

Returns:
  the possibly empty list of access rules for this entry

#### getContentKind

    int getContentKind()

Returns the kind of files found in the package fragments identified by this includepath entry.

Returns:
  `IPackageFragmentRoot.K_SOURCE` for files containing source code, and `IPackageFragmentRoot.K_BINARY` for binary class files. There is no specified value for an entry denoting a variable (`CPE_VARIABLE`) or a includepath container (`CPE_CONTAINER`).

#### getEntryKind

    int getEntryKind()

Returns the kind of this includepath entry.

Returns:
  one of:
  - `CPE_SOURCE` - this entry describes a source root in its project
  - `CPE_LIBRARY` - this entry describes a folder containing non-editable files
  - `CPE_PROJECT` - this entry describes another project
  - `CPE_VARIABLE` - this entry describes a project or library indirectly via a includepath variable in the first segment of the path *
  - `CPE_CONTAINER` - this entry describes set of entries referenced indirectly via a includepath container

#### getExclusionPatterns

    IPath[] getExclusionPatterns()

Returns the set of patterns used to exclude resources or classes associated with this includepath entry.

For source includepath entries, exclusion patterns allow specified portions of the resource tree rooted at this source entry's path to be filtered out. If no exclusion patterns are specified, this source entry includes all relevent files. Each path specified must be a relative path, and will be interpreted relative to this source entry's path. File patterns are case-sensitive. A file matched by one or more of these patterns is excluded from the corresponding package fragment root. Exclusion patterns have higher precedence than inclusion patterns; in other words, exclusion patterns can remove files for the ones that are to be included, not the other way around.

The pattern mechanism is similar to Ant's. Each pattern is represented as a relative path. The path segments can be regular file or folder names or simple patterns involving standard wildcard characters.

'*' matches 0 or more characters within a segment. So `*.js` matches `.js`, `a.js` and `Foo.js`, but not `Foo.properties` (does not end with `.js`).

'?' matches 1 character within a segment. So `?.js` matches `a.js`, `A.js`, but not `.js` or `xyz.js` (neither have just one character before `.js`).

Combinations of *'s and ?'s are allowed.

The special pattern '**' matches zero or more segments. In a source entry, a path like `tests/` that ends in a trailing separator is interpreted as `tests/**`, and would match everything under the folder named `tests`.

Example patterns in source entries (assuming that "js" is the only `JavaScript-like extension`):

- `tests/**` (or simply `tests/`) matches all files under a root folder named `tests`. This includes `tests/Foo.js` and `tests/com/example/Foo.js`, but not `com/example/tests/Foo.js` (not under a root folder named `tests`).
- `tests/*` matches all files directly below a root folder named `tests`. This includes `tests/Foo.js` and `tests/FooHelp.js` but not `tests/com/example/Foo.js` (not directly under a folder named `tests`) or `com/Foo.js` (not under a folder named `tests`).
- `**/tests/**` matches all files under any folder named `tests`. This includes `tests/Foo.js`, `com/examples/tests/Foo.js`, and `com/examples/tests/unit/Foo.js`, but not `com/example/Foo.js` (not under a folder named `tests`).

Returns:
  the possibly empty list of resource exclusion patterns associated with this includepath entry, or `null` if this kind of includepath entry does not support exclusion patterns

#### getExtraAttributes

    IIncludePathAttribute[] getExtraAttributes()

Returns the extra includepath attributes for this includepath entry. Returns an empty array if this entry has no extra attributes.

Returns:
  the possibly empty list of extra includepath attributes for this includepath entry

#### getInclusionPatterns

    IPath[] getInclusionPatterns()

Returns the set of patterns used to explicitly define resources to be included with this includepath entry.

For source includepath entries, when no inclusion patterns are specified, the source entry includes all relevent files in the resource tree rooted at this source entry's path. Specifying one or more inclusion patterns means that only the specified portions of the resource tree are to be included. Each path specified must be a relative path, and will be interpreted relative to this source entry's path. File patterns are case-sensitive. A file matched by one or more of these patterns is included in the corresponding package fragment root unless it is excluded by one or more of this entrie's exclusion patterns. Exclusion patterns have higher precedence than inclusion patterns; in other words, exclusion patterns can remove files for the ones that are to be included, not the other way around.

See `getExclusionPatterns()` for a discussion of the syntax and semantics of path patterns. The absence of any inclusion patterns is semantically equivalent to the explicit inclusion pattern `**`.

Example patterns in source entries:

- The inclusion pattern `src/**` by itself includes all files under a root folder named `src`.
- The inclusion patterns `src/**` and `tests/**` includes all files under the root folders named `src` and `tests`.
- The inclusion pattern `src/**` together with the exclusion pattern `src/**/Foo.js` includes all files under a root folder named `src` except for ones named `Foo.js`.

Returns:
  the possibly empty list of resource inclusion patterns associated with this includepath entry, or `null` if this kind of includepath entry does not support inclusion patterns

#### getPath

    IPath getPath()

Returns the path of this includepath entry. The meaning of the path of a includepath entry depends on its entry kind:

- Source code in the current project (`CPE_SOURCE`) - The path associated with this entry is the absolute path to the root folder.
- A binary library in the current project (`CPE_LIBRARY`) - the path associated with this entry is the absolute path to the file.
- A required project (`CPE_PROJECT`) - the path of the entry denotes the path to the corresponding project resource.
- A variable entry (`CPE_VARIABLE`) - the first segment of the path is the name of a includepath variable. If this includepath variable is bound to the path P, the path of the corresponding includepath entry is computed by appending to P the segments of the returned path without the variable.
- A container entry (`CPE_CONTAINER`) - the path of the entry is the name of the includepath container, which can be bound indirectly to a set of includepath entries after resolution. The containerPath is a formed by a first ID segment followed with extra segments that can be used as additional hints for resolving this container reference (also see `IJsGlobalScopeContainer`).

Returns:
  the path of this includepath entry

#### getSourceAttachmentPath

    IPath getSourceAttachmentPath()

Returns the path to the source archive or folder associated with this includepath entry, or `null` if this includepath entry has no source attachment.

Only library and variable includepath entries may have source attachments. For library includepath entries, the result path (if present) locates a source archive or folder. This archive or folder can be located in a project of the workspace or outside thr workspace. For variable includepath entries, the result path (if present) has an analogous form and meaning as the variable path, namely the first segment is the name of a includepath variable.

Returns:
  the path to the source archive or folder, or `null` if none

#### getSourceAttachmentRootPath

    IPath getSourceAttachmentRootPath()

Returns the path within the source archive or folder where package fragments are located. An empty path indicates that packages are located at the root of the source archive or folder. Returns a non-`null` value if and only if `getSourceAttachmentPath()` returns a non-`null` value.

Returns:
  the path within the source archive or folder, or `null` if not applicable

#### isExported

    boolean isExported()

Returns whether this entry is exported to dependent projects. Always returns `false` for source entries (kind `CPE_SOURCE`), which cannot be exported.

Returns:
  `true` if exported, and `false` otherwise