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