1 /* 2 * Copyright 2014 Google LLC 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except 5 * in compliance with the License. You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software distributed under the License 10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 11 * or implied. See the License for the specific language governing permissions and limitations under 12 * the License. 13 */ 14 package com.google.auto.value; 15 16 import java.lang.annotation.Annotation; 17 import java.lang.annotation.ElementType; 18 import java.lang.annotation.Retention; 19 import java.lang.annotation.RetentionPolicy; 20 import java.lang.annotation.Target; 21 import java.lang.reflect.AnnotatedElement; 22 23 /** 24 * Annotation that causes an implementation of an annotation interface to be generated. The 25 * annotation is applied to a method whose return type is an annotation interface. The method can 26 * then create and return an instance of the generated class that conforms to the specification of 27 * {@link Annotation}, in particular as regards {@link Annotation#equals equals} and {@link 28 * Annotation#hashCode hashCode}. These instances behave essentially the same as instances returned 29 * by {@link AnnotatedElement#getAnnotation}. 30 * 31 * <p>For example, suppose you have an annotation like this: 32 * 33 * <pre> 34 * package com.google.inject.name; 35 * 36 * public @interface Named { 37 * String value(); 38 * }</pre> 39 * 40 * <p>You could write a method like this to construct implementations of the interface: 41 * 42 * <pre> 43 * package com.example; 44 * 45 * public class Names { 46 * @AutoAnnotation public static Named named(String value) { 47 * return new AutoAnnotation_Names_named(value); 48 * } 49 * }</pre> 50 * 51 * <p>Because the annotated method is called {@code Names.named}, the generated class is called 52 * {@code AutoAnnotation_Names_named} in the same package. If the annotated method were in a nested 53 * class, for example {@code Outer.Names.named}, then the generated class would be called {@code 54 * AutoAnnotation_Outer_Names_named}. The generated class is package-private and it is not expected 55 * that it will be referenced outside the {@code @AutoAnnotation} method. 56 * 57 * <p>The names and types of the parameters in the annotated method must be the same as the names 58 * and types of the annotation elements, except that elements which have default values can be 59 * omitted. The parameters do not need to be in any particular order. 60 * 61 * <p>The annotated method does not need to be public. It can have any visibility, including 62 * private. This means the method can be a private implementation called by a public method with a 63 * different API, for example using a builder. 64 * 65 * <p>It is a compile-time error if more than one method with the same name in the same class is 66 * annotated {@code @AutoAnnotation}. 67 * 68 * <p>The constructor of the generated class has the same parameters as the {@code @AutoAnnotation} 69 * method. It will throw {@code NullPointerException} if any parameter is null. In order to 70 * guarantee that the constructed object is immutable, the constructor will clone each array 71 * parameter corresponding to an array-valued annotation member, and the implementation of each such 72 * member will also return a clone of the array. 73 * 74 * @author emcmanus@google.com (Éamonn McManus) 75 */ 76 @Target(ElementType.METHOD) 77 @Retention(RetentionPolicy.SOURCE) 78 public @interface AutoAnnotation {} 79