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