Merge "Improved documentation of AutofillFieldClassificationService.onGetScores()" into pi-dev

    /**

     * Calculates field classification scores in a batch.

     *

     * <p>See {@link AutofillFieldClassificationService} for more info about field classification

     * scores.

     * <p>A field classification score is a {@code float} representing how well an

     * {@link AutofillValue} filled matches a expected value predicted by an autofill service

     * —a full-match is {@code 1.0} (representing 100%), while a full mismatch is {@code 0.0}.

     *

     * <p>The exact score depends on the algorithm used to calculate it&mdash; the service must

     * provide at least one default algorithm (which is used when the algorithm is not specified

     * or is invalid), but it could provide more (in which case the algorithm name should be

     * specifiied by the caller when calculating the scores).

     *

     * <p>For example, if the service provides an algorithm named {@code EXACT_MATCH} that

     * returns {@code 1.0} if all characters in match or {@code 0.0} otherwise, a call to:

     *

     * <pre>

     * service.onGetScores("EXACT_MATCH", null,

     *   Arrays.asList(AutofillValue.forText("email1"), AutofillValue.forText("PHONE1")),

     *   Arrays.asList("email1", "phone1"));

     * </pre>

     *

     * <p>Returns:

     *

     * <pre>

     * [

     *   [1.0, 0.0], // "email1" compared against ["email1", "phone1"]

     *   [0.0, 0.0]  // "PHONE1" compared against ["email1", "phone1"]

     * ];

     * </pre>

     *

     * <p>If the same algorithm allows the caller to specify whether the comparisons should be

     * case sensitive by passing a boolean option named {@code "case_sensitive"}, then a call to:

     *

     * <pre>

     * Bundle algorithmOptions = new Bundle();

     * algorithmOptions.putBoolean("case_sensitive", false);

     *

     * service.onGetScores("EXACT_MATCH", algorithmOptions,

     *   Arrays.asList(AutofillValue.forText("email1"), AutofillValue.forText("PHONE1")),

     *   Arrays.asList("email1", "phone1"));

     * </pre>

     *

     * <p>Returns:

     *

     * <pre>

     * [

     *   [1.0, 0.0], // "email1" compared against ["email1", "phone1"]

     *   [0.0, 1.0]  // "PHONE1" compared against ["email1", "phone1"]

     * ];

     * </pre>

     *

     * @param algorithm name of the algorithm to be used to calculate the scores. If invalid, the

     * default algorithm will be used instead.

     * @param args optional arguments to be passed to the algorithm.

     * @param algorithm name of the algorithm to be used to calculate the scores. If invalid or

     * {@code null}, the default algorithm is used instead.

     * @param algorithmOptions optional arguments to be passed to the algorithm.

     * @param actualValues values entered by the user.

     * @param userDataValues values predicted from the user data.

     * @return the calculated scores, with the first dimension representing actual values and the

     * second dimension values from {@link UserData}.

     * @return the calculated scores of {@code actualValues} x {@code userDataValues}.

     *

     * {@hide}

     */

    @Nullable

    @SystemApi

    public float[][] onGetScores(@Nullable String algorithm,

            @Nullable Bundle args, @NonNull List<AutofillValue> actualValues,

            @Nullable Bundle algorithmOptions, @NonNull List<AutofillValue> actualValues,

            @NonNull List<String> userDataValues) {

        Log.e(TAG, "service implementation (" + getClass() + " does not implement onGetScore()");

        return null;