0f4693ac7824618681d206dd0339d2cec4c57c48
[phpeclipse.git] / 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 }