联系人数据库设计之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;
}
}
}