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