001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jdt.core;
011:
012: import org.eclipse.core.runtime.IPath;
013:
014: /**
015: * An entry on a Java project classpath identifying one or more package fragment
016: * roots. A classpath entry has a content kind (either source,
017: * {@link IPackageFragmentRoot#K_SOURCE}, or binary, {@link IPackageFragmentRoot#K_BINARY}), which is inherited
018: * by each package fragment root and package fragment associated with the entry.
019: * <p>
020: * A classpath entry can refer to any of the following:<ul>
021: *
022: * <li>Source code in the current project. In this case, the entry identifies a
023: * root folder in the current project containing package fragments and
024: * source files with one of the {@link JavaCore#getJavaLikeExtensions()
025: * Java-like extensions}. The root folder itself represents a default
026: * package, subfolders represent package fragments, and files with a
027: * Java-like extension (e.g. <code>.java</code> files)
028: * represent compilation units. All compilation units will be compiled when
029: * the project is built. The classpath entry must specify the
030: * absolute path to the root folder. Entries of this kind are
031: * associated with the {@link #CPE_SOURCE} constant.
032: * Source classpath entries can carry inclusion and exclusion patterns for
033: * selecting which source files appear as compilation
034: * units and get compiled when the project is built.
035: * </li>
036: *
037: * <li>A binary library in the current project, in another project, or in the external
038: * file system. In this case the entry identifies a JAR (or root folder) containing
039: * package fragments and <code>.class</code> files. The classpath entry
040: * must specify the absolute path to the JAR (or root folder), and in case it refers
041: * to an external JAR, then there is no associated resource in the workbench. Entries
042: * of this kind are associated with the {@link #CPE_LIBRARY} constant.</li>
043: *
044: * <li>A required project. In this case the entry identifies another project in
045: * the workspace. The required project is used as a binary library when compiling
046: * (that is, the builder looks in the output location of the required project
047: * for required <code>.class</code> files when building). When performing other
048: * "development" operations - such as code assist, code resolve, type hierarchy
049: * creation, etc. - the source code of the project is referred to. Thus, development
050: * is performed against a required project's source code, and compilation is
051: * performed against a required project's last built state. The
052: * classpath entry must specify the absolute path to the
053: * project. Entries of this kind are associated with the {@link #CPE_PROJECT}
054: * constant.
055: * Note: referencing a required project with a classpath entry refers to the source
056: * code or associated <code>.class</code> files located in its output location.
057: * It will also automatically include any other libraries or projects that the required project's classpath
058: * refers to, iff the corresponding classpath entries are tagged as being exported
059: * ({@link IClasspathEntry#isExported}).
060: * Unless exporting some classpath entries, classpaths are not chained by default -
061: * each project must specify its own classpath in its entirety.</li>
062: *
063: * <li> A path beginning in a classpath variable defined globally to the workspace.
064: * Entries of this kind are associated with the {@link #CPE_VARIABLE} constant.
065: * Classpath variables are created using {@link JavaCore#setClasspathVariable(String, IPath, org.eclipse.core.runtime.IProgressMonitor)},
066: * and gets resolved, to either a project or library entry, using
067: * {@link JavaCore#getResolvedClasspathEntry(IClasspathEntry)}.
068: * It is also possible to register an automatic initializer ({@link ClasspathVariableInitializer}),
069: * which will be invoked through the extension point "org.eclipse.jdt.core.classpathVariableInitializer".
070: * After resolution, a classpath variable entry may either correspond to a project or a library entry. </li>
071: *
072: * <li> A named classpath container identified by its container path.
073: * A classpath container provides a way to indirectly reference a set of classpath entries through
074: * a classpath entry of kind {@link #CPE_CONTAINER}. Typically, a classpath container can
075: * be used to describe a complex library composed of multiple JARs, projects or classpath variables,
076: * considering also that containers can be mapped differently on each project. Several projects can
077: * reference the same generic container path, but have each of them actually bound to a different
078: * container object.
079: * The container path is a formed by a first ID segment followed with extra segments,
080: * which can be used as additional hints for resolving this container reference. If no container was ever
081: * recorded for this container path onto this project (using {@link JavaCore#setClasspathContainer},
082: * then a {@link ClasspathContainerInitializer} will be activated if any was registered for this
083: * container ID onto the extension point "org.eclipse.jdt.core.classpathContainerInitializer".
084: * A classpath container entry can be resolved explicitly using {@link JavaCore#getClasspathContainer}
085: * and the resulting container entries can contain any non-container entry. In particular, it may contain variable
086: * entries, which in turn needs to be resolved before being directly used.
087: * <br> Also note that the container resolution APIs include an IJavaProject argument, so as to allow the same
088: * container path to be interpreted in different ways for different projects. </li>
089: * </ul>
090: * </p>
091: * The result of {@link IJavaProject#getResolvedClasspath} will have all entries of type
092: * {@link #CPE_VARIABLE} and {@link #CPE_CONTAINER} resolved to a set of
093: * {@link #CPE_SOURCE}, {@link #CPE_LIBRARY} or {@link #CPE_PROJECT}
094: * classpath entries.
095: * <p>
096: * Any classpath entry other than a source folder (kind {@link #CPE_SOURCE}) can
097: * be marked as being exported. Exported entries are automatically contributed to
098: * dependent projects, along with the project's default output folder, which is
099: * implicitly exported, and any auxiliary output folders specified on source
100: * classpath entries. The project's output folder(s) are always listed first,
101: * followed by the any exported entries.
102: * <p>
103: * This interface is not intended to be implemented by clients.
104: * Classpath entries can be created via methods on {@link JavaCore}.
105: * </p>
106: *
107: * @see JavaCore#newLibraryEntry(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath)
108: * @see JavaCore#newProjectEntry(org.eclipse.core.runtime.IPath)
109: * @see JavaCore#newSourceEntry(org.eclipse.core.runtime.IPath)
110: * @see JavaCore#newVariableEntry(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath)
111: * @see JavaCore#newContainerEntry(org.eclipse.core.runtime.IPath)
112: * @see ClasspathVariableInitializer
113: * @see ClasspathContainerInitializer
114: */
115: public interface IClasspathEntry {
116:
117: /**
118: * Entry kind constant describing a classpath entry identifying a
119: * library. A library is a folder or JAR containing package
120: * fragments consisting of pre-compiled binaries.
121: */
122: int CPE_LIBRARY = 1;
123:
124: /**
125: * Entry kind constant describing a classpath entry identifying a
126: * required project.
127: */
128: int CPE_PROJECT = 2;
129:
130: /**
131: * Entry kind constant describing a classpath entry identifying a
132: * folder containing package fragments with source code
133: * to be compiled.
134: */
135: int CPE_SOURCE = 3;
136:
137: /**
138: * Entry kind constant describing a classpath entry defined using
139: * a path that begins with a classpath variable reference.
140: */
141: int CPE_VARIABLE = 4;
142:
143: /**
144: * Entry kind constant describing a classpath entry representing
145: * a name classpath container.
146: *
147: * @since 2.0
148: */
149: int CPE_CONTAINER = 5;
150:
151: /**
152: * Returns whether the access rules of the project's exported entries should be combined with this entry's access rules.
153: * Returns true for container entries.
154: * Returns false otherwise.
155: *
156: * @return whether the access rules of the project's exported entries should be combined with this entry's access rules
157: * @since 3.1
158: */
159: boolean combineAccessRules();
160:
161: /**
162: * Returns the possibly empty list of access rules for this entry.
163: *
164: * @return the possibly empty list of access rules for this entry
165: * @since 3.1
166: */
167: IAccessRule[] getAccessRules();
168:
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/**</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/**</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/*</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>**/tests/**</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>**</code>.
315: * </p>
316: * <p>
317: * Example patterns in source entries:
318: * <ul>
319: * <li>
320: * The inclusion pattern <code>src/**</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/**</code> and
325: * <code>tests/**</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/**</code> together with the
330: * exclusion pattern <code>src/**/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: }
|