Frames | No Frames |
1: /* Annotation.java - Base interface for all annotations 2: Copyright (C) 2004 Free Software Foundation 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: package java.lang.annotation; 39: 40: /** 41: * This is the common interface for all annotations. Note that classes 42: * that implement this class manually are not classed as annotations, and 43: * that this interface does not define an annotation type in itself. 44: * 45: * @author Tom Tromey (tromey@redhat.com) 46: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 47: * @since 1.5 48: */ 49: public interface Annotation 50: { 51: 52: /** 53: * Returns the type of this annotation. 54: * 55: * @return the class of which this annotation is an instance. 56: */ 57: /* FIXME[GENERICS]: Should return Class<? extends Annotation> */ 58: Class annotationType(); 59: 60: /** 61: * <p> 62: * Returns true if the supplied object is equivalent to this annotation. 63: * For this property to hold, the following must be true of <code>o</code>: 64: * </p> 65: * <ul> 66: * <li>The object is also an instance of the same annotation type.</li> 67: * <li>The members of the supplied annotation are equal to those of this 68: * annotation, according to the following: 69: * <ul> 70: * <li>If the members are <code>float</code>s, then, for floats 71: * <code>x</code> and <code>y</code>, 72: * <code>Float.valueOf(x).equals(Float.valueOf(y)</code> must return 73: * true. This differs from the usual (<code>==</code>) comparison 74: * in that <code>NaN</code> is considered equal to itself and positive 75: * and negative zero are seen as different.</li> 76: * <li>Likewise, if the members are <code>double</code>s, then, for doubles 77: * <code>x</code> and <code>y</code>, 78: * <code>Double.valueOf(x).equals(Double.valueOf(y)</code> must return 79: * true. This differs from the usual (<code>==</code>) comparison 80: * in that <code>NaN</code> is considered equal to itself and positive 81: * and negative zero are seen as different.</li> 82: * <li>Strings, classes, enumerations and annotations are considered 83: * equal according to the <code>equals()</code> implementation for these 84: * types.</li> 85: * <li>Arrays are considered equal according to <code>Arrays.equals()</code> 86: * </li> 87: * <li>Any remaining types are considered equal using <code>==</code>.</li> 88: * </li> 89: * </ul> 90: * 91: * @param o the object to compare with this annotation. 92: * @return true if the supplied object is an annotation with equivalent 93: * members. 94: */ 95: boolean equals(Object o); 96: 97: /** 98: * <p> 99: * Returns the hash code of the annotation. This is computed as the 100: * sum of the hash codes of the annotation's members. 101: * </p> 102: * <p> 103: * The hash code of a member of the annotation is the result of XORing 104: * the hash code of its value with the result of multiplying the hash code 105: * of its name by 127. Formally, if the value is <code>v</code> and the 106: * name is <code>n</code>, the hash code of the member is 107: * v.hashCode() XOR (127 * String.hashCode(n)). <code>v.hashCode()</code> 108: * is defined as follows: 109: * </p> 110: * <ul> 111: * <li>The hash code of a primitive value (i.e. <code>byte</code>, 112: * <code>char</code>, <code>double</code>, <code>float</code>, 113: * <code>int</code>, <code>long</code>, <code>short</code> and 114: * <code>boolean</code>) is the hash code obtained from its corresponding 115: * wrapper class using <code>valueOf(v).hashCode()</code>, where 116: * <code>v</code> is the primitive value.</li> 117: * <li>The hash code of an enumeration, string, class or other annotation 118: * is obtained using <code>v.hashCode()</code>.</li> 119: * <li>The hash code of an array is computed using 120: * <code>Arrays.hashCode(v)</code>.</li> 121: * </ul> 122: * 123: * @return the hash code of the annotation, computed as the sum of its 124: * member hashcodes. 125: */ 126: int hashCode(); 127: 128: /** 129: * Returns a textual representation of the annotation. This is 130: * implementation-dependent, but is expected to include the classname 131: * and the names and values of each member. 132: * 133: * @return a textual representation of the annotation. 134: */ 135: String toString(); 136: }