org.eclipse.jdt/org.eclipse.jdt.core/3.20.0 : org/eclipse/jdt/core/IJavaElement.java

IJavaElement
http://www.eclipse.org/jdt: Java Development Tools Core (Eclipse Foundation)
Eclipse Public License - v 2.0
Copyright (c) 2000, 2017 IBM Corporation and others.
This program and the accompanying materials
are made available under the terms of the Eclipse Public License 2.0
which accompanies this distribution, and is available at
https://www.eclipse.org/legal/epl-2.0/
SPDX-License-Identifier: EPL-2.0
Contributors:
    IBM Corporation - initial API and implementation
/*******************************************************************************
 * Copyright (c) 2000, 2017 IBM Corporation and others.
 *
 * This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License 2.0
 * which accompanies this distribution, and is available at
 * https://www.eclipse.org/legal/epl-2.0/
 *
 * SPDX-License-Identifier: EPL-2.0
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jdt.core;

import org.eclipse.core.resources.IResource;
import org.eclipse.core.runtime.IAdaptable;
import org.eclipse.core.runtime.IPath;
import org.eclipse.core.runtime.IProgressMonitor;
import org.eclipse.core.runtime.jobs.ISchedulingRule;

Common protocol for all elements provided by the Java model.
Java model elements are exposed to clients as handles to the actual underlying element.
The Java model may hand out any number of handles for each element. Handles
that refer to the same element are guaranteed to be equal, but not necessarily identical.

Methods annotated as "handle-only" do not require underlying elements to exist.
Methods that require underlying elements to exist throw
a JavaModelException when an underlying element is missing.
JavaModelException.isDoesNotExist can be used to recognize
this common special case.

@noimplement This interface is not intended to be implemented by clients./**
 * Common protocol for all elements provided by the Java model.
 * Java model elements are exposed to clients as handles to the actual underlying element.
 * The Java model may hand out any number of handles for each element. Handles
 * that refer to the same element are guaranteed to be equal, but not necessarily identical.
 * <p>
 * Methods annotated as "handle-only" do not require underlying elements to exist.
 * Methods that require underlying elements to exist throw
 * a <code>JavaModelException</code> when an underlying element is missing.
 * <code>JavaModelException.isDoesNotExist</code> can be used to recognize
 * this common special case.
 * </p>
 * @noimplement This interface is not intended to be implemented by clients.
 */
public interface IJavaElement extends IAdaptable {

	Constant representing a Java model (workspace level object). A Java element with this type can be safely cast to IJavaModel. /**
	 * Constant representing a Java model (workspace level object).
	 * A Java element with this type can be safely cast to {@link IJavaModel}.
	 */
	int JAVA_MODEL = 1;

	Constant representing a Java project. A Java element with this type can be safely cast to IJavaProject. /**
	 * Constant representing a Java project.
	 * A Java element with this type can be safely cast to {@link IJavaProject}.
	 */
	int JAVA_PROJECT = 2;

	Constant representing a package fragment root. A Java element with this type can be safely cast to IPackageFragmentRoot. /**
	 * Constant representing a package fragment root.
	 * A Java element with this type can be safely cast to {@link IPackageFragmentRoot}.
	 */
	int PACKAGE_FRAGMENT_ROOT = 3;

	Constant representing a package fragment. A Java element with this type can be safely cast to IPackageFragment. /**
	 * Constant representing a package fragment.
	 * A Java element with this type can be safely cast to {@link IPackageFragment}.
	 */
	int PACKAGE_FRAGMENT = 4;

	Constant representing a Java compilation unit. A Java element with this type can be safely cast to ICompilationUnit. /**
	 * Constant representing a Java compilation unit.
	 * A Java element with this type can be safely cast to {@link ICompilationUnit}.
	 */
	int COMPILATION_UNIT = 5;

	Constant representing a class file. A Java element with this type can be safely cast to IClassFile. /**
	 * Constant representing a class file.
	 * A Java element with this type can be safely cast to {@link IClassFile}.
	 */
	int CLASS_FILE = 6;

	Constant representing a type (a class or interface). A Java element with this type can be safely cast to IType. /**
	 * Constant representing a type (a class or interface).
	 * A Java element with this type can be safely cast to {@link IType}.
	 */
	int TYPE = 7;

	Constant representing a field. A Java element with this type can be safely cast to IField. /**
	 * Constant representing a field.
	 * A Java element with this type can be safely cast to {@link IField}.
	 */
	int FIELD = 8;

	Constant representing a method or constructor. A Java element with this type can be safely cast to IMethod. /**
	 * Constant representing a method or constructor.
	 * A Java element with this type can be safely cast to {@link IMethod}.
	 */
	int METHOD = 9;

	Constant representing a stand-alone instance or class initializer. A Java element with this type can be safely cast to IInitializer. /**
	 * Constant representing a stand-alone instance or class initializer.
	 * A Java element with this type can be safely cast to {@link IInitializer}.
	 */
	int INITIALIZER = 10;

	Constant representing a package declaration within a compilation unit. A Java element with this type can be safely cast to IPackageDeclaration. /**
	 * Constant representing a package declaration within a compilation unit.
	 * A Java element with this type can be safely cast to {@link IPackageDeclaration}.
	 */
	int PACKAGE_DECLARATION = 11;

	Constant representing all import declarations within a compilation unit. A Java element with this type can be safely cast to IImportContainer. /**
	 * Constant representing all import declarations within a compilation unit.
	 * A Java element with this type can be safely cast to {@link IImportContainer}.
	 */
	int IMPORT_CONTAINER = 12;

	Constant representing an import declaration within a compilation unit. A Java element with this type can be safely cast to IImportDeclaration. /**
	 * Constant representing an import declaration within a compilation unit.
	 * A Java element with this type can be safely cast to {@link IImportDeclaration}.
	 */
	int IMPORT_DECLARATION = 13;

	Constant representing a local variable declaration. A Java element with this type can be safely cast to ILocalVariable. 
Since: 3.0/**
	 * Constant representing a local variable declaration.
	 * A Java element with this type can be safely cast to {@link ILocalVariable}.
	 * @since 3.0
	 */
	int LOCAL_VARIABLE = 14;

	Constant representing a type parameter declaration. A Java element with this type can be safely cast to ITypeParameter. 
Since: 3.1/**
	 * Constant representing a type parameter declaration.
	 * A Java element with this type can be safely cast to {@link ITypeParameter}.
	 * @since 3.1
	 */
	int TYPE_PARAMETER = 15;

	Constant representing an annotation. A Java element with this type can be safely cast to IAnnotation. 
Since: 3.4/**
	 * Constant representing an annotation.
	 * A Java element with this type can be safely cast to {@link IAnnotation}.
	 * @since 3.4
	 */
	int ANNOTATION = 16;

	Constant represents a module descriptor. A Java element with this type can be safely cast to IModuleDescription. 
Since: 3.14/**
	 * Constant represents a module descriptor.
	 * A Java element with this type can be safely cast to {@link IModuleDescription}.
	 *
	 * @since 3.14
	 */
	int JAVA_MODULE = 17;

	Returns whether this Java element exists in the model.

Java elements are handle objects that may or may not be backed by an
actual element. Java elements that are backed by an actual element are
said to "exist", and this method returns true. For Java
elements that are not working copies, it is always the case that if the
element exists, then its parent also exists (provided it has one) and
includes the element as one of its children. It is therefore possible
to navigated to any existing Java element from the root of the Java model
along a chain of existing Java elements. On the other hand, working
copies are said to exist until they are destroyed (with
IWorkingCopy.destroy). Unlike regular Java elements, a
working copy never shows up among the children of its parent element
(which may or may not exist).

Returns: true if this element exists in the Java model, and
false if this element does not exist/**
	 * Returns whether this Java element exists in the model.
	 * <p>
	 * Java elements are handle objects that may or may not be backed by an
	 * actual element. Java elements that are backed by an actual element are
	 * said to "exist", and this method returns <code>true</code>. For Java
	 * elements that are not working copies, it is always the case that if the
	 * element exists, then its parent also exists (provided it has one) and
	 * includes the element as one of its children. It is therefore possible
	 * to navigated to any existing Java element from the root of the Java model
	 * along a chain of existing Java elements. On the other hand, working
	 * copies are said to exist until they are destroyed (with
	 * <code>IWorkingCopy.destroy</code>). Unlike regular Java elements, a
	 * working copy never shows up among the children of its parent element
	 * (which may or may not exist).
	 * </p>
	 *
	 * @return <code>true</code> if this element exists in the Java model, and
	 * <code>false</code> if this element does not exist
	 */
	boolean exists();

	Returns this Java element or the first ancestor of this element that has the given type.
Returns null if no such element can be found.
This is a handle-only method.
Params: ancestorType – the given type
Returns: this Java element or the first ancestor of this element that has the given type, or null if no such element can be found
Since: 2.0/**
	 * Returns this Java element or the first ancestor of this element that has the given type.
	 * Returns <code>null</code> if no such element can be found.
	 * This is a handle-only method.
	 *
	 * @param ancestorType the given type
	 * @return this Java element or the first ancestor of this element that has the given type, or <code>null</code> if no such element can be found
	 * @since 2.0
	 */
	IJavaElement getAncestor(int ancestorType);

	Returns the Javadoc as HTML source if this element has attached Javadoc,
null otherwise.
This should be used only for binary elements. Source elements will always return null.
The encoding used to read the Javadoc is the one defined by the content type of the
file. If none is defined, then the project's encoding of this Java element is used. If the project's
encoding cannot be retrieved, then the platform encoding is used.
In case the Javadoc doesn't exist for this element, null is returned.
The HTML is extracted from the attached Javadoc and provided as is. No
transformation or validation is done.
Params: monitor – the given progress monitor, can be null
Throws: JavaModelException – if:
 this element does not exist
 retrieving the attached javadoc fails (timed-out, invalid URL, ...)
 the format of the javadoc doesn't match expected standards (different anchors,...)
 
See Also: IClasspathAttribute.JAVADOC_LOCATION_ATTRIBUTE_NAME
Returns: the extracted javadoc from the attached javadoc, null if none
Since: 3.2/**
	 * <p>Returns the Javadoc as HTML source if this element has attached Javadoc,
	 * <code>null</code> otherwise.</p>
	 * <p>This should be used only for binary elements. Source elements will always return <code>null</code>.</p>
	 * <p>The encoding used to read the Javadoc is the one defined by the content type of the
	 * file. If none is defined, then the project's encoding of this Java element is used. If the project's
	 * encoding cannot be retrieved, then the platform encoding is used.</p>
	 * <p>In case the Javadoc doesn't exist for this element, <code>null</code> is returned.</p>
	 *
	 * <p>The HTML is extracted from the attached Javadoc and provided as is. No
	 * transformation or validation is done.</p>
	 *
	 * @param monitor the given progress monitor, can be <code>null</code>
	 * @exception JavaModelException if:<ul>
	 *  <li>this element does not exist</li>
	 *  <li>retrieving the attached javadoc fails (timed-out, invalid URL, ...)</li>
	 *  <li>the format of the javadoc doesn't match expected standards (different anchors,...)</li>
	 *  </ul>
	 * @return the extracted javadoc from the attached javadoc, <code>null</code> if none
	 * @see IClasspathAttribute#JAVADOC_LOCATION_ATTRIBUTE_NAME
	 * @since 3.2
	 */
	String getAttachedJavadoc(IProgressMonitor monitor) throws JavaModelException;

	Returns the resource that corresponds directly to this element,
or null if there is no resource that corresponds to
this element.

For example, the corresponding resource for an ICompilationUnit
is its underlying IFile. The corresponding resource for
an IPackageFragment that is not contained in an archive
is its underlying IFolder. An IPackageFragment
contained in an archive has no corresponding resource. Similarly, there
are no corresponding resources for IMethods,
IFields, etc.

Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource
Returns: the corresponding resource, or null if none/**
	 * Returns the resource that corresponds directly to this element,
	 * or <code>null</code> if there is no resource that corresponds to
	 * this element.
	 * <p>
	 * For example, the corresponding resource for an <code>ICompilationUnit</code>
	 * is its underlying <code>IFile</code>. The corresponding resource for
	 * an <code>IPackageFragment</code> that is not contained in an archive
	 * is its underlying <code>IFolder</code>. An <code>IPackageFragment</code>
	 * contained in an archive has no corresponding resource. Similarly, there
	 * are no corresponding resources for <code>IMethods</code>,
	 * <code>IFields</code>, etc.
	 * <p>
	 *
	 * @return the corresponding resource, or <code>null</code> if none
	 * @exception JavaModelException if this element does not exist or if an
	 *		exception occurs while accessing its corresponding resource
	 */
	IResource getCorrespondingResource() throws JavaModelException;

	Returns the name of this element. This is a handle-only method.
Returns: the element name/**
	 * Returns the name of this element. This is a handle-only method.
	 *
	 * @return the element name
	 */
	String getElementName();

	Returns this element's kind encoded as an integer.
This is a handle-only method.
See Also: IJavaElement
Returns: the kind of element; one of the constants declared in
  IJavaElement/**
	 * Returns this element's kind encoded as an integer.
	 * This is a handle-only method.
	 *
	 * @return the kind of element; one of the constants declared in
	 *   <code>IJavaElement</code>
	 * @see IJavaElement
	 */
	int getElementType();

	Returns a string representation of this element handle. The format of
the string is not specified; however, the identifier is stable across
workspace sessions, and can be used to recreate this handle via the
JavaCore.create(String) method.
See Also: JavaCore.create(String)
Returns: the string handle identifier/**
	 * Returns a string representation of this element handle. The format of
	 * the string is not specified; however, the identifier is stable across
	 * workspace sessions, and can be used to recreate this handle via the
	 * <code>JavaCore.create(String)</code> method.
	 *
	 * @return the string handle identifier
	 * @see JavaCore#create(java.lang.String)
	 */
	String getHandleIdentifier();

	Returns the Java model.
This is a handle-only method.
Returns: the Java model/**
	 * Returns the Java model.
	 * This is a handle-only method.
	 *
	 * @return the Java model
	 */
	IJavaModel getJavaModel();

	Returns the Java project this element is contained in,
or null if this element is not contained in any Java project
(for instance, the IJavaModel is not contained in any Java
project).
This is a handle-only method.
Returns: the containing Java project, or null if this element is
  not contained in a Java project/**
	 * Returns the Java project this element is contained in,
	 * or <code>null</code> if this element is not contained in any Java project
	 * (for instance, the <code>IJavaModel</code> is not contained in any Java
	 * project).
	 * This is a handle-only method.
	 *
	 * @return the containing Java project, or <code>null</code> if this element is
	 *   not contained in a Java project
	 */
	IJavaProject getJavaProject();

	Returns the first openable parent. If this element is openable, the element
itself is returned. Returns null if this element doesn't have
an openable parent.
This is a handle-only method.
Returns: the first openable parent or null if this element doesn't have
an openable parent.
Since: 2.0/**
	 * Returns the first openable parent. If this element is openable, the element
	 * itself is returned. Returns <code>null</code> if this element doesn't have
	 * an openable parent.
	 * This is a handle-only method.
	 *
	 * @return the first openable parent or <code>null</code> if this element doesn't have
	 * an openable parent.
	 * @since 2.0
	 */
	IOpenable getOpenable();

	Returns the element directly containing this element,
or null if this element has no parent.
This is a handle-only method.
Returns: the parent element, or null if this element has no parent/**
	 * Returns the element directly containing this element,
	 * or <code>null</code> if this element has no parent.
	 * This is a handle-only method.
	 *
	 * @return the parent element, or <code>null</code> if this element has no parent
	 */
	IJavaElement getParent();

	Returns the path to the innermost resource enclosing this element.
If this element is not included in an external library,
the path returned is the full, absolute path to the underlying resource,
relative to the workbench.
If this element is included in an external library,
the path returned is the absolute path to the archive or to the
folder in the file system.
This is a handle-only method.
Returns: the path to the innermost resource enclosing this element
Since: 2.0/**
	 * Returns the path to the innermost resource enclosing this element.
	 * If this element is not included in an external library,
	 * the path returned is the full, absolute path to the underlying resource,
	 * relative to the workbench.
	 * If this element is included in an external library,
	 * the path returned is the absolute path to the archive or to the
	 * folder in the file system.
	 * This is a handle-only method.
	 *
	 * @return the path to the innermost resource enclosing this element
	 * @since 2.0
	 */
	IPath getPath();

	Returns the primary element (whose compilation unit is the primary compilation unit)
this working copy element was created from, or this element if it is a descendant of a
primary compilation unit or if it is not a descendant of a working copy (e.g. it is a
binary member).
The returned element may or may not exist.
Returns: the primary element this working copy element was created from, or this
			element.
Since: 3.0/**
	 * Returns the primary element (whose compilation unit is the primary compilation unit)
	 * this working copy element was created from, or this element if it is a descendant of a
	 * primary compilation unit or if it is not a descendant of a working copy (e.g. it is a
	 * binary member).
	 * The returned element may or may not exist.
	 *
	 * @return the primary element this working copy element was created from, or this
	 * 			element.
	 * @since 3.0
	 */
	IJavaElement getPrimaryElement();

	Returns the innermost resource enclosing this element.
If this element is included in an archive and this archive is not external,
this is the underlying resource corresponding to the archive.
If this element is included in an external library, null
is returned.
This is a handle-only method.
Returns: the innermost resource enclosing this element, null if this
element is included in an external archive
Since: 2.0/**
	 * Returns the innermost resource enclosing this element.
	 * If this element is included in an archive and this archive is not external,
	 * this is the underlying resource corresponding to the archive.
	 * If this element is included in an external library, <code>null</code>
	 * is returned.
	 * This is a handle-only method.
	 *
	 * @return the innermost resource enclosing this element, <code>null</code> if this
	 * element is included in an external archive
	 * @since 2.0
	 */
	IResource getResource();

	Returns the scheduling rule associated with this Java element.
This is a handle-only method.
Returns: the scheduling rule associated with this Java element
Since: 3.0/**
	 * Returns the scheduling rule associated with this Java element.
	 * This is a handle-only method.
	 *
	 * @return the scheduling rule associated with this Java element
	 * @since 3.0
	 */
	ISchedulingRule getSchedulingRule();

	Returns the smallest underlying resource that contains
this element, or null if this element is not contained
in a resource.
Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its underlying resource
Returns: the underlying resource, or null if none/**
	 * Returns the smallest underlying resource that contains
	 * this element, or <code>null</code> if this element is not contained
	 * in a resource.
	 *
	 * @return the underlying resource, or <code>null</code> if none
	 * @exception JavaModelException if this element does not exist or if an
	 *		exception occurs while accessing its underlying resource
	 */
	IResource getUnderlyingResource() throws JavaModelException;

	Returns whether this Java element is read-only. An element is read-only
if its structure cannot be modified by the java model.

Note this is different from IResource.isReadOnly(). For example, .jar
files are read-only as the java model doesn't know how to add/remove
elements in this file, but the underlying IFile can be writable.

This is a handle-only method.
Returns: true if this element is read-only/**
	 * Returns whether this Java element is read-only. An element is read-only
	 * if its structure cannot be modified by the java model.
	 * <p>
	 * Note this is different from IResource.isReadOnly(). For example, .jar
	 * files are read-only as the java model doesn't know how to add/remove
	 * elements in this file, but the underlying IFile can be writable.
	 * <p>
	 * This is a handle-only method.
	 *
	 * @return <code>true</code> if this element is read-only
	 */
	boolean isReadOnly();

	Returns whether the structure of this element is known. For example, for a
compilation unit that has syntax errors, false is returned.
If the structure of an element is unknown, navigations will return reasonable
defaults. For example, getChildren for a compilation unit with
syntax errors will return a collection of the children that could be parsed.

Note: This does not imply anything about consistency with the
underlying resource/buffer contents.

Throws: JavaModelException – if this element does not exist or if an
	exception occurs while accessing its corresponding resource
Returns: true if the structure of this element is known/**
	 * Returns whether the structure of this element is known. For example, for a
	 * compilation unit that has syntax errors, <code>false</code> is returned.
	 * If the structure of an element is unknown, navigations will return reasonable
	 * defaults. For example, <code>getChildren</code> for a compilation unit with
	 * syntax errors will return a collection of the children that could be parsed.
	 * <p>
	 * Note: This does not imply anything about consistency with the
	 * underlying resource/buffer contents.
	 * </p>
	 *
	 * @return <code>true</code> if the structure of this element is known
	 * @exception JavaModelException if this element does not exist or if an
	 *		exception occurs while accessing its corresponding resource
	 */// TODO (philippe) predicate shouldn't throw an exception
	boolean isStructureKnown() throws JavaModelException;
}
Params:	ancestorType – the given type
Returns:	this Java element or the first ancestor of this element that has the given type, or `null` if no such element can be found
Since:	2.0
Params:	monitor – the given progress monitor, can be `null`
Throws:	JavaModelException – if: this element does not exist retrieving the attached javadoc fails (timed-out, invalid URL, ...) the format of the javadoc doesn't match expected standards (different anchors,...)
See Also:	IClasspathAttribute.JAVADOC_LOCATION_ATTRIBUTE_NAME
Returns:	the extracted javadoc from the attached javadoc, `null` if none
Since:	3.2
Throws:	JavaModelException – if this element does not exist or if an exception occurs while accessing its corresponding resource
Returns:	the corresponding resource, or `null` if none
See Also:	JavaCore.create(String)
Returns:	the string handle identifier
Returns:	the first openable parent or `null` if this element doesn't have an openable parent.
Since:	2.0
Returns:	the path to the innermost resource enclosing this element
Since:	2.0
Returns:	the primary element this working copy element was created from, or this element.
Since:	3.0
Returns:	the innermost resource enclosing this element, `null` if this element is included in an external archive
Since:	2.0
Returns:	the scheduling rule associated with this Java element
Since:	3.0
/

org.eclipse.jdt/ org.eclipse.jdt.core/ 3.20.0/ org/eclipse/jdt/core/IJavaElement.java
