1 /* 2 * Copyright (C) 2017 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.dialer.phonelookup; 18 19 import android.content.Context; 20 import android.support.annotation.MainThread; 21 import com.android.dialer.DialerPhoneNumber; 22 import com.google.common.collect.ImmutableMap; 23 import com.google.common.collect.ImmutableSet; 24 import com.google.common.util.concurrent.ListenableFuture; 25 26 /** 27 * Provides operations related to retrieving information about phone numbers. 28 * 29 * <p>Some operations defined by this interface are generally targeted towards specific use cases; 30 * for example {@link #isDirty(ImmutableSet)}, {@link #getMostRecentInfo(ImmutableMap)}, and {@link 31 * #onSuccessfulBulkUpdate()} are generally intended to be used by the call log. 32 */ 33 public interface PhoneLookup<T> { 34 35 /** 36 * Returns a future containing a new info for the provided number. 37 * 38 * <p>The returned message should contain populated data for the sub-message corresponding to this 39 * {@link PhoneLookup}. For example, the CP2 implementation returns a {@link 40 * PhoneLookupInfo.Cp2Info} sub-message. 41 */ lookup(DialerPhoneNumber dialerPhoneNumber)42 ListenableFuture<T> lookup(DialerPhoneNumber dialerPhoneNumber); 43 44 /** 45 * Returns a future which returns true if the information for any of the provided phone numbers 46 * has changed, usually since {@link #onSuccessfulBulkUpdate()} was last invoked. 47 */ isDirty(ImmutableSet<DialerPhoneNumber> phoneNumbers)48 ListenableFuture<Boolean> isDirty(ImmutableSet<DialerPhoneNumber> phoneNumbers); 49 50 /** 51 * Get the most recent phone lookup information for this {@link PhoneLookup}. The returned map 52 * must contain the exact same keys as the provided map. Most implementations will rely on last 53 * modified timestamps to efficiently only update the data which needs to be updated. 54 * 55 * <p>If there are no changes required, it is valid for this method to simply return the provided 56 * {@code existingInfoMap}. 57 * 58 * <p>If there is no longer information associated with a number (for example, a local contact was 59 * deleted) the returned map should contain an empty info for that number. 60 */ getMostRecentInfo( ImmutableMap<DialerPhoneNumber, T> existingInfoMap)61 ListenableFuture<ImmutableMap<DialerPhoneNumber, T>> getMostRecentInfo( 62 ImmutableMap<DialerPhoneNumber, T> existingInfoMap); 63 64 /** 65 * Populates the sub-message that this {@link PhoneLookup} is responsible for by copying {@code 66 * subMessage} into the provided {@code phoneLookupInfo} builder. 67 */ setSubMessage(PhoneLookupInfo.Builder phoneLookupInfo, T subMessage)68 void setSubMessage(PhoneLookupInfo.Builder phoneLookupInfo, T subMessage); 69 70 /** 71 * Gets the sub-message that this {@link PhoneLookup} is responsible for from the provided {@code 72 * phoneLookupInfo}. 73 */ getSubMessage(PhoneLookupInfo phoneLookupInfo)74 T getSubMessage(PhoneLookupInfo phoneLookupInfo); 75 76 /** 77 * Called when the results of the {@link #getMostRecentInfo(ImmutableMap)} have been applied by 78 * the caller. 79 * 80 * <p>Typically implementations will use this to store a "last processed" timestamp so that future 81 * invocations of {@link #isDirty(ImmutableSet)} and {@link #getMostRecentInfo(ImmutableMap)} can 82 * be efficiently implemented. 83 */ onSuccessfulBulkUpdate()84 ListenableFuture<Void> onSuccessfulBulkUpdate(); 85 86 @MainThread registerContentObservers(Context appContext)87 void registerContentObservers(Context appContext); 88 } 89