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
18package 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 */
28public 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