/******************************************************************************* * Copyright (c) 2000, 2001, 2002 International Business Machines Corp. and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Common Public License v0.5 * which accompanies this distribution, and is available at * http://www.eclipse.org/legal/cpl-v05.html * * Contributors: * IBM Corporation - initial API and implementation ******************************************************************************/ package net.sourceforge.phpdt.core; import org.eclipse.core.resources.IResource; import org.eclipse.core.runtime.IAdaptable; import org.eclipse.core.runtime.IPath; /** * 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.
*
* 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 toIJavaModel
.
*/
public static final int JAVA_MODEL = 1;
/**
* Constant representing a Java project.
* A Java element with this type can be safely cast to IJavaProject
.
*/
public static final int JAVA_PROJECT = 2;
/**
* Constant representing a package fragment root.
* A Java element with this type can be safely cast to IPackageFragmentRoot
.
*/
public static final int PACKAGE_FRAGMENT_ROOT = 3;
/**
* Constant representing a package fragment.
* A Java element with this type can be safely cast to IPackageFragment
.
*/
public static final int PACKAGE_FRAGMENT = 4;
/**
* Constant representing a Java compilation unit.
* A Java element with this type can be safely cast to ICompilationUnit
.
*/
public static final int COMPILATION_UNIT = 5;
/**
* Constant representing a class file.
* A Java element with this type can be safely cast to IClassFile
.
*/
public static final int CLASS_FILE = 6;
/**
* Constant representing a type (a class or interface).
* A Java element with this type can be safely cast to IType
.
*/
public static final int TYPE = 7;
/**
* Constant representing a field.
* A Java element with this type can be safely cast to IField
.
*/
public static final int FIELD = 8;
/**
* Constant representing a method or constructor.
* A Java element with this type can be safely cast to IMethod
.
*/
public static final int METHOD = 9;
/**
* Constant representing a stand-alone instance or class initializer.
* A Java element with this type can be safely cast to IInitializer
.
*/
public static final int INITIALIZER = 10;
/**
* Constant representing a package declaration within a compilation unit.
* A Java element with this type can be safely cast to IPackageDeclaration
.
*/
public static final 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
.
*/
public static final 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
.
*/
public static final int IMPORT_DECLARATION = 13;
/**
* Returns whether this Java element exists in the model.
*
* @return true
if this element exists in the Java model
*/
boolean exists();
/**
* Returns the first ancestor of this Java element that has the given type.
* Returns null
if no such an ancestor can be found.
* This is a handle-only method.
*
* @param ancestorType the given type
* @return the first ancestor of this Java element that has the given type, null if no such an ancestor can be found
* @since 2.0
*/
IJavaElement getAncestor(int ancestorType);
/**
* 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.
*
*
* @return the corresponding resource, or null
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.
*
* @return the element name
*/
String getElementName();
/**
* 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
* IJavaElement
* @see IJavaElement
*/
public 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.
*
* @return the string handle identifier
* @see JavaCore#create(java.lang.String)
*/
String getHandleIdentifier();
/**
* 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.
*
* @return the containing Java project, or null
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.
*
* @return the first openable parent or null
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.
*
* @return the parent element, or null
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 archive,
* the path returned is the full, absolute path to the underlying resource,
* relative to the workbench.
* If this element is included in an external archive,
* the path returned is the absolute path to the archive 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 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 archive, null
* is returned.
* If this element is a working copy, null
is returned.
* This is a handle-only method.
*
* @return the innermost resource enclosing this element, null
if this
* element is a working copy or is included in an external archive
* @since 2.0
*/
IResource getResource();
/**
* Returns the smallest underlying resource that contains
* this element, or null
if this element is not contained
* in a resource.
*
* @return the underlying resource, or null
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.
*
* @return true
if this element is read-only
*/
boolean isReadOnly();
/**
* Returns whether the structure of this element is known. For example, for a
* compilation unit that could not be parsed, false
is returned.
* If the structure of an element is unknown, navigations will return reasonable
* defaults. For example, getChildren
will return an empty collection.
*
* Note: This does not imply anything about consistency with the * underlying resource/buffer contents. *
* * @returntrue
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
*/
boolean isStructureKnown() throws JavaModelException;
}