From 30040fa3e2841abc8e024e39a3eca80f76b0cc23 Mon Sep 17 00:00:00 2001 From: Felipe Leme Date: Tue, 3 Oct 2017 11:41:52 -0700 Subject: [PATCH] Improved javadocs for Autofill save workflow. Test: ran 'm -j doc-comment-check-docs' and checked resulting HTML Bug: 67367585 Change-Id: I25e0f2f6667a4fad6e039f9518c973bac0bc8c7c --- .../android/service/autofill/AutofillService.java | 12 +++++++++--- .../android/service/autofill/SaveCallback.java | 15 +++++++++++++-- 2 files changed, 22 insertions(+), 5 deletions(-) diff --git a/core/java/android/service/autofill/AutofillService.java b/core/java/android/service/autofill/AutofillService.java index 045c833040974..1521e7e656a1e 100644 --- a/core/java/android/service/autofill/AutofillService.java +++ b/core/java/android/service/autofill/AutofillService.java @@ -503,13 +503,19 @@ public abstract class AutofillService extends Service { @NonNull CancellationSignal cancellationSignal, @NonNull FillCallback callback); /** - * Called when user requests service to save the fields of a screen. + * Called when the user requests the service to save the contents of a screen. * *

Service must call one of the {@link SaveCallback} methods (like * {@link SaveCallback#onSuccess()} or {@link SaveCallback#onFailure(CharSequence)}) - * to notify the result of the request. + * to notify the Android System of the result of the request. * - *

Note: To retrieve the actual value of the field, the service should call + *

If the service could not handle the request right away—for example, because it must + * launch an activity asking the user to authenticate first or because the network is + * down—the service could keep the {@link SaveRequest request} and reuse it later, + * but the service must call {@link SaveCallback#onSuccess()} right away. + * + *

Note: To retrieve the actual value of fields input by the user, the service + * should call * {@link android.app.assist.AssistStructure.ViewNode#getAutofillValue()}; if it calls * {@link android.app.assist.AssistStructure.ViewNode#getText()} or other methods, there is no * guarantee such method will return the most recent value of the field. diff --git a/core/java/android/service/autofill/SaveCallback.java b/core/java/android/service/autofill/SaveCallback.java index 3a7013841729b..7207f1df3ee56 100644 --- a/core/java/android/service/autofill/SaveCallback.java +++ b/core/java/android/service/autofill/SaveCallback.java @@ -34,9 +34,13 @@ public final class SaveCallback { /** * Notifies the Android System that an - * {@link AutofillService#onSaveRequest(SaveRequest, SaveCallback)} was successfully fulfilled + * {@link AutofillService#onSaveRequest(SaveRequest, SaveCallback)} was successfully handled * by the service. * + *

If the service could not handle the request right away—for example, because it must + * launch an activity asking the user to authenticate first or because the network is + * down—it should still call {@link #onSuccess()}. + * * @throws RuntimeException if an error occurred while calling the Android System. */ public void onSuccess() { @@ -51,9 +55,16 @@ public final class SaveCallback { /** * Notifies the Android System that an - * {@link AutofillService#onSaveRequest(SaveRequest, SaveCallback)} could not be fulfilled + * {@link AutofillService#onSaveRequest(SaveRequest, SaveCallback)} could not be handled * by the service. * + *

This method should only be called when the service could not handle the request right away + * and could not recover or retry it. If the service could retry or recover, it could keep + * the {@link SaveRequest} and call {@link #onSuccess()} instead. + * + *

Note: The Android System displays an UI with the supplied error message; if + * you prefer to show your own message, call {@link #onSuccess()} instead. + * * @param message error message to be displayed to the user. * * @throws RuntimeException if an error occurred while calling the Android System.