diff options
Diffstat (limited to 'java/com/android/dialer/p13n/inference/protocol/P13nRanker.java')
-rw-r--r-- | java/com/android/dialer/p13n/inference/protocol/P13nRanker.java | 81 |
1 files changed, 81 insertions, 0 deletions
diff --git a/java/com/android/dialer/p13n/inference/protocol/P13nRanker.java b/java/com/android/dialer/p13n/inference/protocol/P13nRanker.java new file mode 100644 index 000000000..41f1de49d --- /dev/null +++ b/java/com/android/dialer/p13n/inference/protocol/P13nRanker.java @@ -0,0 +1,81 @@ +/* + * Copyright (C) 2016 The Android Open Source Project + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except + * in compliance with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software distributed under the License + * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express + * or implied. See the License for the specific language governing permissions and limitations under + * the License. + */ + +package com.android.dialer.p13n.inference.protocol; + +import android.database.Cursor; +import android.support.annotation.MainThread; +import android.support.annotation.NonNull; +import android.support.annotation.Nullable; +import java.util.List; + +/** Provides personalized ranking of outgoing call targets. */ +public interface P13nRanker { + + /** + * Re-orders a list of phone numbers according to likelihood they will be the next outgoing call. + * + * @param phoneNumbers the list of candidate numbers to call (may be in contacts list or not) + */ + @NonNull + @MainThread + List<String> rankList(@NonNull List<String> phoneNumbers); + + /** + * Re-orders a retrieved contact list according to likelihood they will be the next outgoing call. + * + * <p>A new cursor with reordered data is returned; the input cursor is unmodified except for its + * position. If the order is unchanged, this method may return a reference to the unmodified input + * cursor directly. The order would be unchanged if the ranking cache is not yet ready, or if the + * input cursor is closed or invalid, or if any other error occurs in the ranking process. + * + * @param phoneQueryResults cursor of results of a Dialer search query + * @param queryLength length of the search query that resulted in the cursor data, if below 0, + * assumes no length is specified, thus applies the default behavior which is same as when + * queryLength is greater than zero. + * @return new cursor of data reordered by ranking (or reference to input cursor if order + * unchanged) + */ + @NonNull + @MainThread + Cursor rankCursor(@NonNull Cursor phoneQueryResults, int queryLength); + + /** + * Refreshes ranking cache (pulls fresh contextual features, pre-caches inference results, etc.). + * + * <p>Asynchronously runs in background as the process might take a few seconds, notifying a + * listener upon completion; meanwhile, any calls to {@link #rankList} will simply return the + * input in same order. + * + * @param listener callback for when ranking refresh has completed; null value skips notification. + */ + @MainThread + void refresh(@Nullable P13nRefreshCompleteListener listener); + + /** Decides if results should be displayed for no-query search. */ + @MainThread + boolean shouldShowEmptyListForNullQuery(); + + /** + * Callback class for when ranking refresh has completed. + * + * <p>Primary use is to notify {@link com.android.dialer.app.DialtactsActivity} that the ranking + * functions {@link #rankList} and {@link #rankCursor(Cursor, int)} will now give useful results. + */ + interface P13nRefreshCompleteListener { + + /** Callback for when ranking refresh has completed. */ + void onP13nRefreshComplete(); + } +} |