net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/core/IJavaElement.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.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         public static final 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         public static final 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         public static final 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         public static final 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         public static final 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         public static final 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         public static final 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         public static final 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         public static final 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         public static final 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         public static final 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         public static final 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         public static final int IMPORT_DECLARATION = 13;
 112
 113 /**
 114  * Returns whether this Java element exists in the model.
 115  *
 116  * @return <code>true</code> if this element exists in the Java model
 117  */
 118 boolean exists();
 119 /**
 120  * Returns the first ancestor of this Java element that has the given type.
 121  * Returns <code>null</code> if no such an ancestor can be found.
 122  * This is a handle-only method.
 123  *
 124  * @param ancestorType the given type
 125  * @return the first ancestor of this Java element that has the given type, null if no such an ancestor can be found
 126  * @since 2.0
 127  */
 128 IJavaElement getAncestor(int ancestorType);
 129 /**
 130  * Returns the resource that corresponds directly to this element,
 131  * or <code>null</code> if there is no resource that corresponds to
 132  * this element.
 133  * <p>
 134  * For example, the corresponding resource for an <code>ICompilationUnit</code>
 135  * is its underlying <code>IFile</code>. The corresponding resource for
 136  * an <code>IPackageFragment</code> that is not contained in an archive
 137  * is its underlying <code>IFolder</code>. An <code>IPackageFragment</code>
 138  * contained in an archive has no corresponding resource. Similarly, there
 139  * are no corresponding resources for <code>IMethods</code>,
 140  * <code>IFields</code>, etc.
 141  * <p>
 142  *
 143  * @return the corresponding resource, or <code>null</code> if none
 144  * @exception JavaModelException if this element does not exist or if an
 145  *              exception occurs while accessing its corresponding resource
 146  */
 147 IResource getCorrespondingResource() throws JavaModelException;
 148 /**
 149  * Returns the name of this element. This is a handle-only method.
 150  *
 151  * @return the element name
 152  */
 153 String getElementName();
 154 /**
 155  * Returns this element's kind encoded as an integer.
 156  * This is a handle-only method.
 157  *
 158  * @return the kind of element; one of the constants declared in
 159  *   <code>IJavaElement</code>
 160  * @see IJavaElement
 161  */
 162 public int getElementType();
 163 /**
 164  * Returns a string representation of this element handle. The format of
 165  * the string is not specified; however, the identifier is stable across
 166  * workspace sessions, and can be used to recreate this handle via the
 167  * <code>JavaCore.create(String)</code> method.
 168  *
 169  * @return the string handle identifier
 170  * @see JavaCore#create(java.lang.String)
 171  */
 172 String getHandleIdentifier();
 173 /**
 174  * Returns the Java model.
 175  * This is a handle-only method.
 176  *
 177  * @return the Java model
 178  */
 179 IJavaModel getJavaModel();
 180 /**
 181  * Returns the Java project this element is contained in,
 182  * or <code>null</code> if this element is not contained in any Java project
 183  * (for instance, the <code>IJavaModel</code> is not contained in any Java
 184  * project).
 185  * This is a handle-only method.
 186  *
 187  * @return the containing Java project, or <code>null</code> if this element is
 188  *   not contained in a Java project
 189  */
 190 IJavaProject getJavaProject();
 191 /**
 192  * Returns the first openable parent. If this element is openable, the element
 193  * itself is returned. Returns <code>null</code> if this element doesn't have
 194  * an openable parent.
 195  * This is a handle-only method.
 196  *
 197  * @return the first openable parent or <code>null</code> if this element doesn't have
 198  * an openable parent.
 199  * @since 2.0
 200  */
 201 IOpenable getOpenable();
 202 /**
 203  * Returns the element directly containing this element,
 204  * or <code>null</code> if this element has no parent.
 205  * This is a handle-only method.
 206  *
 207  * @return the parent element, or <code>null</code> if this element has no parent
 208  */
 209 IJavaElement getParent();
 210 /**
 211  * Returns the path to the innermost resource enclosing this element.
 212  * If this element is not included in an external archive,
 213  * the path returned is the full, absolute path to the underlying resource,
 214  * relative to the workbench.
 215  * If this element is included in an external archive,
 216  * the path returned is the absolute path to the archive in the file system.
 217  * This is a handle-only method.
 218  *
 219  * @return the path to the innermost resource enclosing this element
 220  * @since 2.0
 221  */
 222 IPath getPath();
 223 /**
 224  * Returns the innermost resource enclosing this element.
 225  * If this element is included in an archive and this archive is not external,
 226  * this is the underlying resource corresponding to the archive.
 227  * If this element is included in an external archive, <code>null</code>
 228  * is returned.
 229  * If this element is a working copy, <code>null</code> is returned.
 230  * This is a handle-only method.
 231  *
 232  * @return the innermost resource enclosing this element, <code>null</code> if this
 233  * element is a working copy or is included in an external archive
 234  * @since 2.0
 235  */
 236 IResource getResource();
 237 /**
 238  * Returns the smallest underlying resource that contains
 239  * this element, or <code>null</code> if this element is not contained
 240  * in a resource.
 241  *
 242  * @return the underlying resource, or <code>null</code> if none
 243  * @exception JavaModelException if this element does not exist or if an
 244  *              exception occurs while accessing its underlying resource
 245  */
 246 IResource getUnderlyingResource() throws JavaModelException;
 247 /**
 248  * Returns whether this Java element is read-only. An element is read-only
 249  * if its structure cannot be modified by the java model.
 250  * <p>
 251  * Note this is different from IResource.isReadOnly(). For example, .jar
 252  * files are read-only as the java model doesn't know how to add/remove
 253  * elements in this file, but the underlying IFile can be writable.
 254  * <p>
 255  * This is a handle-only method.
 256  *
 257  * @return <code>true</code> if this element is read-only
 258  */
 259 boolean isReadOnly();
 260 /**
 261  * Returns whether the structure of this element is known. For example, for a
 262  * compilation unit that could not be parsed, <code>false</code> is returned.
 263  * If the structure of an element is unknown, navigations will return reasonable
 264  * defaults. For example, <code>getChildren</code> will return an empty collection.
 265  * <p>
 266  * Note: This does not imply anything about consistency with the
 267  * underlying resource/buffer contents.
 268  * </p>
 269  *
 270  * @return <code>true</code> if the structure of this element is known
 271  * @exception JavaModelException if this element does not exist or if an
 272  *              exception occurs while accessing its corresponding resource
 273  */
 274 boolean isStructureKnown() throws JavaModelException;
 275 }