1 /*
2  * Copyright (C) 2022 The Android Open Source Project
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 
17 package android.processor.immutability;
18 
19 import java.lang.annotation.ElementType;
20 import java.lang.annotation.Retention;
21 import java.lang.annotation.RetentionPolicy;
22 import java.lang.annotation.Target;
23 import java.util.Collection;
24 import java.util.Map;
25 
26 /**
27  * Marks a class as immutable. When used with the Immutability processor, verifies at compile that
28  * the class is truly immutable. Immutable is defined as:
29  * <ul>
30  *     <li>Only exposes methods and/or static final constants</li>
31  *     <li>Every exposed type is an @Immutable interface or otherwise immutable class</li>
32  *     <ul>
33  *         <li>Implicitly immutable types like {@link String} are ignored</li>
34  *         <li>{@link Collection} and {@link Map} and their subclasses where immutability is
35  *         enforced at runtime are ignored</li>
36  *     </ul>
37  *     <li>Every method must return a type (no void methods allowed)</li>
38  *     <li>All inner classes must be @Immutable interfaces</li>
39  * </ul>
40  */
41 public @interface Immutable {
42 
43     /**
44      * Marks a specific class, field, or method as ignored for immutability validation.
45      */
46     @Retention(RetentionPolicy.CLASS) // Not SOURCE as that isn't retained for some reason
47     @Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})
48     @interface Ignore {
reason()49         String reason() default "";
50     }
51 
52     /**
53      * Marks an element and its reachable children with a specific policy.
54      */
55     @Retention(RetentionPolicy.CLASS)
56     @Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD})
57     @interface Policy {
exceptions()58         Exception[] exceptions() default {};
59 
60         enum Exception {
61             /**
62              * Allow final classes with only final fields. By default these are not allowed because
63              * direct field access disallows hard removal of APIs (by having their getters return
64              * mocks/stubs) and also prevents field compaction, which can occur with booleans
65              * stuffed into a number as flags.
66              *
67              * This exception is allowed though because several framework classes are built around
68              * the final field access model and it would be unnecessarily difficult to migrate or
69              * wrap each type.
70              */
71             FINAL_CLASSES_WITH_FINAL_FIELDS,
72         }
73     }
74 }
75