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  ;
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   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   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   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   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   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   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   packageName, String   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   packageName, String   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   packageName, String   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   packageName, String   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  [] 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   getOption(String   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   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   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  [] 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   optionName, String   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags