1 /*
2  * Copyright 2012, Google Inc.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions are
7  * met:
8  *
9  *     * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *     * Redistributions in binary form must reproduce the above
12  * copyright notice, this list of conditions and the following disclaimer
13  * in the documentation and/or other materials provided with the
14  * distribution.
15  *     * Neither the name of Google Inc. nor the names of its
16  * contributors may be used to endorse or promote products derived from
17  * this software without specific prior written permission.
18  *
19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30  */
31 
32 package org.jf.dexlib2.iface;
33 
34 import javax.annotation.Nonnull;
35 import javax.annotation.Nullable;
36 import java.util.Set;
37 
38 /**
39  * This class represents a specific instance of an annotation applied to a class/field/method/parameter
40  */
41 public interface Annotation extends BasicAnnotation, Comparable<Annotation> {
42     /**
43      * Gets the visibility of this annotation.
44      *
45      * This will be one of the AnnotationVisibility.* constants.
46      *
47      * @return The visibility of this annotation
48      */
getVisibility()49     int getVisibility();
50 
51     /**
52      * Gets the type of this annotation.
53      *
54      * This will be the type descriptor of the class that defines this annotation.
55      *
56      * @return The type of this annotation
57      */
getType()58     @Nonnull @Override String getType();
59 
60     /**
61      * Gets a set of the name/value elements associated with this annotation.
62      *
63      * The elements in the returned set will be unique with respect to the element name.
64      *
65      * @return A set of AnnotationElements
66      */
getElements()67     @Nonnull @Override Set<? extends AnnotationElement> getElements();
68 
69     /**
70      * Returns a hashcode for this Annotation.
71      *
72      * This hashCode is defined to be the following:
73      *
74      * <pre>
75      * {@code
76      * int hashCode = getVisibility();
77      * hashCode = hashCode*31 + getType().hashCode();
78      * hashCode = hashCode*31 + getElements().hashCode();
79      * }</pre>
80      *
81      * @return The hash code value for this Annotation
82      */
hashCode()83     @Override int hashCode();
84 
85     /**
86      * Compares this Annotation to another Annotation for equality.
87      *
88      * This Annotation is equal to another Annotation if all of it's "fields" are equal. That is, if the return values
89      * of getVisibility(), getType(), and getElements() are all equal.
90      *
91      * @param o The object to be compared for equality with this Annotation
92      * @return true if the specified object is equal to this Annotation
93      */
equals(@ullable Object o)94     @Override boolean equals(@Nullable Object o);
95 
96     /**
97      * Compares this Annotation to another Annotation.
98      *
99      * The comparison is based on the value of getVisibility(), getType() and getElements(), in that order. When
100      * comparing the set of elements, the comparison is done with the semantics of
101      * org.jf.util.CollectionUtils.compareAsSet(), using the natural ordering of AnnotationElement.
102      *
103      * @param o The Annotation to compare with this Annotation
104      * @return An integer representing the result of the comparison
105      */
compareTo(Annotation o)106     @Override int compareTo(Annotation o);
107 }
108