联系人数据库设计之ContactsTransaction

不当之处，请雅正。

请自行下载android源代码

package com.android.providers.contacts;

import com.google.android.collect.Lists;
import com.google.android.collect.Maps;

import android.database.sqlite.SQLiteDatabase;
import android.database.sqlite.SQLiteTransactionListener;

import java.util.List;
import java.util.Map;

/**
 * A transaction for interacting with a Contacts provider.  This is used to pass state around
 * throughout the operations comprising the transaction, including which databases the overall
 * transaction is involved in, and whether the operation being performed is a batch operation.
 * 
 * 和ContactProvider交互的事务。在包含事务（Transaction）的整个过程中用来传递状态信息，例如：全部的事务涉及那个数据库以及当前
 * 正在处理的数据库是否为批处理等。
 * 
 * 本事务用于管理在事务操作中涉及到的数据库。加入到集合，从集合中删除等。
 */
public class ContactsTransaction {

    /**
     * Whether this transaction is encompassing a batch of operations.  If we're in batch mode,
     * transactional operations from non-batch callers are ignored.
     * 当前的事务是否包含一个批处理操作，如果我们当前处在批处理模式，非批处理事务性请求会忽略。
     */
    private final boolean mBatch;

    /**
     * The list of databases that have been enlisted in this transaction.
     * 在当前事务中还没有建立的数据库列表
     */
    private List<SQLiteDatabase> mDatabasesForTransaction;

    /**
     * The mapping of tags to databases involved in this transaction.
     * 事务中涉及到的数据库tags的map集合
     */
    private Map<String, SQLiteDatabase> mDatabaseTagMap;

    /**
     * Whether any actual changes have been made successfully in this transaction.
     * 在当前事务中，是否发生了任何实际的变化（数据是否发生改变）
     */
    private boolean mIsDirty;

    /**
     * Whether a yield operation failed with an exception.  If this occurred, we may not have a
     * lock on one of the databases that we started the transaction with (the yield code cleans
     * that up itself), so we should do an extra check before ending transactions.
     * 是否一个yield操作由于异常而失败。如果发生了这种情况，yield code会自己
     * 处理，不会在事务（Transaction）要处理的数据库上加锁。
     * 但我们应该在终止事务之前额外检查一下。
     */
    private boolean mYieldFailed;

    /**
     * Creates a new transaction object, optionally marked as a batch transaction.
     * @param batch Whether the transaction is in batch mode.
     * 创建一个事务。参数：是否标记为批处理
     */
    public ContactsTransaction(boolean batch) {
        mBatch = batch;
        mDatabasesForTransaction = Lists.newArrayList();
        mDatabaseTagMap = Maps.newHashMap();
        mIsDirty = false;
    }

    public boolean isBatch() {
        return mBatch;
    }

    public boolean isDirty() {
        return mIsDirty;
    }

    public void markDirty() {
        mIsDirty = true;
    }

    public void markYieldFailed() {
        mYieldFailed = true;
    }

    /**
     * If the given database has not already been enlisted in this transaction, adds it to our
     * list of affected databases and starts a transaction on it.  If we already have the given
     * database in this transaction, this is a no-op.
     * @param db The database to start a transaction on, if necessary.
     * @param tag A constant that can be used to retrieve the DB instance in this transaction.
     * @param listener A transaction listener to attach to this transaction.  May be null.
     * 如果事务作用的数据库没有建立，将数据库增加到（作用列表中）并且对数据库启动事务。
     * 如果数据库建立了，这是一个无效的操作。
     */
    public void startTransactionForDb(SQLiteDatabase db, String tag,
            SQLiteTransactionListener listener) {
        if (!hasDbInTransaction(tag)) {
            mDatabasesForTransaction.add(db);
            mDatabaseTagMap.put(tag, db);
            if (listener != null) {
                db.beginTransactionWithListener(listener);
            } else {
                db.beginTransaction();
            }
        }
    }

    /**
     * Returns whether DB corresponding to the given tag is currently enlisted in this transaction.
     * 返回被事务作用的数据库（DB）是否建立。建立返回true。否则false;
     */
    public boolean hasDbInTransaction(String tag) {
        return mDatabaseTagMap.containsKey(tag);
    }

    /**
     * Retrieves the database enlisted in the transaction corresponding to the given tag.
     * @param tag The tag of the database to look up.
     * @return The database corresponding to the tag, or null if no database with that tag has been
     *     enlisted in this transaction.
     *     返回   根据tag在列表中查找数据库。列表由事务所涉及到的数据库组成。
     *     返回数据库 或者null
     */
    public SQLiteDatabase getDbForTag(String tag) {
        return mDatabaseTagMap.get(tag);
    }

    /**
     * Removes the database corresponding to the given tag from this transaction.  It is now the
     * caller's responsibility to do whatever needs to happen with this database - it is no longer
     * a part of this transaction.
     * @param tag The tag of the database to remove.
     * @return The database corresponding to the tag, or null if no database with that tag has been
     *     enlisted in this transaction.
     *     根据tag从集合中移除数据库并返回。
     *     前期我们构建了事务涉及的数据库集合，现在是用户的指责去操作这些数据库，在数据库上可以做任何用户想做的事情。
     *     移除的数据库不再属于本事务。
     */
    public SQLiteDatabase removeDbForTag(String tag) {
        SQLiteDatabase db = mDatabaseTagMap.get(tag);
        mDatabaseTagMap.remove(tag);
        mDatabasesForTransaction.remove(db);
        return db;
    }

    /**
     * Marks all active DB transactions as successful.
     * @param callerIsBatch Whether this is being performed in the context of a batch operation.
     *     If it is not, and the transaction is marked as batch, this call is a no-op.
     *     将所有的数据库标记为成功。
     *     参数：是否由批处理引发的，如果不是，并且当前事务为批处理（batch标记为true），那么此调用为无用调用。
     */
    public void markSuccessful(boolean callerIsBatch) {
        if (!mBatch || callerIsBatch) {
            for (SQLiteDatabase db : mDatabasesForTransaction) {
                db.setTransactionSuccessful();
            }
        }
    }

    /**
     * Completes the transaction, ending the DB transactions for all associated databases.
     * @param callerIsBatch Whether this is being performed in the context of a batch operation.
     *     If it is not, and the transaction is marked as batch, this call is a no-op.
     *     终止与此事务相关的数据库上的所有事务。
     *     根据mYieldFaild决定是否在finish前终止数据库上的事务（db.endTransaction()）
     *     参数：是否由批处理引发的，如果不是，并且当前事务为批处理（batch标记为true），那么此调用为无用调用。
     */
    public void finish(boolean callerIsBatch) {
        if (!mBatch || callerIsBatch) {
            for (SQLiteDatabase db : mDatabasesForTransaction) {
                // If an exception was thrown while yielding, it's possible that we no longer have
                // a lock on this database, so we need to check before attempting to end its
                // transaction.  Otherwise, we should always expect to be in a transaction (and will
                // throw an exception if this is not the case).
                if (mYieldFailed && !db.isDbLockedByCurrentThread()) {
                    // We no longer hold the lock, so don't do anything with this database.
                    continue;
                }
                db.endTransaction();
            }
            mDatabasesForTransaction.clear();
            mDatabaseTagMap.clear();
            mIsDirty = false;
        }
    }
}