/* * Copyright (C) 2017 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.calllog.datasources; import android.content.ContentValues; import android.content.Context; import android.support.annotation.MainThread; import android.support.annotation.WorkerThread; import com.android.dialer.calllog.database.contract.AnnotatedCallLogContract; import com.google.common.util.concurrent.ListenableFuture; import java.util.List; /** * A source of data for one or more columns in the annotated call log. * *
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. * *
Because {@link #isDirty(Context)} is not always invoked, {@link #fill(Context, * CallLogMutations)} shouldn't rely on any state saved during {@link #isDirty(Context)}. It * is safe to assume that {@link #onSuccessfulFill(Context)} refers to the previous fill * operation. * *
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. * *
{@link #coalesce(List)} may be called from any worker thread at any time. */ public interface CallLogDataSource { /** * A lightweight check which runs frequently to detect if the annotated call log is out of date * with respect to this data source. * *
This is typically used to detect external changes to the underlying data source which have * been made in such a way that the dialer application was not notified. * *
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
*/
ListenableFuture 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