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.app.appsearch.GenericDocument;
20 import android.os.Bundle;
21 
22 import androidx.annotation.RestrictTo;
23 
24 import org.jspecify.annotations.NonNull;
25 
26 /**
27  * A request to execute an app function.
28  *
29  * <p>The {@link ExecuteAppFunctionRequest#getParameters()} contains the parameters for the function
30  * to be executed in a GenericDocument. Structured classes defined in the AppFunction SDK can be
31  * converted into GenericDocuments.
32  *
33  * <p>The {@link ExecuteAppFunctionRequest#getExtras()} provides any extra metadata for the request.
34  * Structured APIs can be exposed in the SDK by packing and unpacking this Bundle.
35  */
36 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
37 public final class ExecuteAppFunctionRequest {
38     /** Returns the package name of the app that hosts the function. */
39     @NonNull
getTargetPackageName()40     public String getTargetPackageName() {
41         throw new RuntimeException("Stub!");
42     }
43 
44     /**
45      * Returns the unique string identifier of the app function to be executed.
46      *
47      * <p>When there is a package change or the device starts up, the metadata of available
48      * functions is indexed by AppSearch. AppSearch stores the indexed information as {@code
49      * AppFunctionStaticMetadata} document.
50      *
51      * <p>The ID can be obtained by querying the {@code AppFunctionStaticMetadata} documents from
52      * AppSearch.
53      *
54      * <p>If the {@code functionId} provided is invalid, the caller will get an invalid argument
55      * response.
56      */
57     @NonNull
getFunctionIdentifier()58     public String getFunctionIdentifier() {
59         throw new RuntimeException("Stub!");
60     }
61 
62     /**
63      * Returns the function parameters. The key is the parameter name, and the value is the
64      * parameter value.
65      *
66      * <p>The {@link GenericDocument} may have missing parameters. Developers are advised to
67      * implement defensive handling measures.
68      *
69      * <p>Similar to {@link #getFunctionIdentifier()} the parameters required by a function can be
70      * obtained by querying AppSearch for the corresponding {@code AppFunctionStaticMetadata}. This
71      * metadata will contain enough information for the caller to resolve the required parameters
72      * either using information from the metadata itself or using the AppFunction SDK for function
73      * callers.
74      */
75     @NonNull
getParameters()76     public GenericDocument getParameters() {
77         throw new RuntimeException("Stub!");
78     }
79 
80     /** Returns the additional data relevant to this function execution. */
81     @NonNull
getExtras()82     public Bundle getExtras() {
83         throw new RuntimeException("Stub!");
84     }
85 
86     /** Builder for {@link ExecuteAppFunctionRequest}. */
87     public static final class Builder {
Builder(@onNull String targetPackageName, @NonNull String functionIdentifier)88         public Builder(@NonNull String targetPackageName, @NonNull String functionIdentifier) {
89             throw new RuntimeException("Stub!");
90         }
91 
92         /** Sets the additional data relevant to this function execution. */
93         @NonNull
setExtras(@onNull Bundle extras)94         public Builder setExtras(@NonNull Bundle extras) {
95             throw new RuntimeException("Stub!");
96         }
97 
98         /** Sets the function parameters. */
99         @NonNull
setParameters(@onNull GenericDocument parameters)100         public Builder setParameters(@NonNull GenericDocument parameters) {
101             throw new RuntimeException("Stub!");
102         }
103 
104         /** Builds the {@link ExecuteAppFunctionRequest}. */
105         @NonNull
build()106         public ExecuteAppFunctionRequest build() {
107             throw new RuntimeException("Stub!");
108         }
109     }
110 }
111