note表及关联data表的核心数据操作封装类
+ * 该类是GTask同步过程中处理笔记/文件夹数据的核心类,封装了以下关键功能:
+ * 1. 加载已有数据:从Cursor、note表ID加载note表数据,并联动加载关联的data表数据;
+ * 2. 数据差异记录:通过mDiffNoteValues仅存储变化的字段,减少数据库操作开销;
+ * 3. JSON序列化/反序列化:实现与JSON的互相转换,支撑GTask同步的网络数据传输;
+ * 4. 数据持久化:支持新数据插入、已有数据更新,联动处理data表的提交,并提供版本验证机制保证同步一致性;
+ * 5. 区分数据类型:对笔记(TYPE_NOTE)、文件夹(TYPE_FOLDER)、系统文件夹(TYPE_SYSTEM)做差异化处理。
+ *
+ * @author MiCode Open Source Community
+ * @date 2010-2011
+ */
public class SqlNote {
+ /**
+ * 日志标签,使用类的简单名称,便于调试时定位日志来源
+ */
private static final String TAG = SqlNote.class.getSimpleName();
+ /**
+ * 无效的ID常量,用于标记note表ID尚未初始化或不存在(区别于数据库的自增ID)
+ */
private static final int INVALID_ID = -99999;
+ /**
+ * note表的查询投影(Projection),定义了查询时需要返回的所有核心列
+ * 包含note表的全部业务字段,减少数据传输开销,适配所有数据加载场景
+ */
public static final String[] PROJECTION_NOTE = new String[] {
NoteColumns.ID, NoteColumns.ALERTED_DATE, NoteColumns.BG_COLOR_ID,
NoteColumns.CREATED_DATE, NoteColumns.HAS_ATTACHMENT, NoteColumns.MODIFIED_DATE,
@@ -52,139 +73,193 @@ public class SqlNote {
NoteColumns.VERSION
};
+ // ====================== PROJECTION_NOTE的列索引常量 ======================
+ /** PROJECTION_NOTE中ID列的索引(对应NoteColumns.ID) */
public static final int ID_COLUMN = 0;
-
+ /** PROJECTION_NOTE中提醒时间列的索引(对应NoteColumns.ALERTED_DATE) */
public static final int ALERTED_DATE_COLUMN = 1;
-
+ /** PROJECTION_NOTE中背景颜色ID列的索引(对应NoteColumns.BG_COLOR_ID) */
public static final int BG_COLOR_ID_COLUMN = 2;
-
+ /** PROJECTION_NOTE中创建时间列的索引(对应NoteColumns.CREATED_DATE) */
public static final int CREATED_DATE_COLUMN = 3;
-
+ /** PROJECTION_NOTE中是否有附件列的索引(对应NoteColumns.HAS_ATTACHMENT) */
public static final int HAS_ATTACHMENT_COLUMN = 4;
-
+ /** PROJECTION_NOTE中修改时间列的索引(对应NoteColumns.MODIFIED_DATE) */
public static final int MODIFIED_DATE_COLUMN = 5;
-
+ /** PROJECTION_NOTE中文件夹笔记数量列的索引(对应NoteColumns.NOTES_COUNT) */
public static final int NOTES_COUNT_COLUMN = 6;
-
+ /** PROJECTION_NOTE中父级ID列的索引(对应NoteColumns.PARENT_ID) */
public static final int PARENT_ID_COLUMN = 7;
-
+ /** PROJECTION_NOTE中摘要/名称列的索引(对应NoteColumns.SNIPPET) */
public static final int SNIPPET_COLUMN = 8;
-
+ /** PROJECTION_NOTE中类型列的索引(对应NoteColumns.TYPE) */
public static final int TYPE_COLUMN = 9;
-
+ /** PROJECTION_NOTE中小组件ID列的索引(对应NoteColumns.WIDGET_ID) */
public static final int WIDGET_ID_COLUMN = 10;
-
+ /** PROJECTION_NOTE中小组件类型列的索引(对应NoteColumns.WIDGET_TYPE) */
public static final int WIDGET_TYPE_COLUMN = 11;
-
+ /** PROJECTION_NOTE中同步ID列的索引(对应NoteColumns.SYNC_ID) */
public static final int SYNC_ID_COLUMN = 12;
-
+ /** PROJECTION_NOTE中本地修改标记列的索引(对应NoteColumns.LOCAL_MODIFIED) */
public static final int LOCAL_MODIFIED_COLUMN = 13;
-
+ /** PROJECTION_NOTE中原始父级ID列的索引(对应NoteColumns.ORIGIN_PARENT_ID) */
public static final int ORIGIN_PARENT_ID_COLUMN = 14;
-
+ /** PROJECTION_NOTE中GTask ID列的索引(对应NoteColumns.GTASK_ID) */
public static final int GTASK_ID_COLUMN = 15;
-
+ /** PROJECTION_NOTE中版本号列的索引(对应NoteColumns.VERSION) */
public static final int VERSION_COLUMN = 16;
+ // ====================== 成员变量 ======================
+ /** 上下文对象,用于获取资源、ContentResolver等 */
private Context mContext;
+ /** Android内容解析器,用于访问ContentProvider进行note/data表的增删改查 */
private ContentResolver mContentResolver;
+ /** 数据创建标记:true表示新数据(需插入数据库),false表示已有数据(需更新数据库) */
private boolean mIsCreate;
+ /** note表的主键ID,关联到具体的行数据 */
private long mId;
+ /** 笔记的提醒时间戳(毫秒) */
private long mAlertDate;
+ /** 笔记/文件夹的背景颜色ID(对应资源文件中的颜色配置) */
private int mBgColorId;
+ /** 数据创建时间戳(毫秒) */
private long mCreatedDate;
+ /** 是否有附件:0表示无,1表示有(整型标记) */
private int mHasAttachment;
+ /** 数据最后修改时间戳(毫秒) */
private long mModifiedDate;
+ /** 父级ID:关联到文件夹的note ID(根文件夹为0) */
private long mParentId;
+ /** 摘要/名称:笔记的内容摘要、文件夹的名称 */
private String mSnippet;
+ /** 数据类型:{@link Notes#TYPE_NOTE}(笔记)、{TYPE_FOLDER}(文件夹)、{TYPE_SYSTEM}(系统文件夹) */
private int mType;
+ /** 关联的小组件ID(无效时为{@link AppWidgetManager#INVALID_APPWIDGET_ID}) */
private int mWidgetId;
+ /** 关联的小组件类型(无效时为{@link Notes#TYPE_WIDGET_INVALIDE}) */
private int mWidgetType;
+ /** 原始父级ID:用于记录文件夹移动前的原始父级,支撑同步回滚 */
private long mOriginParent;
+ /** 版本号:用于同步时的版本验证,防止并发修改冲突 */
private long mVersion;
+ /** note表的差异数据容器,仅存储有变化的字段,用于提交到数据库 */
private ContentValues mDiffNoteValues;
+ /** 关联的data表数据列表(存储笔记的具体内容,如文本、通话记录等) */
private ArrayListnote表数据初始化SqlNote对象
+ * 同时加载关联的data表数据(仅笔记类型)
+ *
+ * @param context 上下文对象
+ * @param c 包含note表数据的Cursor对象(需使用PROJECTION_NOTE投影查询)
+ */
public SqlNote(Context context, Cursor c) {
mContext = context;
mContentResolver = context.getContentResolver();
- mIsCreate = false;
- loadFromCursor(c);
+ mIsCreate = false; // 标记为已有数据
+ loadFromCursor(c); // 从Cursor加载note表数据
mDataList = new ArrayListnote表ID加载已有数据初始化SqlNote对象
+ * 先通过ID查询获取Cursor,再加载数据,最后加载关联的data表数据(仅笔记类型)
+ *
+ * @param context 上下文对象
+ * @param id note表的主键ID
+ */
public SqlNote(Context context, long id) {
mContext = context;
mContentResolver = context.getContentResolver();
- mIsCreate = false;
- loadFromCursor(id);
+ mIsCreate = false; // 标记为已有数据
+ loadFromCursor(id); // 根据ID加载note表数据
mDataList = new ArrayListnote表ID查询数据,获取Cursor并加载到成员变量
+ * 自动关闭Cursor,防止资源泄漏
+ *
+ * @param id note表的主键ID
+ */
private void loadFromCursor(long id) {
Cursor c = null;
try {
+ // 查询note表:根据ID获取单条数据
c = mContentResolver.query(Notes.CONTENT_NOTE_URI, PROJECTION_NOTE, "(_id=?)",
- new String[] {
- String.valueOf(id)
- }, null);
+ new String[] { String.valueOf(id) }, null);
if (c != null) {
- c.moveToNext();
- loadFromCursor(c);
+ c.moveToNext(); // 移动到第一条数据(唯一结果)
+ loadFromCursor(c); // 加载数据到成员变量
} else {
Log.w(TAG, "loadFromCursor: cursor = null");
}
} finally {
+ // 最终关闭Cursor,释放资源
if (c != null)
c.close();
}
}
+ /**
+ * 从Cursor中加载note表数据到成员变量
+ * 需保证Cursor使用PROJECTION_NOTE投影查询,否则会出现列索引越界异常
+ *
+ * @param c 包含note表数据的Cursor对象
+ */
private void loadFromCursor(Cursor c) {
mId = c.getLong(ID_COLUMN);
mAlertDate = c.getLong(ALERTED_DATE_COLUMN);
@@ -200,19 +275,23 @@ public class SqlNote {
mVersion = c.getLong(VERSION_COLUMN);
}
+ /**
+ * 加载当前note关联的data表数据,存入mDataList
+ * 根据note ID查询data表,创建SqlData对象并添加到列表中
+ */
private void loadDataContent() {
Cursor c = null;
- mDataList.clear();
+ mDataList.clear(); // 清空原有数据
try {
+ // 查询data表:根据note ID获取关联的所有数据
c = mContentResolver.query(Notes.CONTENT_DATA_URI, SqlData.PROJECTION_DATA,
- "(note_id=?)", new String[] {
- String.valueOf(mId)
- }, null);
+ "(note_id=?)", new String[] { String.valueOf(mId) }, null);
if (c != null) {
if (c.getCount() == 0) {
Log.w(TAG, "it seems that the note has not data");
return;
}
+ // 遍历Cursor,创建SqlData对象并添加到列表
while (c.moveToNext()) {
SqlData data = new SqlData(mContext, c);
mDataList.add(data);
@@ -221,137 +300,154 @@ public class SqlNote {
Log.w(TAG, "loadDataContent: cursor = null");
}
} finally {
+ // 最终关闭Cursor,释放资源
if (c != null)
c.close();
}
}
+ // ====================== 公共核心方法 ======================
+ /**
+ * 根据JSON对象设置笔记/文件夹内容,并记录数据差异到差异容器
+ * 区分系统文件夹、普通文件夹、笔记类型做差异化处理:
+ * - 系统文件夹:不允许修改,仅输出警告
+ * - 普通文件夹:仅更新名称和类型
+ * - 笔记:更新所有字段,并处理关联的data表数据
+ *
+ * @param js 包含笔记/文件夹数据的JSON对象
+ * @return true表示设置成功,false表示JSON解析失败
+ */
public boolean setContent(JSONObject js) {
try {
+ // 获取JSON中的note核心数据(GTask约定的字段名)
JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
+
+ // 系统文件夹:不允许修改,输出警告
if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM) {
Log.w(TAG, "cannot set system folder");
- } else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {
- // for folder we can only update the snnipet and type
- String snippet = note.has(NoteColumns.SNIPPET) ? note
- .getString(NoteColumns.SNIPPET) : "";
+ }
+ // 普通文件夹:仅更新名称和类型
+ else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {
+ // 更新摘要/名称
+ String snippet = note.has(NoteColumns.SNIPPET) ? note.getString(NoteColumns.SNIPPET) : "";
if (mIsCreate || !mSnippet.equals(snippet)) {
mDiffNoteValues.put(NoteColumns.SNIPPET, snippet);
}
mSnippet = snippet;
- int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE)
- : Notes.TYPE_NOTE;
+ // 更新类型
+ int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE) : Notes.TYPE_NOTE;
if (mIsCreate || mType != type) {
mDiffNoteValues.put(NoteColumns.TYPE, type);
}
mType = type;
- } else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_NOTE) {
+ }
+ // 普通笔记:更新所有字段,并处理关联的data表数据
+ else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_NOTE) {
+ // 获取JSON中的data数组(笔记的具体内容)
JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
+
+ // 1. 处理note表的各个字段,记录差异
long id = note.has(NoteColumns.ID) ? note.getLong(NoteColumns.ID) : INVALID_ID;
if (mIsCreate || mId != id) {
mDiffNoteValues.put(NoteColumns.ID, id);
}
mId = id;
- long alertDate = note.has(NoteColumns.ALERTED_DATE) ? note
- .getLong(NoteColumns.ALERTED_DATE) : 0;
+ long alertDate = note.has(NoteColumns.ALERTED_DATE) ? note.getLong(NoteColumns.ALERTED_DATE) : 0;
if (mIsCreate || mAlertDate != alertDate) {
mDiffNoteValues.put(NoteColumns.ALERTED_DATE, alertDate);
}
mAlertDate = alertDate;
- int bgColorId = note.has(NoteColumns.BG_COLOR_ID) ? note
- .getInt(NoteColumns.BG_COLOR_ID) : ResourceParser.getDefaultBgId(mContext);
+ int bgColorId = note.has(NoteColumns.BG_COLOR_ID) ? note.getInt(NoteColumns.BG_COLOR_ID) : ResourceParser.getDefaultBgId(mContext);
if (mIsCreate || mBgColorId != bgColorId) {
mDiffNoteValues.put(NoteColumns.BG_COLOR_ID, bgColorId);
}
mBgColorId = bgColorId;
- long createDate = note.has(NoteColumns.CREATED_DATE) ? note
- .getLong(NoteColumns.CREATED_DATE) : System.currentTimeMillis();
+ long createDate = note.has(NoteColumns.CREATED_DATE) ? note.getLong(NoteColumns.CREATED_DATE) : System.currentTimeMillis();
if (mIsCreate || mCreatedDate != createDate) {
mDiffNoteValues.put(NoteColumns.CREATED_DATE, createDate);
}
mCreatedDate = createDate;
- int hasAttachment = note.has(NoteColumns.HAS_ATTACHMENT) ? note
- .getInt(NoteColumns.HAS_ATTACHMENT) : 0;
+ int hasAttachment = note.has(NoteColumns.HAS_ATTACHMENT) ? note.getInt(NoteColumns.HAS_ATTACHMENT) : 0;
if (mIsCreate || mHasAttachment != hasAttachment) {
mDiffNoteValues.put(NoteColumns.HAS_ATTACHMENT, hasAttachment);
}
mHasAttachment = hasAttachment;
- long modifiedDate = note.has(NoteColumns.MODIFIED_DATE) ? note
- .getLong(NoteColumns.MODIFIED_DATE) : System.currentTimeMillis();
+ long modifiedDate = note.has(NoteColumns.MODIFIED_DATE) ? note.getLong(NoteColumns.MODIFIED_DATE) : System.currentTimeMillis();
if (mIsCreate || mModifiedDate != modifiedDate) {
mDiffNoteValues.put(NoteColumns.MODIFIED_DATE, modifiedDate);
}
mModifiedDate = modifiedDate;
- long parentId = note.has(NoteColumns.PARENT_ID) ? note
- .getLong(NoteColumns.PARENT_ID) : 0;
+ long parentId = note.has(NoteColumns.PARENT_ID) ? note.getLong(NoteColumns.PARENT_ID) : 0;
if (mIsCreate || mParentId != parentId) {
mDiffNoteValues.put(NoteColumns.PARENT_ID, parentId);
}
mParentId = parentId;
- String snippet = note.has(NoteColumns.SNIPPET) ? note
- .getString(NoteColumns.SNIPPET) : "";
+ String snippet = note.has(NoteColumns.SNIPPET) ? note.getString(NoteColumns.SNIPPET) : "";
if (mIsCreate || !mSnippet.equals(snippet)) {
mDiffNoteValues.put(NoteColumns.SNIPPET, snippet);
}
mSnippet = snippet;
- int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE)
- : Notes.TYPE_NOTE;
+ int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE) : Notes.TYPE_NOTE;
if (mIsCreate || mType != type) {
mDiffNoteValues.put(NoteColumns.TYPE, type);
}
mType = type;
- int widgetId = note.has(NoteColumns.WIDGET_ID) ? note.getInt(NoteColumns.WIDGET_ID)
- : AppWidgetManager.INVALID_APPWIDGET_ID;
+ int widgetId = note.has(NoteColumns.WIDGET_ID) ? note.getInt(NoteColumns.WIDGET_ID) : AppWidgetManager.INVALID_APPWIDGET_ID;
if (mIsCreate || mWidgetId != widgetId) {
mDiffNoteValues.put(NoteColumns.WIDGET_ID, widgetId);
}
mWidgetId = widgetId;
- int widgetType = note.has(NoteColumns.WIDGET_TYPE) ? note
- .getInt(NoteColumns.WIDGET_TYPE) : Notes.TYPE_WIDGET_INVALIDE;
+ int widgetType = note.has(NoteColumns.WIDGET_TYPE) ? note.getInt(NoteColumns.WIDGET_TYPE) : Notes.TYPE_WIDGET_INVALIDE;
if (mIsCreate || mWidgetType != widgetType) {
mDiffNoteValues.put(NoteColumns.WIDGET_TYPE, widgetType);
}
mWidgetType = widgetType;
- long originParent = note.has(NoteColumns.ORIGIN_PARENT_ID) ? note
- .getLong(NoteColumns.ORIGIN_PARENT_ID) : 0;
+ long originParent = note.has(NoteColumns.ORIGIN_PARENT_ID) ? note.getLong(NoteColumns.ORIGIN_PARENT_ID) : 0;
if (mIsCreate || mOriginParent != originParent) {
mDiffNoteValues.put(NoteColumns.ORIGIN_PARENT_ID, originParent);
}
mOriginParent = originParent;
+ // 2. 处理关联的data表数据
for (int i = 0; i < dataArray.length(); i++) {
JSONObject data = dataArray.getJSONObject(i);
SqlData sqlData = null;
+
+ // 根据data ID查找已有SqlData对象(更新场景)
if (data.has(DataColumns.ID)) {
long dataId = data.getLong(DataColumns.ID);
for (SqlData temp : mDataList) {
if (dataId == temp.getId()) {
sqlData = temp;
+ break;
}
}
}
+ // 未找到则创建新SqlData对象(新增场景)
if (sqlData == null) {
sqlData = new SqlData(mContext);
mDataList.add(sqlData);
}
+ // 设置data内容并记录差异
sqlData.setContent(data);
}
}
} catch (JSONException e) {
+ // JSON解析失败,输出错误日志并返回false
Log.e(TAG, e.toString());
e.printStackTrace();
return false;
@@ -359,16 +455,26 @@ public class SqlNote {
return true;
}
+ /**
+ * 将笔记/文件夹数据及关联的data表数据序列化为JSON对象
+ * 区分笔记、文件夹、系统文件夹做差异化序列化:
+ * - 笔记:序列化所有note字段 + 关联的data数组
+ * - 文件夹/系统文件夹:仅序列化核心字段(ID、类型、名称)
+ *
+ * @return 包含完整数据的JSON对象,若为新数据则返回null
+ */
public JSONObject getContent() {
try {
JSONObject js = new JSONObject();
+ // 新数据尚未持久化,输出错误日志并返回null
if (mIsCreate) {
Log.e(TAG, "it seems that we haven't created this in database yet");
return null;
}
JSONObject note = new JSONObject();
+ // 普通笔记:序列化所有字段 + 关联的data数组
if (mType == Notes.TYPE_NOTE) {
note.put(NoteColumns.ID, mId);
note.put(NoteColumns.ALERTED_DATE, mAlertDate);
@@ -384,6 +490,7 @@ public class SqlNote {
note.put(NoteColumns.ORIGIN_PARENT_ID, mOriginParent);
js.put(GTaskStringUtils.META_HEAD_NOTE, note);
+ // 序列化关联的data表数据为JSON数组
JSONArray dataArray = new JSONArray();
for (SqlData sqlData : mDataList) {
JSONObject data = sqlData.getContent();
@@ -392,7 +499,9 @@ public class SqlNote {
}
}
js.put(GTaskStringUtils.META_HEAD_DATA, dataArray);
- } else if (mType == Notes.TYPE_FOLDER || mType == Notes.TYPE_SYSTEM) {
+ }
+ // 文件夹/系统文件夹:仅序列化核心字段
+ else if (mType == Notes.TYPE_FOLDER || mType == Notes.TYPE_SYSTEM) {
note.put(NoteColumns.ID, mId);
note.put(NoteColumns.TYPE, mType);
note.put(NoteColumns.SNIPPET, mSnippet);
@@ -401,92 +510,145 @@ public class SqlNote {
return js;
} catch (JSONException e) {
+ // JSON序列化失败,输出错误日志
Log.e(TAG, e.toString());
e.printStackTrace();
}
return null;
}
+ // ====================== 字段设置方法(记录差异) ======================
+ /**
+ * 设置父级ID,并记录到差异容器
+ * @param id 新的父级ID(文件夹的note ID)
+ */
public void setParentId(long id) {
mParentId = id;
mDiffNoteValues.put(NoteColumns.PARENT_ID, id);
}
+ /**
+ * 设置GTask ID,并记录到差异容器
+ * @param gid GTask的唯一标识ID
+ */
public void setGtaskId(String gid) {
mDiffNoteValues.put(NoteColumns.GTASK_ID, gid);
}
+ /**
+ * 设置同步ID,并记录到差异容器
+ * @param syncId 同步ID(用于标记同步状态)
+ */
public void setSyncId(long syncId) {
mDiffNoteValues.put(NoteColumns.SYNC_ID, syncId);
}
+ /**
+ * 重置本地修改标记为0,并记录到差异容器
+ * 用于同步完成后标记数据已同步,无本地修改
+ */
public void resetLocalModified() {
mDiffNoteValues.put(NoteColumns.LOCAL_MODIFIED, 0);
}
+ // ====================== 字段获取方法 ======================
+ /**
+ * 获取note表的主键ID
+ * @return 主键ID,未初始化则返回INVALID_ID
+ */
public long getId() {
return mId;
}
+ /**
+ * 获取父级ID
+ * @return 父级文件夹的note ID
+ */
public long getParentId() {
return mParentId;
}
+ /**
+ * 获取摘要/名称
+ * @return 笔记摘要或文件夹名称
+ */
public String getSnippet() {
return mSnippet;
}
+ /**
+ * 判断当前数据是否为笔记类型
+ * @return true表示是笔记(TYPE_NOTE),false表示否
+ */
public boolean isNoteType() {
return mType == Notes.TYPE_NOTE;
}
+ /**
+ * 提交数据变更到数据库(插入/更新),并联动处理关联的data表数据
+ * 支持版本验证机制,保证同步过程中数据的一致性,提交后刷新本地数据。
+ *
+ * @param validateVersion 是否开启版本验证:true表示验证,false表示不验证
+ */
public void commit(boolean validateVersion) {
+ // 新数据:执行插入操作
if (mIsCreate) {
+ // 若ID为无效值且差异容器中包含ID,移除该ID(数据库自增ID,无需手动设置)
if (mId == INVALID_ID && mDiffNoteValues.containsKey(NoteColumns.ID)) {
mDiffNoteValues.remove(NoteColumns.ID);
}
+ // 插入note表数据,获取返回的Uri(包含新数据的ID)
Uri uri = mContentResolver.insert(Notes.CONTENT_NOTE_URI, mDiffNoteValues);
try {
+ // 从Uri中解析出新数据的ID(Uri路径分段的第二个元素,如note/123中的123)
mId = Long.valueOf(uri.getPathSegments().get(1));
} catch (NumberFormatException e) {
+ // 解析ID失败,输出错误日志并抛出同步失败异常
Log.e(TAG, "Get note id error :" + e.toString());
throw new ActionFailureException("create note failed");
}
+ // ID为0表示创建失败,抛出异常
if (mId == 0) {
throw new IllegalStateException("Create thread id failed");
}
+ // 笔记类型:联动提交关联的data表数据
if (mType == Notes.TYPE_NOTE) {
for (SqlData sqlData : mDataList) {
- sqlData.commit(mId, false, -1);
+ sqlData.commit(mId, false, -1); // 无需版本验证
}
}
- } else {
+ }
+ // 已有数据:执行更新操作
+ else {
+ // 验证ID有效性(排除系统文件夹的有效ID)
if (mId <= 0 && mId != Notes.ID_ROOT_FOLDER && mId != Notes.ID_CALL_RECORD_FOLDER) {
Log.e(TAG, "No such note");
throw new IllegalStateException("Try to update note with invalid id");
}
+
+ // 仅当存在差异时执行更新操作
if (mDiffNoteValues.size() > 0) {
- mVersion ++;
+ mVersion ++; // 版本号自增
int result = 0;
if (!validateVersion) {
+ // 不验证版本:直接更新数据(根据note ID)
result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
- + NoteColumns.ID + "=?)", new String[] {
- String.valueOf(mId)
- });
+ + NoteColumns.ID + "=?)", new String[] { String.valueOf(mId) });
} else {
+ // 验证版本:仅当note表的版本号小于等于当前版本时才更新
result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
- + NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)",
- new String[] {
- String.valueOf(mId), String.valueOf(mVersion)
- });
+ + NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)",
+ new String[] { String.valueOf(mId), String.valueOf(mVersion) });
}
+ // 更新结果为0,说明数据未更新(可能同步时用户修改了数据),输出警告日志
if (result == 0) {
Log.w(TAG, "there is no update. maybe user updates note when syncing");
}
}
+ // 笔记类型:联动提交关联的data表数据(支持版本验证)
if (mType == Notes.TYPE_NOTE) {
for (SqlData sqlData : mDataList) {
sqlData.commit(mId, validateVersion, mVersion);
@@ -494,12 +656,13 @@ public class SqlNote {
}
}
- // refresh local info
+ // 提交后刷新本地数据:重新加载note和关联的data表数据
loadFromCursor(mId);
if (mType == Notes.TYPE_NOTE)
loadDataContent();
+ // 清空差异容器,标记为已有数据
mDiffNoteValues.clear();
mIsCreate = false;
}
-}
+}
\ No newline at end of file
diff --git a/src/notes/gtask/data/Task.java b/src/notes/gtask/data/Task.java
index 6a19454..885b80e 100644
--- a/src/notes/gtask/data/Task.java
+++ b/src/notes/gtask/data/Task.java
@@ -31,70 +31,116 @@ import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;
-
+/**
+ * GTask任务节点类,继承自核心抽象节点类{@link Node}
+ * 该类是GTask中「任务(Task)」的具体实现,封装了GTask任务的核心属性(完成状态、备注、元信息、层级关系等),
+ * 并实现了父类的抽象方法,完成以下核心功能:
+ * 1. 生成GTask的创建/更新动作JSON(用于向远程GTask服务发送请求);
+ * 2. 从远程GTask的JSON数据初始化任务内容(远程→本地同步);
+ * 3. 从本地笔记的JSON数据初始化任务内容(本地→远程同步);
+ * 4. 将任务内容序列化为本地笔记的JSON数据(GTask→本地笔记转换);
+ * 5. 根据本地数据库Cursor判断同步动作类型(核心同步逻辑);
+ * 6. 管理任务的层级关系(父任务列表、前序兄弟任务)。
+ *
+ * @author MiCode Open Source Community
+ * @date 2010-2011
+ */
public class Task extends Node {
+ /**
+ * 日志标签,使用类的简单名称,便于调试时定位日志来源
+ */
private static final String TAG = Task.class.getSimpleName();
+ // ====================== 成员变量 ======================
+ /**
+ * 任务完成状态:true表示已完成,false表示未完成
+ */
private boolean mCompleted;
+ /**
+ * 任务的备注信息(GTask的Notes字段,对应本地笔记的附加内容)
+ */
private String mNotes;
+ /**
+ * 本地笔记的元信息JSON对象,存储笔记的完整数据(用于GTask与本地笔记的映射)
+ */
private JSONObject mMetaInfo;
+ /**
+ * 前序兄弟任务:用于维护GTask任务的排序(当前任务的上一个同级任务)
+ */
private Task mPriorSibling;
+ /**
+ * 父任务列表:当前任务所属的GTask列表({TaskList}实例),维护层级关系
+ */
private TaskList mParent;
+ /**
+ * 构造方法:初始化GTask任务节点的默认属性
+ * 调用父类{@link Node}的构造方法,同时初始化当前类的成员变量为默认值
+ */
public Task() {
super();
- mCompleted = false;
- mNotes = null;
- mPriorSibling = null;
- mParent = null;
- mMetaInfo = null;
+ mCompleted = false; // 默认未完成
+ mNotes = null; // 默认无备注
+ mPriorSibling = null; // 默认无前序兄弟任务
+ mParent = null; // 默认无父任务列表
+ mMetaInfo = null; // 默认无本地元信息
}
+ /**
+ * 实现父类抽象方法:生成创建GTask任务的动作JSON对象
+ * 该JSON遵循GTask服务的接口规范,包含创建任务所需的所有参数(动作类型、ID、名称、父节点、排序等),
+ * 用于向远程GTask服务发送创建任务的请求。
+ *
+ * @param actionId 动作唯一标识ID(用于GTask服务识别本次动作)
+ * @return 包含创建任务动作的JSON对象
+ * @throws ActionFailureException JSON生成失败时抛出该异常
+ */
public JSONObject getCreateAction(int actionId) {
JSONObject js = new JSONObject();
try {
- // action_type
+ // 1. 动作类型:创建(CREATE)
js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);
- // action_id
+ // 2. 动作ID:唯一标识本次创建动作
js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
- // index
+ // 3. 任务索引:当前任务在父列表中的位置(用于排序)
js.put(GTaskStringUtils.GTASK_JSON_INDEX, mParent.getChildTaskIndex(this));
- // entity_delta
+ // 4. 实体增量:任务的核心属性(名称、创建者、类型、备注等)
JSONObject entity = new JSONObject();
- entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
- entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null");
+ entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName()); // 任务名称(对应笔记标题/内容)
+ entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null"); // 创建者ID(此处设为null)
entity.put(GTaskStringUtils.GTASK_JSON_ENTITY_TYPE,
- GTaskStringUtils.GTASK_JSON_TYPE_TASK);
+ GTaskStringUtils.GTASK_JSON_TYPE_TASK); // 实体类型:任务(TASK)
if (getNotes() != null) {
- entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes());
+ entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes()); // 任务备注(非空时添加)
}
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
- // parent_id
+ // 5. 父节点ID:当前任务所属父列表的GID
js.put(GTaskStringUtils.GTASK_JSON_PARENT_ID, mParent.getGid());
- // dest_parent_type
+ // 6. 目标父类型:父节点的类型为分组(GROUP,对应TaskList)
js.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT_TYPE,
GTaskStringUtils.GTASK_JSON_TYPE_GROUP);
- // list_id
+ // 7. 列表ID:所属父列表的GID(与父节点ID一致)
js.put(GTaskStringUtils.GTASK_JSON_LIST_ID, mParent.getGid());
- // prior_sibling_id
+ // 8. 前序兄弟ID:存在前序兄弟任务时添加该字段(用于排序)
if (mPriorSibling != null) {
js.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, mPriorSibling.getGid());
}
} catch (JSONException e) {
+ // JSON解析/写入失败,输出日志并抛出同步失败异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("fail to generate task-create jsonobject");
@@ -103,30 +149,40 @@ public class Task extends Node {
return js;
}
+ /**
+ * 实现父类抽象方法:生成更新GTask任务的动作JSON对象
+ * 该JSON遵循GTask服务的接口规范,包含更新任务所需的核心参数(动作类型、ID、名称、备注、删除标记等),
+ * 用于向远程GTask服务发送更新任务的请求。
+ *
+ * @param actionId 动作唯一标识ID(用于GTask服务识别本次动作)
+ * @return 包含更新任务动作的JSON对象
+ * @throws ActionFailureException JSON生成失败时抛出该异常
+ */
public JSONObject getUpdateAction(int actionId) {
JSONObject js = new JSONObject();
try {
- // action_type
+ // 1. 动作类型:更新(UPDATE)
js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
- // action_id
+ // 2. 动作ID:唯一标识本次更新动作
js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
- // id
+ // 3. 任务ID:当前任务的GID(标识要更新的任务)
js.put(GTaskStringUtils.GTASK_JSON_ID, getGid());
- // entity_delta
+ // 4. 实体增量:需要更新的任务属性(名称、备注、删除标记)
JSONObject entity = new JSONObject();
- entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
+ entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName()); // 任务名称
if (getNotes() != null) {
- entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes());
+ entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes()); // 任务备注(非空时添加)
}
- entity.put(GTaskStringUtils.GTASK_JSON_DELETED, getDeleted());
+ entity.put(GTaskStringUtils.GTASK_JSON_DELETED, getDeleted()); // 删除标记(是否被删除)
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
} catch (JSONException e) {
+ // JSON解析/写入失败,输出日志并抛出同步失败异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("fail to generate task-update jsonobject");
@@ -135,39 +191,48 @@ public class Task extends Node {
return js;
}
+ /**
+ * 实现父类抽象方法:根据远程GTask的JSON数据设置任务内容
+ * 从远程GTask返回的JSON中解析出任务的核心属性(GID、修改时间、名称、备注、删除标记、完成状态等),
+ * 完成远程GTask数据到本地Task对象的映射(远程→本地同步)。
+ *
+ * @param js 远程GTask返回的任务JSON对象
+ * @throws ActionFailureException JSON解析失败时抛出该异常
+ */
public void setContentByRemoteJSON(JSONObject js) {
if (js != null) {
try {
- // id
+ // 1. 任务GID:远程GTask的唯一标识
if (js.has(GTaskStringUtils.GTASK_JSON_ID)) {
setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
}
- // last_modified
+ // 2. 最后修改时间:用于同步时的版本对比
if (js.has(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED)) {
setLastModified(js.getLong(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED));
}
- // name
+ // 3. 任务名称:对应本地笔记的内容
if (js.has(GTaskStringUtils.GTASK_JSON_NAME)) {
setName(js.getString(GTaskStringUtils.GTASK_JSON_NAME));
}
- // notes
+ // 4. 任务备注:对应本地笔记的附加内容
if (js.has(GTaskStringUtils.GTASK_JSON_NOTES)) {
setNotes(js.getString(GTaskStringUtils.GTASK_JSON_NOTES));
}
- // deleted
+ // 5. 删除标记:是否被远程删除(用于同步删除操作)
if (js.has(GTaskStringUtils.GTASK_JSON_DELETED)) {
setDeleted(js.getBoolean(GTaskStringUtils.GTASK_JSON_DELETED));
}
- // completed
+ // 6. 完成状态:任务是否被远程标记为完成
if (js.has(GTaskStringUtils.GTASK_JSON_COMPLETED)) {
setCompleted(js.getBoolean(GTaskStringUtils.GTASK_JSON_COMPLETED));
}
} catch (JSONException e) {
+ // JSON解析失败,输出日志并抛出同步失败异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("fail to get task content from jsonobject");
@@ -175,60 +240,89 @@ public class Task extends Node {
}
}
+ /**
+ * 实现父类抽象方法:根据本地笔记的JSON数据设置任务内容
+ * 从本地笔记的JSON中解析出核心内容(仅处理普通笔记类型),将笔记内容映射为GTask任务的名称,
+ * 完成本地笔记数据到GTask Task对象的映射(本地→远程同步)。
+ *
+ * @param js 本地笔记的JSON对象(包含note和data字段)
+ */
public void setContentByLocalJSON(JSONObject js) {
+ // 校验JSON的有效性:必须包含note和data核心字段
if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)
|| !js.has(GTaskStringUtils.META_HEAD_DATA)) {
Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
+ return;
}
try {
+ // 1. 解析note核心字段(笔记基础信息)
JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
+ // 2. 解析data数组(笔记具体内容)
JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
+ // 仅处理普通笔记类型(TYPE_NOTE),其他类型直接返回
if (note.getInt(NoteColumns.TYPE) != Notes.TYPE_NOTE) {
Log.e(TAG, "invalid type");
return;
}
+ // 3. 遍历data数组,获取文本笔记的内容并设置为任务名称
for (int i = 0; i < dataArray.length(); i++) {
JSONObject data = dataArray.getJSONObject(i);
+ // 匹配文本笔记的MIME类型(DataConstants.NOTE)
if (TextUtils.equals(data.getString(DataColumns.MIME_TYPE), DataConstants.NOTE)) {
setName(data.getString(DataColumns.CONTENT));
- break;
+ break; // 仅取第一个文本内容
}
}
} catch (JSONException e) {
+ // JSON解析失败,输出日志
Log.e(TAG, e.toString());
e.printStackTrace();
}
}
+ /**
+ * 实现父类抽象方法:将任务内容序列化为本地笔记的JSON对象
+ * 根据任务的元信息(mMetaInfo)状态,分为两种场景:
+ * 1. 无元信息:新创建的GTask任务,生成空的本地笔记JSON(仅包含核心字段);
+ * 2. 有元信息:已同步的任务,更新笔记的内容字段为当前任务名称,保留原有元信息;
+ * 最终完成GTask Task对象到本地笔记JSON的映射(GTask→本地笔记转换)。
+ *
+ * @return 本地笔记的JSON对象,若序列化失败则返回null
+ */
public JSONObject getLocalJSONFromContent() {
- String name = getName();
+ String name = getName(); // 获取当前任务名称
try {
+ // 场景1:无元信息(新任务,从GTask网页端创建)
if (mMetaInfo == null) {
- // new task created from web
+ // 任务名称为空,输出警告并返回null
if (name == null) {
Log.w(TAG, "the note seems to be an empty one");
return null;
}
+ // 构建空的本地笔记JSON对象
JSONObject js = new JSONObject();
JSONObject note = new JSONObject();
JSONArray dataArray = new JSONArray();
JSONObject data = new JSONObject();
- data.put(DataColumns.CONTENT, name);
+ data.put(DataColumns.CONTENT, name); // 任务名称作为笔记内容
dataArray.put(data);
- js.put(GTaskStringUtils.META_HEAD_DATA, dataArray);
- note.put(NoteColumns.TYPE, Notes.TYPE_NOTE);
- js.put(GTaskStringUtils.META_HEAD_NOTE, note);
+ js.put(GTaskStringUtils.META_HEAD_DATA, dataArray); // 写入data数组
+ note.put(NoteColumns.TYPE, Notes.TYPE_NOTE); // 标记为普通笔记
+ js.put(GTaskStringUtils.META_HEAD_NOTE, note); // 写入note字段
return js;
- } else {
- // synced task
+ }
+ // 场景2:有元信息(已同步的任务,更新内容)
+ else {
+ // 从元信息中解析note和data字段
JSONObject note = mMetaInfo.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
JSONArray dataArray = mMetaInfo.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
+ // 遍历data数组,更新文本笔记的内容为当前任务名称
for (int i = 0; i < dataArray.length(); i++) {
JSONObject data = dataArray.getJSONObject(i);
if (TextUtils.equals(data.getString(DataColumns.MIME_TYPE), DataConstants.NOTE)) {
@@ -237,73 +331,99 @@ public class Task extends Node {
}
}
+ // 标记为普通笔记类型
note.put(NoteColumns.TYPE, Notes.TYPE_NOTE);
- return mMetaInfo;
+ return mMetaInfo; // 返回更新后的元信息
}
} catch (JSONException e) {
+ // JSON序列化失败,输出日志并返回null
Log.e(TAG, e.toString());
e.printStackTrace();
return null;
}
}
+ /**
+ * 设置本地笔记的元信息(从MetaData对象中解析)
+ * 将MetaData中的笔记JSON字符串转换为JSONObject,存储到mMetaInfo成员变量,
+ * 用于GTask任务与本地笔记的映射。
+ *
+ * @param metaData 本地笔记的元数据对象(包含笔记的JSON字符串)
+ */
public void setMetaInfo(MetaData metaData) {
if (metaData != null && metaData.getNotes() != null) {
try {
+ // 将JSON字符串转换为JSONObject
mMetaInfo = new JSONObject(metaData.getNotes());
} catch (JSONException e) {
+ // 解析失败,输出警告并置空元信息
Log.w(TAG, e.toString());
mMetaInfo = null;
}
}
}
+ /**
+ * 实现父类抽象方法:根据本地数据库Cursor判断当前任务的同步动作类型
+ * 核心同步逻辑:对比本地笔记数据与远程GTask任务数据的状态(ID、修改时间、本地修改标记、GID等),
+ * 返回对应的同步动作常量(无操作、更新本地、更新远程、冲突、错误等)。
+ *
+ * @param c 本地数据库的Cursor对象(包含note表的核心字段)
+ * @return 同步动作类型(对应{@link Node}中的SYNC_ACTION_*常量)
+ */
public int getSyncAction(Cursor c) {
try {
+ // 从元信息中解析note核心字段(笔记基础信息)
JSONObject noteInfo = null;
if (mMetaInfo != null && mMetaInfo.has(GTaskStringUtils.META_HEAD_NOTE)) {
noteInfo = mMetaInfo.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
}
+ // 场景1:元信息中无note字段(笔记元数据被删除)→ 更新远程
if (noteInfo == null) {
Log.w(TAG, "it seems that note meta has been deleted");
return SYNC_ACTION_UPDATE_REMOTE;
}
+ // 场景2:note字段中无ID(远程笔记ID丢失)→ 更新本地
if (!noteInfo.has(NoteColumns.ID)) {
Log.w(TAG, "remote note id seems to be deleted");
return SYNC_ACTION_UPDATE_LOCAL;
}
- // validate the note id now
+ // 校验笔记ID:本地Cursor中的ID与元信息中的ID必须匹配
if (c.getLong(SqlNote.ID_COLUMN) != noteInfo.getLong(NoteColumns.ID)) {
Log.w(TAG, "note id doesn't match");
return SYNC_ACTION_UPDATE_LOCAL;
}
+ // 核心同步逻辑:根据本地修改标记和同步时间判断
if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
- // there is no local update
+ // 子场景1:本地无修改
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
- // no update both side
+ // 本地和远程都无修改 → 无操作
return SYNC_ACTION_NONE;
} else {
- // apply remote to local
+ // 远程有修改 → 更新本地
return SYNC_ACTION_UPDATE_LOCAL;
}
} else {
- // validate gtask id
+ // 子场景2:本地有修改
+ // 校验GTask ID:本地Cursor中的GID与任务的GID必须匹配,否则为错误
if (!c.getString(SqlNote.GTASK_ID_COLUMN).equals(getGid())) {
Log.e(TAG, "gtask id doesn't match");
return SYNC_ACTION_ERROR;
}
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
- // local modification only
+ // 仅本地有修改 → 更新远程
return SYNC_ACTION_UPDATE_REMOTE;
} else {
+ // 本地和远程都有修改 → 冲突
return SYNC_ACTION_UPDATE_CONFLICT;
}
}
} catch (Exception e) {
+ // 异常捕获:所有异常都标记为同步错误
Log.e(TAG, e.toString());
e.printStackTrace();
}
@@ -311,41 +431,80 @@ public class Task extends Node {
return SYNC_ACTION_ERROR;
}
+ /**
+ * 判断当前任务是否值得保存(是否有有效数据)
+ * 判定条件:有元信息,或任务名称非空,或任务备注非空 → 值得保存
+ *
+ * @return true表示值得保存,false表示无需保存(空任务)
+ */
public boolean isWorthSaving() {
return mMetaInfo != null || (getName() != null && getName().trim().length() > 0)
|| (getNotes() != null && getNotes().trim().length() > 0);
}
+ // ====================== 成员变量的setter/getter方法 ======================
+ /**
+ * 设置任务的完成状态
+ * @param completed true表示已完成,false表示未完成
+ */
public void setCompleted(boolean completed) {
this.mCompleted = completed;
}
+ /**
+ * 设置任务的备注信息
+ * @param notes 备注字符串
+ */
public void setNotes(String notes) {
this.mNotes = notes;
}
+ /**
+ * 设置任务的前序兄弟任务(用于排序)
+ * @param priorSibling 前序兄弟任务实例
+ */
public void setPriorSibling(Task priorSibling) {
this.mPriorSibling = priorSibling;
}
+ /**
+ * 设置任务的父任务列表(维护层级关系)
+ * @param parent 父任务列表实例
+ */
public void setParent(TaskList parent) {
this.mParent = parent;
}
+ /**
+ * 获取任务的完成状态
+ * @return true表示已完成,false表示未完成
+ */
public boolean getCompleted() {
return this.mCompleted;
}
+ /**
+ * 获取任务的备注信息
+ * @return 备注字符串,若未设置则返回null
+ */
public String getNotes() {
return this.mNotes;
}
+ /**
+ * 获取任务的前序兄弟任务
+ * @return 前序兄弟任务实例,若未设置则返回null
+ */
public Task getPriorSibling() {
return this.mPriorSibling;
}
+ /**
+ * 获取任务的父任务列表
+ * @return 父任务列表实例,若未设置则返回null
+ */
public TaskList getParent() {
return this.mParent;
}
-}
+}
\ No newline at end of file
diff --git a/src/notes/gtask/data/TaskList.java b/src/notes/gtask/data/TaskList.java
index 4ea21c5..28c6bc7 100644
--- a/src/notes/gtask/data/TaskList.java
+++ b/src/notes/gtask/data/TaskList.java
@@ -29,43 +29,80 @@ import org.json.JSONObject;
import java.util.ArrayList;
-
+/**
+ * GTask任务列表类,继承自核心抽象节点类{@link Node}
+ * 该类是GTask中「任务列表(TaskList/Group)」的具体实现,对应本地笔记的「文件夹」/「系统文件夹」,
+ * 封装了任务列表的核心属性(排序索引、子任务列表),并实现了父类的抽象方法,完成以下核心功能:
+ * 1. 生成GTask的创建/更新动作JSON(用于向远程GTask服务发送请求);
+ * 2. 从远程GTask的JSON数据初始化列表内容(远程→本地同步);
+ * 3. 从本地文件夹的JSON数据初始化列表内容(本地→远程同步,区分普通文件夹/系统文件夹);
+ * 4. 将列表内容序列化为本地文件夹的JSON数据(GTask→本地文件夹转换);
+ * 5. 根据本地数据库Cursor判断同步动作类型(核心同步逻辑,文件夹冲突直接采用本地修改);
+ * 6. 管理子任务的增删改查、排序与层级关系(维护子任务的前序兄弟、父列表关联)。
+ *
+ * @author MiCode Open Source Community
+ * @date 2010-2011
+ */
public class TaskList extends Node {
+ /**
+ * 日志标签,使用类的简单名称,便于调试时定位日志来源
+ */
private static final String TAG = TaskList.class.getSimpleName();
+ // ====================== 成员变量 ======================
+ /**
+ * 任务列表的排序索引:用于GTask服务中任务列表的显示排序(默认值为1)
+ */
private int mIndex;
+ /**
+ * 子任务列表:存储当前任务列表下的所有{@link Task}实例,维护父子层级关系
+ */
private ArrayListOR-10u8Y1?Q;3&!y5M@#; Y72SrhwM?pxa$fuqflTq6$B^$%IiWF#qOZzVNs;-b%7lf(`UK
zqF@>*w92+t(#SJjZ|!Vp136}4DMsGks``U2S~Fg$MC?F2W+HMW?dS>2rb2#oY+WT8
ze+*2Va)!m}1}>tJL?Ex8&;C@R|2D$VhS2=$F-ndJmZJ+r=Fw5m_sUxP!aXKKBNb{^W@O)Q3SMeI*4E^*w*2ea
z+LFjJd2Tg5RZ0`#6DZ?gS03wP9-EuE%*&&m+#J3^dSfkx|1@
zxwE*BAw?BmBV8K8R;rs+iZiG*ETy77*gnk!)oCO`nIjGFfB#|fVH)~