KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*******************************************************************************
2  * Copyright (c) 2000, 2007 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  * 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  * IBM Corporation - added setOption(String, String)
15  * IBM Corporation - added forceClasspathReload(IProgressMonitor)
16  *******************************************************************************/

17 package org.eclipse.jdt.core;
18
19 import java.util.Map JavaDoc;
20
21 import org.eclipse.core.resources.IProject;
22 import org.eclipse.core.resources.IResource;
23 import org.eclipse.core.runtime.IProgressMonitor;
24 import org.eclipse.core.runtime.IPath;
25
26 import org.eclipse.jdt.core.eval.IEvaluationContext;
27
28 /**
29  * A Java project represents a view of a project resource in terms of Java
30  * elements such as package fragments, types, methods and fields.
31  * A project may contain several package roots, which contain package fragments.
32  * A package root corresponds to an underlying folder or JAR.
33  * <p>
34  * Each Java project has a classpath, defining which folders contain source code and
35  * where required libraries are located. Each Java project also has an output location,
36  * defining where the builder writes <code>.class</code> files. A project that
37  * references packages in another project can access the packages by including
38  * the required project in a classpath entry. The Java model will present the
39  * source elements in the required project; when building, the compiler will use
40  * the corresponding generated class files from the required project's output
41  * location(s)). The classpath format is a sequence of classpath entries
42  * describing the location and contents of package fragment roots.
43  * </p>
44  * Java project elements need to be opened before they can be navigated or manipulated.
45  * The children of a Java project are the package fragment roots that are
46  * defined by the classpath and contained in this project (in other words, it
47  * does not include package fragment roots for other projects).
48  * </p>
49  * <p>
50  * This interface is not intended to be implemented by clients. An instance
51  * of one of these handles can be created via
52  * <code>JavaCore.create(project)</code>.
53  * </p>
54  *
55  * @see JavaCore#create(org.eclipse.core.resources.IProject)
56  * @see IClasspathEntry
57  */

58 public interface IJavaProject extends IParent, IJavaElement, IOpenable {
59
60     /**
61      * Decodes the classpath entry that has been encoded in the given string
62      * in the context of this project.
63      * Returns null if the encoded entry is malformed.
64      *
65      * @param encodedEntry the encoded classpath entry
66      * @return the decoded classpath entry, or <code>null</code> if unable to decode it
67      * @since 3.2
68      */

69     IClasspathEntry decodeClasspathEntry(String JavaDoc encodedEntry);
70     
71     /**
72      * Encodes the given classpath entry into a string in the context of this project.
73      *
74      * @param classpathEntry the classpath entry to encode
75      * @return the encoded classpath entry
76      * @since 3.2
77      */

78     String JavaDoc encodeClasspathEntry(IClasspathEntry classpathEntry);
79     
80     /**
81      * Returns the <code>IJavaElement</code> corresponding to the given
82      * classpath-relative path, or <code>null</code> if no such
83      * <code>IJavaElement</code> is found. The result is one of an
84      * <code>ICompilationUnit</code>, <code>IClassFile</code>, or
85      * <code>IPackageFragment</code>.
86      * <p>
87      * When looking for a package fragment, there might be several potential
88      * matches; only one of them is returned.
89      *
90      * <p>For example, the path "java/lang/Object.java", would result in the
91      * <code>ICompilationUnit</code> or <code>IClassFile</code> corresponding to
92      * "java.lang.Object". The path "java/lang" would result in the
93      * <code>IPackageFragment</code> for "java.lang".
94      * @param path the given classpath-relative path
95      * @exception JavaModelException if the given path is <code>null</code>
96      * or absolute
97      * @return the <code>IJavaElement</code> corresponding to the given
98      * classpath-relative path, or <code>null</code> if no such
99      * <code>IJavaElement</code> is found
100      */

101     IJavaElement findElement(IPath path) throws JavaModelException;
102     
103     /**
104      * Returns the <code>IJavaElement</code> corresponding to the given
105      * classpath-relative path, or <code>null</code> if no such
106      * <code>IJavaElement</code> is found. The result is one of an
107      * <code>ICompilationUnit</code>, <code>IClassFile</code>, or
108      * <code>IPackageFragment</code>. If it is an <code>ICompilationUnit</code>,
109      * its owner is the given owner.
110      * <p>
111      * When looking for a package fragment, there might be several potential
112      * matches; only one of them is returned.
113      *
114      * <p>For example, the path "java/lang/Object.java", would result in the
115      * <code>ICompilationUnit</code> or <code>IClassFile</code> corresponding to
116      * "java.lang.Object". The path "java/lang" would result in the
117      * <code>IPackageFragment</code> for "java.lang".
118      * @param path the given classpath-relative path
119      * @param owner the owner of the returned compilation unit, ignored if it is
120      * not a compilation unit.
121      * @exception JavaModelException if the given path is <code>null</code>
122      * or absolute
123      * @return the <code>IJavaElement</code> corresponding to the given
124      * classpath-relative path, or <code>null</code> if no such
125      * <code>IJavaElement</code> is found
126      * @since 3.0
127      */

128     IJavaElement findElement(IPath path, WorkingCopyOwner owner) throws JavaModelException;
129
130     /**
131      * Returns the first existing package fragment on this project's classpath
132      * whose path matches the given (absolute) path, or <code>null</code> if none
133      * exist.
134      * The path can be:
135      * - internal to the workbench: "/Project/src"
136      * - external to the workbench: "c:/jdk/classes.zip/java/lang"
137      * @param path the given absolute path
138      * @exception JavaModelException if this project does not exist or if an
139      * exception occurs while accessing its corresponding resource
140      * @return the first existing package fragment on this project's classpath
141      * whose path matches the given (absolute) path, or <code>null</code> if none
142      * exist
143      */

144     IPackageFragment findPackageFragment(IPath path) throws JavaModelException;
145
146     /**
147      * Returns the existing package fragment root on this project's classpath
148      * whose path matches the given (absolute) path, or <code>null</code> if
149      * one does not exist.
150      * The path can be:
151      * - internal to the workbench: "/Compiler/src"
152      * - external to the workbench: "c:/jdk/classes.zip"
153      * @param path the given absolute path
154      * @exception JavaModelException if this project does not exist or if an
155      * exception occurs while accessing its corresponding resource
156      * @return the existing package fragment root on this project's classpath
157      * whose path matches the given (absolute) path, or <code>null</code> if
158      * one does not exist
159      */

160     IPackageFragmentRoot findPackageFragmentRoot(IPath path)
161         throws JavaModelException;
162     /**
163      * Returns the existing package fragment roots identified by the given entry.
164      * Note that a classpath entry that refers to another project may
165      * have more than one root (if that project has more than on root
166      * containing source), and classpath entries within the current
167      * project identify a single root.
168      * <p>
169      * If the classpath entry denotes a variable, it will be resolved and return
170      * the roots of the target entry (empty if not resolvable).
171      * <p>
172      * If the classpath entry denotes a container, it will be resolved and return
173      * the roots corresponding to the set of container entries (empty if not resolvable).
174      *
175      * @param entry the given entry
176      * @return the existing package fragment roots identified by the given entry
177      * @see IClasspathContainer
178      * @since 2.1
179      */

180     IPackageFragmentRoot[] findPackageFragmentRoots(IClasspathEntry entry);
181     /**
182      * Returns the first type found following this project's classpath
183      * with the given fully qualified name or <code>null</code> if none is found.
184      * The fully qualified name is a dot-separated name. For example,
185      * a class B defined as a member type of a class A in package x.y should have a
186      * the fully qualified name "x.y.A.B".
187      *
188      * Note that in order to be found, a type name (or its toplevel enclosing
189      * type name) must match its corresponding compilation unit name. As a
190      * consequence, secondary types cannot be found using this functionality.
191      * To find secondary types use {@link #findType(String, IProgressMonitor)} instead.
192      *
193      * @param fullyQualifiedName the given fully qualified name
194      * @exception JavaModelException if this project does not exist or if an
195      * exception occurs while accessing its corresponding resource
196      * @return the first type found following this project's classpath
197      * with the given fully qualified name or <code>null</code> if none is found
198      * @see IType#getFullyQualifiedName(char)
199      * @since 2.0
200      */

201     IType findType(String JavaDoc fullyQualifiedName) throws JavaModelException;
202     /**
203      * Same functionality as {@link #findType(String)} but also look for secondary
204      * types if given name does not match a compilation unit name.
205      *
206      * @param fullyQualifiedName the given fully qualified name
207      * @param progressMonitor the progress monitor to report progress to,
208      * or <code>null</code> if no progress monitor is provided
209      * @exception JavaModelException if this project does not exist or if an
210      * exception occurs while accessing its corresponding resource
211      * @return the first type found following this project's classpath
212      * with the given fully qualified name or <code>null</code> if none is found
213      * @see IType#getFullyQualifiedName(char)
214      * @since 3.2
215      */

216     IType findType(String JavaDoc fullyQualifiedName, IProgressMonitor progressMonitor) throws JavaModelException;
217     /**
218      * Returns the first type found following this project's classpath
219      * with the given fully qualified name or <code>null</code> if none is found.
220      * The fully qualified name is a dot-separated name. For example,
221      * a class B defined as a member type of a class A in package x.y should have a
222      * the fully qualified name "x.y.A.B".
223      * If the returned type is part of a compilation unit, its owner is the given
224      * owner.
225      *
226      * Note that in order to be found, a type name (or its toplevel enclosing
227      * type name) must match its corresponding compilation unit name. As a
228      * consequence, secondary types cannot be found using this functionality.
229      * To find secondary types use {@link #findType(String, WorkingCopyOwner, IProgressMonitor)}
230      * instead.
231      *
232      * @param fullyQualifiedName the given fully qualified name
233      * @param owner the owner of the returned type's compilation unit
234      * @exception JavaModelException if this project does not exist or if an
235      * exception occurs while accessing its corresponding resource
236      * @return the first type found following this project's classpath
237      * with the given fully qualified name or <code>null</code> if none is found
238      * @see IType#getFullyQualifiedName(char)
239      * @since 3.0
240      */

241     IType findType(String JavaDoc fullyQualifiedName, WorkingCopyOwner owner) throws JavaModelException;
242     /**
243      * Same functionality as {@link #findType(String, WorkingCopyOwner)}
244      * but also look for secondary types if given name does not match
245      * a compilation unit name.
246      *
247      * @param fullyQualifiedName the given fully qualified name
248      * @param owner the owner of the returned type's compilation unit
249      * @param progressMonitor the progress monitor to report progress to,
250      * or <code>null</code> if no progress monitor is provided
251      * @exception JavaModelException if this project does not exist or if an
252      * exception occurs while accessing its corresponding resource
253      * @return the first type found following this project's classpath
254      * with the given fully qualified name or <code>null</code> if none is found
255      * @see IType#getFullyQualifiedName(char)
256      * @since 3.2
257      */

258     IType findType(String JavaDoc fullyQualifiedName, WorkingCopyOwner owner, IProgressMonitor progressMonitor) throws JavaModelException;
259     /**
260      * Returns the first type found following this project's classpath
261      * with the given package name and type qualified name
262      * or <code>null</code> if none is found.
263      * The package name is a dot-separated name.
264      * The type qualified name is also a dot-separated name. For example,
265      * a class B defined as a member type of a class A should have the
266      * type qualified name "A.B".
267      *
268      * Note that in order to be found, a type name (or its toplevel enclosing
269      * type name) must match its corresponding compilation unit name. As a
270      * consequence, secondary types cannot be found using this functionality.
271      * To find secondary types use {@link #findType(String, String, IProgressMonitor)}
272      * instead.
273      *
274      * @param packageName the given package name
275      * @param typeQualifiedName the given type qualified name
276      * @exception JavaModelException if this project does not exist or if an
277      * exception occurs while accessing its corresponding resource
278      * @return the first type found following this project's classpath
279      * with the given package name and type qualified name
280      * or <code>null</code> if none is found
281      * @see IType#getTypeQualifiedName(char)
282      * @since 2.0
283      */

284     IType findType(String JavaDoc packageName, String JavaDoc typeQualifiedName) throws JavaModelException;
285     /**
286      * Same functionality as {@link #findType(String, String)} but also look for
287      * secondary types if given name does not match a compilation unit name.
288      *
289      * @param packageName the given package name
290      * @param typeQualifiedName the given type qualified name
291      * @param progressMonitor the progress monitor to report progress to,
292      * or <code>null</code> if no progress monitor is provided
293      * @exception JavaModelException if this project does not exist or if an
294      * exception occurs while accessing its corresponding resource
295      * @return the first type found following this project's classpath
296      * with the given fully qualified name or <code>null</code> if none is found
297      * @see IType#getFullyQualifiedName(char)
298      * @since 3.2
299      */

300     IType findType(String JavaDoc packageName, String JavaDoc typeQualifiedName, IProgressMonitor progressMonitor) throws JavaModelException;
301     /**
302      * Returns the first type found following this project's classpath
303      * with the given package name and type qualified name
304      * or <code>null</code> if none is found.
305      * The package name is a dot-separated name.
306      * The type qualified name is also a dot-separated name. For example,
307      * a class B defined as a member type of a class A should have the
308      * type qualified name "A.B".
309      * If the returned type is part of a compilation unit, its owner is the given
310      * owner.
311      *
312      * Note that in order to be found, a type name (or its toplevel enclosing
313      * type name) must match its corresponding compilation unit name. As a
314      * consequence, secondary types cannot be found using this functionality.
315      * To find secondary types use {@link #findType(String, String, WorkingCopyOwner, IProgressMonitor)}
316      * instead.
317      *
318      * @param packageName the given package name
319      * @param typeQualifiedName the given type qualified name
320      * @param owner the owner of the returned type's compilation unit
321      * @exception JavaModelException if this project does not exist or if an
322      * exception occurs while accessing its corresponding resource
323      * @return the first type found following this project's classpath
324      * with the given package name and type qualified name
325      * or <code>null</code> if none is found
326      * @see IType#getTypeQualifiedName(char)
327      * @since 3.0
328      */

329     IType findType(String JavaDoc packageName, String JavaDoc typeQualifiedName, WorkingCopyOwner owner) throws JavaModelException;
330     /**
331      * Same functionality as {@link #findType(String, String, WorkingCopyOwner)}
332      * but also look for secondary types if given name does not match a compilation unit name.
333      *
334      * @param packageName the given package name
335      * @param typeQualifiedName the given type qualified name
336      * @param owner the owner of the returned type's compilation unit
337      * @param progressMonitor the progress monitor to report progress to,
338      * or <code>null</code> if no progress monitor is provided
339      * @exception JavaModelException if this project does not exist or if an
340      * exception occurs while accessing its corresponding resource
341      * @return the first type found following this project's classpath
342      * with the given fully qualified name or <code>null</code> if none is found
343      * @see IType#getFullyQualifiedName(char)
344      * @since 3.2
345      */

346     IType findType(String JavaDoc packageName, String JavaDoc typeQualifiedName, WorkingCopyOwner owner, IProgressMonitor progressMonitor) throws JavaModelException;
347     
348     /**
349      * Returns all of the existing package fragment roots that exist
350      * on the classpath, in the order they are defined by the classpath.
351      *
352      * @return all of the existing package fragment roots that exist
353      * on the classpath
354      * @exception JavaModelException if this element does not exist or if an
355      * exception occurs while accessing its corresponding resource
356      */

357     IPackageFragmentRoot[] getAllPackageFragmentRoots() throws JavaModelException;
358
359     /**
360      * Returns an array of non-Java resources directly contained in this project.
361      * It does not transitively answer non-Java resources contained in folders;
362      * these would have to be explicitly iterated over.
363      * <p>
364      * Non-Java resources includes other files and folders located in the
365      * project not accounted for by any of it source or binary package fragment
366      * roots. If the project is a source folder itself, resources excluded from the
367      * corresponding source classpath entry by one or more exclusion patterns
368      * are considered non-Java resources and will appear in the result
369      * (possibly in a folder)
370      * </p>
371      *
372      * @return an array of non-Java resources (<code>IFile</code>s and/or
373      * <code>IFolder</code>s) directly contained in this project
374      * @exception JavaModelException if this element does not exist or if an
375      * exception occurs while accessing its corresponding resource
376      */

377     Object JavaDoc[] getNonJavaResources() throws JavaModelException;
378
379     /**
380      * Helper method for returning one option value only. Equivalent to <code>(String)this.getOptions(inheritJavaCoreOptions).get(optionName)</code>
381      * Note that it may answer <code>null</code> if this option does not exist, or if there is no custom value for it.
382      * <p>
383      * For a complete description of the configurable options, see <code>JavaCore#getDefaultOptions</code>.
384      * </p>
385      *
386      * @param optionName the name of an option
387      * @param inheritJavaCoreOptions - boolean indicating whether JavaCore options should be inherited as well
388      * @return the String value of a given option
389      * @see JavaCore#getDefaultOptions()
390      * @since 2.1
391      */

392     String JavaDoc getOption(String JavaDoc optionName, boolean inheritJavaCoreOptions);
393     
394     /**
395      * Returns the table of the current custom options for this project. Projects remember their custom options,
396      * in other words, only the options different from the the JavaCore global options for the workspace.
397      * A boolean argument allows to directly merge the project options with global ones from <code>JavaCore</code>.
398      * <p>
399      * For a complete description of the configurable options, see <code>JavaCore#getDefaultOptions</code>.
400      * </p>
401      *
402      * @param inheritJavaCoreOptions - boolean indicating whether JavaCore options should be inherited as well
403      * @return table of current settings of all options
404      * (key type: <code>String</code>; value type: <code>String</code>)
405      * @see JavaCore#getDefaultOptions()
406      * @since 2.1
407      */

408     Map JavaDoc getOptions(boolean inheritJavaCoreOptions);
409
410     /**
411      * Returns the default output location for this project as a workspace-
412      * relative absolute path.
413      * <p>
414      * The default output location is where class files are ordinarily generated
415      * (and resource files, copied). Each source classpath entry can also
416      * specify an output location for the generated class files (and copied
417      * resource files) corresponding to compilation units under that source
418      * folder. This makes it possible to arrange generated class files for
419      * different source folders in different output folders, and not
420      * necessarily the default output folder. This means that the generated
421      * class files for the project may end up scattered across several folders,
422      * rather than all in the default output folder (which is more standard).
423      * </p>
424      *
425      * @return the workspace-relative absolute path of the default output folder
426      * @exception JavaModelException if this element does not exist
427      * @see #setOutputLocation(org.eclipse.core.runtime.IPath, IProgressMonitor)
428      * @see IClasspathEntry#getOutputLocation()
429      */

430     IPath getOutputLocation() throws JavaModelException;
431
432     /**
433      * Returns a package fragment root for the JAR at the specified file system path.
434      * This is a handle-only method. The underlying <code>java.io.File</code>
435      * may or may not exist. No resource is associated with this local JAR
436      * package fragment root.
437      *
438      * @param jarPath the jars's file system path
439      * @return a package fragment root for the JAR at the specified file system path
440      */

441     IPackageFragmentRoot getPackageFragmentRoot(String JavaDoc jarPath);
442
443     /**
444      * Returns a package fragment root for the given resource, which
445      * must either be a folder representing the top of a package hierarchy,
446      * or a <code>.jar</code> or <code>.zip</code> file.
447      * This is a handle-only method. The underlying resource may or may not exist.
448      *
449      * @param resource the given resource
450      * @return a package fragment root for the given resource, which
451      * must either be a folder representing the top of a package hierarchy,
452      * or a <code>.jar</code> or <code>.zip</code> file
453      */

454     IPackageFragmentRoot getPackageFragmentRoot(IResource resource);
455
456     /**
457      * Returns all of the package fragment roots contained in this
458      * project, identified on this project's resolved classpath. The result
459      * does not include package fragment roots in other projects referenced
460      * on this project's classpath.
461      *
462      * <p>NOTE: This is equivalent to <code>getChildren()</code>.
463      *
464      * @return all of the package fragment roots contained in this
465      * project, identified on this project's resolved classpath
466      * @exception JavaModelException if this element does not exist or if an
467      * exception occurs while accessing its corresponding resource
468      */

469     IPackageFragmentRoot[] getPackageFragmentRoots() throws JavaModelException;
470
471     /**
472      * Returns the existing package fragment roots identified by the given entry.
473      * Note that a classpath entry that refers to another project may
474      * have more than one root (if that project has more than on root
475      * containing source), and classpath entries within the current
476      * project identify a single root.
477      * <p>
478      * If the classpath entry denotes a variable, it will be resolved and return
479      * the roots of the target entry (empty if not resolvable).
480      * <p>
481      * If the classpath entry denotes a container, it will be resolved and return
482      * the roots corresponding to the set of container entries (empty if not resolvable).
483      *
484      * @param entry the given entry
485      * @return the existing package fragment roots identified by the given entry
486      * @see IClasspathContainer
487      * @deprecated Use {@link IJavaProject#findPackageFragmentRoots(IClasspathEntry)} instead
488      */

489     IPackageFragmentRoot[] getPackageFragmentRoots(IClasspathEntry entry);
490
491     /**
492      * Returns all package fragments in all package fragment roots contained
493      * in this project. This is a convenience method.
494      *
495      * Note that the package fragment roots corresponds to the resolved
496      * classpath of the project.
497      *
498      * @return all package fragments in all package fragment roots contained
499      * in this project
500      * @exception JavaModelException if this element does not exist or if an
501      * exception occurs while accessing its corresponding resource
502      */

503     IPackageFragment[] getPackageFragments() throws JavaModelException;
504
505     /**
506      * Returns the <code>IProject</code> on which this <code>IJavaProject</code>
507      * was created. This is handle-only method.
508      *
509      * @return the <code>IProject</code> on which this <code>IJavaProject</code>
510      * was created
511      */

512     IProject getProject();
513
514     /**
515      * Returns the raw classpath for the project, as a list of classpath
516      * entries. This corresponds to the exact set of entries which were assigned
517      * using <code>setRawClasspath</code>, in particular such a classpath may
518      * contain classpath variable and classpath container entries. Classpath
519      * variable and classpath container entries can be resolved using the
520      * helper method <code>getResolvedClasspath</code>; classpath variable
521      * entries also can be resolved individually using
522      * <code>JavaCore#getClasspathVariable</code>).
523      * <p>
524      * Both classpath containers and classpath variables provides a level of
525      * indirection that can make the <code>.classpath</code> file stable across
526      * workspaces.
527      * As an example, classpath variables allow a classpath to no longer refer
528      * directly to external JARs located in some user specific location.
529      * The classpath can simply refer to some variables defining the proper
530      * locations of these external JARs. Similarly, classpath containers
531      * allows classpath entries to be computed dynamically by the plug-in that
532      * defines that kind of classpath container.
533      * </p>
534      * <p>
535      * Note that in case the project isn't yet opened, the classpath will
536      * be read directly from the associated <tt>.classpath</tt> file.
537      * </p>
538      *
539      * @return the raw classpath for the project, as a list of classpath entries
540      * @exception JavaModelException if this element does not exist or if an
541      * exception occurs while accessing its corresponding resource
542      * @see IClasspathEntry
543      */

544     IClasspathEntry[] getRawClasspath() throws JavaModelException;
545
546     /**
547      * Returns the names of the projects that are directly required by this
548      * project. A project is required if it is in its classpath.
549      * <p>
550      * The project names are returned in the order they appear on the classpath.
551      *
552      * @return the names of the projects that are directly required by this
553      * project in classpath order
554      * @exception JavaModelException if this element does not exist or if an
555      * exception occurs while accessing its corresponding resource
556      */

557     String JavaDoc[] getRequiredProjectNames() throws JavaModelException;
558
559     /**
560      * This is a helper method returning the resolved classpath for the project
561      * as a list of simple (non-variable, non-container) classpath entries.
562      * All classpath variable and classpath container entries in the project's
563      * raw classpath will be replaced by the simple classpath entries they
564      * resolve to.
565      * <p>
566      * The resulting resolved classpath is accurate for the given point in time.
567      * If the project's raw classpath is later modified, or if classpath
568      * variables are changed, the resolved classpath can become out of date.
569      * Because of this, hanging on resolved classpath is not recommended.
570      * </p>
571      *
572      * @param ignoreUnresolvedEntry indicates how to handle unresolvable
573      * variables and containers; <code>true</code> indicates that missing
574      * variables and unresolvable classpath containers should be silently
575      * ignored, and that the resulting list should consist only of the
576      * entries that could be successfully resolved; <code>false</code> indicates
577      * that a <code>JavaModelException</code> should be thrown for the first
578      * unresolved variable or container
579      * @return the resolved classpath for the project as a list of simple
580      * classpath entries, where all classpath variable and container entries
581      * have been resolved and substituted with their final target entries
582      * @exception JavaModelException in one of the corresponding situation:
583      * <ul>
584      * <li>this element does not exist</li>
585      * <li>an exception occurs while accessing its corresponding resource</li>
586      * <li>a classpath variable or classpath container was not resolvable
587      * and <code>ignoreUnresolvedEntry</code> is <code>false</code>.</li>
588      * </ul>
589      * @see IClasspathEntry
590      */

591     IClasspathEntry[] getResolvedClasspath(boolean ignoreUnresolvedEntry)
592          throws JavaModelException;
593
594     /**
595      * Returns whether this project has been built at least once and thus whether it has a build state.
596      * @return true if this project has been built at least once, false otherwise
597      */

598     boolean hasBuildState();
599
600     /**
601      * Returns whether setting this project's classpath to the given classpath entries
602      * would result in a cycle.
603      *
604      * If the set of entries contains some variables, those are resolved in order to determine
605      * cycles.
606      *
607      * @param entries the given classpath entries
608      * @return true if the given classpath entries would result in a cycle, false otherwise
609      */

610     boolean hasClasspathCycle(IClasspathEntry[] entries);
611     /**
612      * Returns whether the given element is on the classpath of this project,
613      * that is, referenced from a classpath entry and not explicitly excluded
614      * using an exclusion pattern.
615      *
616      * @param element the given element
617      * @return <code>true</code> if the given element is on the classpath of
618      * this project, <code>false</code> otherwise
619      * @see IClasspathEntry#getInclusionPatterns()
620      * @see IClasspathEntry#getExclusionPatterns()
621      * @since 2.0
622      */

623     boolean isOnClasspath(IJavaElement element);
624     /**
625      * Returns whether the given resource is on the classpath of this project,
626      * that is, referenced from a classpath entry and not explicitly excluded
627      * using an exclusion pattern.
628      *
629      * @param resource the given resource
630      * @return <code>true</code> if the given resource is on the classpath of
631      * this project, <code>false</code> otherwise
632      * @see IClasspathEntry#getInclusionPatterns()
633      * @see IClasspathEntry#getExclusionPatterns()
634      * @since 2.1
635      */

636     boolean isOnClasspath(IResource resource);
637
638     /**
639      * Creates a new evaluation context.
640      * @return a new evaluation context.
641      */

642     IEvaluationContext newEvaluationContext();
643
644     /**
645      * Creates and returns a type hierarchy for all types in the given
646      * region, considering subtypes within that region.
647      *
648      * @param monitor the given progress monitor
649      * @param region the given region
650      * @exception JavaModelException if this element does not exist or if an
651      * exception occurs while accessing its corresponding resource
652      * @exception IllegalArgumentException if region is <code>null</code>
653      * @return a type hierarchy for all types in the given
654      * region, considering subtypes within that region
655      */

656     ITypeHierarchy newTypeHierarchy(IRegion region, IProgressMonitor monitor)
657         throws JavaModelException;
658
659     /**
660      * Creates and returns a type hierarchy for all types in the given
661      * region, considering subtypes within that region and considering types in the
662      * working copies with the given owner.
663      * In other words, the owner's working copies will take
664      * precedence over their original compilation units in the workspace.
665      * <p>
666      * Note that if a working copy is empty, it will be as if the original compilation
667      * unit had been deleted.
668      * <p>
669      *
670      * @param monitor the given progress monitor
671      * @param region the given region
672      * @param owner the owner of working copies that take precedence over their original compilation units
673      * @exception JavaModelException if this element does not exist or if an
674      * exception occurs while accessing its corresponding resource
675      * @exception IllegalArgumentException if region is <code>null</code>
676      * @return a type hierarchy for all types in the given
677      * region, considering subtypes within that region
678      * @since 3.0
679      */

680     ITypeHierarchy newTypeHierarchy(IRegion region, WorkingCopyOwner owner, IProgressMonitor monitor)
681         throws JavaModelException;
682
683     /**
684      * Creates and returns a type hierarchy for the given type considering
685      * subtypes in the specified region.
686      *
687      * @param type the given type
688      * @param region the given region
689      * @param monitor the given monitor
690      *
691      * @exception JavaModelException if this element does not exist or if an
692      * exception occurs while accessing its corresponding resource
693      *
694      * @exception IllegalArgumentException if type or region is <code>null</code>
695      * @return a type hierarchy for the given type considering
696      * subtypes in the specified region
697      */

698     ITypeHierarchy newTypeHierarchy(
699         IType type,
700         IRegion region,
701         IProgressMonitor monitor)
702         throws JavaModelException;
703
704     /**
705      * Creates and returns a type hierarchy for the given type considering
706      * subtypes in the specified region and considering types in the
707      * working copies with the given owner.
708      * In other words, the owner's working copies will take
709      * precedence over their original compilation units in the workspace.
710      * <p>
711      * Note that if a working copy is empty, it will be as if the original compilation
712      * unit had been deleted.
713      * <p>
714      *
715      * @param type the given type
716      * @param region the given region
717      * @param monitor the given monitor
718      * @param owner the owner of working copies that take precedence over their original compilation units
719      *
720      * @exception JavaModelException if this element does not exist or if an
721      * exception occurs while accessing its corresponding resource
722      *
723      * @exception IllegalArgumentException if type or region is <code>null</code>
724      * @return a type hierarchy for the given type considering
725      * subtypes in the specified region
726      * @since 3.0
727      */

728     ITypeHierarchy newTypeHierarchy(
729         IType type,
730         IRegion region,
731         WorkingCopyOwner owner,
732         IProgressMonitor monitor)
733         throws JavaModelException;
734
735     /**
736      * Returns the default output location for the project as defined by its <code>.classpath</code> file from disk, or <code>null</code>
737      * if unable to read the file.
738      * <p>
739      * This output location may differ from the in-memory one returned by <code>getOutputLocation</code>, in case the
740      * automatic reconciliation mechanism has not been performed yet. Usually, any change to the <code>.classpath</code> file
741      * is automatically noticed and reconciled at the next resource change notification event.
742      * However, if the file is modified within an operation, where this change needs to be taken into account before the
743      * operation ends, then the output location from disk can be read using this method, and further assigned to the project
744      * using <code>setRawClasspath(...)</code>.
745      * <p>
746      * The default output location is where class files are ordinarily generated
747      * (and resource files, copied). Each source classpath entry can also
748      * specify an output location for the generated class files (and copied
749      * resource files) corresponding to compilation units under that source
750      * folder. This makes it possible to arrange generated class files for
751      * different source folders in different output folders, and not
752      * necessarily the default output folder. This means that the generated
753      * class files for the project may end up scattered across several folders,
754      * rather than all in the default output folder (which is more standard).
755      * <p>
756      * In order to manually force a project classpath refresh, one can simply assign the project classpath using the result of this
757      * method, as follows:
758      * <code>proj.setRawClasspath(proj.readRawClasspath(), proj.readOutputLocation(), monitor)</code>
759      * (note that the <code>readRawClasspath/readOutputLocation</code> methods could return <code>null</code>).
760      * <p>
761      * @return the workspace-relative absolute path of the default output folder
762      * @see #getOutputLocation()
763      * @since 3.0
764      */

765     IPath readOutputLocation();
766
767     /**
768      * Returns the raw classpath for the project as defined by its
769      * <code>.classpath</code> file from disk, or <code>null</code>
770      * if unable to read the file.
771      * <p>
772      * This classpath may differ from the in-memory classpath returned by
773      * <code>getRawClasspath</code>, in case the automatic reconciliation
774      * mechanism has not been performed yet. Usually, any change to the
775      * <code>.classpath</code> file is automatically noticed and reconciled at
776      * the next resource change notification event. However, if the file is
777      * modified within an operation, where this change needs to be taken into
778      * account before the operation ends, then the classpath from disk can be
779      * read using this method, and further assigned to the project using
780      * <code>setRawClasspath(...)</code>.
781      * </p>
782      * <p>
783      * Classpath variable and classpath container entries can be resolved using
784      * the helper method <code>getResolvedClasspath</code>; classpath variable
785      * entries also can be resolved individually using
786      * <code>JavaCore#getClasspathVariable</code>).
787      * </p>
788      * <p>
789      * Note that no check is performed whether the project has the Java nature
790      * set, allowing an existing <code>.classpath</code> file to be considered
791      * independantly (unlike <code>getRawClasspath</code> which requires the
792      * Java nature to be associated with the project).
793      * </p>
794      * <p>
795      * In order to manually force a project classpath refresh, one can simply
796      * assign the project classpath using the result of this method, as follows:
797      * <code>proj.setRawClasspath(proj.readRawClasspath(), proj.readOutputLocation(), monitor)</code>
798      * (note that the <code>readRawClasspath/readOutputLocation</code> methods
799      * could return <code>null</code>).
800      * </p>
801      *
802      * @return the raw classpath from disk for the project, as a list of
803      * classpath entries
804      * @see #getRawClasspath()
805      * @see IClasspathEntry
806      * @since 3.0
807      */

808     IClasspathEntry[] readRawClasspath();
809
810     /**
811      * Helper method for setting one option value only. Equivalent to <code>Map options = this.getOptions(false); map.put(optionName, optionValue); this.setOptions(map)</code>
812      * <p>
813      * For a complete description of the configurable options, see <code>JavaCore#getDefaultOptions</code>.
814      * </p>
815      *
816      * @param optionName the name of an option
817      * @param optionValue the value of the option to set
818      * @see JavaCore#getDefaultOptions()
819      * @since 3.0
820      */

821     void setOption(String JavaDoc optionName, String JavaDoc optionValue);
822
823     /**
824      * Sets the project custom options. All and only the options explicitly included in the given table
825      * are remembered; all previous option settings are forgotten, including ones not explicitly
826      * mentioned.
827      * <p>
828      * For a complete description of the configurable options, see <code>JavaCore#getDefaultOptions</code>.
829      * </p>
830      *
831      * @param newOptions the new options (key type: <code>String</code>; value type: <code>String</code>),
832      * or <code>null</code> to flush all custom options (clients will automatically get the global JavaCore options).
833      * @see JavaCore#getDefaultOptions()
834      * @since 2.1
835      */

836     void setOptions(Map JavaDoc newOptions);
837
838     /**
839      * Sets the default output location of this project to the location
840      * described by the given workspace-relative absolute path.
841      * <p>
842      * The default output location is where class files are ordinarily generated
843      * (and resource files, copied). Each source classpath entries can also
844      * specify an output location for the generated class files (and copied
845      * resource files) corresponding to compilation units under that source
846      * folder. This makes it possible to arrange that generated class files for
847      * different source folders to end up in different output folders, and not
848      * necessarily the default output folder. This means that the generated
849      * class files for the project may end up scattered across several folders,
850      * rather than all in the default output folder (which is more standard).
851      * </p>
852      *
853      * @param path the workspace-relative absolute path of the default output
854      * folder
855      * @param monitor the progress monitor
856      *
857      * @exception JavaModelException if the classpath could not be set. Reasons include:
858      * <ul>
859      * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
860      * <li> The path refers to a location not contained in this project (<code>PATH_OUTSIDE_PROJECT</code>)
861      * <li> The path is not an absolute path (<code>RELATIVE_PATH</code>)
862      * <li> The path is nested inside a package fragment root of this project (<code>INVALID_PATH</code>)
863      * <li> The output location is being modified during resource change event notification (CORE_EXCEPTION)
864      * </ul>
865      * @see #getOutputLocation()
866      * @see IClasspathEntry#getOutputLocation()
867      */

868     void setOutputLocation(IPath path, IProgressMonitor monitor)
869         throws JavaModelException;
870
871     /**
872      * Sets both the classpath of this project and its default output
873      * location at once. The classpath is defined using a list of classpath
874      * entries. In particular such a classpath may contain classpath variable entries.
875      * Classpath variable entries can be resolved individually ({@link JavaCore#getClasspathVariable(String)}),
876      * or the full classpath can be resolved at once using the helper method {@link #getResolvedClasspath(boolean)}.
877      * <p>
878      * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
879      * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
880      * can simply refer to some variables defining the proper locations of these external JARs.
881      * </p><p>
882      * If it is specified that this operation cannot modify resources, the .classpath file will not be written to disk
883      * and no error marker will be generated. To synchronize the .classpath with the in-memory classpath,
884      * one can use <code>setRawClasspath(readRawClasspath(), true, monitor)</code>.
885      * </p><p>
886      * Setting the classpath to <code>null</code> specifies a default classpath
887      * (the project root). Setting the classpath to an empty array specifies an
888      * empty classpath.
889      * </p><p>
890      * If a cycle is detected while setting this classpath (and if resources can be modified), an error marker will be added
891      * to the project closing the cycle.
892      * To avoid this problem, use {@link #hasClasspathCycle(IClasspathEntry[])}
893      * before setting the classpath.
894      * <p>
895      * This operation acquires a lock on the workspace's root.
896      *
897      * @param entries a list of classpath entries
898      * @param outputLocation the default output location
899      * @param canModifyResources whether resources should be written to disk if needed
900      * @param monitor the given progress monitor
901      * @exception JavaModelException if the classpath could not be set. Reasons include:
902      * <ul>
903      * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
904      * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
905      * <li> The classpath failed the validation check as defined by {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)}
906      * </ul>
907      * @see IClasspathEntry
908      * @since 3.2
909      */

910     void setRawClasspath(IClasspathEntry[] entries, IPath outputLocation, boolean canModifyResources, IProgressMonitor monitor) throws JavaModelException;
911     
912     /**
913      * Sets the classpath of this project using a list of classpath entries. In particular such a classpath may contain
914      * classpath variable entries. Classpath variable entries can be resolved individually ({@link JavaCore#getClasspathVariable(String)}),
915      * or the full classpath can be resolved at once using the helper method {@link #getResolvedClasspath(boolean)}.
916      * <p>
917      * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
918      * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
919      * can simply refer to some variables defining the proper locations of these external JARs.
920      * </p><p>
921      * If it is specified that this operation cannot modify resources, the .classpath file will not be written to disk
922      * and no error marker will be generated. To synchronize the .classpath with the in-memory classpath,
923      * one can use <code>setRawClasspath(readRawClasspath(), true, monitor)</code>.
924      * </p><p>
925      * Setting the classpath to <code>null</code> specifies a default classpath
926      * (the project root). Setting the classpath to an empty array specifies an
927      * empty classpath.
928      * </p><p>
929      * If a cycle is detected while setting this classpath (and if resources can be modified), an error marker will be added
930      * to the project closing the cycle.
931      * To avoid this problem, use {@link #hasClasspathCycle(IClasspathEntry[])}
932      * before setting the classpath.
933      * <p>
934      * This operation acquires a lock on the workspace's root.
935      *
936      * @param entries a list of classpath entries
937      * @param canModifyResources whether resources should be written to disk if needed
938      * @param monitor the given progress monitor
939      * @exception JavaModelException if the classpath could not be set. Reasons include:
940      * <ul>
941      * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
942      * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
943      * <li> The classpath failed the validation check as defined by {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)}
944      * </ul>
945      * @see IClasspathEntry
946      * @since 3.2
947      */

948     void setRawClasspath(IClasspathEntry[] entries, boolean canModifyResources, IProgressMonitor monitor) throws JavaModelException;
949     
950     /**
951      * Sets the classpath of this project using a list of classpath entries. In particular such a classpath may contain
952      * classpath variable entries. Classpath variable entries can be resolved individually ({@link JavaCore#getClasspathVariable(String)}),
953      * or the full classpath can be resolved at once using the helper method {@link #getResolvedClasspath(boolean)}.
954      * <p>
955      * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
956      * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
957      * can simply refer to some variables defining the proper locations of these external JARs.
958      * <p>
959      * Setting the classpath to <code>null</code> specifies a default classpath
960      * (the project root). Setting the classpath to an empty array specifies an
961      * empty classpath.
962      * <p>
963      * If a cycle is detected while setting this classpath, an error marker will be added
964      * to the project closing the cycle.
965      * To avoid this problem, use {@link #hasClasspathCycle(IClasspathEntry[])}
966      * before setting the classpath.
967      * <p>
968      * This operation acquires a lock on the workspace's root.
969      *
970      * @param entries a list of classpath entries
971      * @param monitor the given progress monitor
972      * @exception JavaModelException if the classpath could not be set. Reasons include:
973      * <ul>
974      * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
975      * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
976      * <li> The classpath failed the validation check as defined by {@link JavaConventions#validateClasspath(IJavaProject, IClasspathEntry[], IPath)}
977      * </ul>
978      * @see IClasspathEntry
979      */

980     void setRawClasspath(IClasspathEntry[] entries, IProgressMonitor monitor)
981         throws JavaModelException;
982         
983     /**
984      * Sets the both the classpath of this project and its default output
985      * location at once. The classpath is defined using a list of classpath
986      * entries. In particular, such a classpath may contain classpath variable
987      * entries. Classpath variable entries can be resolved individually (see
988      * ({@link JavaCore#getClasspathVariable(String)}), or the full classpath can be
989      * resolved at once using the helper method
990      * {@link #getResolvedClasspath(boolean)}.
991      * <p>
992      * A classpath variable provides an indirection level for better sharing a
993      * classpath. As an example, it allows a classpath to no longer refer
994      * directly to external JARs located in some user specific location. The
995      * classpath can simply refer to some variables defining the proper
996      * locations of these external JARs.
997      * </p>
998      * <p>
999      * Setting the classpath to <code>null</code> specifies a default classpath
1000     * (the project root). Setting the classpath to an empty array specifies an
1001     * empty classpath.
1002     * </p>
1003     * <p>
1004     * If a cycle is detected while setting this classpath, an error marker will
1005     * be added to the project closing the cycle. To avoid this problem, use
1006     * {@link #hasClasspathCycle(IClasspathEntry[])} before setting
1007     * the classpath.
1008     * </p>
1009     * <p>
1010     * This operation acquires a lock on the workspace's root.
1011     * </p>
1012     *
1013     * @param entries a list of classpath entries
1014     * @param monitor the progress monitor
1015     * @param outputLocation the default output location
1016     * @exception JavaModelException if the classpath could not be set. Reasons
1017     * include:
1018     * <ul>
1019     * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
1020     * <li> Two or more entries specify source roots with the same or overlapping paths (NAME_COLLISION)
1021     * <li> A entry of kind <code>CPE_PROJECT</code> refers to this project (INVALID_PATH)
1022     * <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
1023     * <li>The output location path refers to a location not contained in this project (<code>PATH_OUTSIDE_PROJECT</code>)
1024     * <li>The output location path is not an absolute path (<code>RELATIVE_PATH</code>)
1025     * <li>The output location path is nested inside a package fragment root of this project (<code>INVALID_PATH</code>)
1026     * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
1027     * </ul>
1028     * @see IClasspathEntry
1029     * @since 2.0
1030     */

1031    void setRawClasspath(IClasspathEntry[] entries, IPath outputLocation, IProgressMonitor monitor)
1032        throws JavaModelException;
1033}
1034
Popular Tags