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