151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/* 225fbd653a83f3a22235eb61e6e34f46ef3e990b7Przemyslaw Szczepaniak * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. 351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is free software; you can redistribute it and/or modify it 651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * under the terms of the GNU General Public License version 2 only, as 751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * published by the Free Software Foundation. Oracle designates this 851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * particular file as subject to the "Classpath" exception as provided 951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * by Oracle in the LICENSE file that accompanied this code. 1051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * This code is distributed in the hope that it will be useful, but WITHOUT 1251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 1351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 1451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * version 2 for more details (a copy is included in the LICENSE file that 1551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * accompanied this code). 1651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 1751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * You should have received a copy of the GNU General Public License version 1851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2 along with this work; if not, write to the Free Software Foundation, 1951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 2151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 2251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * or visit www.oracle.com if you need additional information or have any 2351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * questions. 2451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 2551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipackage java.lang.annotation; 2751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 2851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski/** 2951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The common interface extended by all annotation types. Note that an 3051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * interface that manually extends this one does <i>not</i> define 3151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * an annotation type. Also note that this interface does not itself 3251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * define an annotation type. 3351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 3451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * More information about annotation types can be found in section 9.6 of 3551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <cite>The Java™ Language Specification</cite>. 3651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 3725fbd653a83f3a22235eb61e6e34f46ef3e990b7Przemyslaw Szczepaniak * The {@link java.lang.reflect.AnnotatedElement} interface discusses 3825fbd653a83f3a22235eb61e6e34f46ef3e990b7Przemyslaw Szczepaniak * compatibility concerns when evolving an annotation type from being 3925fbd653a83f3a22235eb61e6e34f46ef3e990b7Przemyslaw Szczepaniak * non-repeatable to being repeatable. 4025fbd653a83f3a22235eb61e6e34f46ef3e990b7Przemyslaw Szczepaniak * 4151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @author Josh Bloch 4251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @since 1.5 4351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 4451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebskipublic interface Annotation { 4551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 4651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns true if the specified object represents an annotation 4751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that is logically equivalent to this one. In other words, 4851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * returns true if the specified object is an instance of the same 4951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * annotation type as this instance, all of whose members are equal 5051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to the corresponding member of this annotation, as defined below: 5151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <ul> 5251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li>Two corresponding primitive typed members whose values are 5351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>x</tt> and <tt>y</tt> are considered equal if <tt>x == y</tt>, 5451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * unless their type is <tt>float</tt> or <tt>double</tt>. 5551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 5651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li>Two corresponding <tt>float</tt> members whose values 5751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * are <tt>x</tt> and <tt>y</tt> are considered equal if 5851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>Float.valueOf(x).equals(Float.valueOf(y))</tt>. 5951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * (Unlike the <tt>==</tt> operator, NaN is considered equal 6051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to itself, and <tt>0.0f</tt> unequal to <tt>-0.0f</tt>.) 6151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 6251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li>Two corresponding <tt>double</tt> members whose values 6351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * are <tt>x</tt> and <tt>y</tt> are considered equal if 6451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt>Double.valueOf(x).equals(Double.valueOf(y))</tt>. 6551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * (Unlike the <tt>==</tt> operator, NaN is considered equal 6651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to itself, and <tt>0.0</tt> unequal to <tt>-0.0</tt>.) 6751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 6851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li>Two corresponding <tt>String</tt>, <tt>Class</tt>, enum, or 6951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * annotation typed members whose values are <tt>x</tt> and <tt>y</tt> 7051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * are considered equal if <tt>x.equals(y)</tt>. (Note that this 7151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * definition is recursive for annotation typed members.) 7251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li>Two corresponding array typed members <tt>x</tt> and <tt>y</tt> 7451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * are considered equal if <tt>Arrays.equals(x, y)</tt>, for the 7551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * appropriate overloading of {@link java.util.Arrays#equals}. 7651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </ul> 7751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 7851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return true if the specified object represents an annotation 7951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * that is logically equivalent to this one, otherwise false 8051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 8151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski boolean equals(Object obj); 8251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 8351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 8451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the hash code of this annotation, as defined below: 8551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 8651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>The hash code of an annotation is the sum of the hash codes 8751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * of its members (including those with default values), as defined 8851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * below: 8951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * The hash code of an annotation member is (127 times the hash code 9151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * of the member-name as computed by {@link String#hashCode()}) XOR 9251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the hash code of the member-value, as defined below: 9351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 9451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <p>The hash code of a member-value depends on its type: 9551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <ul> 9651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li>The hash code of a primitive value <tt><i>v</i></tt> is equal to 9751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt><i>WrapperType</i>.valueOf(<i>v</i>).hashCode()</tt>, where 9851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt><i>WrapperType</i></tt> is the wrapper type corresponding 9951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * to the primitive type of <tt><i>v</i></tt> ({@link Byte}, 10051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link Character}, {@link Double}, {@link Float}, {@link Integer}, 10151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link Long}, {@link Short}, or {@link Boolean}). 10251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 10351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li>The hash code of a string, enum, class, or annotation member-value 10451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski I <tt><i>v</i></tt> is computed as by calling 10551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <tt><i>v</i>.hashCode()</tt>. (In the case of annotation 10651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * member values, this is a recursive definition.) 10751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 10851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <li>The hash code of an array member-value is computed by calling 10951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * the appropriate overloading of 11051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * {@link java.util.Arrays#hashCode(long[]) Arrays.hashCode} 11151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * on the value. (There is one overloading for each primitive 11251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * type, and one for object reference types.) 11351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </ul> 11451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 11551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return the hash code of this annotation 11651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 11751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski int hashCode(); 11851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 11951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 12051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns a string representation of this annotation. The details 12151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * of the representation are implementation-dependent, but the following 12251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * may be regarded as typical: 12351b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * <pre> 12451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @com.acme.util.Name(first=Alfred, middle=E., last=Neuman) 12551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * </pre> 12651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * 12751b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * @return a string representation of this annotation 12851b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 12951b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski String toString(); 13051b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski 13151b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski /** 13251b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski * Returns the annotation type of this annotation. 13325fbd653a83f3a22235eb61e6e34f46ef3e990b7Przemyslaw Szczepaniak * @return the annotation type of this annotation 13451b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski */ 13551b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski Class<? extends Annotation> annotationType(); 13651b1b6997fd3f980076b8081f7f1165ccc2a4008Piotr Jastrzebski} 137