diff options
Diffstat (limited to 'java/com/android/dialer/calllog/datasources/CallLogDataSource.java')
-rw-r--r-- | java/com/android/dialer/calllog/datasources/CallLogDataSource.java | 67 |
1 files changed, 59 insertions, 8 deletions
diff --git a/java/com/android/dialer/calllog/datasources/CallLogDataSource.java b/java/com/android/dialer/calllog/datasources/CallLogDataSource.java index 13d0b842d..3fff3ba53 100644 --- a/java/com/android/dialer/calllog/datasources/CallLogDataSource.java +++ b/java/com/android/dialer/calllog/datasources/CallLogDataSource.java @@ -16,13 +16,39 @@ package com.android.dialer.calllog.datasources; +import android.content.ContentValues; import android.content.Context; -import android.database.sqlite.SQLiteDatabase; import android.support.annotation.MainThread; import android.support.annotation.WorkerThread; -import com.android.dialer.calllog.database.CallLogMutations; +import com.android.dialer.calllog.database.contract.AnnotatedCallLogContract; +import java.util.List; -/** A source of data for one or more columns in the annotated call log. */ +/** + * A source of data for one or more columns in the annotated call log. + * + * <p>Data sources have three lifecycle operations, which are always called on the same thread and + * in the same order for a particular "checkDirtyAndRebuild" cycle. However, not all operations are + * always invoked. + * + * <ol> + * <li>{@link #isDirty(Context)}: Invoked only if the framework doesn't yet know if a rebuild is + * necessary. + * <li>{@link #fill(Context, CallLogMutations)}: Invoked only if the framework determined a + * rebuild is necessary. + * <li>{@link #onSuccessfulFill(Context)}: Invoked if and only if fill was previously called and + * the mutations provided by the previous fill operation succeeded in being applied. + * </ol> + * + * <p>Because {@link #isDirty(Context)} is not always invoked, {@link #fill(Context, + * CallLogMutations)} shouldn't rely on any state saved during {@link #isDirty(Context)}. It + * <em>is</em> safe to assume that {@link #onSuccessfulFill(Context)} refers to the previous fill + * operation. + * + * <p>The same data source objects may be reused across multiple checkDirtyAndRebuild cycles, so + * implementors should take care to clear any internal state at the start of a new cycle. + * + * <p>{@link #coalesce(List)} may be called from any worker thread at any time. + */ public interface CallLogDataSource { /** @@ -35,6 +61,8 @@ public interface CallLogDataSource { * <p>Most implementations of this method will rely on some sort of last modified timestamp. If it * is impossible for a data source to be modified without the dialer application being notified, * this method may immediately return false. + * + * @see CallLogDataSource class doc for complete lifecyle information */ @WorkerThread boolean isDirty(Context appContext); @@ -43,16 +71,39 @@ public interface CallLogDataSource { * Computes the set of mutations necessary to update the annotated call log with respect to this * data source. * + * @see CallLogDataSource class doc for complete lifecyle information * @param mutations the set of mutations which this method should contribute to. Note that it may * contain inserts from the system call log, and these inserts should be modified by each data * source. */ @WorkerThread - void fill( - Context appContext, - SQLiteDatabase readableDatabase, - long lastRebuildTimeMillis, - CallLogMutations mutations); + void fill(Context appContext, CallLogMutations mutations); + + /** + * Called after database mutations have been applied to all data sources. This is useful for + * saving state such as the timestamp of the last row processed in an underlying database. Note + * that all mutations across all data sources are applied in a single transaction. + * + * @see CallLogDataSource class doc for complete lifecyle information + */ + @WorkerThread + void onSuccessfulFill(Context appContext); + + /** + * Combines raw annotated call log rows into a single coalesced row. + * + * <p>May be called by any worker thread at any time so implementations should take care to be + * threadsafe. (Ideally no state should be required to implement this.) + * + * @param individualRowsSortedByTimestampDesc group of fully populated rows from {@link + * AnnotatedCallLogContract.AnnotatedCallLog} which need to be combined for display purposes. + * This method should not modify this list. + * @return a partial {@link AnnotatedCallLogContract.CoalescedAnnotatedCallLog} row containing + * only columns which this data source is responsible for, which is the result of aggregating + * {@code individualRowsSortedByTimestampDesc}. + */ + @WorkerThread + ContentValues coalesce(List<ContentValues> individualRowsSortedByTimestampDesc); @MainThread void registerContentObservers( |