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 17 package android.app.appsearch.functions; 18 19 import android.annotation.FlaggedApi; 20 import android.annotation.NonNull; 21 import android.app.appsearch.GenericDocument; 22 import android.app.appsearch.safeparcel.AbstractSafeParcelable; 23 import android.app.appsearch.safeparcel.GenericDocumentParcel; 24 import android.app.appsearch.safeparcel.SafeParcelable; 25 import android.os.Bundle; 26 import android.os.Parcel; 27 import android.os.Parcelable; 28 29 import com.android.appsearch.flags.Flags; 30 31 import java.util.Objects; 32 import java.util.concurrent.Executor; 33 import java.util.function.Consumer; 34 35 /** 36 * Represents a response of an execution of an app function. 37 * 38 * @see AppFunctionManager#executeAppFunction(ExecuteAppFunctionRequest, Executor, Consumer) 39 */ 40 @SafeParcelable.Class(creator = "ExecuteAppFunctionResponseCreator") 41 @FlaggedApi(Flags.FLAG_ENABLE_APP_FUNCTIONS) 42 public final class ExecuteAppFunctionResponse extends AbstractSafeParcelable { 43 /** 44 * The name of the property that stores the result within the result {@link GenericDocument}. 45 * 46 * @see #getResult(). 47 */ 48 public static final String PROPERTY_RESULT = "result"; 49 50 @NonNull 51 public static final Parcelable.Creator<ExecuteAppFunctionResponse> CREATOR = 52 new ExecuteAppFunctionResponseCreator(); 53 54 @Field(id = 1) 55 @NonNull 56 final GenericDocumentParcel mResult; 57 58 @Field(id = 2, getter = "getExtras") 59 @NonNull 60 private final Bundle mExtras; 61 62 @NonNull private final GenericDocument mResultCached; 63 64 @Constructor ExecuteAppFunctionResponse( @aramid = 1) @onNull GenericDocumentParcel result, @Param(id = 2) @NonNull Bundle extras)65 ExecuteAppFunctionResponse( 66 @Param(id = 1) @NonNull GenericDocumentParcel result, 67 @Param(id = 2) @NonNull Bundle extras) { 68 mResult = Objects.requireNonNull(result); 69 mResultCached = new GenericDocument(mResult); 70 mExtras = extras; 71 } 72 ExecuteAppFunctionResponse(@onNull GenericDocument result, @NonNull Bundle extras)73 private ExecuteAppFunctionResponse(@NonNull GenericDocument result, @NonNull Bundle extras) { 74 mResultCached = Objects.requireNonNull(result); 75 mResult = mResultCached.getDocumentParcel(); 76 mExtras = Objects.requireNonNull(extras); 77 } 78 79 /** 80 * Returns the return value of the executed function. An empty document indicates that the 81 * function does not produce a return value. 82 */ 83 @NonNull getResult()84 public GenericDocument getResult() { 85 return mResultCached; 86 } 87 88 /** Returns the additional metadata data relevant to this function execution response. */ 89 @NonNull getExtras()90 public Bundle getExtras() { 91 return mExtras; 92 } 93 94 @Override writeToParcel(@onNull Parcel dest, int flags)95 public void writeToParcel(@NonNull Parcel dest, int flags) { 96 ExecuteAppFunctionResponseCreator.writeToParcel(this, dest, flags); 97 } 98 99 /** The builder for creating {@link ExecuteAppFunctionResponse} instances. */ 100 @FlaggedApi(Flags.FLAG_ENABLE_APP_FUNCTIONS) 101 public static final class Builder { 102 @NonNull private GenericDocument mResult = GenericDocument.EMPTY; 103 @NonNull private Bundle mExtras = Bundle.EMPTY; 104 105 /** 106 * Sets the result of the app function execution. The result is stored within a {@link 107 * GenericDocument} under the property name {@link #PROPERTY_RESULT}. An empty {@link 108 * GenericDocument} indicates that the function does not produce a return value. Defaults to 109 * an empty {@link GenericDocument} if not set. 110 */ 111 @NonNull setResult(@onNull GenericDocument result)112 public Builder setResult(@NonNull GenericDocument result) { 113 mResult = result; 114 return this; 115 } 116 117 /** 118 * Sets the additional metadata relevant to this function execution response. Defaults to 119 * {@link Bundle#EMPTY} if not set. 120 */ 121 @NonNull setExtras(@onNull Bundle extras)122 public Builder setExtras(@NonNull Bundle extras) { 123 mExtras = extras; 124 return this; 125 } 126 127 /** 128 * Constructs a new {@link ExecuteAppFunctionResponse} from the contents of this builder. 129 */ 130 @NonNull build()131 public ExecuteAppFunctionResponse build() { 132 return new ExecuteAppFunctionResponse(mResult, mExtras); 133 } 134 } 135 } 136