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 com.android.extensions.appfunctions; 18 19 import android.annotation.NonNull; 20 import android.app.appsearch.GenericDocument; 21 import android.os.Bundle; 22 23 import java.util.Objects; 24 25 /** 26 * A request to execute an app function. 27 * 28 * <p>This class copies {@link android.app.appfunctions.ExecuteAppFunctionRequest} without parcel 29 * functionality and exposes it here as a sidecar library (avoiding direct dependency on the 30 * platform API). 31 */ 32 public final class ExecuteAppFunctionRequest { 33 /** Returns the package name of the app that hosts the function. */ 34 @NonNull private final String mTargetPackageName; 35 36 /** 37 * The unique string identifier of the app function to be executed. This identifier is used to 38 * execute a specific app function. 39 */ 40 @NonNull private final String mFunctionIdentifier; 41 42 /** Returns additional metadata relevant to this function execution request. */ 43 @NonNull private final Bundle mExtras; 44 45 /** 46 * Returns the parameters required to invoke this function. Within this [GenericDocument], the 47 * property names are the names of the function parameters and the property values are the 48 * values of those parameters. 49 * 50 * <p>The document may have missing parameters. Developers are advised to implement defensive 51 * handling measures. 52 */ 53 @NonNull private final GenericDocument mParameters; 54 ExecuteAppFunctionRequest( @onNull String targetPackageName, @NonNull String functionIdentifier, @NonNull Bundle extras, @NonNull GenericDocument parameters)55 private ExecuteAppFunctionRequest( 56 @NonNull String targetPackageName, 57 @NonNull String functionIdentifier, 58 @NonNull Bundle extras, 59 @NonNull GenericDocument parameters) { 60 mTargetPackageName = Objects.requireNonNull(targetPackageName); 61 mFunctionIdentifier = Objects.requireNonNull(functionIdentifier); 62 mExtras = Objects.requireNonNull(extras); 63 mParameters = Objects.requireNonNull(parameters); 64 } 65 66 /** Returns the package name of the app that hosts the function. */ 67 @NonNull getTargetPackageName()68 public String getTargetPackageName() { 69 return mTargetPackageName; 70 } 71 72 /** 73 * Returns the unique string identifier of the app function to be executed. 74 * 75 * <p>When there is a package change or the device starts up, the metadata of available 76 * functions is indexed by AppSearch. AppSearch stores the indexed information as {@code 77 * AppFunctionStaticMetadata} document. 78 * 79 * <p>The ID can be obtained by querying the {@code AppFunctionStaticMetadata} documents from 80 * AppSearch. 81 * 82 * <p>If the {@code functionId} provided is invalid, the caller will get an invalid argument 83 * response. 84 */ 85 @NonNull getFunctionIdentifier()86 public String getFunctionIdentifier() { 87 return mFunctionIdentifier; 88 } 89 90 /** 91 * Returns the function parameters. The key is the parameter name, and the value is the 92 * parameter value. 93 * 94 * <p>The {@link GenericDocument} may have missing parameters. Developers are advised to 95 * implement defensive handling measures. 96 * 97 * <p>Similar to {@link #getFunctionIdentifier()} the parameters required by a function can be 98 * obtained by querying AppSearch for the corresponding {@code AppFunctionStaticMetadata}. This 99 * metadata will contain enough information for the caller to resolve the required parameters 100 * either using information from the metadata itself or using the AppFunction SDK for function 101 * callers. 102 */ 103 @NonNull getParameters()104 public GenericDocument getParameters() { 105 return mParameters; 106 } 107 108 /** Returns the additional data relevant to this function execution. */ 109 @NonNull getExtras()110 public Bundle getExtras() { 111 return mExtras; 112 } 113 114 /** Builder for {@link ExecuteAppFunctionRequest}. */ 115 public static final class Builder { 116 @NonNull private final String mTargetPackageName; 117 @NonNull private final String mFunctionIdentifier; 118 @NonNull private Bundle mExtras = Bundle.EMPTY; 119 120 @NonNull 121 private GenericDocument mParameters = new GenericDocument.Builder<>("", "", "").build(); 122 Builder(@onNull String targetPackageName, @NonNull String functionIdentifier)123 public Builder(@NonNull String targetPackageName, @NonNull String functionIdentifier) { 124 mTargetPackageName = Objects.requireNonNull(targetPackageName); 125 mFunctionIdentifier = Objects.requireNonNull(functionIdentifier); 126 } 127 128 /** Sets the additional data relevant to this function execution. */ 129 @NonNull setExtras(@onNull Bundle extras)130 public Builder setExtras(@NonNull Bundle extras) { 131 mExtras = Objects.requireNonNull(extras); 132 return this; 133 } 134 135 /** Sets the function parameters. */ 136 @NonNull setParameters(@onNull GenericDocument parameters)137 public Builder setParameters(@NonNull GenericDocument parameters) { 138 Objects.requireNonNull(parameters); 139 mParameters = parameters; 140 return this; 141 } 142 143 /** Builds the {@link ExecuteAppFunctionRequest}. */ 144 @NonNull build()145 public ExecuteAppFunctionRequest build() { 146 return new ExecuteAppFunctionRequest( 147 mTargetPackageName, mFunctionIdentifier, mExtras, mParameters); 148 } 149 } 150 } 151