1 /*******************************************************************************
2 * Copyright (c) 2000, 2003 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Common Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/cpl-v10.html
9 * IBM Corporation - initial API and implementation
10 * IBM Corporation - added getOption(String, boolean), getOptions(boolean) and setOptions(Map)
11 * IBM Corporation - deprecated getPackageFragmentRoots(IClasspathEntry) and
12 * added findPackageFragmentRoots(IClasspathEntry)
13 * IBM Corporation - added isOnClasspath(IResource)
14 *******************************************************************************/
15 package net.sourceforge.phpdt.core;
19 import org.eclipse.core.resources.IProject;
20 import org.eclipse.core.resources.IResource;
21 import org.eclipse.core.runtime.IPath;
22 import org.eclipse.core.runtime.IProgressMonitor;
25 * A Java project represents a view of a project resource in terms of Java
26 * elements such as package fragments, types, methods and fields. A project may
27 * contain several package roots, which contain package fragments. A package
28 * root corresponds to an underlying folder or JAR.
30 * Each Java project has a classpath, defining which folders contain source code
31 * and where required libraries are located. Each Java project also has an
32 * output location, defining where the builder writes <code>.class</code>
33 * files. A project that references packages in another project can access the
34 * packages by including the required project in a classpath entry. The Java
35 * model will present the source elements in the required project; when
36 * building, the compiler will use the corresponding generated class files from
37 * the required project's output location(s)). The classpath format is a
38 * sequence of classpath entries describing the location and contents of package
41 * Java project elements need to be opened before they can be navigated or
42 * manipulated. The children of a Java project are the package fragment roots
43 * that are defined by the classpath and contained in this project (in other
44 * words, it does not include package fragment roots for other projects).
47 * This interface is not intended to be implemented by clients. An instance of
48 * one of these handles can be created via <code>JavaCore.create(project)</code>.
51 * @see JavaCore#create(org.eclipse.core.resources.IProject)
52 * @see IClasspathEntry
54 public interface IJavaProject extends IParent, IJavaElement, IOpenable {
57 * Returns the <code>IJavaElement</code> corresponding to the given
58 * classpath-relative path, or <code>null</code> if no such
59 * <code>IJavaElement</code> is found. The result is one of an
60 * <code>ICompilationUnit</code>, <code>IClassFile</code>, or
61 * <code>IPackageFragment</code>.
63 * When looking for a package fragment, there might be several potential
64 * matches; only one of them is returned.
67 * For example, the path "java/lang/Object.java", would result in the
68 * <code>ICompilationUnit</code> or <code>IClassFile</code>
69 * corresponding to "java.lang.Object". The path "java/lang" would result in
70 * the <code>IPackageFragment</code> for "java.lang".
73 * the given classpath-relative path
74 * @exception JavaModelException
75 * if the given path is <code>null</code> or absolute
76 * @return the <code>IJavaElement</code> corresponding to the given
77 * classpath-relative path, or <code>null</code> if no such
78 * <code>IJavaElement</code> is found
80 IJavaElement findElement(IPath path) throws JavaModelException;
83 * Returns the first existing package fragment on this project's classpath
84 * whose path matches the given (absolute) path, or <code>null</code> if
85 * none exist. The path can be: - internal to the workbench: "/Project/src" -
86 * external to the workbench: "c:/jdk/classes.zip/java/lang"
89 * the given absolute path
90 * @exception JavaModelException
91 * if this element does not exist or if an exception occurs
92 * while accessing its corresponding resource
93 * @return the first existing package fragment on this project's classpath
94 * whose path matches the given (absolute) path, or
95 * <code>null</code> if none exist
97 // IPackageFragment findPackageFragment(IPath path) throws
98 // JavaModelException;
100 * Returns the existing package fragment root on this project's classpath
101 * whose path matches the given (absolute) path, or <code>null</code> if
102 * one does not exist. The path can be: - internal to the workbench:
103 * "/Compiler/src" - external to the workbench: "c:/jdk/classes.zip"
106 * the given absolute path
107 * @exception JavaModelException
108 * if this element does not exist or if an exception occurs
109 * while accessing its corresponding resource
110 * @return the existing package fragment root on this project's classpath
111 * whose path matches the given (absolute) path, or
112 * <code>null</code> if one does not exist
114 IPackageFragmentRoot findPackageFragmentRoot(IPath path)
115 throws JavaModelException;
118 * Returns the existing package fragment roots identified by the given
119 * entry. Note that a classpath entry that refers to another project may
120 * have more than one root (if that project has more than on root containing
121 * source), and classpath entries within the current project identify a
124 * If the classpath entry denotes a variable, it will be resolved and return
125 * the roots of the target entry (empty if not resolvable).
127 * If the classpath entry denotes a container, it will be resolved and
128 * return the roots corresponding to the set of container entries (empty if
133 * @return the existing package fragment roots identified by the given entry
134 * @see IClasspathContainer
137 IPackageFragmentRoot[] findPackageFragmentRoots(IClasspathEntry entry);
140 * Returns the first type found following this project's classpath with the
141 * given fully qualified name or <code>null</code> if none is found. The
142 * fully qualified name is a dot-separated name. For example, a class B
143 * defined as a member type of a class A in package x.y should have a the
144 * fully qualified name "x.y.A.B".
146 * Note that in order to be found, a type name (or its toplevel enclosing
147 * type name) must match its corresponding compilation unit name. As a
148 * consequence, secondary types cannot be found using this functionality.
149 * Secondary types can however be explicitely accessed through their
150 * enclosing unit or found by the <code>SearchEngine</code>.
152 * @param fullyQualifiedName
153 * the given fully qualified name
154 * @exception JavaModelException
155 * if this element does not exist or if an exception occurs
156 * while accessing its corresponding resource
157 * @return the first type found following this project's classpath with the
158 * given fully qualified name or <code>null</code> if none is
160 * @see IType#getFullyQualifiedName(char)
163 // IType findType(String fullyQualifiedName) throws JavaModelException;
165 * Returns the first type found following this project's classpath with the
166 * given package name and type qualified name or <code>null</code> if none
167 * is found. The package name is a dot-separated name. The type qualified
168 * name is also a dot-separated name. For example, a class B defined as a
169 * member type of a class A should have the type qualified name "A.B".
171 * Note that in order to be found, a type name (or its toplevel enclosing
172 * type name) must match its corresponding compilation unit name. As a
173 * consequence, secondary types cannot be found using this functionality.
174 * Secondary types can however be explicitely accessed through their
175 * enclosing unit or found by the <code>SearchEngine</code>.
178 * the given package name
179 * @param typeQualifiedName
180 * the given type qualified name
181 * @exception JavaModelException
182 * if this element does not exist or if an exception occurs
183 * while accessing its corresponding resource
184 * @return the first type found following this project's classpath with the
185 * given package name and type qualified name or <code>null</code>
187 * @see IType#getTypeQualifiedName(char)
191 // IType findType(String packageName, String typeQualifiedName) throws
192 // JavaModelException;
194 * Returns all of the existing package fragment roots that exist on the
195 * classpath, in the order they are defined by the classpath.
197 * @return all of the existing package fragment roots that exist on the
199 * @exception JavaModelException
200 * if this element does not exist or if an exception occurs
201 * while accessing its corresponding resource
203 IPackageFragmentRoot[] getAllPackageFragmentRoots()
204 throws JavaModelException;
207 * Returns an array of non-Java resources directly contained in this
208 * project. It does not transitively answer non-Java resources contained in
209 * folders; these would have to be explicitly iterated over.
211 * Non-Java resources includes other files and folders located in the
212 * project not accounted for by any of it source or binary package fragment
213 * roots. If the project is a source folder itself, resources excluded from
214 * the corresponding source classpath entry by one or more exclusion
215 * patterns are considered non-Java resources and will appear in the result
216 * (possibly in a folder)
219 * @return an array of non-Java resources directly contained in this project
220 * @exception JavaModelException
221 * if this element does not exist or if an exception occurs
222 * while accessing its corresponding resource
224 // Object[] getNonJavaResources() throws JavaModelException;
226 * Helper method for returning one option value only. Equivalent to
227 * <code>(String)this.getOptions(inheritJavaCoreOptions).get(optionName)</code>
228 * Note that it may answer <code>null</code> if this option does not
229 * exist, or if there is no custom value for it.
231 * For a complete description of the configurable options, see
232 * <code>JavaCore#getDefaultOptions</code>.
236 * the name of an option
237 * @param inheritJavaCoreOptions -
238 * boolean indicating whether JavaCore options should be
240 * @return the String value of a given option
241 * @see JavaCore#getDefaultOptions
244 String getOption(String optionName, boolean inheritJavaCoreOptions);
247 * Returns the table of the current custom options for this project.
248 * Projects remember their custom options, in other words, only the options
249 * different from the the JavaCore global options for the workspace. A
250 * boolean argument allows to directly merge the project options with global
251 * ones from <code>JavaCore</code>.
253 * For a complete description of the configurable options, see
254 * <code>JavaCore#getDefaultOptions</code>.
257 * @param inheritJavaCoreOptions -
258 * boolean indicating whether JavaCore options should be
260 * @return table of current settings of all options (key type:
261 * <code>String</code>; value type: <code>String</code>)
262 * @see JavaCore#getDefaultOptions
265 Map getOptions(boolean inheritJavaCoreOptions);
268 * Returns the default output location for this project as a workspace-
269 * relative absolute path.
271 * The default output location is where class files are ordinarily generated
272 * (and resource files, copied). Each source classpath entry can also
273 * specify an output location for the generated class files (and copied
274 * resource files) corresponding to compilation units under that source
275 * folder. This makes it possible to arrange generated class files for
276 * different source folders in different output folders, and not necessarily
277 * the default output folder. This means that the generated class files for
278 * the project may end up scattered across several folders, rather than all
279 * in the default output folder (which is more standard).
282 * @return the workspace-relative absolute path of the default output folder
283 * @exception JavaModelException
284 * if this element does not exist
285 * @see #setOutputLocation
286 * @see IClasspathEntry#getOutputLocation
288 IPath getOutputLocation() throws JavaModelException;
291 * Returns a package fragment root for the JAR at the specified file system
292 * path. This is a handle-only method. The underlying
293 * <code>java.io.File</code> may or may not exist. No resource is
294 * associated with this local JAR package fragment root.
297 * the jars's file system path
298 * @return a package fragment root for the JAR at the specified file system
301 // IPackageFragmentRoot getPackageFragmentRoot(String jarPath);
303 * Returns a package fragment root for the given resource, which must either
304 * be a folder representing the top of a package hierarchy, or a
305 * <code>.jar</code> or <code>.zip</code> file. This is a handle-only
306 * method. The underlying resource may or may not exist.
310 * @return a package fragment root for the given resource, which must either
311 * be a folder representing the top of a package hierarchy, or a
312 * <code>.jar</code> or <code>.zip</code> file
314 IPackageFragmentRoot getPackageFragmentRoot(IResource resource);
317 * Returns all of the package fragment roots contained in this project,
318 * identified on this project's resolved classpath. The result does not
319 * include package fragment roots in other projects referenced on this
320 * project's classpath.
323 * NOTE: This is equivalent to <code>getChildren()</code>.
325 * @return all of the package fragment roots contained in this project,
326 * identified on this project's resolved classpath
327 * @exception JavaModelException
328 * if this element does not exist or if an exception occurs
329 * while accessing its corresponding resource
331 IPackageFragmentRoot[] getPackageFragmentRoots() throws JavaModelException;
334 * Returns the existing package fragment roots identified by the given
335 * entry. Note that a classpath entry that refers to another project may
336 * have more than one root (if that project has more than on root containing
337 * source), and classpath entries within the current project identify a
340 * If the classpath entry denotes a variable, it will be resolved and return
341 * the roots of the target entry (empty if not resolvable).
343 * If the classpath entry denotes a container, it will be resolved and
344 * return the roots corresponding to the set of container entries (empty if
349 * @return the existing package fragment roots identified by the given entry
350 * @see IClasspathContainer
351 * @deprecated Use IJavaProject#findPackageFragmentRoots instead
353 IPackageFragmentRoot[] getPackageFragmentRoots(IClasspathEntry entry);
356 * Returns all package fragments in all package fragment roots contained in
357 * this project. This is a convenience method.
359 * Note that the package fragment roots corresponds to the resolved
360 * classpath of the project.
362 * @return all package fragments in all package fragment roots contained in
364 * @exception JavaModelException
365 * if this element does not exist or if an exception occurs
366 * while accessing its corresponding resource
368 IPackageFragment[] getPackageFragments() throws JavaModelException;
371 * Returns the <code>IProject</code> on which this
372 * <code>IJavaProject</code> was created. This is handle-only method.
374 * @return the <code>IProject</code> on which this
375 * <code>IJavaProject</code> was created
377 IProject getProject();
380 * Returns the raw classpath for the project, as a list of classpath
381 * entries. This corresponds to the exact set of entries which were assigned
382 * using <code>setRawClasspath</code>, in particular such a classpath may
383 * contain classpath variable entries. Classpath variable entries can be
384 * resolved individually (see <code>JavaCore#getClasspathVariable</code>),
385 * or the full classpath can be resolved at once using the helper method
386 * <code>getResolvedClasspath</code>.
388 * A classpath variable provides an indirection level for better sharing a
389 * classpath. As an example, it allows a classpath to no longer refer
390 * directly to external JARs located in some user specific location. The
391 * classpath can simply refer to some variables defining the proper
392 * locations of these external JARs.
394 * Note that in case the project isn't yet opened, the classpath will
395 * directly be read from the associated <tt>.classpath</tt> file.
398 * @return the raw classpath for the project, as a list of classpath entries
399 * @exception JavaModelException
400 * if this element does not exist or if an exception occurs
401 * while accessing its corresponding resource
402 * @see IClasspathEntry
404 IClasspathEntry[] getRawClasspath() throws JavaModelException;
407 * Returns the names of the projects that are directly required by this
408 * project. A project is required if it is in its classpath.
410 * The project names are returned in the order they appear on the classpath.
412 * @return the names of the projects that are directly required by this
413 * project in classpath order
414 * @exception JavaModelException
415 * if this element does not exist or if an exception occurs
416 * while accessing its corresponding resource
418 String[] getRequiredProjectNames() throws JavaModelException;
421 * This is a helper method returning the resolved classpath for the project
422 * as a list of simple (non-variable, non-container) classpath entries. All
423 * classpath variable and classpath container entries in the project's raw
424 * classpath will be replaced by the simple classpath entries they resolve
427 * The resulting resolved classpath is accurate for the given point in time.
428 * If the project's raw classpath is later modified, or if classpath
429 * variables are changed, the resolved classpath can become out of date.
430 * Because of this, hanging on resolved classpath is not recommended.
433 * @param ignoreUnresolvedEntry
434 * indicates how to handle unresolvable variables and containers;
435 * <code>true</code> indicates that missing variables and
436 * unresolvable classpath containers should be silently ignored,
437 * and that the resulting list should consist only of the entries
438 * that could be successfully resolved; <code>false</code>
439 * indicates that a <code>JavaModelException</code> should be
440 * thrown for the first unresolved variable or container
441 * @return the resolved classpath for the project as a list of simple
442 * classpath entries, where all classpath variable and container
443 * entries have been resolved and substituted with their final
445 * @exception JavaModelException
446 * in one of the corresponding situation:
448 * <li>this element does not exist</li>
449 * <li>an exception occurs while accessing its corresponding
451 * <li>a classpath variable or classpath container was not
452 * resolvable and <code>ignoreUnresolvedEntry</code> is
453 * <code>false</code>.</li>
455 * @see IClasspathEntry
457 IClasspathEntry[] getResolvedClasspath(boolean ignoreUnresolvedEntry)
458 throws JavaModelException;
461 * Returns whether this project has been built at least once and thus
462 * whether it has a build state.
464 * @return true if this project has been built at least once, false
467 boolean hasBuildState();
470 * Returns whether setting this project's classpath to the given classpath
471 * entries would result in a cycle.
473 * If the set of entries contains some variables, those are resolved in
474 * order to determine cycles.
477 * the given classpath entries
478 * @return true if the given classpath entries would result in a cycle,
481 boolean hasClasspathCycle(IClasspathEntry[] entries);
484 * Returns whether the given element is on the classpath of this project,
485 * that is, referenced from a classpath entry and not explicitly excluded
486 * using an exclusion pattern.
490 * @return <code>true</code> if the given element is on the classpath of
491 * this project, <code>false</code> otherwise
492 * @see IClasspathEntry#getExclusionPatterns
495 // boolean isOnClasspath(IJavaElement element);
497 * Returns whether the given resource is on the classpath of this project,
498 * that is, referenced from a classpath entry and not explicitly excluded
499 * using an exclusion pattern.
503 * @return <code>true</code> if the given resource is on the classpath of
504 * this project, <code>false</code> otherwise
505 * @see IClasspathEntry#getExclusionPatterns
508 // boolean isOnClasspath(IResource resource);
510 * Creates a new evaluation context.
512 * @return a new evaluation context.
514 // IEvaluationContext newEvaluationContext();
516 * Creates and returns a type hierarchy for all types in the given region,
517 * considering subtypes within that region.
520 * the given progress monitor
523 * @exception JavaModelException
524 * if this element does not exist or if an exception occurs
525 * while accessing its corresponding resource
526 * @exception IllegalArgumentException
527 * if region is <code>null</code>
528 * @return a type hierarchy for all types in the given region, considering
529 * subtypes within that region
531 // ITypeHierarchy newTypeHierarchy(IRegion region, IProgressMonitor monitor)
532 // throws JavaModelException;
534 * Creates and returns a type hierarchy for the given type considering
535 * subtypes in the specified region.
544 * @exception JavaModelException
545 * if this element does not exist or if an exception occurs
546 * while accessing its corresponding resource
548 * @exception IllegalArgumentException
549 * if type or region is <code>null</code>
550 * @return a type hierarchy for the given type considering subtypes in the
553 // ITypeHierarchy newTypeHierarchy(
556 // IProgressMonitor monitor)
557 // throws JavaModelException;
559 * Sets the project custom options. All and only the options explicitly
560 * included in the given table are remembered; all previous option settings
561 * are forgotten, including ones not explicitly mentioned.
563 * For a complete description of the configurable options, see
564 * <code>JavaCore#getDefaultOptions</code>.
568 * the new options (key type: <code>String</code>; value type:
569 * <code>String</code>), or <code>null</code> to flush all
570 * custom options (clients will automatically get the global
572 * @see JavaCore#getDefaultOptions
575 void setOptions(Map newOptions);
578 * Sets the default output location of this project to the location
579 * described by the given workspace-relative absolute path.
581 * The default output location is where class files are ordinarily generated
582 * (and resource files, copied). Each source classpath entries can also
583 * specify an output location for the generated class files (and copied
584 * resource files) corresponding to compilation units under that source
585 * folder. This makes it possible to arrange that generated class files for
586 * different source folders to end up in different output folders, and not
587 * necessarily the default output folder. This means that the generated
588 * class files for the project may end up scattered across several folders,
589 * rather than all in the default output folder (which is more standard).
593 * the workspace-relative absolute path of the default output
596 * the progress monitor
598 * @exception JavaModelException
599 * if the classpath could not be set. Reasons include:
601 * <li> This Java element does not exist
602 * (ELEMENT_DOES_NOT_EXIST)</li>
603 * <li> The path refers to a location not contained in this
604 * project (<code>PATH_OUTSIDE_PROJECT</code>)
605 * <li> The path is not an absolute path (<code>RELATIVE_PATH</code>)
606 * <li> The path is nested inside a package fragment root of
607 * this project (<code>INVALID_PATH</code>)
608 * <li> The output location is being modified during resource
609 * change event notification (CORE_EXCEPTION)
611 * @see #getOutputLocation
612 * @see IClasspathEntry#getOutputLocation
614 void setOutputLocation(IPath path, IProgressMonitor monitor)
615 throws JavaModelException;
618 * Sets the classpath of this project using a list of classpath entries. In
619 * particular such a classpath may contain classpath variable entries.
620 * Classpath variable entries can be resolved individually (see
621 * <code>JavaCore#getClasspathVariable</code>), or the full classpath can
622 * be resolved at once using the helper method
623 * <code>getResolvedClasspath</code>.
625 * A classpath variable provides an indirection level for better sharing a
626 * classpath. As an example, it allows a classpath to no longer refer
627 * directly to external JARs located in some user specific location. The
628 * classpath can simply refer to some variables defining the proper
629 * locations of these external JARs.
631 * Setting the classpath to <code>null</code> specifies a default
632 * classpath (the project root). Setting the classpath to an empty array
633 * specifies an empty classpath.
635 * If a cycle is detected while setting this classpath, an error marker will
636 * be added to the project closing the cycle. To avoid this problem, use
637 * <code>hasClasspathCycle(IClasspathEntry[] entries)</code> before
638 * setting the classpath.
641 * a list of classpath entries
643 * the given progress monitor
644 * @exception JavaModelException
645 * if the classpath could not be set. Reasons include:
647 * <li> This Java element does not exist
648 * (ELEMENT_DOES_NOT_EXIST)</li>
649 * <li> The classpath is being modified during resource
650 * change event notification (CORE_EXCEPTION)
651 * <li> The classpath failed the validation check as defined
652 * by <code>JavaConventions#validateClasspath</code>
654 * @see IClasspathEntry
656 void setRawClasspath(IClasspathEntry[] entries, IProgressMonitor monitor)
657 throws JavaModelException;
660 * Sets the both the classpath of this project and its default output
661 * location at once. The classpath is defined using a list of classpath
662 * entries. In particular, such a classpath may contain classpath variable
663 * entries. Classpath variable entries can be resolved individually (see
664 * <code>JavaCore#getClasspathVariable</code>), or the full classpath can
665 * be resolved at once using the helper method
666 * <code>getResolvedClasspath</code>.
668 * A classpath variable provides an indirection level for better sharing a
669 * classpath. As an example, it allows a classpath to no longer refer
670 * directly to external JARs located in some user specific location. The
671 * classpath can simply refer to some variables defining the proper
672 * locations of these external JARs.
675 * Setting the classpath to <code>null</code> specifies a default
676 * classpath (the project root). Setting the classpath to an empty array
677 * specifies an empty classpath.
680 * If a cycle is detected while setting this classpath, an error marker will
681 * be added to the project closing the cycle. To avoid this problem, use
682 * <code>hasClasspathCycle(IClasspathEntry[] entries)</code> before
683 * setting the classpath.
687 * a list of classpath entries
689 * the progress monitor
690 * @param outputLocation
691 * the default output location
692 * @exception JavaModelException
693 * if the classpath could not be set. Reasons include:
695 * <li> This Java element does not exist
696 * (ELEMENT_DOES_NOT_EXIST)</li>
697 * <li> Two or more entries specify source roots with the
698 * same or overlapping paths (NAME_COLLISION)
699 * <li> A entry of kind <code>CPE_PROJECT</code> refers to
700 * this project (INVALID_PATH)
701 * <li>This Java element does not exist
702 * (ELEMENT_DOES_NOT_EXIST)</li>
703 * <li>The output location path refers to a location not
704 * contained in this project (<code>PATH_OUTSIDE_PROJECT</code>)
705 * <li>The output location path is not an absolute path (<code>RELATIVE_PATH</code>)
706 * <li>The output location path is nested inside a package
707 * fragment root of this project (<code>INVALID_PATH</code>)
708 * <li> The classpath is being modified during resource
709 * change event notification (CORE_EXCEPTION)
711 * @see IClasspathEntry
714 void setRawClasspath(IClasspathEntry[] entries, IPath outputLocation,
715 IProgressMonitor monitor) throws JavaModelException;