IJavaElement


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