1 /* 2 * Copyright 2013 Google LLC 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package com.google.auto.factory; 17 18 import static java.lang.annotation.ElementType.ANNOTATION_TYPE; 19 import static java.lang.annotation.ElementType.CONSTRUCTOR; 20 import static java.lang.annotation.ElementType.TYPE; 21 22 import java.lang.annotation.Target; 23 24 /** 25 * An annotation to be applied to elements for which a factory should be automatically generated. 26 * 27 * <h2>Visibility</h2> 28 * <p>The visibility of the generated factories will always be either {@code public} or default 29 * visibility. The visibility of any given factory method is determined by the visibility of the 30 * type being created. The generated factory is {@code public} if any of the factory methods are. 31 * Any method that implements an interface method is necessarily public and any method that 32 * overrides an abstract method has the same visibility as that method. 33 * 34 * @author Gregory Kick 35 */ 36 @Target({TYPE, CONSTRUCTOR}) 37 public @interface AutoFactory { 38 /** 39 * The <i>simple</i> name of the generated factory; the factory is always generated in the same 40 * package as the annotated type. The default value (the empty string) will result in a factory 41 * with the name of the type being created with {@code Factory} appended to the end. For example, 42 * the default name for a factory for {@code MyType} will be {@code MyTypeFactory}. 43 * 44 * <p>If the annotated type is nested, then the generated factory's name will start with the 45 * enclosing type names, separated by underscores. For example, the default name for a factory for 46 * {@code Outer.Inner.ReallyInner} is {@code Outer_Inner_ReallyInnerFactory}. If {@code className} 47 * is {@code Foo}, then the factory name is {@code Outer_Inner_Foo}. 48 */ className()49 String className() default ""; 50 51 /** 52 * A list of interfaces that the generated factory is required to implement. 53 */ implementing()54 Class<?>[] implementing() default {}; 55 56 /** 57 * The type that the generated factory is required to extend. 58 */ extending()59 Class<?> extending() default Object.class; 60 61 /** 62 * Whether or not the generated factory should be final. 63 * Defaults to disallowing subclasses (generating the factory as final). 64 */ allowSubclasses()65 boolean allowSubclasses() default false; 66 67 /** 68 * Specifies that an annotation should be used to determine how to annotate generated AutoFactory 69 * classes. For example, suppose you have this annotation: 70 * <pre> 71 * {@code @AutoFactory.AnnotationsToApply} 72 * {@code @interface} ApplyImmutableAndSuppressWarnings { 73 * Immutable immutable() default @Immutable; 74 * SuppressWarnings suppressWarnings() default @SuppressWarnings("Immutable"); 75 * } 76 * </pre> 77 * 78 * And suppose you use it like this: 79 * <pre> 80 * {@code @ApplyImmutableAndSuppressWarnings} 81 * {@code @AutoFactory} 82 * public class Foo {...} 83 * </pre> 84 * 85 * Then the generated {@code FooFactory} would look like this: 86 * <pre> 87 * {@code @Immutable} 88 * {@code @SuppressWarnings("Immutable")} 89 * public class FooFactory {...} 90 * </pre> 91 * 92 * The same would be true if you used it like this: 93 * <pre> 94 * {@code @ApplyImmutableAndSuppressWarnings}( 95 * immutable = @Immutable, 96 * suppressWarnings = @SuppressWarnings("Immutable")) 97 * {@code @AutoFactory} 98 * public class Foo {...} 99 * </pre> 100 * 101 * You could also have {@code suppressWarnings = @SuppressWarnings({"Immutable", "unchecked"})}, 102 * etc, to specify a value different from the default. 103 */ 104 @Target(ANNOTATION_TYPE) 105 @interface AnnotationsToApply {} 106 } 107