Improve javadocs of app functions (046f770b) · Commits · e / os / android_frameworks_base

core/java/android/app/appfunctions/AppFunctionManager.java

+28 −17

Original line number	Diff line number	Diff line
		@@ -50,29 +50,40 @@ import java.util.function.Consumer;
		* <p>Building App Functions:
		*
		* <p>Most developers should build app functions through the AppFunctions SDK. This SDK library
		* offers a more convenient and type-safe way to represent the inputs and outputs of an app
		* function, using custom data classes called "AppFunction Schemas".
		* offers a more convenient and type-safe way to build app functions. The SDK provides predefined
		* function schemas for common use cases and associated data classes for function parameters and
		* return values. Apps only have to implement the provided interfaces. Internally, the SDK converts
		* these data classes into {@link ExecuteAppFunctionRequest#getParameters()} and
		* {@link ExecuteAppFunctionResponse#getResultDocument()}.
		*
		* <p>The suggested way to build an app function is to use the AppFunctions SDK. The SDK provides
		* custom data classes (AppFunctions Schemas) and handles the conversion to the underlying {@link
		* android.app.appsearch.GenericDocument}/{@link android.os.Bundle} format used in {@link
		* ExecuteAppFunctionRequest} and {@link ExecuteAppFunctionResponse}.
		*
		* <p>Discovering (Listing) App Functions:
		* <p>Discovering App Functions:
		*
		* <p>When there is a package change or the device starts up, the metadata of available functions is
		* indexed on-device by {@link AppSearchManager}. AppSearch stores the indexed information as a
		* {@code AppFunctionStaticMetadata} document. This allows other apps and the app itself to discover
		* these functions using the AppSearch search APIs. Visibility to this metadata document is based on
		* the packages that have visibility to the app providing the app functions.
		* indexed on-device by {@link AppSearchManager}. AppSearch stores the indexed information as an
		* {@code AppFunctionStaticMetadata} document. This document contains the {@code functionIdentifier}
		* and the schema information that the app function implements. This allows other apps and the app
		* itself to discover these functions using the AppSearch search APIs. Visibility to this metadata
		* document is based on the packages that have visibility to the app providing the app functions.
		* AppFunction SDK provides a convenient way to achieve this and is the preferred method.
		*
		* <p>Executing App Functions:
		*
		* <p>Requests to execute a function are built using the {@link ExecuteAppFunctionRequest} class.
		* Callers need the {@code android.permission.EXECUTE_APP_FUNCTIONS} or {@code
		* android.permission.EXECUTE_APP_FUNCTIONS_TRUSTED} permission to execute app functions from other
		* apps. An app has automatic visibility to its own functions and doesn't need these permissions to
		* call its own functions via {@code AppFunctionManager}.
		* <p>To execute an app function, the caller app can retrieve the {@code functionIdentifier} from
		* the {@code AppFunctionStaticMetadata} document and use it to build an
		* {@link ExecuteAppFunctionRequest}. Then, invoke {@link #executeAppFunction} with the request
		* to execute the app function. Callers need the {@code android.permission.EXECUTE_APP_FUNCTIONS}
		* or {@code android.permission.EXECUTE_APP_FUNCTIONS_TRUSTED} permission to execute app
		* functions from other apps. An app can always execute its own app functions and doesn't need these
		* permissions. AppFunction SDK provides a convenient way to achieve this and is the preferred
		* method.
		*
		* <p>Example:
		*
		* <p>An assistant app is trying to fulfill the user request "Save XYZ into my note". The assistant
		* app should first list all available app functions as {@code AppFunctionStaticMetadata} documents
		* from AppSearch. Then, it should identify an app function that implements the {@code CreateNote}
		* schema. Finally, the assistant app can invoke {@link #executeAppFunction} with the {@code
		* functionIdentifier} of the chosen function.
		*/
		@FlaggedApi(FLAG_ENABLE_APP_FUNCTION_MANAGER)
		@SystemService(Context.APP_FUNCTION_SERVICE)

core/java/android/app/appfunctions/ExecuteAppFunctionRequest.java

+16 −8

Original line number	Diff line number	Diff line
		@@ -114,18 +114,14 @@ public final class ExecuteAppFunctionRequest implements Parcelable {
		* <p>The bundle may have missing parameters. Developers are advised to implement defensive
		* handling measures.
		*
		* <p>Similar to {@link #getFunctionIdentifier()} the parameters required by a function can be
		* obtained by querying AppSearch for the corresponding {@code AppFunctionStaticMetadata}. This
		* metadata will contain enough information for the caller to resolve the required parameters
		* either using information from the metadata itself or using the AppFunction SDK for function
		* callers.
		* @see AppFunctionManager on how to determine the expected parameters.
		*/
		@NonNull
		public GenericDocument getParameters() {
		return mParameters.getValue();
		}

		/** Returns the additional data relevant to this function execution. */
		/** Returns the additional metadata for this function execution request. */
		@NonNull
		public Bundle getExtras() {
		return mExtras;
		@@ -153,19 +149,31 @@ public final class ExecuteAppFunctionRequest implements Parcelable {
		@NonNull
		private GenericDocument mParameters = new GenericDocument.Builder<>("", "", "").build();

		/**
		* Creates a new instance of this builder class.
		*
		* @param targetPackageName The package name of the target app providing the app function to
		* invoke.
		* @param functionIdentifier The identifier used by the {@link AppFunctionService} from the
		* target app to uniquely identify the function to be invoked.
		*/
		public Builder(@NonNull String targetPackageName, @NonNull String functionIdentifier) {
		mTargetPackageName = Objects.requireNonNull(targetPackageName);
		mFunctionIdentifier = Objects.requireNonNull(functionIdentifier);
		}

		/** Sets the additional data relevant to this function execution. */
		/** Sets the additional metadata for this function execution request. */
		@NonNull
		public Builder setExtras(@NonNull Bundle extras) {
		mExtras = Objects.requireNonNull(extras);
		return this;
		}

		/** Sets the function parameters. */
		/**
		* Sets the function parameters.
		*
		* @see #ExecuteAppFunctionRequest#getParameters()
		*/
		@NonNull
		public Builder setParameters(@NonNull GenericDocument parameters) {
		Objects.requireNonNull(parameters);

core/java/android/app/appfunctions/ExecuteAppFunctionResponse.java

+5 −3

Original line number	Diff line number	Diff line
		@@ -156,7 +156,7 @@ public final class ExecuteAppFunctionResponse implements Parcelable {
		* Returns a successful response.
		*
		* @param resultDocument The return value of the executed function.
		* @param extras The additional metadata data relevant to this function execution response.
		* @param extras The additional metadata for this function execution response.
		*/
		@NonNull
		@FlaggedApi(FLAG_ENABLE_APP_FUNCTION_MANAGER)
		@@ -174,7 +174,7 @@ public final class ExecuteAppFunctionResponse implements Parcelable {
		* Returns a failure response.
		*
		* @param resultCode The result code of the app function execution.
		* @param extras The additional metadata data relevant to this function execution response.
		* @param extras The additional metadata for this function execution response.
		* @param errorMessage The error message associated with the result, if any.
		*/
		@NonNull
		@@ -216,13 +216,15 @@ public final class ExecuteAppFunctionResponse implements Parcelable {
		* // Do something with the returnValue
		* }
		* </pre>
		*
		* @see AppFunctionManager on how to determine the expected function return.
		*/
		@NonNull
		public GenericDocument getResultDocument() {
		return mResultDocumentWrapper.getValue();
		}

		/** Returns the extras of the app function execution. */
		/** Returns the additional metadata for this function execution response. */
		@NonNull
		public Bundle getExtras() {
		return mExtras;