net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IClasspathEntry.java

   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
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.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  * <code>K_SOURCE</code>, or binary, <code>K_BINARY</code>), which is
  19  * inherited by each package fragment root and package fragment associated with
  20  * the entry.
  21  * <p>
  22  * A classpath entry can refer to any of the following:
  23  * <ul>
  24  *
  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>
  36  *
  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>
  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
  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>
  63  *
  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
  74  * entry. </li>
  75  *
  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
  95  * used. <br>
  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>
  99  * </ul>
 100  * </p>
 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.
 105  * <p>
 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.
 112  * <p>
 113  * This interface is not intended to be implemented by clients. Classpath
 114  * entries can be created via methods on <code>JavaCore</code>.
 115  * </p>
 116  *
 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
 124  */
 125 public interface IClasspathEntry {
 126
 127         /**
 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.
 131          */
 132         int CPE_LIBRARY = 1;
 133
 134         /**
 135          * Entry kind constant describing a classpath entry identifying a required
 136          * project.
 137          */
 138         int CPE_PROJECT = 2;
 139
 140         /**
 141          * Entry kind constant describing a classpath entry identifying a folder
 142          * containing package fragments with source code to be compiled.
 143          */
 144         int CPE_SOURCE = 3;
 145
 146         /**
 147          * Entry kind constant describing a classpath entry defined using a path
 148          * that begins with a classpath variable reference.
 149          */
 150         int CPE_VARIABLE = 4;
 151
 152         /**
 153          * Entry kind constant describing a classpath entry representing a name
 154          * classpath container.
 155          *
 156          * @since 2.0
 157          */
 158         int CPE_CONTAINER = 5;
 159
 160         /**
 161          * Returns the kind of files found in the package fragments identified by
 162          * this classpath entry.
 163          *
 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>).
 169          */
 170         int getContentKind();
 171
 172         /**
 173          * Returns the kind of this classpath entry.
 174          *
 175          * @return one of:
 176          *         <ul>
 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
 182          *         project
 183          *
 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
 186          * path *
 187          * <li><code>CPE_CONTAINER</code> - this entry describes set of entries
 188          * referenced indirectly via a classpath container
 189          * </ul>
 190          */
 191         int getEntryKind();
 192
 193         /**
 194          * Returns the set of patterns used to exclude resources associated with
 195          * this source entry.
 196          * <p>
 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.
 204          * </p>
 205          * <p>
 206          * Note that there is no need to supply a pattern to exclude ".class" files
 207          * because a source entry filters these out automatically.
 208          * </p>
 209          * <p>
 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.
 213          * </p>
 214          * <p>
 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>).
 219          * </p>
 220          * <p>
 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>).
 225          * </p>
 226          * <p>
 227          * Combinations of *'s and ?'s are allowed.
 228          * </p>
 229          * <p>
 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/&#42;&#42;</code>, and would match all files under the the
 233          * folder named <code>tests</code>.
 234          * </p>
 235          * <p>
 236          * Examples:
 237          * <ul>
 238          * <li> <code>tests/&#42;&#42;</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/&#42;</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>&#42;&#42;/tests/&#42;&#42;</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>
 256          * </ul>
 257          * </p>
 258          *
 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
 262          * @since 2.1
 263          */
 264         IPath[] getExclusionPatterns();
 265
 266         /**
 267          * Returns the set of patterns used to explicitly define resources to be
 268          * included with this source entry.
 269          * <p>
 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.
 281          * </p>
 282          * <p>
 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>&#42;&#42;</code>.
 287          * </p>
 288          * <p>
 289          * Examples:
 290          * <ul>
 291          * <li> The inclusion pattern <code>src/&#42;&#42;</code> by itself
 292          * includes all files under a root folder named <code>src</code>. </li>
 293          * <li> The inclusion patterns <code>src/&#42;&#42;</code> and
 294          * <code>tests/&#42;&#42;</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/&#42;&#42;</code> together with
 297          * the exclusion pattern <code>src/&#42;&#42;/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>
 300          * </ul>
 301          * </p>
 302          *
 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
 306          * @since 3.0
 307          */
 308         IPath[] getInclusionPatterns();
 309
 310         /**
 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>).
 314          * <p>
 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>).
 319          * </p>
 320          * <p>
 321          * NOTE: A specific output location cannot coincidate with another
 322          * source/library entry.
 323          * </p>
 324          *
 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
 328          * @since 2.1
 329          */
 330         IPath getOutputLocation();
 331
 332         /**
 333          * Returns the path of this classpath entry.
 334          *
 335          * The meaning of the path of a classpath entry depends on its entry kind:
 336          * <ul>
 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
 339          * folder. </li>
 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>
 357          * </ul>
 358          *
 359          * @return the path of this classpath entry
 360          */
 361         IPath getPath();
 362
 363         /**
 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
 366          * source attachment.
 367          * <p>
 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
 374          * variable.
 375          * </p>
 376          *
 377          * @return the path to the source archive or folder, or <code>null</code>
 378          *         if none
 379          */
 380         IPath getSourceAttachmentPath();
 381
 382         /**
 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.
 388          *
 389          * @return the path within the source archive or folder, or
 390          *         <code>null</code> if not applicable
 391          */
 392         IPath getSourceAttachmentRootPath();
 393
 394         /**
 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.
 398          *
 399          * @return <code>true</code> if exported, and <code>false</code>
 400          *         otherwise
 401          * @since 2.0
 402          */
 403         boolean isExported();
 404
 405         /**
 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:
 410          * <ul>
 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>
 417          * </ul>
 418          * <p>
 419          * Variable source attachment is also resolved and recorded in the resulting
 420          * classpath entry.
 421          * <p>
 422          *
 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
 425          *         <p>
 426          *         Note that this deprecated API doesn't handle CPE_CONTAINER
 427          *         entries.
 428          *
 429          * @deprecated - use JavaCore.getResolvedClasspathEntry(...)
 430          */
 431         IClasspathEntry getResolvedEntry();
 432 }