1 /*
2  * Copyright 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 androidx.appfunctions
18 
19 import androidx.annotation.RestrictTo
20 import androidx.annotation.StringDef
21 
22 /**
23  * Marks a class as a registry for AppFunction components, enabling compile-time aggregation.
24  *
25  * This annotation is used by the AppFunction compiler plugin to discover and aggregate AppFunction
26  * components declared across different modules. The compiler plugin searches for classes annotated
27  * with [AppFunctionComponentRegistry] within the designated `appfunctions_aggregated_deps` package.
28  *
29  * The registry classes are usually generated by AppFunction compiler plugin automatically while
30  * processing each submodules. For example, for an AppFunction implementation like
31  *
32  * ```
33  * package com.notes
34  *
35  * class NotesFunction {
36  *   @AppFunction
37  *   suspend fun createNote(params: Params): Note { ... }
38  * }
39  * ```
40  *
41  * An inventory registry would be generated:
42  * ```
43  * package appfunctions_aggregated_deps
44  *
45  * @AppFunctionComponentRegistry(
46  *   componentCategory = AppFunctionComponentCategory.INVENTORY,
47  *   componentNames = [
48  *     "com.notes.${'$'}NotesFunction_AppFunctionInventory",
49  *   ]
50  * )
51  * ```
52  */
53 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
54 @Retention(AnnotationRetention.BINARY)
55 @Target(AnnotationTarget.CLASS)
56 public annotation class AppFunctionComponentRegistry(
57     @AppFunctionComponentCategory public val componentCategory: String,
58     public val componentNames: Array<String>,
59 )
60 
61 /**
62  * Defines the categories of AppFunction components that can be registered in a
63  * [AppFunctionComponentRegistry].
64  *
65  * These categories guide the AppFunction compiler plugin in how to process and aggregate the
66  * registered components.
67  */
68 @StringDef(
69     AppFunctionComponentCategory.INVENTORY,
70     AppFunctionComponentCategory.INVOKER,
71     AppFunctionComponentCategory.FUNCTION,
72 )
73 @Retention(AnnotationRetention.SOURCE)
74 internal annotation class AppFunctionComponentCategory {
75     companion object {
76         /**
77          * The components in inventory category are used to generate the implementation of an
78          * [androidx.appfunctions.internal.AggregatedAppFunctionInventory].
79          */
80         const val INVENTORY: String = "INVENTORY"
81         /**
82          * The components in invoker category are used to generate the implementation of an
83          * [androidx.appfunctions.internal.AggregatedAppFunctionInvoker].
84          */
85         const val INVOKER: String = "INVOKER"
86         /**
87          * The components in function category are used to generate the asset XML file for platform
88          * indexer to index available functions from the app.
89          */
90         const val FUNCTION: String = "FUNCTION"
91     }
92 }
93