1 /*
2  * Copyright 2022 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.intentresolver.model;
18 
19 import android.content.pm.ResolveInfo;
20 
21 import com.android.intentresolver.chooser.TargetInfo;
22 
23 import java.util.Comparator;
24 
25 /**
26  * A ranking model for resolver targets, providing ordering and (optionally) numerical scoring.
27  *
28  * As required by the {@link Comparator} contract, objects returned by {@code getComparator()} must
29  * apply a total ordering on its inputs consistent across all calls to {@code Comparator#compare()}.
30  * Other query methods and ranking feedback should refer to that same ordering, so implementors are
31  * generally advised to "lock in" an immutable snapshot of their model data when this object is
32  * initialized (preferring to replace the entire {@code ResolverComparatorModel} instance if the
33  * backing data needs to be updated in the future).
34  */
35 interface ResolverComparatorModel {
36     /**
37      * Get a {@code Comparator} that can be used to sort {@code ResolveInfo} targets according to
38      * the model ranking.
39      */
getComparator()40     Comparator<ResolveInfo> getComparator();
41 
42     /**
43      * Get the numerical score, if any, that the model assigns to the component with the specified
44      * {@code name}. Scores range from zero to one, with one representing the highest possible
45      * likelihood that the user will select that component as the target. Implementations that don't
46      * assign numerical scores are <em>recommended</em> to return a value of 0 for all components.
47      */
getScore(TargetInfo targetInfo)48     float getScore(TargetInfo targetInfo);
49 
50     /**
51      * Notify the model that the user selected a target. (Models may log this information, use it as
52      * a feedback signal for their ranking, etc.) Because the data in this
53      * {@code ResolverComparatorModel} instance is immutable, clients will need to get an up-to-date
54      * instance in order to see any changes in the ranking that might result from this feedback.
55      */
notifyOnTargetSelected(TargetInfo targetInfo)56     void notifyOnTargetSelected(TargetInfo targetInfo);
57 }
58