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