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.calllog.datasources; 18 19 import android.support.annotation.MainThread; 20 import com.google.common.util.concurrent.ListenableFuture; 21 22 /** 23 * A source of data for one or more columns in the annotated call log. 24 * 25 * <p>Data sources have three lifecycle operations, which are always called on the same thread and 26 * in the same order for a particular "checkDirtyAndRebuild" cycle. However, not all operations are 27 * always invoked. 28 * 29 * <ol> 30 * <li>{@link #isDirty()}: Invoked only if the framework doesn't yet know if a rebuild is 31 * necessary. 32 * <li>{@link #fill(CallLogMutations)}: Invoked only if the framework determined a rebuild is 33 * necessary. 34 * <li>{@link #onSuccessfulFill()}: Invoked if and only if fill was previously called and the 35 * mutations provided by the previous fill operation succeeded in being applied. 36 * </ol> 37 * 38 * <p>Because {@link #isDirty()} is not always invoked, {@link #fill(CallLogMutations)} shouldn't 39 * rely on any state saved during {@link #isDirty()}. It <em>is</em> safe to assume that {@link 40 * #onSuccessfulFill()} refers to the previous fill operation. 41 * 42 * <p>The same data source objects may be reused across multiple checkDirtyAndRebuild cycles, so 43 * implementors should take care to clear any internal state at the start of a new cycle. 44 */ 45 public interface CallLogDataSource { 46 47 /** 48 * A lightweight check which runs frequently to detect if the annotated call log is out of date 49 * with respect to this data source. 50 * 51 * <p>This is typically used to detect external changes to the underlying data source which have 52 * been made in such a way that the dialer application was not notified. 53 * 54 * <p>Most implementations of this method will rely on some sort of last modified timestamp. If it 55 * is impossible for a data source to be modified without the dialer application being notified, 56 * this method may immediately return false. 57 * 58 * @see CallLogDataSource class doc for complete lifecyle information 59 */ isDirty()60 ListenableFuture<Boolean> isDirty(); 61 62 /** 63 * Computes the set of mutations necessary to update the annotated call log with respect to this 64 * data source. 65 * 66 * @see CallLogDataSource class doc for complete lifecyle information 67 * @param mutations the set of mutations which this method should contribute to. Note that it may 68 * contain inserts from the system call log, and these inserts should be modified by each data 69 * source. 70 */ fill(CallLogMutations mutations)71 ListenableFuture<Void> fill(CallLogMutations mutations); 72 73 /** 74 * Called after database mutations have been applied to all data sources. This is useful for 75 * saving state such as the timestamp of the last row processed in an underlying database. Note 76 * that all mutations across all data sources are applied in a single transaction. 77 * 78 * @see CallLogDataSource class doc for complete lifecyle information 79 */ onSuccessfulFill()80 ListenableFuture<Void> onSuccessfulFill(); 81 82 @MainThread registerContentObservers()83 void registerContentObservers(); 84 85 @MainThread unregisterContentObservers()86 void unregisterContentObservers(); 87 88 /** 89 * Clear any data written by this data source. This is called when the new call log framework has 90 * been disabled (because for example there was a problem with it). 91 */ 92 @MainThread clearData()93 ListenableFuture<Void> clearData(); 94 95 /** 96 * The name of this daa source for logging purposes. This is generally the same as the class name 97 * (but should not use methods from {@link Class} because the class names are generally obfuscated 98 * by Proguard. 99 */ getLoggingName()100 String getLoggingName(); 101 } 102