1 /* 2 * Copyright (C) 2025 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 com.android.tools.metalava.model.api.flags 18 19 import com.android.tools.metalava.model.ANNOTATION_IN_ALL_STUBS 20 import com.android.tools.metalava.model.AnnotationTarget 21 import com.android.tools.metalava.model.Item 22 import com.android.tools.metalava.model.NO_ANNOTATION_TARGETS 23 import com.android.tools.metalava.model.Showability 24 25 /** 26 * The available set of configured [ApiFlag]s. 27 * 28 * @param byQualifiedName map from qualified flag name to [ApiFlag]. 29 */ 30 class ApiFlags(val byQualifiedName: Map<String, ApiFlag>) { 31 /** 32 * Get the [ApiFlag] by qualified name. 33 * 34 * If no such [ApiFlag] exists then return [ApiFlag.REVERT_FLAGGED_API]. 35 */ getnull36 operator fun get(qualifiedName: String) = 37 byQualifiedName[qualifiedName] ?: ApiFlag.REVERT_FLAGGED_API 38 39 override fun toString(): String { 40 return "ApiFlags(byQualifiedName=$byQualifiedName)" 41 } 42 } 43 44 /** A representation of an [ApiFlag] that is associated with an `@FlaggedApi` annotation. */ 45 class ApiFlag 46 private constructor( 47 /** 48 * The qualified name of the flag. 49 * 50 * Provided for debug purposes only and cannot be relied upon to be the name of an actual flag, 51 * e.g. [REVERT_FLAGGED_API]'s [qualifiedName] is simply `<disabled>`. 52 */ 53 val description: String, 54 55 /** 56 * The [Showability] of any [Item]s annotated with an `@FlaggedApi` annotation that references 57 * this [ApiFlag]. 58 */ 59 val showability: Showability, 60 61 /** Controls whether `@FlaggedApi` annotations for this [ApiFlag] are kept or discarded. */ 62 val annotationTargets: Set<AnnotationTarget>, 63 ) { toStringnull64 override fun toString(): String { 65 return "ApiFlag(description='$description')" 66 } 67 68 companion object { 69 /** Revert any associated [Item]s. */ 70 val REVERT_FLAGGED_API = 71 ApiFlag( 72 "<revert>", 73 showability = Showability.REVERT_UNSTABLE_API, 74 annotationTargets = NO_ANNOTATION_TARGETS 75 ) 76 77 /** Keep any associated [Item]s and their `@FlaggedApi` annotation. */ 78 val KEEP_FLAGGED_API = 79 ApiFlag( 80 "<keep>", 81 showability = Showability.NO_EFFECT, 82 annotationTargets = ANNOTATION_IN_ALL_STUBS, 83 ) 84 85 /** 86 * Keep any associated [Item]s but remove their `@FlaggedApi` annotation as this is being 87 * (or has been) finalized. 88 */ 89 val FINALIZE_FLAGGED_API = 90 ApiFlag( 91 "<finalize>", 92 showability = Showability.NO_EFFECT, 93 annotationTargets = NO_ANNOTATION_TARGETS, 94 ) 95 } 96 } 97