1 /*******************************************************************************
2 * Copyright (c) 2000, 2003 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Common Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/cpl-v10.html
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
13 import org.eclipse.core.runtime.IPath;
16 * An entry on a Java project classpath identifying one or more package fragment
17 * roots. A classpath entry has a content kind (either source,
18 * <code>K_SOURCE</code>, or binary, <code>K_BINARY</code>), which is
19 * inherited by each package fragment root and package fragment associated with
22 * A classpath entry can refer to any of the following:
25 * <li>Source code in the current project. In this case, the entry identifies a
26 * root folder in the current project containing package fragments and
27 * <code>.java</code> source files. The root folder itself represents a
28 * default package, subfolders represent package fragments, and
29 * <code>.java</code> files represent compilation units. All compilation units
30 * will be compiled when the project is built. The classpath entry must specify
31 * the absolute path to the root folder. Entries of this kind are associated
32 * with the <code>CPE_SOURCE</code> constant. Source classpath entries can
33 * carry patterns to exclude selected files. Excluded <code>.java</code>
34 * source files do not appear as compilation units and are not compiled when the
35 * project is built. </li>
37 * <li>A binary library in the current project, in another project, or in the
38 * external file system. In this case the entry identifies a JAR (or root
39 * folder) containing package fragments and <code>.class</code> files. The
40 * classpath entry must specify the absolute path to the JAR (or root folder),
41 * and in case it refers to an external JAR, then there is no associated
42 * resource in the workbench. Entries of this kind are associated with the
43 * <code>CPE_LIBRARY</code> constant.</li>
45 * <li>A required project. In this case the entry identifies another project in
46 * the workspace. The required project is used as a binary library when
47 * compiling (that is, the builder looks in the output location of the required
48 * project for required <code>.class</code> files when building). When
49 * performing other "development" operations - such as code assist, code
50 * resolve, type hierarchy creation, etc. - the source code of the project is
51 * referred to. Thus, development is performed against a required project's
52 * source code, and compilation is performed against a required project's last
53 * built state. The classpath entry must specify the absolute path to the
54 * project. Entries of this kind are associated with the
55 * <code>CPE_PROJECT</code> constant. Note: referencing a required project
56 * with a classpath entry refers to the source code or associated
57 * <code>.class</code> files located in its output location. It will also
58 * automatically include any other libraries or projects that the required
59 * project's classpath refers to, iff the corresponding classpath entries are
60 * tagged as being exported (<code>IClasspathEntry#isExported</code>).
61 * Unless exporting some classpath entries, classpaths are not chained by
62 * default - each project must specify its own classpath in its entirety.</li>
64 * <li> A path beginning in a classpath variable defined globally to the
65 * workspace. Entries of this kind are associated with the
66 * <code>CPE_VARIABLE</code> constant. Classpath variables are created using
67 * <code>JavaCore#setClasspathVariable</code>, and gets resolved, to either a
68 * project or library entry, using
69 * <code>JavaCore#getResolvedClasspathVariable</code>. It is also possible to
70 * register an automatic initializer (<code>ClasspathVariableInitializer</code>),
71 * which will be invoked through the extension point
72 * "net.sourceforge.phpdt.core.classpathVariableInitializer". After resolution,
73 * a classpath variable entry may either correspond to a project or a library
76 * <li> A named classpath container identified by its container path. A
77 * classpath container provides a way to indirectly reference a set of classpath
78 * entries through a classpath entry of kind <code>CPE_CONTAINER</code>.
79 * Typically, a classpath container can be used to describe a complex library
80 * composed of multiple JARs, projects or classpath variables, considering also
81 * that containers can be mapped differently on each project. Several projects
82 * can reference the same generic container path, but have each of them actually
83 * bound to a different container object. The container path is a formed by a
84 * first ID segment followed with extra segments, which can be used as
85 * additional hints for resolving this container reference. If no container was
86 * ever recorded for this container path onto this project (using
87 * <code>setClasspathContainer</code>, then a
88 * <code>ClasspathContainerInitializer</code> will be activated if any was
89 * registered for this container ID onto the extension point
90 * "net.sourceforge.phpdt.core.classpathContainerInitializer". A classpath
91 * container entry can be resolved explicitly using
92 * <code>JavaCore#getClasspathContainer</code> and the resulting container
93 * entries can contain any non-container entry. In particular, it may contain
94 * variable entries, which in turn needs to be resolved before being directly
96 * Also note that the container resolution APIs include an IJavaProject
97 * argument, so as to allow the same container path to be interpreted in
98 * different ways for different projects. </li>
101 * The result of <code>IJavaProject#getResolvedClasspath</code> will have all
102 * entries of type <code>CPE_VARIABLE</code> and <code>CPE_CONTAINER</code>
103 * resolved to a set of <code>CPE_SOURCE</code>, <code>CPE_LIBRARY</code>
104 * or <code>CPE_PROJECT</code> classpath entries.
106 * Any classpath entry other than a source folder (kind <code>CPE_SOURCE</code>)
107 * can be marked as being exported. Exported entries are automatically
108 * contributed to dependent projects, along with the project's default output
109 * folder, which is implicitly exported, and any auxiliary output folders
110 * specified on source classpath entries. The project's output folder(s) are
111 * always listed first, followed by the any exported entries.
113 * This interface is not intended to be implemented by clients. Classpath
114 * entries can be created via methods on <code>JavaCore</code>.
117 * @see JavaCore#newLibraryEntry
118 * @see JavaCore#newProjectEntry
119 * @see JavaCore#newSourceEntry
120 * @see JavaCore#newVariableEntry
121 * @see JavaCore#newContainerEntry
122 * @see ClasspathVariableInitializer
123 * @see ClasspathContainerInitializer
125 public interface IClasspathEntry {
128 * Entry kind constant describing a classpath entry identifying a library. A
129 * library is a folder or JAR containing package fragments consisting of
130 * pre-compiled binaries.
135 * Entry kind constant describing a classpath entry identifying a required
141 * Entry kind constant describing a classpath entry identifying a folder
142 * containing package fragments with source code to be compiled.
147 * Entry kind constant describing a classpath entry defined using a path
148 * that begins with a classpath variable reference.
150 int CPE_VARIABLE = 4;
153 * Entry kind constant describing a classpath entry representing a name
154 * classpath container.
158 int CPE_CONTAINER = 5;
161 * Returns the kind of files found in the package fragments identified by
162 * this classpath entry.
164 * @return <code>IPackageFragmentRoot.K_SOURCE</code> for files containing
165 * source code, and <code>IPackageFragmentRoot.K_BINARY</code> for
166 * binary class files. There is no specified value for an entry
167 * denoting a variable (<code>CPE_VARIABLE</code>) or a
168 * classpath container (<code>CPE_CONTAINER</code>).
170 int getContentKind();
173 * Returns the kind of this classpath entry.
177 * <li><code>CPE_SOURCE</code> - this entry describes a source
178 * root in its project
179 * <li><code>CPE_LIBRARY</code> - this entry describes a folder
180 * or JAR containing binaries
181 * <li><code>CPE_PROJECT</code> - this entry describes another
184 * <li><code>CPE_VARIABLE</code> - this entry describes a project or
185 * library indirectly via a classpath variable in the first segment of the
187 * <li><code>CPE_CONTAINER</code> - this entry describes set of entries
188 * referenced indirectly via a classpath container
194 * Returns the set of patterns used to exclude resources associated with
197 * Exclusion patterns allow specified portions of the resource tree rooted
198 * at this source entry's path to be filtered out. If no exclusion patterns
199 * are specified, this source entry includes all relevent files. Each path
200 * specified must be a relative path, and will be interpreted relative to
201 * this source entry's path. File patterns are case-sensitive. A file
202 * matched by one or more of these patterns is excluded from the
203 * corresponding package fragment root.
206 * Note that there is no need to supply a pattern to exclude ".class" files
207 * because a source entry filters these out automatically.
210 * The pattern mechanism is similar to Ant's. Each pattern is represented as
211 * a relative path. The path segments can be regular file or folder names or
212 * simple patterns involving standard wildcard characters.
215 * '*' matches 0 or more characters within a segment. So <code>*.java</code>
216 * matches <code>.java</code>, <code>a.java</code> and
217 * <code>Foo.java</code>, but not <code>Foo.properties</code> (does not
218 * end with <code>.java</code>).
221 * '?' matches 1 character within a segment. So <code>?.java</code>
222 * matches <code>a.java</code>, <code>A.java</code>, but not
223 * <code>.java</code> or <code>xyz.java</code> (neither have just one
224 * character before <code>.java</code>).
227 * Combinations of *'s and ?'s are allowed.
230 * The special pattern '**' matches zero or more segments. A path like
231 * <code>tests/</code> that ends in a trailing separator is interpreted as
232 * <code>tests/**</code>, and would match all files under the the
233 * folder named <code>tests</code>.
238 * <li> <code>tests/**</code> (or simply <code>tests/</code>)
239 * matches all files under a root folder named <code>tests</code>. This
240 * includes <code>tests/Foo.java</code> and
241 * <code>tests/com/example/Foo.java</code>, but not
242 * <code>com/example/tests/Foo.java</code> (not under a root folder named
243 * <code>tests</code>). </li>
244 * <li> <code>tests/*</code> matches all files directly below a root
245 * folder named <code>tests</code>. This includes
246 * <code>tests/Foo.java</code> and <code>tests/FooHelp.java</code> but
247 * not <code>tests/com/example/Foo.java</code> (not directly under a
248 * folder named <code>tests</code>) or <code>com/Foo.java</code> (not
249 * under a folder named <code>tests</code>). </li>
250 * <li> <code>**/tests/**</code> matches all files under
251 * any folder named <code>tests</code>. This includes
252 * <code>tests/Foo.java</code>, <code>com/examples/tests/Foo.java</code>,
253 * and <code>com/examples/tests/unit/Foo.java</code>, but not
254 * <code>com/example/Foo.java</code> (not under a folder named
255 * <code>tests</code>). </li>
259 * @return the possibly empty list of resource exclusion patterns associated
260 * with this source entry, and <code>null</code> for other kinds
261 * of classpath entries
264 IPath[] getExclusionPatterns();
267 * Returns the set of patterns used to explicitly define resources to be
268 * included with this source entry.
270 * When no inclusion patterns are specified, the source entry includes all
271 * relevent files in the resource tree rooted at this source entry's path.
272 * Specifying one or more inclusion patterns means that only the specified
273 * portions of the resource tree are to be included. Each path specified
274 * must be a relative path, and will be interpreted relative to this source
275 * entry's path. File patterns are case-sensitive. A file matched by one or
276 * more of these patterns is included in the corresponding package fragment
277 * root unless it is excluded by one or more of this entrie's exclusion
278 * patterns. Exclusion patterns have higher precedence than inclusion
279 * patterns; in other words, exclusion patterns can remove files for the
280 * ones that are to be included, not the other way around.
283 * See {@link #getExclusionPatterns()} for a discussion of the syntax and
284 * semantics of path patterns. The absence of any inclusion patterns is
285 * semantically equivalent to the explicit inclusion pattern
286 * <code>**</code>.
291 * <li> The inclusion pattern <code>src/**</code> by itself
292 * includes all files under a root folder named <code>src</code>. </li>
293 * <li> The inclusion patterns <code>src/**</code> and
294 * <code>tests/**</code> includes all files under the root folders
295 * named <code>src</code> and <code>tests</code>. </li>
296 * <li> The inclusion pattern <code>src/**</code> together with
297 * the exclusion pattern <code>src/**/Foo.java</code> includes all
298 * files under a root folder named <code>src</code> except for ones named
299 * <code>Foo.java</code>. </li>
303 * @return the possibly empty list of resource inclusion patterns associated
304 * with this source entry, and <code>null</code> for other kinds
305 * of classpath entries
308 IPath[] getInclusionPatterns();
311 * Returns the full path to the specific location where the builder writes
312 * <code>.class</code> files generated for this source entry (entry kind
313 * <code>CPE_SOURCE</code>).
315 * Source entries can optionally be associated with a specific output
316 * location. If none is provided, the source entry will be implicitly
317 * associated with its project default output location (see
318 * <code>IJavaProject#getOutputLocation</code>).
321 * NOTE: A specific output location cannot coincidate with another
322 * source/library entry.
325 * @return the full path to the specific location where the builder writes
326 * <code>.class</code> files for this source entry, or
327 * <code>null</code> if using default output folder
330 IPath getOutputLocation();
333 * Returns the path of this classpath entry.
335 * The meaning of the path of a classpath entry depends on its entry kind:
337 * <li>Source code in the current project (<code>CPE_SOURCE</code>) -
338 * The path associated with this entry is the absolute path to the root
340 * <li>A binary library in the current project (<code>CPE_LIBRARY</code>) -
341 * the path associated with this entry is the absolute path to the JAR (or
342 * root folder), and in case it refers to an external JAR, then there is no
343 * associated resource in the workbench.
344 * <li>A required project (<code>CPE_PROJECT</code>) - the path of the
345 * entry denotes the path to the corresponding project resource.</li>
346 * <li>A variable entry (<code>CPE_VARIABLE</code>) - the first segment
347 * of the path is the name of a classpath variable. If this classpath
348 * variable is bound to the path <it>P</it>, the path of the corresponding
349 * classpath entry is computed by appending to <it>P</it> the segments of
350 * the returned path without the variable.</li>
351 * <li> A container entry (<code>CPE_CONTAINER</code>) - the path of the
352 * entry is the name of the classpath container, which can be bound
353 * indirectly to a set of classpath entries after resolution. The
354 * containerPath is a formed by a first ID segment followed with extra
355 * segments that can be used as additional hints for resolving this
356 * container reference (also see <code>IClasspathContainer</code>). </li>
359 * @return the path of this classpath entry
364 * Returns the path to the source archive or folder associated with this
365 * classpath entry, or <code>null</code> if this classpath entry has no
368 * Only library and variable classpath entries may have source attachments.
369 * For library classpath entries, the result path (if present) locates a
370 * source archive or folder. This archive or folder can be located in a
371 * project of the workspace or outside thr workspace. For variable classpath
372 * entries, the result path (if present) has an analogous form and meaning
373 * as the variable path, namely the first segment is the name of a classpath
377 * @return the path to the source archive or folder, or <code>null</code>
380 IPath getSourceAttachmentPath();
383 * Returns the path within the source archive or folder where package
384 * fragments are located. An empty path indicates that packages are located
385 * at the root of the source archive or folder. Returns a non-<code>null</code>
386 * value if and only if <code>getSourceAttachmentPath</code> returns a
387 * non-<code>null</code> value.
389 * @return the path within the source archive or folder, or
390 * <code>null</code> if not applicable
392 IPath getSourceAttachmentRootPath();
395 * Returns whether this entry is exported to dependent projects. Always
396 * returns <code>false</code> for source entries (kind
397 * <code>CPE_SOURCE</code>), which cannot be exported.
399 * @return <code>true</code> if exported, and <code>false</code>
403 boolean isExported();
406 * This is a helper method, which returns the resolved classpath entry
407 * denoted by an entry (if it is a variable entry). It is obtained by
408 * resolving the variable reference in the first segment. Returns <node>null</code>
409 * if unable to resolve using the following algorithm:
411 * <li> if variable segment cannot be resolved, returns <code>null</code></li>
412 * <li> finds a project, JAR or binary folder in the workspace at the
413 * resolved path location</li>
414 * <li> if none finds an external JAR file or folder outside the workspace
415 * at the resolved path location </li>
416 * <li> if none returns <code>null</code></li>
419 * Variable source attachment is also resolved and recorded in the resulting
423 * @return the resolved library or project classpath entry, or <code>null</code>
424 * if the given path could not be resolved to a classpath entry
426 * Note that this deprecated API doesn't handle CPE_CONTAINER
429 * @deprecated - use JavaCore.getResolvedClasspathEntry(...)
431 IClasspathEntry getResolvedEntry();