package java.lang.annotation;

import ej.annotation.Nullable;

/**
 * The common interface extended by all annotation types. Note that an interface that manually
 * extends this one does <i>not</i> define an annotation type. Also note that this interface does
 * not itself define an annotation type.
 *
 * More information about annotation types can be found in section 9.6 of <cite>The Java&trade;
 * Language Specification</cite>.
 */
public interface Annotation {

	/**
	 * Returns the annotation type of this annotation.
	 * @return the annotation type of this annotation.
	 */
	Class<? extends Annotation> annotationType();

	/**
	 * Returns true if the specified object represents an annotation that is logically equivalent to
	 * this one. In other words, returns true if the specified object is an instance of the same
	 * annotation type as this instance, all of whose members are equal to the corresponding member of
	 * this annotation, as defined below:
	 * <ul>
	 * <li>Two corresponding primitive typed members whose values are <code>x</code> and <code>y</code> are
	 * considered equal if <code>x == y</code>, unless their type is <code>float</code> or <code>double</code>.
	 *
	 * <li>Two corresponding <code>float</code> members whose values are <code>x</code> and <code>y</code> are
	 * considered equal if <code>Float.valueOf(x).equals(Float.valueOf(y))</code>. (Unlike the <code>==</code>
	 * operator, NaN is considered equal to itself, and <code>0.0f</code> unequal to <code>-0.0f</code>.)
	 *
	 * <li>Two corresponding <code>double</code> members whose values are <code>x</code> and <code>y</code> are
	 * considered equal if <code>Double.valueOf(x).equals(Double.valueOf(y))</code>. (Unlike the <code>==</code>
	 * operator, NaN is considered equal to itself, and <code>0.0</code> unequal to <code>-0.0</code>.)
	 *
	 * <li>Two corresponding <code>String</code>, <code>Class</code>, enum, or annotation typed members whose
	 * values are <code>x</code> and <code>y</code> are considered equal if <code>x.equals(y)</code>. (Note that
	 * this definition is recursive for annotation typed members.)
	 * </ul>
	 * @return true if the specified object represents an annotation that is logically equivalent to
	 *         this one, otherwise false
	 */
	@Override
	boolean equals(@Nullable Object obj);

	/**
	 * Returns the hash code of this annotation, as defined below:
	 *
	 * <p>
	 * The hash code of an annotation is the sum of the hash codes of its members (including those with
	 * default values), as defined below:
	 *
	 * The hash code of an annotation member is (127 times the hash code of the member-name as computed
	 * by {@link String#hashCode()}) XOR the hash code of the member-value, as defined below:
	 *
	 * <p>
	 * The hash code of a member-value depends on its type:
	 * <ul>
	 * <li>The hash code of a primitive value <code><i>v</i></code> is equal to
	 * <code><i>WrapperType</i>.valueOf(<i>v</i>).hashCode()</code>, where <code><i>WrapperType</i></code> is
	 * the wrapper type corresponding to the primitive type of <code><i>v</i></code> ({@link Byte},
	 * {@link Character}, {@link Double}, {@link Float}, {@link Integer}, {@link Long}, {@link Short},
	 * or {@link Boolean}).
	 *
	 * <li>The hash code of a string, enum, class, or annotation member-value I <code><i>v</i></code> is
	 * computed as by calling <code><i>v</i>.hashCode()</code>. (In the case of annotation member values,
	 * this is a recursive definition.)
	 * </ul>
	 *
	 * @return the hash code of this annotation
	 */
	@Override
	int hashCode();

	/**
	 * Returns a string representation of this annotation. The details of the representation are
	 * implementation-dependent, but the following may be regarded as typical:
	 *
	 * <pre>
	 *   &#064;com.acme.util.Name(first=Alfred, middle=E., last=Neuman)
	 * </pre>
	 *
	 * @return a string representation of this annotation
	 */
	@Override
	String toString();
}