From af719e9e11aebf649d01651ed1960c6db9c1f2ef Mon Sep 17 00:00:00 2001
From: Zachary Heidepriem <zachh@google.com>
Date: Wed, 1 Nov 2017 12:24:16 -0700
Subject: Added CompositePhoneLookup and added and implemented "lookup" method.

Fleshed out docs for PhoneLookup.

Added dagger components and modules.

Bug: 34672501
Test: unit
PiperOrigin-RevId: 173977963
Change-Id: If07795d9d3d56a59afd27cdda3e98543bf30fdb8
---
 .../android/dialer/phonelookup/PhoneLookup.java    | 35 ++++++++++++++++------
 1 file changed, 26 insertions(+), 9 deletions(-)

(limited to 'java/com/android/dialer/phonelookup/PhoneLookup.java')

diff --git a/java/com/android/dialer/phonelookup/PhoneLookup.java b/java/com/android/dialer/phonelookup/PhoneLookup.java
index 63b01c8e6..66f166d6d 100644
--- a/java/com/android/dialer/phonelookup/PhoneLookup.java
+++ b/java/com/android/dialer/phonelookup/PhoneLookup.java
@@ -16,30 +16,47 @@
 
 package com.android.dialer.phonelookup;
 
+import android.support.annotation.NonNull;
+import android.telecom.Call;
 import com.android.dialer.DialerPhoneNumber;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
 import com.google.common.util.concurrent.ListenableFuture;
 
-/** TODO(zachh) update documentation. */
+/**
+ * Provides operations related to retrieving information about phone numbers.
+ *
+ * <p>Some operations defined by this interface are generally targeted towards specific use cases;
+ * for example {@link #isDirty(ImmutableSet, long)} and {@link #bulkUpdate(ImmutableMap, long)} are
+ * generally intended to be used by the call log.
+ */
 public interface PhoneLookup {
 
   /**
-   * For Call Log "isDirty" operation.
+   * Returns a future containing a new {@link PhoneLookupInfo} for the provided call.
    *
-   * @param phoneNumbers
-   * @param lastModified
-   * @return TODO(zachh)
+   * <p>The returned message should contain populated data for the sub-message corresponding to this
+   * {@link PhoneLookup}. For example, the CP2 implementation returns a {@link PhoneLookupInfo} with
+   * the {@link PhoneLookupInfo.Cp2Info} sub-message populated.
+   */
+  ListenableFuture<PhoneLookupInfo> lookup(@NonNull Call call);
+
+  /**
+   * Returns a future which returns true if the information for any of the provided phone numbers
+   * has changed since {@code lastModified} according to this {@link PhoneLookup}.
    */
   ListenableFuture<Boolean> isDirty(
       ImmutableSet<DialerPhoneNumber> phoneNumbers, long lastModified);
 
   /**
-   * For Call Log "fill" operation.
+   * Given a set of existing information and a timestamp, returns a set of information with any
+   * changes made since the timestamp according to this {@link PhoneLookup}.
+   *
+   * <p>If there are no changes required, it is valid for this method to simply return the provided
+   * {@code existingInfoMap}.
    *
-   * @param existingInfoMap
-   * @param lastModified
-   * @return TODO(zachh)
+   * <p>If there is no longer information associated with a number (for example, a local contact was
+   * deleted) the returned map should contain an empty {@link PhoneLookupInfo} for that number.
    */
   ListenableFuture<ImmutableMap<DialerPhoneNumber, PhoneLookupInfo>> bulkUpdate(
       ImmutableMap<DialerPhoneNumber, PhoneLookupInfo> existingInfoMap, long lastModified);
-- 
cgit v1.2.3