75ffe0461e90b51cc6c2751f13bebf9eb7520842
[phpeclipse.git] / net.sourceforge.phpeclipse / src / net / sourceforge / phpdt / core / IJavaProject.java
1 /*******************************************************************************
2  * Copyright (c) 2000, 2001, 2002 International Business Machines Corp. and others.
3  * All rights reserved. This program and the accompanying materials 
4  * are made available under the terms of the Common Public License v0.5 
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/cpl-v05.html
7  * 
8  * Contributors:
9  *     IBM Corporation - initial API and implementation
10  ******************************************************************************/
11 package net.sourceforge.phpdt.core;
12
13 import org.eclipse.core.resources.IProject;
14 import org.eclipse.core.runtime.IPath;
15 import org.eclipse.core.runtime.IProgressMonitor;
16
17 //import net.sourceforge.phpdt.core.eval.IEvaluationContext;
18
19 /**
20  * A Java project represents a view of a project resource in terms of Java 
21  * elements such as package fragments, types, methods and fields.
22  * A project may contain several package roots, which contain package fragments. 
23  * A package root corresponds to an underlying folder or JAR.
24  * <p>
25  * Each Java project has a classpath, defining which folders contain source code and
26  * where required libraries are located. Each Java project also has an output location,
27  * defining where the builder writes <code>.class</code> files. A project that
28  * references packages in another project can access the packages by including
29  * the required project in a classpath entry. The Java model will present the
30  * source elements in the required project, and when building, the compiler will
31  * use the binaries from that project (that is, the output location of the 
32  * required project is used as a library). The classpath format is a sequence 
33  * of classpath entries describing the location and contents of package fragment
34  * roots.
35  * </p>
36  * Java project elements need to be opened before they can be navigated or manipulated.
37  * The children of a Java project are the package fragment roots that are 
38  * defined by the classpath and contained in this project (in other words, it
39  * does not include package fragment roots for other projects).
40  * </p>
41  * <p>
42  * This interface is not intended to be implemented by clients. An instance
43  * of one of these handles can be created via 
44  * <code>JavaCore.create(project)</code>.
45  * </p>
46  *
47  * @see JavaCore#create(org.eclipse.core.resources.IProject)
48  * @see IClasspathEntry
49  */
50 public interface IJavaProject extends IParent, IJavaElement, IOpenable {
51
52   /**
53    * Returns the <code>IJavaElement</code> corresponding to the given
54    * classpath-relative path, or <code>null</code> if no such 
55    * <code>IJavaElement</code> is found. The result is one of an
56    * <code>ICompilationUnit</code>, <code>IClassFile</code>, or
57    * <code>IPackageFragment</code>. 
58    * <p>
59    * When looking for a package fragment, there might be several potential
60    * matches; only one of them is returned.
61    *
62    * <p>For example, the path "java/lang/Object.java", would result in the
63    * <code>ICompilationUnit</code> or <code>IClassFile</code> corresponding to
64    * "java.lang.Object". The path "java/lang" would result in the
65    * <code>IPackageFragment</code> for "java.lang".
66    * @param path the given classpath-relative path
67    * @exception JavaModelException if the given path is <code>null</code>
68    *  or absolute
69    * @return the <code>IJavaElement</code> corresponding to the given
70    * classpath-relative path, or <code>null</code> if no such 
71    * <code>IJavaElement</code> is found
72    */
73   IJavaElement findElement(IPath path) throws JavaModelException;
74
75   /**
76    * Returns the first existing package fragment on this project's classpath
77    * whose path matches the given (absolute) path, or <code>null</code> if none
78    * exist.
79    * The path can be:
80    *    - internal to the workbench: "/Project/src"
81    *  - external to the workbench: "c:/jdk/classes.zip/java/lang"
82    * @param path the given absolute path
83    * @exception JavaModelException if this element does not exist or if an
84    *            exception occurs while accessing its corresponding resource
85    * @return the first existing package fragment on this project's classpath
86    * whose path matches the given (absolute) path, or <code>null</code> if none
87    * exist
88    */
89   //IPackageFragment findPackageFragment(IPath path) throws JavaModelException;
90
91   /**
92    * Returns the existing package fragment root on this project's classpath
93    * whose path matches the given (absolute) path, or <code>null</code> if
94    * one does not exist.
95    * The path can be:
96    *    - internal to the workbench: "/Compiler/src"
97    *    - external to the workbench: "c:/jdk/classes.zip"
98    * @param path the given absolute path
99    * @exception JavaModelException if this element does not exist or if an
100    *            exception occurs while accessing its corresponding resource
101    * @return the existing package fragment root on this project's classpath
102    * whose path matches the given (absolute) path, or <code>null</code> if
103    * one does not exist
104    */
105   //    IPackageFragmentRoot findPackageFragmentRoot(IPath path)
106   //            throws JavaModelException;
107   /**
108    * Returns the first type found following this project's classpath 
109    * with the given fully qualified name or <code>null</code> if none is found.
110    * The fully qualified name is a dot-separated name. For example,
111    * a class B defined as a member type of a class A in package x.y should have a 
112    * the fully qualified name "x.y.A.B".
113    * 
114    * @param fullyQualifiedName the given fully qualified name
115    * @exception JavaModelException if this element does not exist or if an
116    *            exception occurs while accessing its corresponding resource
117    * @return the first type found following this project's classpath 
118    * with the given fully qualified name or <code>null</code> if none is found
119    * @see IType#getFullyQualifiedName(char)
120    * @since 2.0
121    */
122   IType findType(String fullyQualifiedName) throws JavaModelException;
123   /**
124    * Returns the first type found following this project's classpath 
125    * with the given package name and type qualified name
126    * or <code>null</code> if none is found.
127    * The package name is a dot-separated name.
128    * The type qualified name is also a dot-separated name. For example,
129    * a class B defined as a member type of a class A should have the 
130    * type qualified name "A.B".
131    * 
132    * @param packageName the given package name
133    * @param typeQualifiedName the given type qualified name
134    * @exception JavaModelException if this element does not exist or if an
135    *            exception occurs while accessing its corresponding resource
136    * @return the first type found following this project's classpath 
137    * with the given package name and type qualified name
138    * or <code>null</code> if none is found
139    * @see IType#getTypeQualifiedName(char)
140    * @since 2.0
141    */
142   IType findType(String packageName, String typeQualifiedName) throws JavaModelException;
143
144   /**
145    * Returns all of the existing package fragment roots that exist
146    * on the classpath, in the order they are defined by the classpath.
147    *
148    * @return all of the existing package fragment roots that exist
149    * on the classpath
150    * @exception JavaModelException if this element does not exist or if an
151    *            exception occurs while accessing its corresponding resource
152    */
153   // IPackageFragmentRoot[] getAllPackageFragmentRoots() throws JavaModelException;
154
155   /**
156    * Returns an array of non-Java resources directly contained in this project.
157    * It does not transitively answer non-Java resources contained in folders;
158    * these would have to be explicitly iterated over.
159    * @return an array of non-Java resources directly contained in this project
160    */
161   Object[] getNonJavaResources() throws JavaModelException;
162
163   /**
164    * Returns the full path to the location where the builder writes 
165    * <code>.class</code> files.
166    *
167    * @exception JavaModelException if this element does not exist or if an
168    *            exception occurs while accessing its corresponding resource
169    * @return the full path to the location where the builder writes 
170    * <code>.class</code> files
171    */
172   IPath getOutputLocation() throws JavaModelException;
173
174   /**
175    * Returns a package fragment root for the JAR at the specified file system path.
176    * This is a handle-only method.  The underlying <code>java.io.File</code>
177    * may or may not exist. No resource is associated with this local JAR
178    * package fragment root.
179    * 
180    * @param jarPath the jars's file system path
181    * @return a package fragment root for the JAR at the specified file system path
182    */
183   // IPackageFragmentRoot getPackageFragmentRoot(String jarPath);
184
185   /**
186    * Returns a package fragment root for the given resource, which
187    * must either be a folder representing the top of a package hierarchy,
188    * or a <code>.jar</code> or <code>.zip</code> file.
189    * This is a handle-only method.  The underlying resource may or may not exist. 
190    * 
191    * @param resource the given resource
192    * @return a package fragment root for the given resource, which
193    * must either be a folder representing the top of a package hierarchy,
194    * or a <code>.jar</code> or <code>.zip</code> file
195    */
196   // IPackageFragmentRoot getPackageFragmentRoot(IResource resource);
197
198   /**
199    * Returns all of the  package fragment roots contained in this
200    * project, identified on this project's resolved classpath. The result
201    * does not include package fragment roots in other projects referenced
202    * on this project's classpath.
203    *
204    * <p>NOTE: This is equivalent to <code>getChildren()</code>.
205    *
206    * @return all of the  package fragment roots contained in this
207    * project, identified on this project's resolved classpath
208    * @exception JavaModelException if this element does not exist or if an
209    *            exception occurs while accessing its corresponding resource
210    */
211   // IPackageFragmentRoot[] getPackageFragmentRoots() throws JavaModelException;
212
213   /**
214    * Returns the existing package fragment roots identified by the given entry.
215    * Note that a classpath entry that refers to another project may
216    * have more than one root (if that project has more than on root
217    * containing source), and classpath entries within the current
218    * project identify a single root.
219    * <p>
220    * If the classpath entry denotes a variable, it will be resolved and return
221    * the roots of the target entry (empty if not resolvable).
222    * <p>
223    * If the classpath entry denotes a container, it will be resolved and return
224    * the roots corresponding to the set of container entries (empty if not resolvable).
225    * 
226    * @param entry the given entry
227    * @return the existing package fragment roots identified by the given entry
228    * @see IClasspathContainer
229    */
230   // IPackageFragmentRoot[] getPackageFragmentRoots(IClasspathEntry entry);
231
232   /**
233    * Returns all package fragments in all package fragment roots contained
234    * in this project. This is a convenience method.
235    *
236    * Note that the package fragment roots corresponds to the resolved
237    * classpath of the project.
238    *
239    * @return all package fragments in all package fragment roots contained
240    * in this project
241    * @exception JavaModelException if this element does not exist or if an
242    *            exception occurs while accessing its corresponding resource
243    */
244   // IPackageFragment[] getPackageFragments() throws JavaModelException;
245
246   /**
247    * Returns the <code>IProject</code> on which this <code>IJavaProject</code>
248    * was created. This is handle-only method.
249    * 
250    * @return the <code>IProject</code> on which this <code>IJavaProject</code>
251    * was created
252    */
253   IProject getProject();
254
255   /**
256    * This is a helper method returning the resolved classpath for the project, as a list of classpath entries, 
257    * where all classpath variable entries have been resolved and substituted with their final target entries.
258    * <p>
259    * A resolved classpath corresponds to a particular instance of the raw classpath bound in the context of 
260    * the current values of the referred variables, and thus should not be persisted.
261    * <p>
262    * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
263    * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
264    * can simply refer to some variables defining the proper locations of these external JARs.
265    * <p>
266    * The boolean argument <code>ignoreUnresolvedVariable</code> allows to specify how to handle unresolvable variables,
267    * when set to <code>true</code>, missing variables are simply ignored, the resulting path is then only formed of the
268    * resolvable entries, without any indication about which variable(s) was ignored. When set to <code>false</code>, a
269    * JavaModelException will be thrown for the first unresolved variable (from left to right).
270    * 
271    * @exception JavaModelException in one of the corresponding situation:
272    * <ul>
273    *    <li> this element does not exist </li>
274    *    <li> an exception occurs while accessing its corresponding resource </li>
275    *    <li> a classpath variable was not resolvable and <code>ignoreUnresolvedVariable</code> was set to <code>false</code>. </li>
276    * </ul>
277    * @return 
278    * @see IClasspathEntry 
279    */
280   //    IClasspathEntry[] getExpandedClasspath(boolean ignoreUnresolvedVariable)
281   //            throws JavaModelException;
282
283   /**
284    * Returns the raw classpath for the project, as a list of classpath entries. This corresponds to the exact set
285    * of entries which were assigned using <code>setRawClasspath</code>, in particular such a classpath may contain
286    * classpath variable entries. Classpath variable entries can be resolved individually (see <code>JavaCore#getClasspathVariable</code>),
287    * or the full classpath can be resolved at once using the helper method <code>getResolvedClasspath</code>.
288    * <p>
289    * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
290    * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
291    * can simply refer to some variables defining the proper locations of these external JARs.
292    *  <p>
293    * Note that in case the project isn't yet opened, the classpath will directly be read from the associated <tt>.classpath</tt> file.
294    * <p>
295    * 
296    * @return the raw classpath for the project, as a list of classpath entries
297    * @exception JavaModelException if this element does not exist or if an
298    *            exception occurs while accessing its corresponding resource
299    * @see IClasspathEntry
300    */
301   // IClasspathEntry[] getRawClasspath() throws JavaModelException;
302
303   /**
304    * Returns the names of the projects that are directly required by this
305    * project. A project is required if it is in its classpath.
306    *
307    * @return the names of the projects that are directly required by this
308    * project
309    * @exception JavaModelException if this element does not exist or if an
310    *            exception occurs while accessing its corresponding resource
311    */
312   String[] getRequiredProjectNames() throws JavaModelException;
313
314   /**
315    * This is a helper method returning the resolved classpath for the project, as a list of classpath entries, 
316    * where all classpath variable entries have been resolved and substituted with their final target entries.
317    * <p>
318    * A resolved classpath corresponds to a particular instance of the raw classpath bound in the context of 
319    * the current values of the referred variables, and thus should not be persisted.
320    * <p>
321    * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
322    * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
323    * can simply refer to some variables defining the proper locations of these external JARs.
324    * <p>
325    * The boolean argument <code>ignoreUnresolvedVariable</code> allows to specify how to handle unresolvable variables,
326    * when set to <code>true</code>, missing variables are simply ignored, the resulting path is then only formed of the
327    * resolvable entries, without any indication about which variable(s) was ignored. When set to <code>false</code>, a
328    * JavaModelException will be thrown for the first unresolved variable (from left to right).
329    * 
330    * @param ignoreUnresolvedVariable specify how to handle unresolvable variables
331    * @return the resolved classpath for the project, as a list of classpath entries, 
332    * where all classpath variable entries have been resolved and substituted with their final target entries
333    * @exception JavaModelException in one of the corresponding situation:
334    * <ul>
335    *    <li> this element does not exist </li>
336    *    <li> an exception occurs while accessing its corresponding resource </li>
337    *    <li> a classpath variable was not resolvable and <code>ignoreUnresolvedVariable</code> was set to <code>false</code>. </li>
338    * </ul>
339    * @see IClasspathEntry 
340    */
341   // IClasspathEntry[] getResolvedClasspath(boolean ignoreUnresolvedVariable) throws JavaModelException;
342
343   /**
344    * Returns whether this project has been built at least once and thus whether it has a build state.
345    * @return true if this project has been built at least once, false otherwise
346    */
347   boolean hasBuildState();
348
349   /**
350    * Returns whether setting this project's classpath to the given classpath entries
351    * would result in a cycle.
352    *
353    * If the set of entries contains some variables, those are resolved in order to determine
354    * cycles.
355    * 
356    * @param entries the given classpath entries
357    * @return true if the given classpath entries would result in a cycle, false otherwise
358    */
359   // boolean hasClasspathCycle(IClasspathEntry[] entries);
360   /**
361    * Returns whether the given element is on the classpath of this project.
362    * 
363    * @param element the given element
364    * @exception JavaModelException if this element does not exist or if an
365    *            exception occurs while accessing its corresponding resource
366    * @return true if the given element is on the classpath of this project, false otherwise
367    * @since 2.0
368    */
369   boolean isOnClasspath(IJavaElement element) throws JavaModelException;
370
371   /**
372    * Creates a new evaluation context.
373    * @return a new evaluation context.
374    */
375   // IEvaluationContext newEvaluationContext();
376
377   /**
378    * Creates and returns a type hierarchy for all types in the given
379    * region, considering subtypes within that region.
380    *
381    * @param monitor the given progress monitor
382    * @param region the given region
383    * @exception JavaModelException if this element does not exist or if an
384    *            exception occurs while accessing its corresponding resource
385    * @exception IllegalArgumentException if region is <code>null</code>
386    * @return a type hierarchy for all types in the given
387    * region, considering subtypes within that region
388    */
389   //    ITypeHierarchy newTypeHierarchy(IRegion region, IProgressMonitor monitor)
390   //            throws JavaModelException;
391
392   /**
393    * Creates and returns a type hierarchy for the given type considering
394    * subtypes in the specified region.
395    * 
396    * @param monitor the given monitor
397    * @param region the given region
398    * @param type the given type
399    * 
400    * @exception JavaModelException if this element does not exist or if an
401    *            exception occurs while accessing its corresponding resource
402    *
403    * @exception IllegalArgumentException if type or region is <code>null</code>
404    * @return a type hierarchy for the given type considering
405    * subtypes in the specified region
406    */
407   //    ITypeHierarchy newTypeHierarchy(
408   //            IType type,
409   //            IRegion region,
410   //            IProgressMonitor monitor)
411   //            throws JavaModelException;
412
413   /**
414    * Sets the output location of this project to the location
415    * described by the given absolute path.
416    * <p>
417    *
418    * @param path the given absolute path
419    * @param monitor the given progress monitor
420    * 
421    * @exception JavaModelException if the classpath could not be set. Reasons include:
422    * <ul>
423    *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
424    *    <li>The path refers to a location not contained in this project (<code>PATH_OUTSIDE_PROJECT</code>)
425    *    <li>The path is not an absolute path (<code>RELATIVE_PATH</code>)
426    *  <li>The path is nested inside a package fragment root of this project (<code>INVALID_PATH</code>)
427    *  <li> The output location is being modified during resource change event notification (CORE_EXCEPTION)      
428    * </ul>
429    */
430   void setOutputLocation(IPath path, IProgressMonitor monitor) throws JavaModelException;
431
432   /**
433    * Sets the classpath of this project using a list of classpath entries. In particular such a classpath may contain
434    * classpath variable entries. Classpath variable entries can be resolved individually (see <code>JavaCore#getClasspathVariable</code>),
435    * or the full classpath can be resolved at once using the helper method <code>getResolvedClasspath</code>.
436    * <p>
437    * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
438    * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
439    * can simply refer to some variables defining the proper locations of these external JARs.
440    * <p>
441    * Setting the classpath to <code>null</code> specifies a default classpath
442    * (the project root). Setting the classpath to an empty array specifies an
443    * empty classpath.
444    * <p>
445    * If a cycle is detected while setting this classpath, an error marker will be added
446    * to the project closing the cycle.
447    * To avoid this problem, use <code>hasClasspathCycle(IClasspathEntry[] entries)</code>
448    * before setting the classpath.
449    *
450    * @param entries a list of classpath entries
451    * @param monitor the given progress monitor
452    * @exception JavaModelException if the classpath could not be set. Reasons include:
453    * <ul>
454    * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
455    * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
456    * <li> The classpath failed the validation check as defined by <code>JavaConventions#validateClasspath</code>
457    * </ul>
458    * @see IClasspathEntry
459    */
460   //    void setRawClasspath(IClasspathEntry[] entries, IProgressMonitor monitor)
461   //            throws JavaModelException;
462
463   /**
464    * Sets the both the classpath of this project and its output location at once.
465    * The classpath is defined using a list of classpath entries. In particular such a classpath may contain
466    * classpath variable entries. Classpath variable entries can be resolved individually (see <code>JavaCore#getClasspathVariable</code>),
467    * or the full classpath can be resolved at once using the helper method <code>getResolvedClasspath</code>.
468    * <p>
469    * A classpath variable provides an indirection level for better sharing a classpath. As an example, it allows
470    * a classpath to no longer refer directly to external JARs located in some user specific location. The classpath
471    * can simply refer to some variables defining the proper locations of these external JARs.
472    * <p>
473    * Setting the classpath to <code>null</code> specifies a default classpath
474    * (the project root). Setting the classpath to an empty array specifies an
475    * empty classpath.
476    * <p>
477    * If a cycle is detected while setting this classpath, an error marker will be added
478    * to the project closing the cycle.
479    * To avoid this problem, use <code>hasClasspathCycle(IClasspathEntry[] entries)</code>
480    * before setting the classpath.
481    *
482    * @param entries a list of classpath entries
483    * @param monitor the given progress monitor
484    * @param outputLocation the given output location
485    * 
486    * @exception JavaModelException if the classpath could not be set. Reasons include:
487    * <ul>
488    * <li> This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
489    * <li> Two or more entries specify source roots with the same or overlapping paths (NAME_COLLISION)
490    * <li> A entry of kind <code>CPE_PROJECT</code> refers to this project (INVALID_PATH)
491    *  <li>This Java element does not exist (ELEMENT_DOES_NOT_EXIST)</li>
492    *    <li>The output location path refers to a location not contained in this project (<code>PATH_OUTSIDE_PROJECT</code>)
493    *    <li>The output location path is not an absolute path (<code>RELATIVE_PATH</code>)
494    *  <li>The output location path is nested inside a package fragment root of this project (<code>INVALID_PATH</code>)
495    * <li> The classpath is being modified during resource change event notification (CORE_EXCEPTION)
496    * </ul>
497    * @see IClasspathEntry
498    * @since 2.0
499    */
500   //    void setRawClasspath(IClasspathEntry[] entries, IPath outputLocation, IProgressMonitor monitor)
501   //            throws JavaModelException;
502 }