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.RestrictTo.Scope
21 import kotlin.reflect.KClass
22 
23 /**
24  * Marks an [AppFunctionSerializable] compatible class as a *serialization proxy* for a Java/Android
25  * object.
26  *
27  * This annotation designates an [AppFunctionSerializable] compatible class as a *serialization
28  * proxy* for a specified Java/Android object class ([targetClass]). This proxy will be used to
29  * represent/serialize instances of [targetClass] in
30  * [androidx.appfunctions.metadata.AppFunctionMetadata].
31  *
32  * The [targetClass] parameter specifies the Java/Android object being represented.
33  *
34  * The annotated class *must* adhere to these rules:
35  * - It *must* be a valid [AppFunctionSerializable] (Even though it does not need this annotation).
36  * - It *must* provide a public member function `to[targetClass]` that returns an instance of
37  *   [targetClass].
38  * - It *must* provide a public `companion object` function `from[targetClass]` that accepts a
39  *   [targetClass] instance and returns the annotated proxy object. This function acts as a factory
40  *   method.
41  *
42  * For example, to create a proxy for [java.time.LocalDateTime]:
43  * ```
44  * @AppFunctionSerializableProxy(targetClass = LocalDateTime::class)
45  * public data class AppFunctionLocalDateTime(
46  *     val year: Int,
47  *     val month: Int,
48  *     val dayOfMonth: Int,
49  *     val hour: Int,
50  *     val minute: Int,
51  *     val second: Int,
52  *     val nanoOfSecond: Int,
53  * ) {
54  *     public fun toLocalDateTime(): LocalDateTime {
55  *         return LocalDateTime.of(year, month, dayOfMonth, hour, minute, second, nanoOfSecond)
56  *     }
57  *
58  *     public companion object {
59  *         public fun fromLocalDateTime(localDateTime: LocalDateTime): AppFunctionLocalDateTime {
60  *             return AppFunctionLocalDateTime(
61  *                 localDateTime.year,
62  *                 localDateTime.monthValue,
63  *                 localDateTime.dayOfMonth,
64  *                 localDateTime.hour,
65  *                 localDateTime.minute,
66  *                 localDateTime.second,
67  *                 localDateTime.nano
68  *             )
69  *         }
70  *     }
71  * }
72  * ```
73  *
74  * When [androidx.appfunctions.metadata.AppFunctionMetadata] is generated, any instance of
75  * [java.time.LocalDateTime] will be represented by the
76  * [androidx.appfunctions.metadata.AppFunctionObjectTypeMetadata] of the `AppFunctionLocalDateTime`
77  * proxy.
78  *
79  * This annotation is for internal library use only.
80  */
81 @RestrictTo(Scope.LIBRARY_GROUP)
82 @Retention(AnnotationRetention.BINARY)
83 @Target(AnnotationTarget.CLASS)
84 public annotation class AppFunctionSerializableProxy(val targetClass: KClass<*>)
85