net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IJavaElement.java

   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
   7  *
   8  * Contributors:
   9  *     IBM Corporation - initial API and implementation
  10  *******************************************************************************/
  11 package net.sourceforge.phpdt.core;
  12
  13 import org.eclipse.core.resources.IResource;
  14 import org.eclipse.core.runtime.IAdaptable;
  15 import org.eclipse.core.runtime.IPath;
  16 import org.eclipse.core.runtime.jobs.ISchedulingRule;
  17
  18 /**
  19  * Common protocol for all elements provided by the Java model.
  20  * Java model elements are exposed to clients as handles to the actual underlying element.
  21  * The Java model may hand out any number of handles for each element. Handles
  22  * that refer to the same element are guaranteed to be equal, but not necessarily identical.
  23  * <p>
  24  * Methods annotated as "handle-only" do not require underlying elements to exist.
  25  * Methods that require underlying elements to exist throw
  26  * a <code>JavaModelException</code> when an underlying element is missing.
  27  * <code>JavaModelException.isDoesNotExist</code> can be used to recognize
  28  * this common special case.
  29  * </p>
  30  * <p>
  31  * This interface is not intended to be implemented by clients.
  32  * </p>
  33  */
  34 public interface IJavaElement extends IAdaptable {
  35
  36         /**
  37          * Constant representing a Java model (workspace level object).
  38          * A Java element with this type can be safely cast to <code>IJavaModel</code>.
  39          */
  40         int JAVA_MODEL = 1;
  41
  42         /**
  43          * Constant representing a Java project.
  44          * A Java element with this type can be safely cast to <code>IJavaProject</code>.
  45          */
  46         int JAVA_PROJECT = 2;
  47
  48         /**
  49          * Constant representing a package fragment root.
  50          * A Java element with this type can be safely cast to <code>IPackageFragmentRoot</code>.
  51          */
  52         int PACKAGE_FRAGMENT_ROOT = 3;
  53
  54         /**
  55          * Constant representing a package fragment.
  56          * A Java element with this type can be safely cast to <code>IPackageFragment</code>.
  57          */
  58         int PACKAGE_FRAGMENT = 4;
  59
  60         /**
  61          * Constant representing a Java compilation unit.
  62          * A Java element with this type can be safely cast to <code>ICompilationUnit</code>.
  63          */
  64         int COMPILATION_UNIT = 5;
  65
  66         /**
  67          * Constant representing a class file.
  68          * A Java element with this type can be safely cast to <code>IClassFile</code>.
  69          */
  70         int CLASS_FILE = 6;
  71
  72         /**
  73          * Constant representing a type (a class or interface).
  74          * A Java element with this type can be safely cast to <code>IType</code>.
  75          */
  76         int TYPE = 7;
  77
  78         /**
  79          * Constant representing a field.
  80          * A Java element with this type can be safely cast to <code>IField</code>.
  81          */
  82         int FIELD = 8;
  83
  84         /**
  85          * Constant representing a method or constructor.
  86          * A Java element with this type can be safely cast to <code>IMethod</code>.
  87          */
  88         int METHOD = 9;
  89
  90         /**
  91          * Constant representing a stand-alone instance or class initializer.
  92          * A Java element with this type can be safely cast to <code>IInitializer</code>.
  93          */
  94         int INITIALIZER = 10;
  95
  96         /**
  97          * Constant representing a package declaration within a compilation unit.
  98          * A Java element with this type can be safely cast to <code>IPackageDeclaration</code>.
  99          */
 100         int PACKAGE_DECLARATION = 11;
 101
 102         /**
 103          * Constant representing all import declarations within a compilation unit.
 104          * A Java element with this type can be safely cast to <code>IImportContainer</code>.
 105          */
 106         int IMPORT_CONTAINER = 12;
 107
 108         /**
 109          * Constant representing an import declaration within a compilation unit.
 110          * A Java element with this type can be safely cast to <code>IImportDeclaration</code>.
 111          */
 112         int IMPORT_DECLARATION = 13;
 113
 114         /**
 115          * Constant representing a local variable declaration.
 116          * A Java element with this type can be safely cast to <code>ILocalVariable</code>.
 117          * @since 3.0
 118          */
 119         int LOCAL_VARIABLE = 14;
 120         /**
 121          * Returns whether this Java element exists in the model.
 122          * <p>
 123          * Java elements are handle objects that may or may not be backed by an
 124          * actual element. Java elements that are backed by an actual element are
 125          * said to "exist", and this method returns <code>true</code>. For Java
 126          * elements that are not working copies, it is always the case that if the
 127          * element exists, then its parent also exists (provided it has one) and
 128          * includes the element as one of its children. It is therefore possible
 129          * to navigated to any existing Java element from the root of the Java model
 130          * along a chain of existing Java elements. On the other hand, working
 131          * copies are said to exist until they are destroyed (with
 132          * <code>IWorkingCopy.destroy</code>). Unlike regular Java elements, a
 133          * working copy never shows up among the children of its parent element
 134          * (which may or may not exist).
 135          * </p>
 136          *
 137          * @return <code>true</code> if this element exists in the Java model, and
 138          * <code>false</code> if this element does not exist
 139          */
 140         boolean exists();
 141
 142         /**
 143          * Returns the first ancestor of this Java element that has the given type.
 144          * Returns <code>null</code> if no such an ancestor can be found.
 145          * This is a handle-only method.
 146          *
 147          * @param ancestorType the given type
 148          * @return the first ancestor of this Java element that has the given type, null if no such an ancestor can be found
 149          * @since 2.0
 150          */
 151         IJavaElement getAncestor(int ancestorType);
 152
 153         /**
 154          * Returns the resource that corresponds directly to this element,
 155          * or <code>null</code> if there is no resource that corresponds to
 156          * this element.
 157          * <p>
 158          * For example, the corresponding resource for an <code>ICompilationUnit</code>
 159          * is its underlying <code>IFile</code>. The corresponding resource for
 160          * an <code>IPackageFragment</code> that is not contained in an archive
 161          * is its underlying <code>IFolder</code>. An <code>IPackageFragment</code>
 162          * contained in an archive has no corresponding resource. Similarly, there
 163          * are no corresponding resources for <code>IMethods</code>,
 164          * <code>IFields</code>, etc.
 165          * <p>
 166          *
 167          * @return the corresponding resource, or <code>null</code> if none
 168          * @exception JavaModelException if this element does not exist or if an
 169          *              exception occurs while accessing its corresponding resource
 170          */
 171         IResource getCorrespondingResource() throws JavaModelException;
 172
 173         /**
 174          * Returns the name of this element. This is a handle-only method.
 175          *
 176          * @return the element name
 177          */
 178         String getElementName();
 179
 180         /**
 181          * Returns this element's kind encoded as an integer.
 182          * This is a handle-only method.
 183          *
 184          * @return the kind of element; one of the constants declared in
 185          *   <code>IJavaElement</code>
 186          * @see IJavaElement
 187          */
 188         int getElementType();
 189
 190         /**
 191          * Returns a string representation of this element handle. The format of
 192          * the string is not specified; however, the identifier is stable across
 193          * workspace sessions, and can be used to recreate this handle via the
 194          * <code>JavaCore.create(String)</code> method.
 195          *
 196          * @return the string handle identifier
 197          * @see JavaCore#create(java.lang.String)
 198          */
 199         String getHandleIdentifier();
 200
 201         /**
 202          * Returns the Java model.
 203          * This is a handle-only method.
 204          *
 205          * @return the Java model
 206          */
 207          IJavaModel getJavaModel();
 208
 209         /**
 210          * Returns the Java project this element is contained in,
 211          * or <code>null</code> if this element is not contained in any Java project
 212          * (for instance, the <code>IJavaModel</code> is not contained in any Java
 213          * project).
 214          * This is a handle-only method.
 215          *
 216          * @return the containing Java project, or <code>null</code> if this element is
 217          *   not contained in a Java project
 218          */
 219         IJavaProject getJavaProject();
 220
 221         /**
 222          * Returns the first openable parent. If this element is openable, the element
 223          * itself is returned. Returns <code>null</code> if this element doesn't have
 224          * an openable parent.
 225          * This is a handle-only method.
 226          *
 227          * @return the first openable parent or <code>null</code> if this element doesn't have
 228          * an openable parent.
 229          * @since 2.0
 230          */
 231         IOpenable getOpenable();
 232
 233         /**
 234          * Returns the element directly containing this element,
 235          * or <code>null</code> if this element has no parent.
 236          * This is a handle-only method.
 237          *
 238          * @return the parent element, or <code>null</code> if this element has no parent
 239          */
 240         IJavaElement getParent();
 241
 242         /**
 243          * Returns the path to the innermost resource enclosing this element.
 244          * If this element is not included in an external archive,
 245          * the path returned is the full, absolute path to the underlying resource,
 246          * relative to the workbench.
 247          * If this element is included in an external archive,
 248          * the path returned is the absolute path to the archive in the file system.
 249          * This is a handle-only method.
 250          *
 251          * @return the path to the innermost resource enclosing this element
 252          * @since 2.0
 253          */
 254         IPath getPath();
 255         /**
 256          * Returns the primary element (whose compilation unit is the primary compilation unit)
 257          * this working copy element was created from, or this element if it is a descendant of a
 258          * primary compilation unit or if it is not a descendant of a working copy (e.g. it is a
 259          * binary member).
 260          * The returned element may or may not exist.
 261          *
 262          * @return the primary element this working copy element was created from, or this
 263          *                      element.
 264          * @since 3.0
 265          */
 266         IJavaElement getPrimaryElement();
 267         /**
 268          * Returns the innermost resource enclosing this element.
 269          * If this element is included in an archive and this archive is not external,
 270          * this is the underlying resource corresponding to the archive.
 271          * If this element is included in an external archive, <code>null</code>
 272          * is returned.
 273          * If this element is a working copy, <code>null</code> is returned.
 274          * This is a handle-only method.
 275          *
 276          * @return the innermost resource enclosing this element, <code>null</code> if this
 277          * element is a working copy or is included in an external archive
 278          * @since 2.0
 279          */
 280         IResource getResource();
 281         /**
 282          * Returns the scheduling rule associated with this Java element.
 283          * This is a handle-only method.
 284          *
 285          * @return the scheduling rule associated with this Java element
 286          * @since 3.0
 287          */
 288         ISchedulingRule getSchedulingRule();
 289         /**
 290          * Returns the smallest underlying resource that contains
 291          * this element, or <code>null</code> if this element is not contained
 292          * in a resource.
 293          *
 294          * @return the underlying resource, or <code>null</code> if none
 295          * @exception JavaModelException if this element does not exist or if an
 296          *              exception occurs while accessing its underlying resource
 297          */
 298         IResource getUnderlyingResource() throws JavaModelException;
 299
 300         /**
 301          * Returns whether this Java element is read-only. An element is read-only
 302          * if its structure cannot be modified by the java model.
 303          * <p>
 304          * Note this is different from IResource.isReadOnly(). For example, .jar
 305          * files are read-only as the java model doesn't know how to add/remove
 306          * elements in this file, but the underlying IFile can be writable.
 307          * <p>
 308          * This is a handle-only method.
 309          *
 310          * @return <code>true</code> if this element is read-only
 311          */
 312         boolean isReadOnly();
 313
 314         /**
 315          * Returns whether the structure of this element is known. For example, for a
 316          * compilation unit that could not be parsed, <code>false</code> is returned.
 317          * If the structure of an element is unknown, navigations will return reasonable
 318          * defaults. For example, <code>getChildren</code> will return an empty collection.
 319          * <p>
 320          * Note: This does not imply anything about consistency with the
 321          * underlying resource/buffer contents.
 322          * </p>
 323          *
 324          * @return <code>true</code> if the structure of this element is known
 325          * @exception JavaModelException if this element does not exist or if an
 326          *              exception occurs while accessing its corresponding resource
 327          */
 328         boolean isStructureKnown() throws JavaModelException;
 329 }