Java Doc for IClasspathEntry.java in  » IDE-Eclipse » jdt » org » eclipse » jdt » core » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A classpath 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 JavaCore.getJavaLikeExtensions Java-like extensions . The root folder itself represents a default package, subfolders represent package fragments, and files with a Java-like extension (e.g. .java files) represent compilation units. All compilation units will be compiled when the project is built. The classpath entry must specify the absolute path to the root folder. Entries of this kind are associated with the IClasspathEntry.CPE_SOURCE constant. Source classpath entries can carry inclusion and exclusion patterns for selecting which source files appear as compilation 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 a JAR (or root folder) containing package fragments and .class files. The classpath entry must specify the absolute path to the JAR (or root folder), and in case it refers to an external JAR, then there is no associated resource in the workbench. Entries of this kind are associated with the IClasspathEntry.CPE_LIBRARY constant.
• A required project. In this case the entry identifies another project in the workspace. The required project is used as a binary library when compiling (that is, the builder looks in the output location of the required project for required .class files when building). 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, and compilation is performed against a required project's last built state. The classpath entry must specify the absolute path to the project. Entries of this kind are associated with the IClasspathEntry.CPE_PROJECT constant. Note: referencing a required project with a classpath 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 classpath refers to, iff the corresponding classpath entries are tagged as being exported ( IClasspathEntry.isExported ). Unless exporting some classpath entries, classpaths are not chained by default - each project must specify its own classpath in its entirety.
• A path beginning in a classpath variable defined globally to the workspace. Entries of this kind are associated with the IClasspathEntry.CPE_VARIABLE constant. Classpath variables are created using JavaCore.setClasspathVariable(StringIPathorg.eclipse.core.runtime.IProgressMonitor) , and gets resolved, to either a project or library entry, using JavaCore.getResolvedClasspathEntry(IClasspathEntry) . It is also possible to register an automatic initializer ( ClasspathVariableInitializer ), which will be invoked through the extension point "org.eclipse.jdt.core.classpathVariableInitializer". After resolution, a classpath variable entry may either correspond to a project or a library entry.
• A named classpath container identified by its container path. A classpath container provides a way to indirectly reference a set of classpath entries through a classpath entry of kind IClasspathEntry.CPE_CONTAINER . Typically, a classpath container can be used to describe a complex library composed of multiple JARs, projects or classpath 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 JavaCore.setClasspathContainer , then a ClasspathContainerInitializer will be activated if any was registered for this container ID onto the extension point "org.eclipse.jdt.core.classpathContainerInitializer". A classpath container entry can be resolved explicitly using JavaCore.getClasspathContainer 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 IJavaProject argument, so as to allow the same container path to be interpreted in different ways for different projects.

Any classpath entry other than a source folder (kind IClasspathEntry.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 classpath 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. Classpath entries can be created via methods on JavaCore .

For source classpath entries, exclusion patterns allow specified portions of the resource tree rooted at this source entry's path to be filtered out.

For source classpath 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.

• Source code in the current project ( IClasspathEntry.CPE_SOURCE ) - The path associated with this entry is the absolute path to the root folder.

Only library and variable classpath entries may have source attachments. For library classpath entries, the result path (if present) locates a source archive or folder.

• IClasspathEntry.CPE_SOURCE - this entry describes a source root inits project
• IClasspathEntry.CPE_LIBRARY - this entry describes a folder or JARcontaining binaries
• IClasspathEntry.CPE_PROJECT - this entry describes another project
• IClasspathEntry.CPE_VARIABLE - this entry describes a project or libraryindirectly via a classpath variable in the first segment of the path
• IClasspathEntry.CPE_CONTAINER - this entry describes set of entriesreferenced indirectly via a classpath container

For source classpath 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.

Note that there is no need to supply a pattern to exclude ".class" files because a source entry filters these out automatically.

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 *.java matches .java, a.java and Foo.java, but not Foo.properties (does not end with .java).

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

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 "java" is the only JavaCore.getJavaLikeExtensions Java-like extension ):

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

For source classpath 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 IClasspathEntry.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.java includes all files under a root folder named src except for ones named Foo.java.

Source entries can optionally be associated with a specific output location. If none is provided, the source entry will be implicitly associated with its project default output location (see IJavaProject.getOutputLocation ).

NOTE: A specific output location cannot coincidate with another source/library entry.

• Source code in the current project ( IClasspathEntry.CPE_SOURCE ) - The path associated with this entry is the absolute path to the root folder.
• A binary library in the current project ( IClasspathEntry.CPE_LIBRARY ) - the path associated with this entry is the absolute path to the JAR (or root folder), and in case it refers to an external JAR, then there is no associated resource in the workbench.
• A required project ( IClasspathEntry.CPE_PROJECT ) - the path of the entry denotes the path to the corresponding project resource.
• A variable entry ( IClasspathEntry.CPE_VARIABLE ) - the first segment of the path is the name of a classpath variable. If this classpath variable is bound to the path P, the path of the corresponding classpath entry is computed by appending to P the segments of the returned path without the variable.
• A container entry ( IClasspathEntry.CPE_CONTAINER ) - the path of the entry is the name of the classpath container, which can be bound indirectly to a set of classpath 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 IClasspathContainer ).

• if variable segment cannot be resolved, returns null
• finds a project, JAR or binary folder in the workspace at the resolved path location
• if none finds an external JAR file or folder outside the workspace at the resolved path location
• if none returns null

Variable source attachment is also resolved and recorded in the resulting classpath entry.

the resolved library or project classpath entry, or nullif the given path could not be resolved to a classpath entry

Note that this deprecated API doesn't handle CPE_CONTAINER entries.JavaCore.getResolvedClasspathEntry(IClasspathEntry)

Only library and variable classpath entries may have source attachments. For library classpath 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 classpath 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 classpath variable.