KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jdt > core > IClasspathEntry


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/
11 package org.eclipse.jdt.core;
12
13 import org.eclipse.core.runtime.IPath;
14
15 /**
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  * {@link IPackageFragmentRoot#K_SOURCE}, or binary, {@link IPackageFragmentRoot#K_BINARY}), which is inherited
19  * by each package fragment root and package fragment associated with the entry.
20  * <p>
21  * A classpath entry can refer to any of the following:<ul>
22  *
23  * <li>Source code in the current project. In this case, the entry identifies a
24  * root folder in the current project containing package fragments and
25  * source files with one of the {@link JavaCore#getJavaLikeExtensions()
26  * Java-like extensions}. The root folder itself represents a default
27  * package, subfolders represent package fragments, and files with a
28  * Java-like extension (e.g. <code>.java</code> files)
29  * represent compilation units. All compilation units will be compiled when
30  * the project is built. The classpath entry must specify the
31  * absolute path to the root folder. Entries of this kind are
32  * associated with the {@link #CPE_SOURCE} constant.
33  * Source classpath entries can carry inclusion and exclusion patterns for
34  * selecting which source files appear as compilation
35  * units and get compiled when the project is built.
36  * </li>
37  *
38  * <li>A binary library in the current project, in another project, or in the external
39  * file system. In this case the entry identifies a JAR (or root folder) containing
40  * package fragments and <code>.class</code> files. The classpath entry
41  * must specify the absolute path to the JAR (or root folder), and in case it refers
42  * to an external JAR, then there is no associated resource in the workbench. Entries
43  * of this kind are associated with the {@link #CPE_LIBRARY} constant.</li>
44  *
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 compiling
47  * (that is, the builder looks in the output location of the required project
48  * for required <code>.class</code> files when building). When performing other
49  * "development" operations - such as code assist, code resolve, type hierarchy
50  * creation, etc. - the source code of the project is referred to. Thus, development
51  * is performed against a required project's source code, and compilation is
52  * performed against a required project's last built state. The
53  * classpath entry must specify the absolute path to the
54  * project. Entries of this kind are associated with the {@link #CPE_PROJECT}
55  * constant.
56  * Note: referencing a required project with a classpath entry refers to the source
57  * code or associated <code>.class</code> files located in its output location.
58  * It will also automatically include any other libraries or projects that the required project's classpath
59  * refers to, iff the corresponding classpath entries are tagged as being exported
60  * ({@link IClasspathEntry#isExported}).
61  * Unless exporting some classpath entries, classpaths are not chained by default -
62  * each project must specify its own classpath in its entirety.</li>
63  *
64  * <li> A path beginning in a classpath variable defined globally to the workspace.
65  * Entries of this kind are associated with the {@link #CPE_VARIABLE} constant.
66  * Classpath variables are created using {@link JavaCore#setClasspathVariable(String, IPath, org.eclipse.core.runtime.IProgressMonitor)},
67  * and gets resolved, to either a project or library entry, using
68  * {@link JavaCore#getResolvedClasspathEntry(IClasspathEntry)}.
69  * It is also possible to register an automatic initializer ({@link ClasspathVariableInitializer}),
70  * which will be invoked through the extension point "org.eclipse.jdt.core.classpathVariableInitializer".
71  * After resolution, a classpath variable entry may either correspond to a project or a library entry. </li>
72  *
73  * <li> A named classpath container identified by its container path.
74  * A classpath container provides a way to indirectly reference a set of classpath entries through
75  * a classpath entry of kind {@link #CPE_CONTAINER}. Typically, a classpath container can
76  * be used to describe a complex library composed of multiple JARs, projects or classpath variables,
77  * considering also that containers can be mapped differently on each project. Several projects can
78  * reference the same generic container path, but have each of them actually bound to a different
79  * container object.
80  * The container path is a formed by a first ID segment followed with extra segments,
81  * which can be used as additional hints for resolving this container reference. If no container was ever
82  * recorded for this container path onto this project (using {@link JavaCore#setClasspathContainer},
83  * then a {@link ClasspathContainerInitializer} will be activated if any was registered for this
84  * container ID onto the extension point "org.eclipse.jdt.core.classpathContainerInitializer".
85  * A classpath container entry can be resolved explicitly using {@link JavaCore#getClasspathContainer}
86  * and the resulting container entries can contain any non-container entry. In particular, it may contain variable
87  * entries, which in turn needs to be resolved before being directly used.
88  * <br> Also note that the container resolution APIs include an IJavaProject argument, so as to allow the same
89  * container path to be interpreted in different ways for different projects. </li>
90  * </ul>
91  * </p>
92  * The result of {@link IJavaProject#getResolvedClasspath} will have all entries of type
93  * {@link #CPE_VARIABLE} and {@link #CPE_CONTAINER} resolved to a set of
94  * {@link #CPE_SOURCE}, {@link #CPE_LIBRARY} or {@link #CPE_PROJECT}
95  * classpath entries.
96  * <p>
97  * Any classpath entry other than a source folder (kind {@link #CPE_SOURCE}) can
98  * be marked as being exported. Exported entries are automatically contributed to
99  * dependent projects, along with the project's default output folder, which is
100  * implicitly exported, and any auxiliary output folders specified on source
101  * classpath entries. The project's output folder(s) are always listed first,
102  * followed by the any exported entries.
103  * <p>
104  * This interface is not intended to be implemented by clients.
105  * Classpath entries can be created via methods on {@link JavaCore}.
106  * </p>
107  *
108  * @see JavaCore#newLibraryEntry(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath)
109  * @see JavaCore#newProjectEntry(org.eclipse.core.runtime.IPath)
110  * @see JavaCore#newSourceEntry(org.eclipse.core.runtime.IPath)
111  * @see JavaCore#newVariableEntry(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath)
112  * @see JavaCore#newContainerEntry(org.eclipse.core.runtime.IPath)
113  * @see ClasspathVariableInitializer
114  * @see ClasspathContainerInitializer
115  */
116 public interface IClasspathEntry {
117
118     /**
119      * Entry kind constant describing a classpath entry identifying a
120      * library. A library is a folder or JAR containing package
121      * fragments consisting of pre-compiled binaries.
122      */
123     int CPE_LIBRARY = 1;
124
125     /**
126      * Entry kind constant describing a classpath entry identifying a
127      * required project.
128      */
129     int CPE_PROJECT = 2;
130
131     /**
132      * Entry kind constant describing a classpath entry identifying a
133      * folder containing package fragments with source code
134      * to be compiled.
135      */
136     int CPE_SOURCE = 3;
137
138     /**
139      * Entry kind constant describing a classpath entry defined using
140      * a path that begins with a classpath variable reference.
141      */
142     int CPE_VARIABLE = 4;
143
144     /**
145      * Entry kind constant describing a classpath entry representing
146      * a name classpath container.
147      *
148      * @since 2.0
149      */
150     int CPE_CONTAINER = 5;
151     
152     /**
153      * Returns whether the access rules of the project's exported entries should be combined with this entry's access rules.
154      * Returns true for container entries.
155      * Returns false otherwise.
156      *
157      * @return whether the access rules of the project's exported entries should be combined with this entry's access rules
158      * @since 3.1
159      */
160     boolean combineAccessRules();
161
162     /**
163      * Returns the possibly empty list of access rules for this entry.
164      *
165      * @return the possibly empty list of access rules for this entry
166      * @since 3.1
167      */
168     IAccessRule[] getAccessRules();
169     /**
170      * Returns the kind of files found in the package fragments identified by this
171      * classpath entry.
172      *
173      * @return {@link IPackageFragmentRoot#K_SOURCE} for files containing
174      * source code, and {@link IPackageFragmentRoot#K_BINARY} for binary
175      * class files.
176      * There is no specified value for an entry denoting a variable ({@link #CPE_VARIABLE})
177      * or a classpath container ({@link #CPE_CONTAINER}).
178      */
179     int getContentKind();
180
181     /**
182      * Returns the kind of this classpath entry.
183      *
184      * @return one of:
185      * <ul>
186      * <li>{@link #CPE_SOURCE} - this entry describes a source root in
187             its project
188      * <li>{@link #CPE_LIBRARY} - this entry describes a folder or JAR
189             containing binaries
190      * <li>{@link #CPE_PROJECT} - this entry describes another project
191      *
192      * <li>{@link #CPE_VARIABLE} - this entry describes a project or library
193      * indirectly via a classpath variable in the first segment of the path
194      * *
195      * <li>{@link #CPE_CONTAINER} - this entry describes set of entries
196      * referenced indirectly via a classpath container
197      * </ul>
198      */
199     int getEntryKind();
200
201     /**
202      * Returns the set of patterns used to exclude resources or classes associated with
203      * this classpath entry.
204      * <p>
205      * For source classpath entries,
206      * exclusion patterns allow specified portions of the resource tree rooted
207      * at this source entry's path to be filtered out. If no exclusion patterns
208      * are specified, this source entry includes all relevent files. Each path
209      * specified must be a relative path, and will be interpreted relative
210      * to this source entry's path. File patterns are case-sensitive. A file
211      * matched by one or more of these patterns is excluded from the
212      * corresponding package fragment root.
213      * Exclusion patterns have higher precedence than inclusion patterns;
214      * in other words, exclusion patterns can remove files for the ones that
215      * are to be included, not the other way around.
216      * </p>
217      * <p>
218      * Note that there is no need to supply a pattern to exclude ".class" files
219      * because a source entry filters these out automatically.
220      * </p>
221      * <p>
222      * The pattern mechanism is similar to Ant's. Each pattern is represented as
223      * a relative path. The path segments can be regular file or folder names or simple patterns
224      * involving standard wildcard characters.
225      * </p>
226      * <p>
227      * '*' matches 0 or more characters within a segment. So
228      * <code>*.java</code> matches <code>.java</code>, <code>a.java</code>
229      * and <code>Foo.java</code>, but not <code>Foo.properties</code>
230      * (does not end with <code>.java</code>).
231      * </p>
232      * <p>
233      * '?' matches 1 character within a segment. So <code>?.java</code>
234      * matches <code>a.java</code>, <code>A.java</code>,
235      * but not <code>.java</code> or <code>xyz.java</code> (neither have
236      * just one character before <code>.java</code>).
237      * </p>
238      * <p>
239      * Combinations of *'s and ?'s are allowed.
240      * </p>
241      * <p>
242      * The special pattern '**' matches zero or more segments. In a source entry,
243      * a path like <code>tests/</code> that ends in a trailing separator is interpreted
244      * as <code>tests/&#42;&#42;</code>, and would match everything under
245      * the folder named <code>tests</code>.
246      * </p>
247      * <p>
248      * Example patterns in source entries (assuming that "java" is the only {@link JavaCore#getJavaLikeExtensions() Java-like extension}):
249      * <ul>
250      * <li>
251      * <code>tests/&#42;&#42;</code> (or simply <code>tests/</code>)
252      * matches all files under a root folder
253      * named <code>tests</code>. This includes <code>tests/Foo.java</code>
254      * and <code>tests/com/example/Foo.java</code>, but not
255      * <code>com/example/tests/Foo.java</code> (not under a root folder named
256      * <code>tests</code>).
257      * </li>
258      * <li>
259      * <code>tests/&#42;</code> matches all files directly below a root
260      * folder named <code>tests</code>. This includes <code>tests/Foo.java</code>
261      * and <code>tests/FooHelp.java</code>
262      * but not <code>tests/com/example/Foo.java</code> (not directly under
263      * a folder named <code>tests</code>) or
264      * <code>com/Foo.java</code> (not under a folder named <code>tests</code>).
265      * </li>
266      * <li>
267      * <code>&#42;&#42;/tests/&#42;&#42;</code> matches all files under any
268      * folder named <code>tests</code>. This includes <code>tests/Foo.java</code>,
269      * <code>com/examples/tests/Foo.java</code>, and
270      * <code>com/examples/tests/unit/Foo.java</code>, but not
271      * <code>com/example/Foo.java</code> (not under a folder named
272      * <code>tests</code>).
273      * </li>
274      * </ul>
275      * </p>
276      *
277      * @return the possibly empty list of resource exclusion patterns
278      * associated with this classpath entry, or <code>null</code> if this kind
279      * of classpath entry does not support exclusion patterns
280      * @since 2.1
281      */
282     IPath[] getExclusionPatterns();
283     
284     /**
285      * Returns the extra classpath attributes for this classpath entry. Returns an empty array if this entry
286      * has no extra attributes.
287      *
288      * @return the possibly empty list of extra classpath attributes for this classpath entry
289      * @since 3.1
290      */
291     IClasspathAttribute[] getExtraAttributes();
292     
293     /**
294      * Returns the set of patterns used to explicitly define resources or classes
295      * to be included with this classpath entry.
296      * <p>
297      * For source classpath entries,
298      * when no inclusion patterns are specified, the source entry includes all
299      * relevent files in the resource tree rooted at this source entry's path.
300      * Specifying one or more inclusion patterns means that only the specified
301      * portions of the resource tree are to be included. Each path specified
302      * must be a relative path, and will be interpreted relative to this source
303      * entry's path. File patterns are case-sensitive. A file matched by one or
304      * more of these patterns is included in the corresponding package fragment
305      * root unless it is excluded by one or more of this entrie's exclusion
306      * patterns. Exclusion patterns have higher precedence than inclusion
307      * patterns; in other words, exclusion patterns can remove files for the
308      * ones that are to be included, not the other way around.
309      * </p>
310      * <p>
311      * See {@link #getExclusionPatterns()} for a discussion of the syntax and
312      * semantics of path patterns. The absence of any inclusion patterns is
313      * semantically equivalent to the explicit inclusion pattern
314      * <code>&#42;&#42;</code>.
315      * </p>
316      * <p>
317      * Example patterns in source entries:
318      * <ul>
319      * <li>
320      * The inclusion pattern <code>src/&#42;&#42;</code> by itself includes all
321      * files under a root folder named <code>src</code>.
322      * </li>
323      * <li>
324      * The inclusion patterns <code>src/&#42;&#42;</code> and
325      * <code>tests/&#42;&#42;</code> includes all files under the root folders
326      * named <code>src</code> and <code>tests</code>.
327      * </li>
328      * <li>
329      * The inclusion pattern <code>src/&#42;&#42;</code> together with the
330      * exclusion pattern <code>src/&#42;&#42;/Foo.java</code> includes all
331      * files under a root folder named <code>src</code> except for ones
332      * named <code>Foo.java</code>.
333      * </li>
334      * </ul>
335      * </p>
336      *
337      * @return the possibly empty list of resource inclusion patterns
338      * associated with this classpath entry, or <code>null</code> if this kind
339      * of classpath entry does not support inclusion patterns
340      * @since 3.0
341      */
342     IPath[] getInclusionPatterns();
343
344     /**
345      * Returns the full path to the specific location where the builder writes
346      * <code>.class</code> files generated for this source entry
347      * (entry kind {@link #CPE_SOURCE}).
348      * <p>
349      * Source entries can optionally be associated with a specific output location.
350      * If none is provided, the source entry will be implicitly associated with its project
351      * default output location (see {@link IJavaProject#getOutputLocation}).
352      * </p><p>
353      * NOTE: A specific output location cannot coincidate with another source/library entry.
354      * </p>
355      *
356      * @return the full path to the specific location where the builder writes
357      * <code>.class</code> files for this source entry, or <code>null</code>
358      * if using default output folder
359      * @since 2.1
360      */
361     IPath getOutputLocation();
362     
363     /**
364      * Returns the path of this classpath entry.
365      *
366      * The meaning of the path of a classpath entry depends on its entry kind:<ul>
367      * <li>Source code in the current project ({@link #CPE_SOURCE}) -
368      * The path associated with this entry is the absolute path to the root folder. </li>
369      * <li>A binary library in the current project ({@link #CPE_LIBRARY}) - the path
370      * associated with this entry is the absolute path to the JAR (or root folder), and
371      * in case it refers to an external JAR, then there is no associated resource in
372      * the workbench.
373      * <li>A required project ({@link #CPE_PROJECT}) - the path of the entry denotes the
374      * path to the corresponding project resource.</li>
375      * <li>A variable entry ({@link #CPE_VARIABLE}) - the first segment of the path
376      * is the name of a classpath variable. If this classpath variable
377      * is bound to the path <i>P</i>, the path of the corresponding classpath entry
378      * is computed by appending to <i>P</i> the segments of the returned
379      * path without the variable.</li>
380      * <li> A container entry ({@link #CPE_CONTAINER}) - the path of the entry
381      * is the name of the classpath container, which can be bound indirectly to a set of classpath
382      * entries after resolution. The containerPath is a formed by a first ID segment followed with
383      * extra segments that can be used as additional hints for resolving this container
384      * reference (also see {@link IClasspathContainer}).
385      * </li>
386      * </ul>
387      *
388      * @return the path of this classpath entry
389      */
390     IPath getPath();
391
392     /**
393      * Returns the path to the source archive or folder associated with this
394      * classpath entry, or <code>null</code> if this classpath entry has no
395      * source attachment.
396      * <p>
397      * Only library and variable classpath entries may have source attachments.
398      * For library classpath entries, the result path (if present) locates a source
399      * archive or folder. This archive or folder can be located in a project of the
400      * workspace or outside thr workspace. For variable classpath entries, the
401      * result path (if present) has an analogous form and meaning as the
402      * variable path, namely the first segment is the name of a classpath variable.
403      * </p>
404      *
405      * @return the path to the source archive or folder, or <code>null</code> if none
406      */
407     IPath getSourceAttachmentPath();
408
409     /**
410      * Returns the path within the source archive or folder where package fragments
411      * are located. An empty path indicates that packages are located at
412      * the root of the source archive or folder. Returns a non-<code>null</code> value
413      * if and only if {@link #getSourceAttachmentPath} returns
414      * a non-<code>null</code> value.
415      *
416      * @return the path within the source archive or folder, or <code>null</code> if
417      * not applicable
418      */
419     IPath getSourceAttachmentRootPath();
420     
421     /**
422      * Returns whether this entry is exported to dependent projects.
423      * Always returns <code>false</code> for source entries (kind
424      * {@link #CPE_SOURCE}), which cannot be exported.
425      *
426      * @return <code>true</code> if exported, and <code>false</code> otherwise
427      * @since 2.0
428      */
429     boolean isExported();
430     
431     /**
432      * This is a helper method, which returns the resolved classpath entry denoted
433      * by an entry (if it is a variable entry). It is obtained by resolving the variable
434      * reference in the first segment. Returns <code>null</code> if unable to resolve using
435      * the following algorithm:
436      * <ul>
437      * <li> if variable segment cannot be resolved, returns <code>null</code></li>
438      * <li> finds a project, JAR or binary folder in the workspace at the resolved path location</li>
439      * <li> if none finds an external JAR file or folder outside the workspace at the resolved path location </li>
440      * <li> if none returns <code>null</code></li>
441      * </ul>
442      * <p>
443      * Variable source attachment is also resolved and recorded in the resulting classpath entry.
444      * <p>
445      * @return the resolved library or project classpath entry, or <code>null</code>
446      * if the given path could not be resolved to a classpath entry
447      * <p>
448      * Note that this deprecated API doesn't handle CPE_CONTAINER entries.
449      *
450      * @deprecated Use {@link JavaCore#getResolvedClasspathEntry(IClasspathEntry)} instead
451      */
452     IClasspathEntry getResolvedEntry();
453 }
454
Popular Tags