/*******************************************************************************
 * Copyright (c) 2000, 2017 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.aspectj.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.
 * <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 {@link IJavaModel}.
	 */
	int JAVA_MODEL = 1;

	/**
	 * 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 {@link IPackageFragmentRoot}.
	 */
	int PACKAGE_FRAGMENT_ROOT = 3;

	/**
	 * 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 {@link ICompilationUnit}.
	 */
	int COMPILATION_UNIT = 5;

	/**
	 * 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 {@link IType}.
	 */
	int TYPE = 7;

	/**
	 * 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 {@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 {@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 {@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 {@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 {@link IImportDeclaration}.
	 */
	int IMPORT_DECLARATION = 13;

	/**
	 * 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 {@link ITypeParameter}.
	 * @since 3.1
	 */
	int TYPE_PARAMETER = 15;

	/**
	 * 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 {@link IModuleDescription}.
	 *
	 * @since 3.14
	 */
	int JAVA_MODULE = 17;

	/**
	 * 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 <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);

	/**
	 * <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 <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.
	 *
	 * @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
	 *   <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
	 * <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.
	 *
	 * @return the Java model
	 */
	IJavaModel getJavaModel();

	/**
	 * 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 <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 <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.
	 *
	 * @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.
	 *
	 * @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, <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.
	 *
	 * @return the scheduling rule associated with this Java element
	 * @since 3.0
	 */
	ISchedulingRule getSchedulingRule();

	/**
	 * 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.
	 * <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, <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;
}