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 /** 20 * Annotates a class to indicate that it can be serialized and transferred between processes using 21 * AppFunction. 22 * 23 * When a class is annotated with `@AppFunctionSerializable` and is used as a parameter or return 24 * type (directly or as a nested entity) in an AppFunction, the shape of the entity defined within 25 * its primary constructor will be exposed to the caller as an 26 * [androidx.appfunctions.metadata.AppFunctionMetadataDocument]. This information allows the caller 27 * to construct the structured input to call an AppFunction or understand what properties are 28 * provided in the structured output. 29 * 30 * **Constraints for Classes Annotated with `@AppFunctionSerializable`:** 31 * * **Primary Constructor Parameters:** Only properties declared in the primary constructor that 32 * expose a getter method are eligible for inclusion in the AppFunctionMetadata. Critically, it is 33 * a **requirement** to place properties with a getter in primary constructor. Attempting to 34 * include constructor parameters that are not declared as properties (and thus don't have a 35 * getter) will result in a compiler error. 36 * * **Supported Property Types:** The properties in the primary constructor must be of one of the 37 * following types: 38 * * `Int` 39 * * `Long` 40 * * `Float` 41 * * `Double` 42 * * `Boolean` 43 * * `String` 44 * * `IntArray` 45 * * `LongArray` 46 * * `FloatArray` 47 * * `DoubleArray` 48 * * `BooleanArray` 49 * * `List<String>` 50 * * Another class annotated with `@AppFunctionSerializable` (enabling nested structures) or a 51 * list of a class annotated with `@AppFunctionSerializable` 52 * * **Public Primary Constructor:** The primary constructor of the annotated class must have public 53 * visibility to allow instantiation. 54 * * ** 55 * 56 * **IMPORTANT:** The default value set in the constructor parameter is ignored when the value is 57 * missing from the function calling request. Instead, the specified rule is always used: 58 * * **Non-nullable Properties:** If a value is missing for a non-nullable property from the caller, 59 * the library will throw an exception to notify the caller automatically. 60 * * **Nullable Properties:** If a value is missing for a nullable property, `null` will be used. 61 * * **Collection Properties:** If a value is missing for a collection property, an empty collection 62 * will be used. 63 * 64 * **Example:** 65 * 66 * ``` 67 * @AppFunctionSerializable 68 * class Location(val latitude: Double, val longitude: Double) 69 * 70 * @AppFunctionSerializable 71 * class Place( 72 * val name: String, 73 * val location: Location, // Nested AppFunctionSerializable 74 * // Nullable String is allowed, if missing, will be null. The default value will not be used 75 * // when the value is missing 76 * val notes: String? = "default" 77 * ) 78 * 79 * @AppFunctionSerializable 80 * class SearchPlaceResult( 81 * val places: List<Place> // If missing, will be an empty list 82 * ) 83 * 84 * @AppFunctionSerializable 85 * class Attachment( 86 * uri: String // Putting constructor parameter without getter will result in compiler error 87 * ) 88 * ``` 89 */ 90 // Use BINARY here so that the annotation is kept around at the aggregation stage. 91 @Retention(AnnotationRetention.BINARY) 92 @Target(AnnotationTarget.CLASS) 93 public annotation class AppFunctionSerializable 94