/*******************************************************************************
* Copyright (c) 2000, 2003 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Common Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/cpl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package net.sourceforge.phpdt.core;
import org.eclipse.core.runtime.IPath;
/**
* An entry on a Java project classpath identifying one or more package fragment
* roots. A classpath entry has a content kind (either source,
* K_SOURCE
, or binary, K_BINARY
), which is inherited
* by each package fragment root and package fragment associated with the entry.
*
* A classpath entry can refer to any of the following:
.java
source files. The root folder itself represents a default
* package, subfolders represent package fragments, and .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 CPE_SOURCE
constant.
* Source classpath entries can carry patterns to exclude selected files.
* Excluded .java
source files do not appear as compilation
* units and are not compiled when the project is built.
* .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 CPE_LIBRARY
constant..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 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.CPE_VARIABLE
constant.
* Classpath variables are created using JavaCore#setClasspathVariable
,
* and gets resolved, to either a project or library entry, using
* JavaCore#getResolvedClasspathVariable
.
* It is also possible to register an automatic initializer (ClasspathVariableInitializer
),
* which will be invoked through the extension point "net.sourceforge.phpdt.core.classpathVariableInitializer".
* After resolution, a classpath variable entry may either correspond to a project or a library entry. 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 setClasspathContainer
,
* then a ClasspathContainerInitializer
will be activated if any was registered for this
* container ID onto the extension point "net.sourceforge.phpdt.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.
* IJavaProject#getResolvedClasspath
will have all entries of type
* CPE_VARIABLE
and CPE_CONTAINER
resolved to a set of
* CPE_SOURCE
, CPE_LIBRARY
or CPE_PROJECT
* classpath entries.
*
* Any classpath 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
* 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
.
*
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 classpath container (CPE_CONTAINER
).
*/
int getContentKind();
/**
* Returns the kind of this classpath entry.
*
* @return one of:
* CPE_SOURCE
- this entry describes a source root in
its project
* CPE_LIBRARY
- this entry describes a folder or JAR
containing binaries
* CPE_PROJECT
- this entry describes another project
*
* CPE_VARIABLE
- this entry describes a project or library
* indirectly via a classpath variable in the first segment of the path
* *
* CPE_CONTAINER
- this entry describes set of entries
* referenced indirectly via a classpath container
* * 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. *
** 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. A path
* like tests/
that ends in a trailing separator is interpreted
* as tests/**
, and would match all files under the
* the folder named tests
.
*
* Examples: *
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
).
* null
for other
* kinds of classpath entries
* @since 2.1
*/
IPath[] getExclusionPatterns();
/**
* Returns the set of patterns used to explicitly define resources to be
* included with this source entry.
* * 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 {@link #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
* **
.
*
* Examples: *
src/**
by itself includes all
* files under a root folder named src
.
* src/**
and
* tests/**
includes all files under the root folders
* named src
and tests
.
* src/**
together with the
* exclusion pattern src/**/Foo.java
includes all
* files under a root folder named src
except for ones
* named Foo.java
.
* null
for other
* kinds of classpath entries
* @since 3.0
*/
IPath[] getInclusionPatterns();
/**
* Returns the full path to the specific location where the builder writes
* .class
files generated for this source entry
* (entry kind CPE_SOURCE
).
*
* 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. *
* * @return the full path to the specific location where the builder writes *.class
files for this source entry, or null
* if using default output folder
* @since 2.1
*/
IPath getOutputLocation();
/**
* Returns the path of this classpath entry.
*
* The meaning of the path of a classpath entry depends on its entry kind:CPE_SOURCE
) -
* The path associated with this entry is the absolute path to the root folder. 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.
* CPE_PROJECT
) - the path of the entry denotes the
* path to the corresponding project resource.CPE_VARIABLE
) - the first segment of the path
* is the name of a classpath variable. If this classpath variable
* is bound to the path 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
).
* null
if this classpath entry has no
* source attachment.
* * 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. *
* * @return the path to the source archive or folder, ornull
if none
*/
IPath getSourceAttachmentPath();
/**
* 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.
*
* @return the path within the source archive or folder, or null
if
* not applicable
*/
IPath getSourceAttachmentRootPath();
/**
* Returns whether this entry is exported to dependent projects.
* Always returns false
for source entries (kind
* CPE_SOURCE
), which cannot be exported.
*
* @return true
if exported, and false
otherwise
* @since 2.0
*/
boolean isExported();
/**
* This is a helper method, which returns the resolved classpath entry denoted
* by an entry (if it is a variable entry). It is obtained by resolving the variable
* reference in the first segment. Returns null
null
* Variable source attachment is also resolved and recorded in the resulting classpath entry. *
* @return the resolved library or project classpath entry, or null
* if the given path could not be resolved to a classpath entry
*
* Note that this deprecated API doesn't handle CPE_CONTAINER entries. * * @deprecated - use JavaCore.getResolvedClasspathEntry(...) */ IClasspathEntry getResolvedEntry(); }