Home | History | Annotate | Download | only in datasources 
      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.content.ContentValues;
     20 import android.content.Context;
     21 import android.support.annotation.MainThread;
     22 import android.support.annotation.WorkerThread;
     23 import com.android.dialer.calllog.database.contract.AnnotatedCallLogContract;
     24 import java.util.List;
     25 
     26 /**
     27  * A source of data for one or more columns in the annotated call log.
     28  *
     29  * <p>Data sources have three lifecycle operations, which are always called on the same thread and
     30  * in the same order for a particular "checkDirtyAndRebuild" cycle. However, not all operations are
     31  * always invoked.
     32  *
     33  * <ol>
     34  *   <li>{@link #isDirty(Context)}: Invoked only if the framework doesn't yet know if a rebuild is
     35  *       necessary.
     36  *   <li>{@link #fill(Context, CallLogMutations)}: Invoked only if the framework determined a
     37  *       rebuild is necessary.
     38  *   <li>{@link #onSuccessfulFill(Context)}: Invoked if and only if fill was previously called and
     39  *       the mutations provided by the previous fill operation succeeded in being applied.
     40  * </ol>
     41  *
     42  * <p>Because {@link #isDirty(Context)} is not always invoked, {@link #fill(Context,
     43  * CallLogMutations)} shouldn't rely on any state saved during {@link #isDirty(Context)}. It
     44  * <em>is</em> safe to assume that {@link #onSuccessfulFill(Context)} refers to the previous fill
     45  * operation.
     46  *
     47  * <p>The same data source objects may be reused across multiple checkDirtyAndRebuild cycles, so
     48  * implementors should take care to clear any internal state at the start of a new cycle.
     49  *
     50  * <p>{@link #coalesce(List)} may be called from any worker thread at any time.
     51  */
     52 public interface CallLogDataSource {
     53 
     54   /**
     55    * A lightweight check which runs frequently to detect if the annotated call log is out of date
     56    * with respect to this data source.
     57    *
     58    * <p>This is typically used to detect external changes to the underlying data source which have
     59    * been made in such a way that the dialer application was not notified.
     60    *
     61    * <p>Most implementations of this method will rely on some sort of last modified timestamp. If it
     62    * is impossible for a data source to be modified without the dialer application being notified,
     63    * this method may immediately return false.
     64    *
     65    * @see CallLogDataSource class doc for complete lifecyle information
     66    */
     67   @WorkerThread
     68   boolean isDirty(Context appContext);
     69 
     70   /**
     71    * Computes the set of mutations necessary to update the annotated call log with respect to this
     72    * data source.
     73    *
     74    * @see CallLogDataSource class doc for complete lifecyle information
     75    * @param mutations the set of mutations which this method should contribute to. Note that it may
     76    *     contain inserts from the system call log, and these inserts should be modified by each data
     77    *     source.
     78    */
     79   @WorkerThread
     80   void fill(Context appContext, CallLogMutations mutations);
     81 
     82   /**
     83    * Called after database mutations have been applied to all data sources. This is useful for
     84    * saving state such as the timestamp of the last row processed in an underlying database. Note
     85    * that all mutations across all data sources are applied in a single transaction.
     86    *
     87    * @see CallLogDataSource class doc for complete lifecyle information
     88    */
     89   @WorkerThread
     90   void onSuccessfulFill(Context appContext);
     91 
     92   /**
     93    * Combines raw annotated call log rows into a single coalesced row.
     94    *
     95    * <p>May be called by any worker thread at any time so implementations should take care to be
     96    * threadsafe. (Ideally no state should be required to implement this.)
     97    *
     98    * @param individualRowsSortedByTimestampDesc group of fully populated rows from {@link
     99    *     AnnotatedCallLogContract.AnnotatedCallLog} which need to be combined for display purposes.
    100    *     This method should not modify this list.
    101    * @return a partial {@link AnnotatedCallLogContract.CoalescedAnnotatedCallLog} row containing
    102    *     only columns which this data source is responsible for, which is the result of aggregating
    103    *     {@code individualRowsSortedByTimestampDesc}.
    104    */
    105   @WorkerThread
    106   ContentValues coalesce(List<ContentValues> individualRowsSortedByTimestampDesc);
    107 
    108   @MainThread
    109   void registerContentObservers(
    110       Context appContext, ContentObserverCallbacks contentObserverCallbacks);
    111 
    112   /**
    113    * Methods which may optionally be called as a result of a data source's content observer firing.
    114    */
    115   interface ContentObserverCallbacks {
    116     @MainThread
    117     void markDirtyAndNotify(Context appContext);
    118   }
    119 }
    120