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 }