net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IJavaProject.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  *     IBM Corporation - added getOption(String, boolean), getOptions(boolean) and setOptions(Map)
  11  *     IBM Corporation - deprecated getPackageFragmentRoots(IClasspathEntry) and
  12  *                               added findPackageFragmentRoots(IClasspathEntry)
  13  *     IBM Corporation - added isOnClasspath(IResource)
  14  *******************************************************************************/
  15 package net.sourceforge.phpdt.core;
  16
  17 import java.util.Map;
  18
  19 import org.eclipse.core.resources.IProject;
  20 import org.eclipse.core.resources.IResource;
  21 import org.eclipse.core.runtime.IPath;
  22 import org.eclipse.core.runtime.IProgressMonitor;
  23
  24 /**
  25  * A Java project represents a view of a project resource in terms of Java
  26  * elements such as package fragments, types, methods and fields. A project may
  27  * contain several package roots, which contain package fragments. A package
  28  * root corresponds to an underlying folder or JAR.
  29  * <p>
  30  * Each Java project has a classpath, defining which folders contain source code
  31  * and where required libraries are located. Each Java project also has an
  32  * output location, defining where the builder writes <code>.class</code>
  33  * files. A project that references packages in another project can access the
  34  * packages by including the required project in a classpath entry. The Java
  35  * model will present the source elements in the required project; when
  36  * building, the compiler will use the corresponding generated class files from
  37  * the required project's output location(s)). The classpath format is a
  38  * sequence of classpath entries describing the location and contents of package
  39  * fragment roots.
  40  * </p>
  41  * Java project elements need to be opened before they can be navigated or
  42  * manipulated. The children of a Java project are the package fragment roots
  43  * that are defined by the classpath and contained in this project (in other
  44  * words, it does not include package fragment roots for other projects).
  45  * </p>
  46  * <p>
  47  * This interface is not intended to be implemented by clients. An instance of
  48  * one of these handles can be created via <code>JavaCore.create(project)</code>.
  49  * </p>
  50  *
  51  * @see JavaCore#create(org.eclipse.core.resources.IProject)
  52  * @see IClasspathEntry
  53  */
  54 public interface IJavaProject extends IParent, IJavaElement, IOpenable {
  55
  56         /**
  57          * Returns the <code>IJavaElement</code> corresponding to the given
  58          * classpath-relative path, or <code>null</code> if no such
  59          * <code>IJavaElement</code> is found. The result is one of an
  60          * <code>ICompilationUnit</code>, <code>IClassFile</code>, or
  61          * <code>IPackageFragment</code>.
  62          * <p>
  63          * When looking for a package fragment, there might be several potential
  64          * matches; only one of them is returned.
  65          *
  66          * <p>
  67          * For example, the path "java/lang/Object.java", would result in the
  68          * <code>ICompilationUnit</code> or <code>IClassFile</code>
  69          * corresponding to "java.lang.Object". The path "java/lang" would result in
  70          * the <code>IPackageFragment</code> for "java.lang".
  71          *
  72          * @param path
  73          *            the given classpath-relative path
  74          * @exception JavaModelException
  75          *                if the given path is <code>null</code> or absolute
  76          * @return the <code>IJavaElement</code> corresponding to the given
  77          *         classpath-relative path, or <code>null</code> if no such
  78          *         <code>IJavaElement</code> is found
  79          */
  80         IJavaElement findElement(IPath path) throws JavaModelException;
  81
  82         /**
  83          * Returns the first existing package fragment on this project's classpath
  84          * whose path matches the given (absolute) path, or <code>null</code> if
  85          * none exist. The path can be: - internal to the workbench: "/Project/src" -
  86          * external to the workbench: "c:/jdk/classes.zip/java/lang"
  87          *
  88          * @param path
  89          *            the given absolute path
  90          * @exception JavaModelException
  91          *                if this element does not exist or if an exception occurs
  92          *                while accessing its corresponding resource
  93          * @return the first existing package fragment on this project's classpath
  94          *         whose path matches the given (absolute) path, or
  95          *         <code>null</code> if none exist
  96          */
  97         // IPackageFragment findPackageFragment(IPath path) throws
  98         // JavaModelException;
  99         /**
 100          * Returns the existing package fragment root on this project's classpath
 101          * whose path matches the given (absolute) path, or <code>null</code> if
 102          * one does not exist. The path can be: - internal to the workbench:
 103          * "/Compiler/src" - external to the workbench: "c:/jdk/classes.zip"
 104          *
 105          * @param path
 106          *            the given absolute path
 107          * @exception JavaModelException
 108          *                if this element does not exist or if an exception occurs
 109          *                while accessing its corresponding resource
 110          * @return the existing package fragment root on this project's classpath
 111          *         whose path matches the given (absolute) path, or
 112          *         <code>null</code> if one does not exist
 113          */
 114         IPackageFragmentRoot findPackageFragmentRoot(IPath path)
 115                         throws JavaModelException;
 116
 117         /**
 118          * Returns the existing package fragment roots identified by the given
 119          * entry. Note that a classpath entry that refers to another project may
 120          * have more than one root (if that project has more than on root containing
 121          * source), and classpath entries within the current project identify a
 122          * single root.
 123          * <p>
 124          * If the classpath entry denotes a variable, it will be resolved and return
 125          * the roots of the target entry (empty if not resolvable).
 126          * <p>
 127          * If the classpath entry denotes a container, it will be resolved and
 128          * return the roots corresponding to the set of container entries (empty if
 129          * not resolvable).
 130          *
 131          * @param entry
 132          *            the given entry
 133          * @return the existing package fragment roots identified by the given entry
 134          * @see IClasspathContainer
 135          * @since 2.1
 136          */
 137         IPackageFragmentRoot[] findPackageFragmentRoots(IClasspathEntry entry);
 138
 139         /**
 140          * Returns the first type found following this project's classpath with the
 141          * given fully qualified name or <code>null</code> if none is found. The
 142          * fully qualified name is a dot-separated name. For example, a class B
 143          * defined as a member type of a class A in package x.y should have a the
 144          * fully qualified name "x.y.A.B".
 145          *
 146          * Note that in order to be found, a type name (or its toplevel enclosing
 147          * type name) must match its corresponding compilation unit name. As a
 148          * consequence, secondary types cannot be found using this functionality.
 149          * Secondary types can however be explicitely accessed through their
 150          * enclosing unit or found by the <code>SearchEngine</code>.
 151          *
 152          * @param fullyQualifiedName
 153          *            the given fully qualified name
 154          * @exception JavaModelException
 155          *                if this element does not exist or if an exception occurs
 156          *                while accessing its corresponding resource
 157          * @return the first type found following this project's classpath with the
 158          *         given fully qualified name or <code>null</code> if none is
 159          *         found
 160          * @see IType#getFullyQualifiedName(char)
 161          * @since 2.0
 162          */
 163         // IType findType(String fullyQualifiedName) throws JavaModelException;
 164         /**
 165          * Returns the first type found following this project's classpath with the
 166          * given package name and type qualified name or <code>null</code> if none
 167          * is found. The package name is a dot-separated name. The type qualified
 168          * name is also a dot-separated name. For example, a class B defined as a
 169          * member type of a class A should have the type qualified name "A.B".
 170          *
 171          * Note that in order to be found, a type name (or its toplevel enclosing
 172          * type name) must match its corresponding compilation unit name. As a
 173          * consequence, secondary types cannot be found using this functionality.
 174          * Secondary types can however be explicitely accessed through their
 175          * enclosing unit or found by the <code>SearchEngine</code>.
 176          *
 177          * @param packageName
 178          *            the given package name
 179          * @param typeQualifiedName
 180          *            the given type qualified name
 181          * @exception JavaModelException
 182          *                if this element does not exist or if an exception occurs
 183          *                while accessing its corresponding resource
 184          * @return the first type found following this project's classpath with the
 185          *         given package name and type qualified name or <code>null</code>
 186          *         if none is found
 187          * @see IType#getTypeQualifiedName(char)
 188          *
 189          * @since 2.0
 190          */
 191         // IType findType(String packageName, String typeQualifiedName) throws
 192         // JavaModelException;
 193         /**
 194          * Returns all of the existing package fragment roots that exist on the
 195          * classpath, in the order they are defined by the classpath.
 196          *
 197          * @return all of the existing package fragment roots that exist on the
 198          *         classpath
 199          * @exception JavaModelException
 200          *                if this element does not exist or if an exception occurs
 201          *                while accessing its corresponding resource
 202          */
 203         IPackageFragmentRoot[] getAllPackageFragmentRoots()
 204                         throws JavaModelException;
 205
 206         /**
 207          * Returns an array of non-Java resources directly contained in this
 208          * project. It does not transitively answer non-Java resources contained in
 209          * folders; these would have to be explicitly iterated over.
 210          * <p>
 211          * Non-Java resources includes other files and folders located in the
 212          * project not accounted for by any of it source or binary package fragment
 213          * roots. If the project is a source folder itself, resources excluded from
 214          * the corresponding source classpath entry by one or more exclusion
 215          * patterns are considered non-Java resources and will appear in the result
 216          * (possibly in a folder)
 217          * </p>
 218          *
 219          * @return an array of non-Java resources directly contained in this project
 220          * @exception JavaModelException
 221          *                if this element does not exist or if an exception occurs
 222          *                while accessing its corresponding resource
 223          */
 224         // Object[] getNonJavaResources() throws JavaModelException;
 225         /**
 226          * Helper method for returning one option value only. Equivalent to
 227          * <code>(String)this.getOptions(inheritJavaCoreOptions).get(optionName)</code>
 228          * Note that it may answer <code>null</code> if this option does not
 229          * exist, or if there is no custom value for it.
 230          * <p>
 231          * For a complete description of the configurable options, see
 232          * <code>JavaCore#getDefaultOptions</code>.
 233          * </p>
 234          *
 235          * @param optionName
 236          *            the name of an option
 237          * @param inheritJavaCoreOptions -
 238          *            boolean indicating whether JavaCore options should be
 239          *            inherited as well
 240          * @return the String value of a given option
 241          * @see JavaCore#getDefaultOptions
 242          * @since 2.1
 243          */
 244         String getOption(String optionName, boolean inheritJavaCoreOptions);
 245
 246         /**
 247          * Returns the table of the current custom options for this project.
 248          * Projects remember their custom options, in other words, only the options
 249          * different from the the JavaCore global options for the workspace. A
 250          * boolean argument allows to directly merge the project options with global
 251          * ones from <code>JavaCore</code>.
 252          * <p>
 253          * For a complete description of the configurable options, see
 254          * <code>JavaCore#getDefaultOptions</code>.
 255          * </p>
 256          *
 257          * @param inheritJavaCoreOptions -
 258          *            boolean indicating whether JavaCore options should be
 259          *            inherited as well
 260          * @return table of current settings of all options (key type:
 261          *         <code>String</code>; value type: <code>String</code>)
 262          * @see JavaCore#getDefaultOptions
 263          * @since 2.1
 264          */
 265         Map getOptions(boolean inheritJavaCoreOptions);
 266
 267         /**
 268          * Returns the default output location for this project as a workspace-
 269          * relative absolute path.
 270          * <p>
 271          * The default output location is where class files are ordinarily generated
 272          * (and resource files, copied). Each source classpath entry can also
 273          * specify an output location for the generated class files (and copied
 274          * resource files) corresponding to compilation units under that source
 275          * folder. This makes it possible to arrange generated class files for
 276          * different source folders in different output folders, and not necessarily
 277          * the default output folder. This means that the generated class files for
 278          * the project may end up scattered across several folders, rather than all
 279          * in the default output folder (which is more standard).
 280          * </p>
 281          *
 282          * @return the workspace-relative absolute path of the default output folder
 283          * @exception JavaModelException
 284          *                if this element does not exist
 285          * @see #setOutputLocation
 286          * @see IClasspathEntry#getOutputLocation
 287          */
 288         IPath getOutputLocation() throws JavaModelException;
 289
 290         /**
 291          * Returns a package fragment root for the JAR at the specified file system
 292          * path. This is a handle-only method. The underlying
 293          * <code>java.io.File</code> may or may not exist. No resource is
 294          * associated with this local JAR package fragment root.
 295          *
 296          * @param jarPath
 297          *            the jars's file system path
 298          * @return a package fragment root for the JAR at the specified file system
 299          *         path
 300          */
 301         // IPackageFragmentRoot getPackageFragmentRoot(String jarPath);
 302         /**
 303          * Returns a package fragment root for the given resource, which must either
 304          * be a folder representing the top of a package hierarchy, or a
 305          * <code>.jar</code> or <code>.zip</code> file. This is a handle-only
 306          * method. The underlying resource may or may not exist.
 307          *
 308          * @param resource
 309          *            the given resource
 310          * @return a package fragment root for the given resource, which must either
 311          *         be a folder representing the top of a package hierarchy, or a
 312          *         <code>.jar</code> or <code>.zip</code> file
 313          */
 314         IPackageFragmentRoot getPackageFragmentRoot(IResource resource);
 315
 316         /**
 317          * Returns all of the package fragment roots contained in this project,
 318          * identified on this project's resolved classpath. The result does not
 319          * include package fragment roots in other projects referenced on this
 320          * project's classpath.
 321          *
 322          * <p>
 323          * NOTE: This is equivalent to <code>getChildren()</code>.
 324          *
 325          * @return all of the package fragment roots contained in this project,
 326          *         identified on this project's resolved classpath
 327          * @exception JavaModelException
 328          *                if this element does not exist or if an exception occurs
 329          *                while accessing its corresponding resource
 330          */
 331         IPackageFragmentRoot[] getPackageFragmentRoots() throws JavaModelException;
 332
 333         /**
 334          * Returns the existing package fragment roots identified by the given
 335          * entry. Note that a classpath entry that refers to another project may
 336          * have more than one root (if that project has more than on root containing
 337          * source), and classpath entries within the current project identify a
 338          * single root.
 339          * <p>
 340          * If the classpath entry denotes a variable, it will be resolved and return
 341          * the roots of the target entry (empty if not resolvable).
 342          * <p>
 343          * If the classpath entry denotes a container, it will be resolved and
 344          * return the roots corresponding to the set of container entries (empty if
 345          * not resolvable).
 346          *
 347          * @param entry
 348          *            the given entry
 349          * @return the existing package fragment roots identified by the given entry
 350          * @see IClasspathContainer
 351          * @deprecated Use IJavaProject#findPackageFragmentRoots instead
 352          */
 353         IPackageFragmentRoot[] getPackageFragmentRoots(IClasspathEntry entry);
 354
 355         /**
 356          * Returns all package fragments in all package fragment roots contained in
 357          * this project. This is a convenience method.
 358          *
 359          * Note that the package fragment roots corresponds to the resolved
 360          * classpath of the project.
 361          *
 362          * @return all package fragments in all package fragment roots contained in
 363          *         this project
 364          * @exception JavaModelException
 365          *                if this element does not exist or if an exception occurs
 366          *                while accessing its corresponding resource
 367          */
 368         IPackageFragment[] getPackageFragments() throws JavaModelException;
 369
 370         /**
 371          * Returns the <code>IProject</code> on which this
 372          * <code>IJavaProject</code> was created. This is handle-only method.
 373          *
 374          * @return the <code>IProject</code> on which this
 375          *         <code>IJavaProject</code> was created
 376          */
 377         IProject getProject();
 378
 379         /**
 380          * Returns the raw classpath for the project, as a list of classpath
 381          * entries. This corresponds to the exact set of entries which were assigned
 382          * using <code>setRawClasspath</code>, in particular such a classpath may
 383          * contain classpath variable entries. Classpath variable entries can be
 384          * resolved individually (see <code>JavaCore#getClasspathVariable</code>),
 385          * or the full classpath can be resolved at once using the helper method
 386          * <code>getResolvedClasspath</code>.
 387          * <p>
 388          * A classpath variable provides an indirection level for better sharing a
 389          * classpath. As an example, it allows a classpath to no longer refer
 390          * directly to external JARs located in some user specific location. The
 391          * classpath can simply refer to some variables defining the proper
 392          * locations of these external JARs.
 393          * <p>
 394          * Note that in case the project isn't yet opened, the classpath will
 395          * directly be read from the associated <tt>.classpath</tt> file.
 396          * <p>
 397          *
 398          * @return the raw classpath for the project, as a list of classpath entries
 399          * @exception JavaModelException
 400          *                if this element does not exist or if an exception occurs
 401          *                while accessing its corresponding resource
 402          * @see IClasspathEntry
 403          */
 404         IClasspathEntry[] getRawClasspath() throws JavaModelException;
 405
 406         /**
 407          * Returns the names of the projects that are directly required by this
 408          * project. A project is required if it is in its classpath.
 409          * <p>
 410          * The project names are returned in the order they appear on the classpath.
 411          *
 412          * @return the names of the projects that are directly required by this
 413          *         project in classpath order
 414          * @exception JavaModelException
 415          *                if this element does not exist or if an exception occurs
 416          *                while accessing its corresponding resource
 417          */
 418         String[] getRequiredProjectNames() throws JavaModelException;
 419
 420         /**
 421          * This is a helper method returning the resolved classpath for the project
 422          * as a list of simple (non-variable, non-container) classpath entries. All
 423          * classpath variable and classpath container entries in the project's raw
 424          * classpath will be replaced by the simple classpath entries they resolve
 425          * to.
 426          * <p>
 427          * The resulting resolved classpath is accurate for the given point in time.
 428          * If the project's raw classpath is later modified, or if classpath
 429          * variables are changed, the resolved classpath can become out of date.
 430          * Because of this, hanging on resolved classpath is not recommended.
 431          * </p>
 432          *
 433          * @param ignoreUnresolvedEntry
 434          *            indicates how to handle unresolvable variables and containers;
 435          *            <code>true</code> indicates that missing variables and
 436          *            unresolvable classpath containers should be silently ignored,
 437          *            and that the resulting list should consist only of the entries
 438          *            that could be successfully resolved; <code>false</code>
 439          *            indicates that a <code>JavaModelException</code> should be
 440          *            thrown for the first unresolved variable or container
 441          * @return the resolved classpath for the project as a list of simple
 442          *         classpath entries, where all classpath variable and container
 443          *         entries have been resolved and substituted with their final
 444          *         target entries
 445          * @exception JavaModelException
 446          *                in one of the corresponding situation:
 447          *                <ul>
 448          *                <li>this element does not exist</li>
 449          *                <li>an exception occurs while accessing its corresponding
 450          *                resource</li>
 451          *                <li>a classpath variable or classpath container was not
 452          *                resolvable and <code>ignoreUnresolvedEntry</code> is
 453          *                <code>false</code>.</li>
 454          *                </ul>
 455          * @see IClasspathEntry
 456          */
 457         IClasspathEntry[] getResolvedClasspath(boolean ignoreUnresolvedEntry)
 458                         throws JavaModelException;
 459
 460         /**
 461          * Returns whether this project has been built at least once and thus
 462          * whether it has a build state.
 463          *
 464          * @return true if this project has been built at least once, false
 465          *         otherwise
 466          */
 467         boolean hasBuildState();
 468
 469         /**
 470          * Returns whether setting this project's classpath to the given classpath
 471          * entries would result in a cycle.
 472          *
 473          * If the set of entries contains some variables, those are resolved in
 474          * order to determine cycles.
 475          *
 476          * @param entries
 477          *            the given classpath entries
 478          * @return true if the given classpath entries would result in a cycle,
 479          *         false otherwise
 480          */
 481         boolean hasClasspathCycle(IClasspathEntry[] entries);
 482
 483         /**
 484          * Returns whether the given element is on the classpath of this project,
 485          * that is, referenced from a classpath entry and not explicitly excluded
 486          * using an exclusion pattern.
 487          *
 488          * @param element
 489          *            the given element
 490          * @return <code>true</code> if the given element is on the classpath of
 491          *         this project, <code>false</code> otherwise
 492          * @see IClasspathEntry#getExclusionPatterns
 493          * @since 2.0
 494          */
 495         // boolean isOnClasspath(IJavaElement element);
 496         /**
 497          * Returns whether the given resource is on the classpath of this project,
 498          * that is, referenced from a classpath entry and not explicitly excluded
 499          * using an exclusion pattern.
 500          *
 501          * @param element
 502          *            the given element
 503          * @return <code>true</code> if the given resource is on the classpath of
 504          *         this project, <code>false</code> otherwise
 505          * @see IClasspathEntry#getExclusionPatterns
 506          * @since 2.1
 507          */
 508         // boolean isOnClasspath(IResource resource);
 509         /**
 510          * Creates a new evaluation context.
 511          *
 512          * @return a new evaluation context.
 513          */
 514         // IEvaluationContext newEvaluationContext();
 515         /**
 516          * Creates and returns a type hierarchy for all types in the given region,
 517          * considering subtypes within that region.
 518          *
 519          * @param monitor
 520          *            the given progress monitor
 521          * @param region
 522          *            the given region
 523          * @exception JavaModelException
 524          *                if this element does not exist or if an exception occurs
 525          *                while accessing its corresponding resource
 526          * @exception IllegalArgumentException
 527          *                if region is <code>null</code>
 528          * @return a type hierarchy for all types in the given region, considering
 529          *         subtypes within that region
 530          */
 531         // ITypeHierarchy newTypeHierarchy(IRegion region, IProgressMonitor monitor)
 532         // throws JavaModelException;
 533         /**
 534          * Creates and returns a type hierarchy for the given type considering
 535          * subtypes in the specified region.
 536          *
 537          * @param monitor
 538          *            the given monitor
 539          * @param region
 540          *            the given region
 541          * @param type
 542          *            the given type
 543          *
 544          * @exception JavaModelException
 545          *                if this element does not exist or if an exception occurs
 546          *                while accessing its corresponding resource
 547          *
 548          * @exception IllegalArgumentException
 549          *                if type or region is <code>null</code>
 550          * @return a type hierarchy for the given type considering subtypes in the
 551          *         specified region
 552          */
 553         // ITypeHierarchy newTypeHierarchy(
 554         // IType type,
 555         // IRegion region,
 556         // IProgressMonitor monitor)
 557         // throws JavaModelException;
 558         /**
 559          * Sets the project custom options. All and only the options explicitly
 560          * included in the given table are remembered; all previous option settings
 561          * are forgotten, including ones not explicitly mentioned.
 562          * <p>
 563          * For a complete description of the configurable options, see
 564          * <code>JavaCore#getDefaultOptions</code>.
 565          * </p>
 566          *
 567          * @param newOptions
 568          *            the new options (key type: <code>String</code>; value type:
 569          *            <code>String</code>), or <code>null</code> to flush all
 570          *            custom options (clients will automatically get the global
 571          *            JavaCore options).
 572          * @see JavaCore#getDefaultOptions
 573          * @since 2.1
 574          */
 575         void setOptions(Map newOptions);
 576
 577         /**
 578          * Sets the default output location of this project to the location
 579          * described by the given workspace-relative absolute path.
 580          * <p>
 581          * The default output location is where class files are ordinarily generated
 582          * (and resource files, copied). Each source classpath entries can also
 583          * specify an output location for the generated class files (and copied
 584          * resource files) corresponding to compilation units under that source
 585          * folder. This makes it possible to arrange that generated class files for
 586          * different source folders to end up in different output folders, and not
 587          * necessarily the default output folder. This means that the generated
 588          * class files for the project may end up scattered across several folders,
 589          * rather than all in the default output folder (which is more standard).
 590          * </p>
 591          *
 592          * @param path
 593          *            the workspace-relative absolute path of the default output
 594          *            folder
 595          * @param monitor
 596          *            the progress monitor
 597          *
 598          * @exception JavaModelException
 599          *                if the classpath could not be set. Reasons include:
 600          *                <ul>
 601          *                <li> This Java element does not exist
 602          *                (ELEMENT_DOES_NOT_EXIST)</li>
 603          *                <li> The path refers to a location not contained in this
 604          *                project (<code>PATH_OUTSIDE_PROJECT</code>)
 605          *                <li> The path is not an absolute path (<code>RELATIVE_PATH</code>)
 606          *                <li> The path is nested inside a package fragment root of
 607          *                this project (<code>INVALID_PATH</code>)
 608          *                <li> The output location is being modified during resource
 609          *                change event notification (CORE_EXCEPTION)
 610          *                </ul>
 611          * @see #getOutputLocation
 612          * @see IClasspathEntry#getOutputLocation
 613          */
 614         void setOutputLocation(IPath path, IProgressMonitor monitor)
 615                         throws JavaModelException;
 616
 617         /**
 618          * Sets the classpath of this project using a list of classpath entries. In
 619          * particular such a classpath may contain classpath variable entries.
 620          * Classpath variable entries can be resolved individually (see
 621          * <code>JavaCore#getClasspathVariable</code>), or the full classpath can
 622          * be resolved at once using the helper method
 623          * <code>getResolvedClasspath</code>.
 624          * <p>
 625          * A classpath variable provides an indirection level for better sharing a
 626          * classpath. As an example, it allows a classpath to no longer refer
 627          * directly to external JARs located in some user specific location. The
 628          * classpath can simply refer to some variables defining the proper
 629          * locations of these external JARs.
 630          * <p>
 631          * Setting the classpath to <code>null</code> specifies a default
 632          * classpath (the project root). Setting the classpath to an empty array
 633          * specifies an empty classpath.
 634          * <p>
 635          * If a cycle is detected while setting this classpath, an error marker will
 636          * be added to the project closing the cycle. To avoid this problem, use
 637          * <code>hasClasspathCycle(IClasspathEntry[] entries)</code> before
 638          * setting the classpath.
 639          *
 640          * @param entries
 641          *            a list of classpath entries
 642          * @param monitor
 643          *            the given progress monitor
 644          * @exception JavaModelException
 645          *                if the classpath could not be set. Reasons include:
 646          *                <ul>
 647          *                <li> This Java element does not exist
 648          *                (ELEMENT_DOES_NOT_EXIST)</li>
 649          *                <li> The classpath is being modified during resource
 650          *                change event notification (CORE_EXCEPTION)
 651          *                <li> The classpath failed the validation check as defined
 652          *                by <code>JavaConventions#validateClasspath</code>
 653          *                </ul>
 654          * @see IClasspathEntry
 655          */
 656         void setRawClasspath(IClasspathEntry[] entries, IProgressMonitor monitor)
 657                         throws JavaModelException;
 658
 659         /**
 660          * Sets the both the classpath of this project and its default output
 661          * location at once. The classpath is defined using a list of classpath
 662          * entries. In particular, such a classpath may contain classpath variable
 663          * entries. Classpath variable entries can be resolved individually (see
 664          * <code>JavaCore#getClasspathVariable</code>), or the full classpath can
 665          * be resolved at once using the helper method
 666          * <code>getResolvedClasspath</code>.
 667          * <p>
 668          * A classpath variable provides an indirection level for better sharing a
 669          * classpath. As an example, it allows a classpath to no longer refer
 670          * directly to external JARs located in some user specific location. The
 671          * classpath can simply refer to some variables defining the proper
 672          * locations of these external JARs.
 673          * </p>
 674          * <p>
 675          * Setting the classpath to <code>null</code> specifies a default
 676          * classpath (the project root). Setting the classpath to an empty array
 677          * specifies an empty classpath.
 678          * </p>
 679          * <p>
 680          * If a cycle is detected while setting this classpath, an error marker will
 681          * be added to the project closing the cycle. To avoid this problem, use
 682          * <code>hasClasspathCycle(IClasspathEntry[] entries)</code> before
 683          * setting the classpath.
 684          * </p>
 685          *
 686          * @param entries
 687          *            a list of classpath entries
 688          * @param monitor
 689          *            the progress monitor
 690          * @param outputLocation
 691          *            the default output location
 692          * @exception JavaModelException
 693          *                if the classpath could not be set. Reasons include:
 694          *                <ul>
 695          *                <li> This Java element does not exist
 696          *                (ELEMENT_DOES_NOT_EXIST)</li>
 697          *                <li> Two or more entries specify source roots with the
 698          *                same or overlapping paths (NAME_COLLISION)
 699          *                <li> A entry of kind <code>CPE_PROJECT</code> refers to
 700          *                this project (INVALID_PATH)
 701          *                <li>This Java element does not exist
 702          *                (ELEMENT_DOES_NOT_EXIST)</li>
 703          *                <li>The output location path refers to a location not
 704          *                contained in this project (<code>PATH_OUTSIDE_PROJECT</code>)
 705          *                <li>The output location path is not an absolute path (<code>RELATIVE_PATH</code>)
 706          *                <li>The output location path is nested inside a package
 707          *                fragment root of this project (<code>INVALID_PATH</code>)
 708          *                <li> The classpath is being modified during resource
 709          *                change event notification (CORE_EXCEPTION)
 710          *                </ul>
 711          * @see IClasspathEntry
 712          * @since 2.0
 713          */
 714         void setRawClasspath(IClasspathEntry[] entries, IPath outputLocation,
 715                         IProgressMonitor monitor) throws JavaModelException;
 716 }