1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with this 4 * work for additional information regarding copyright ownership. The ASF 5 * licenses this file to you under the Apache License, Version 2.0 (the 6 * "License"); you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 13 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 14 * License for the specific language governing permissions and limitations under 15 * the License. 16 */ 17 18 package java.lang.annotation; 19 20 /** 21 * Defines the interface implemented by all annotations. Note that the interface 22 * itself is <i>not</i> an annotation, and neither is an interface that simply 23 * extends this one. Only the compiler is able to create proper annotation 24 * types. 25 * 26 * @since 1.5 27 */ 28 public interface Annotation { 29 30 /** 31 * Returns the type of this annotation. 32 * 33 * @return A {@code Class} instance representing the annotation type. 34 */ 35 Class<? extends Annotation> annotationType(); 36 37 /** 38 * Determines whether or not this annotation is equivalent to the annotation 39 * passed. This is determined according to the following rules: 40 * 41 * <ul> 42 * <li> 43 * Two annotations {@code x} and {@code y} are equal if and only if 44 * they are members of the same annotation type and all the member 45 * values of {@code x} are equal to the corresponding member values 46 * of {@code y}. 47 * </li> 48 * <li> 49 * The equality of primitive member values {@code x} and {@code y} 50 * is determined (in a way similar to) using the corresponding 51 * wrapper classes. For example, 52 * {@code Integer.valueOf(x).equals(Integer.valueOf(y)} is used for 53 * {@code int} values. Note: The behavior is identical to the 54 * {@code ==} operator for all but the floating point type, so the 55 * implementation may as well use {@code ==} in these cases for 56 * performance reasons. Only for the {@code float} and {@code double} 57 * types the result will be slightly different: {@code NaN} is equal 58 * to {@code NaN}, and {@code -0.0} is equal to {@code 0.0}, both of 59 * which is normally not the case. 60 * </li> 61 * <li> 62 * The equality of two array member values {@code x} and {@code y} 63 * is determined using the corresponding {@code equals(x, y)} 64 * helper function in {@link java.util.Arrays}. 65 * </li> 66 * <li> 67 * The hash code for all other member values is determined by simply 68 * calling their {@code equals()} method. 69 * </li> 70 * </ul> 71 * 72 * @param obj 73 * The object to compare to. 74 * 75 * @return {@code true} if {@code obj} is equal to this annotation, 76 * {@code false} otherwise. 77 */ 78 boolean equals(Object obj); 79 80 /** 81 * Returns the hash code of this annotation. The hash code is determined 82 * according to the following rules: 83 * 84 * <ul> 85 * <li> 86 * The hash code of an annotation is the sum of the hash codes of 87 * its annotation members. 88 * </li> 89 * <li> 90 * The hash code of an annotation member is calculated as {@code 91 * (0x7f * n.hashCode()) ^ v.hashCode())}, where {@code n} is the 92 * name of the member (as a {@code String}) and {@code v} its value. 93 * </li> 94 * <li> 95 * The hash code for a primitive member value is determined using 96 * the corresponding wrapper type. For example, {@code 97 * Integer.valueOf(v).hashCode()} is used for an {@code int} value 98 * {@code v}. 99 * </li> 100 * <li> 101 * The hash code for an array member value {@code v} is determined 102 * using the corresponding {@code hashCode(v)} helper function in 103 * {@link java.util.Arrays}. 104 * </li> 105 * <li> 106 * The hash code for all other member values is determined by simply 107 * calling their {@code hashCode} method. 108 * </li> 109 * </ul> 110 * 111 * @return the hash code. 112 */ 113 int hashCode(); 114 115 /** 116 * Returns a {@code String} representation of this annotation. It is not 117 * strictly defined what the representation has to look like, but it usually 118 * consists of the name of the annotation, preceded by a "@". If the 119 * annotation contains field members, their names and values are also 120 * included in the result. 121 * 122 * @return the {@code String} that represents this annotation. 123 */ 124 String toString(); 125 } 126
