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
9 * IBM Corporation - initial API and implementation
10 *******************************************************************************/
11 package net.sourceforge.phpdt.core;
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;
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.
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.
32 * This interface is not intended to be implemented by clients.
35 public interface IJavaElement extends IAdaptable {
38 * Constant representing a Java model (workspace level object). A Java
39 * element with this type can be safely cast to <code>IJavaModel</code>.
44 * Constant representing a Java project. A Java element with this type can
45 * be safely cast to <code>IJavaProject</code>.
50 * Constant representing a package fragment root. A Java element with this
51 * type can be safely cast to <code>IPackageFragmentRoot</code>.
53 int PACKAGE_FRAGMENT_ROOT = 3;
56 * Constant representing a package fragment. A Java element with this type
57 * can be safely cast to <code>IPackageFragment</code>.
59 int PACKAGE_FRAGMENT = 4;
62 * Constant representing a Java compilation unit. A Java element with this
63 * type can be safely cast to <code>ICompilationUnit</code>.
65 int COMPILATION_UNIT = 5;
68 * Constant representing a class file. A Java element with this type can be
69 * safely cast to <code>IClassFile</code>.
74 * Constant representing a type (a class or interface). A Java element with
75 * this type can be safely cast to <code>IType</code>.
80 * Constant representing a field. A Java element with this type can be
81 * safely cast to <code>IField</code>.
86 * Constant representing a method or constructor. A Java element with this
87 * type can be safely cast to <code>IMethod</code>.
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>.
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>.
102 int PACKAGE_DECLARATION = 11;
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>.
109 int IMPORT_CONTAINER = 12;
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>.
116 int IMPORT_DECLARATION = 13;
119 * Constant representing a local variable declaration. A Java element with
120 * this type can be safely cast to <code>ILocalVariable</code>.
124 int LOCAL_VARIABLE = 14;
127 * Returns whether this Java element exists in the model.
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).
143 * @return <code>true</code> if this element exists in the Java model, and
144 * <code>false</code> if this element does not exist
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.
153 * @param ancestorType
155 * @return the first ancestor of this Java element that has the given type,
156 * null if no such an ancestor can be found
159 IJavaElement getAncestor(int ancestorType);
162 * Returns the resource that corresponds directly to this element, or
163 * <code>null</code> if there is no resource that corresponds to this
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.
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
180 IResource getCorrespondingResource() throws JavaModelException;
183 * Returns the name of this element. This is a handle-only method.
185 * @return the element name
187 String getElementName();
190 * Returns this element's kind encoded as an integer. This is a handle-only
193 * @return the kind of element; one of the constants declared in
194 * <code>IJavaElement</code>
197 int getElementType();
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.
205 * @return the string handle identifier
206 * @see JavaCore#create(java.lang.String)
208 String getHandleIdentifier();
211 * Returns the Java model. This is a handle-only method.
213 * @return the Java model
215 IJavaModel getJavaModel();
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.
223 * @return the containing Java project, or <code>null</code> if this
224 * element is not contained in a Java project
226 IJavaProject getJavaProject();
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.
233 * @return the first openable parent or <code>null</code> if this element
234 * doesn't have an openable parent.
237 IOpenable getOpenable();
240 * Returns the element directly containing this element, or
241 * <code>null</code> if this element has no parent. This is a handle-only
244 * @return the parent element, or <code>null</code> if this element has no
247 IJavaElement getParent();
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.
257 * @return the path to the innermost resource enclosing this element
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.
269 * @return the primary element this working copy element was created from,
273 IJavaElement getPrimaryElement();
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.
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
288 IResource getResource();
291 * Returns the scheduling rule associated with this Java element. This is a
292 * handle-only method.
294 * @return the scheduling rule associated with this Java element
297 ISchedulingRule getSchedulingRule();
300 * Returns the smallest underlying resource that contains this element, or
301 * <code>null</code> if this element is not contained in a resource.
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
308 IResource getUnderlyingResource() throws JavaModelException;
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.
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.
318 * This is a handle-only method.
320 * @return <code>true</code> if this element is read-only
322 boolean isReadOnly();
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.
331 * Note: This does not imply anything about consistency with the underlying
332 * resource/buffer contents.
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
340 boolean isStructureKnown() throws JavaModelException;