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