/**
 * Represents an annotation on a package declaration, a type, a method, a field
 * or a local variable in a compilation unit or a class file.
 * <p>
 * Annotations are obtained using {@link IAnnotatable#getAnnotation(String)}.
 * </p><p>
 * Note that annotations are not children of their declaring element. 
 * To get a list of the annotations use {@link IAnnotatable#getAnnotations()}.
 * </p>
 * <p>
 * This interface is not intended to be implemented or extended by clients.
 * </p>
 *
 * @since 3.4
 */
public interface IAnnotation extends IJavaElement, ISourceReference {
	
	/**
	 * Returns the name of this annotation. If this annotation is coming from 
	 * a compilation unit, this is either a simple name (e.g. for <code>@MyAnnot</code>, the name
 	 * is "MyAnnot"), or a qualified name  (e.g. for <code>@x. y.    MyAnnot</code>, the name is
 	 * "x.y.MyAnnot"). If this annotation is coming from a class file, this is always a fully 
 	 * qualified name.
 	 * <p>Note that the name has been trimmed from its whitespaces. To extract the name as it 
 	 * appears in the source, use {@link #getNameRange()}.
 	 * </p><p>
	 * This is a handle-only method.  The annotation may or may not be present.
	 * </p>
	 * 
	 * @return the name of this annotation
	 */
	String getElementName();

	/**
	 * Returns the member-value pairs of this annotation. Returns an empty
	 * array if this annotation is a marker annotation. Returns a size-1 array if this 
	 * annotation is a single member annotation. In this case, the member
	 * name is always <code>"value"</code>.
	 * 
	 * @return the member-value pairs of this annotation
	 * @throws JavaModelException if this element does not exist or if an
	 *		exception occurs while accessing its corresponding resource
	 */
	IMemberValuePair[] getMemberValuePairs() throws JavaModelException;
	
	/**
	 * Returns the source range of this annotation's name,
	 * or <code>null</code> if this annotation does not have
	 * associated source code (for example, in a binary type).
	 *
	 * @exception JavaModelException if this element does not exist or if an
	 *      exception occurs while accessing its corresponding resource.
	 * @return the source range of this annotation's name,
	 * 		or <code>null</code> if this annotation does not have
	 * 		associated source code (for example, in a binary type)
	 */
	ISourceRange getNameRange() throws JavaModelException;

	/**
	 * Returns the position relative to the order this annotation is defined in the source.
	 * Numbering starts at 1 (thus the first occurrence is occurrence 1, not occurrence 0).
	 * <p>
	 * Two annotations ann1 and ann2 that are equal (e.g. 2 annotations with the same name on 
	 * the same type) can be distinguished using their occurrence counts. If annotation 
	 * ann1 appears first in the source, it will have an occurrence count of 1. If annotation 
	 * ann2 appears right after annotation ann1, it will have an occurrence count of 2.
	 * </p><p>
	 * This is a handle-only method.  The annotation may or may not be present.
	 * </p>
	 * 
	 * @return the position relative to the order this annotation is defined in the source
	 */
	int getOccurrenceCount();
}

/**
 * Represents a member-value pair of an annotation.
 * The {@link #getValue() value} is represented by an {@link Object}. To get the exact 
 * type of this object, use its {@link #getValueKind() value kind}. If this value is an array,
 * {@link #getValue()} returns an instance of {@link Object}[] and the value kind returns 
 * the kind of the first element in this array.
 * <p>
 * This interface is not intended to be implemented or extended by clients.
 * </p>
 *
 * @since 3.4
 */
public interface IMemberValuePair {
	/**
	 * Constant indicating that the value kind is an <code>int</code> represented by
	 * an instance of {@link Integer}.
	 */
	int K_INT = 1;

	/**
	 * Constant indicating that the value kind is a <code>byte</code> represented by
	 * an instance of {@link Byte}.
	 */
	int K_BYTE = 2;

	/**
	 * Constant indicating that the value kind is a <code>short</code> represented by
	 * an instance of {@link Short}.
	 */
	int K_SHORT = 3;

	/**
	 * Constant indicating that the value kind is a <code>char</code> represented by
	 * an instance of {@link Character}.
	 */
	int K_CHAR = 4;

	/**
	 * Constant indicating that the value kind is a <code>float</code> represented by
	 * an instance of {@link Float}.
	 */
	int K_FLOAT = 5;

	/**
	 * Constant indicating that the value kind is a <code>double</code> represented by
	 * an instance of {@link Double}.
	 */
	int K_DOUBLE = 6;

	/**
	 * Constant indicating that the value kind is a <code>long</code> represented by
	 * an instance of {@link Long}.
	 */
	int K_LONG = 7;

	/**
	 * Constant indicating that the value kind is a <code>boolean</code> represented by
	 * an instance of {@link Boolean}.
	 */
	int K_BOOLEAN = 8;

	/**
	 * Constant indicating that the value kind is a {@link String} represented by
	 * the corresponding {@link String}.
	 */
	int K_STRING = 9;
	
	/**
	 * Constant indicating that the value kind is an annotation represented by 
	 * an instance of {@link IAnnotation}.
	 */
	int K_ANNOTATION = 10;

	/**
	 * Constant indicating that the value kind is a {@link Class} represented by 
	 * the name of the class (i.e. a {@link String}. If the member-value pair is coming from 
	 * a compilation unit, this is either a simple name (e.g. for <code>MyType.class</code>, 
	 * the name is "MyType"), or a qualified name  (e.g. for <code>x.y.MyType.MyNestedType.class</code>, 
	 * the name is "x.y.MyType.MyNestedType"). If the member-value pair is coming from a class file, this is 
	 * always a fully qualified name.
	 * <p>
	 * Note that one can use {@link IType#resolveType(String)} to find the corresponding
	 * {@link IType}.
	 * </p>
	 */
	int K_CLASS = 11;
	
	/**
	 * Constant indicating that the value is a qualified name represented by a {@link String}.
	 * This usually represents an enumeration's constant (e.g. "MyEnum.FIRST"), but this 
	 * would need to be further analyzed to ensure that.
	 */
	int K_QUALIFIED_NAME = 12;
	
	/**
	 * Constant indicating that the value kind is unknown at this stage. The value is unknown in the
	 * following cases:
	 * <ul>
	 * <li>the value is an expression that would need to be further analyzed to determine its kind. For
	 * example, in <code>@MyAnnot(1 + 2.3)</code> the kind of the expression "1 + 2.3" is
	 * unknown</li>
	 * <li>the value is an array of size 0, e.g. <code>@MyAnnot({})</code></li>
	 * <li>the value is an array that contains at least one expression that would need to be further 
	 *      analyzed to determine its kind. For example, in <code>@MyAnnot({3.4, 1 + 2.3})</code>,
	 *      the kind of the second element "1 + 2.3" is unknown.</li>
	 * <li>the value is an array that contains heterogeneous values, e.g. 
	 *      <code>@MyAnnot(1, 2.3, "abc")</code></li>
	 * </ul>
	 * If the value kind is unknown, the returned value is always either <code>null</code>, or an 
	 * array containing only <code>null</code>s.
	 */
	int K_UNKNOWN = 13;

	/**
	 * Returns the member's name of this member-value pair.
	 * 
	 * @return the member's name of this member-value pair.
	 */
	String getMemberName();

	/**
	 * Returns the value of this member-value pair. The type of this value
	 * is function of this member-value pair's {@link #getValueKind() value kind}. It is an
	 * instance of {@link Object}[] if the value is an array. 
	 * <p>
	 * If the value kind is {@link #K_UNKNOWN} and the value is not an array, then the
	 * value is <code>null</code>. 
	 * If the value kind is {@link #K_UNKNOWN} and the value is an array, then the 
	 * value is an array containing <code>null</code>s.
	 * See {@link #K_UNKNOWN} for more details.
	 * </p>
	 * @return the value of this member-value pair.
	 */
	Object getValue();

	/**
	 * Returns the value kind of this member-value pair. This indicates the instance of
	 * the returned {@link #getValue() value}, or the instance of the first element if the value
	 * is an array. The value kind is one of the following constants:
	 * {@link #K_ANNOTATION}, {@link #K_BOOLEAN}, {@link #K_BYTE}, {@link #K_CHAR},
	 * {@link #K_CLASS}, {@link #K_DOUBLE}, {@link #K_FLOAT}, {@link #K_INT}, {@link #K_LONG},
	 * {@link #K_QUALIFIED_NAME}, {@link #K_SHORT}, {@link #K_STRING}, {@link #K_UNKNOWN}.
	 * 
	 * @return the value kind of this member-value pair
	 */
	int getValueKind();

}

/**
 * Common protocol for Java elements that can be annotated.
 * <p>
 * This interface is not intended to be implemented by clients.
 * </p>
 * 
 * @since 3.4
 */
public interface IAnnotatable {

	/**
	 * Returns the annotation with the given name declared on this element.
	 * This is a handle-only method. The annotation may or may not exist.
	 * 
	 * @param name the given simple name
	 * @return the annotation with the given name declared on this element
	 */
	IAnnotation getAnnotation(String name);
	
	/**
	 * Returns the annotations for this element.
	 * Returns an empty array if this method has no annotations.
	 *
	 * @exception JavaModelException if this element does not exist or if an
	 *      exception occurs while accessing its corresponding resource.
	 * @return the annotations of this element,
	 * 		in the order declared in the source, or an empty array if none
	 * @since 3.4
	 */
	IAnnotation[] getAnnotations() throws JavaModelException;
}

public interface IField extends IMember, IAnnotatable {
	...
}

public interface IMethod extends IMember, IAnnotatable {
	...
}

public interface IType extends IMember, IAnnotatable {
	...
}

public interface IPackageDeclaration extends IJavaElement, ISourceReference, IAnnotatable {
	...
}

public interface ILocalVariable extends IJavaElement, ISourceReference, IAnnotatable {
	...
}

public interface IJavaElement extends IAdaptable {
	...

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

public interface IJavaElementDelta {
	...
	/**
	 * Change flag indicating that the annotations of the element have changed.
	 * This flag is only valid if the element is an {@link IAnnotatable}.
	 * 
	 * @since 3.4
	 */
	public int F_ANNOTATIONS = 0x400000;
	...
}

/**
 * Common protocol for Java elements that have associated source code.
 * This set consists of {@link IClassFile}, {@link ICompilationUnit},
 * {@link IPackageDeclaration}, {@link IImportDeclaration},
 * {@link IImportContainer}, {@link IType}, {@link IField},
 * {@link IMethod}, {@link IInitializer}, {@link ITypeParameter}, 
 * and {@link IAnnotation}.
 * <p>
 * Note: For <code>IClassFile</code>, <code>IType</code> and other members
 * derived from a binary type, the implementation returns source iff the
 * element has attached source code.
 * </p>
 * <p>
 * Source reference elements may be working copies if they were created from
 * a compilation unit that is a working copy.
 * </p>
 * <p>
 * This interface is not intended to be implemented by clients.
 * </p>
 *
 * @see IPackageFragmentRoot#attachSource(org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IPath, org.eclipse.core.runtime.IProgressMonitor)
 */
public interface ISourceReference {
	...
}

public interface IBinding {
	...
	/**
	 * Returns the Java element that corresponds to this binding.
	 * Returns <code>null</code> if this binding has no corresponding
	 * Java element.
	 * <p>
	 * For array types, this method returns the Java element that corresponds
	 * to the array's element type. For raw and parameterized types, this method
	 * returns the Java element of the erasure. Since 3.4 for annotations, this method
	 * returns the Java element of the annotation (i.e. an {@link IAnnotation}).
	 * </p>
	 * <p>
	 * Here are the cases where a <code>null</code> should be expected:
	 * <ul>
	 * <li>primitive types, including void</li>
	 * <li>null type</li>
	 * <li>wildcard types</li>
	 * <li>capture types</li>
	 * <li>array types of any of the above</li>
	 * <li>the "length" field of an array type</li>
	 * <li>the default constructor of a source class</li>
	 * <li>the constructor of an anonymous class</li>
	 * <li>member value pairs</li>
	 * </ul>
	 * For all other kind of type, method, variable, annotation and package bindings,
	 * this method returns non-<code>null</code>.
	 * </p>
	 *
	 * @return the Java element that corresponds to this binding,
	 * 		or <code>null</code> if none
	 * @since 3.1
	 */
	public IJavaElement getJavaElement();
	...
}