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