1 /*
2  * Copyright (C) 2024 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 package com.android.adservices.shared.common.flags;
17 
18 import static java.lang.annotation.ElementType.FIELD;
19 import static java.lang.annotation.RetentionPolicy.SOURCE;
20 
21 import java.lang.annotation.Retention;
22 import java.lang.annotation.Target;
23 
24 /**
25  * Annotation used to indicate a constant defines the default value of a flag guarding a feature.
26  *
27  * @hide
28  */
29 @Retention(SOURCE)
30 @Target({FIELD})
31 public @interface FeatureFlag {
value()32     Type value() default Type.DEFAULT;
33 
34     /** Types of feature flag - they define the (expected) value of the constant being annotated. */
35     enum Type {
36         /**
37          * This is the default type for most feature flags - it means the feature flag guards a
38          * feature at runtime - when the flag is {@code false}, the feature would be disabled.
39          *
40          * <p>The value of the field annotated by it should be {@code false}.
41          */
42         DEFAULT,
43 
44         /**
45          * Used after a flag has been completely ramped up - its getter is always returning {@code
46          * true} and eventually will be removed.
47          *
48          * <p>The value of the field annotated by it should be {@code true}, and should be marked as
49          * {@code deprecated}.
50          */
51         RAMPED_UP,
52 
53         /**
54          * The value of the field annotated by it should be dynamically set, based in the SDK level
55          * of the device.
56          */
57         SDK_LEVEL_BASED,
58 
59         /**
60          * Used on constants defined in the shared code package - the "real" runtime flag guarding
61          * the feature will be independently set by different projects.
62          *
63          * <p>The value of the field annotated by it should be {@code false}.
64          */
65         SHARED,
66 
67         // TODO(b/335725725) - remove once getAdServicesShellCommandEnabled() is moved to DebugFlags
68         /**
69          * Flag that is only used for debugging / development purposes - it's not pushed to the
70          * device and can only be set locally by developers / tests.
71          *
72          * <p>The value of the field annotated by it should be {@code false}.
73          *
74          * @deprecated should use {@code DebugFlags} instead
75          */
76         @Deprecated
77         DEBUG,
78 
79         /**
80          * Used for a legacy flags that followed the "kill-switch convention" (where the feature is
81          * disabled when the flag is {@code true}.
82          *
83          * <p>Should only be used by the "global" flag that guards all features provide by the
84          * mainline module.
85          *
86          * <p>The value of the field annotated by it should be {@code true}.
87          */
88         LEGACY_KILL_SWITCH_GLOBAL,
89 
90         /**
91          * Used for legacy flags that followed the "kill-switch convention" (where the feature is
92          * disabled when the flag is {@code true}.
93          *
94          * <p>Should only be used in flags that were already pushed to production (and are still
95          * ramping up) and hence cannot be changed (into a "feature flag").
96          *
97          * <p>The value of the field annotated by it should be {@code true}.
98          */
99         LEGACY_KILL_SWITCH,
100 
101         /**
102          * Same as {@link #LEGACY_KILL_SWITCH}, but used while its getters are converted to feature
103          * flag getter and hence the value of the field annotated by it is {@code false} -
104          * eventually the field will become a {@link #LEGACY_KILL_SWITCH}, and its value will be
105          * {@code true}.
106          *
107          * @deprecated TODO(b/324077542) - remove once all kill-switches have been converted
108          */
109         @Deprecated
110         LEGACY_KILL_SWITCH_BEING_CONVERTED,
111 
112         /**
113          * Used for legacy flags that followed the "kill-switch convention" (where the feature is
114          * disabled when the flag is {@code true}.
115          *
116          * <p>Should only be used in flags that were already pushed to production (and already
117          * completely ramped up) and hence cannot be changed (into a "feature flag").
118          *
119          * <p>The value of the field annotated by it should be {@code false}.
120          */
121         LEGACY_KILL_SWITCH_RAMPED_UP,
122     }
123 }
124