From cc040dfac9005af321f867338b9061b62906ffe9 Mon Sep 17 00:00:00 2001
From: mc19 <2716188191@qq.com>
Date: Wed, 24 Dec 2025 00:34:49 +0800
Subject: [PATCH 1/4] =?UTF-8?q?=E5=A2=9E=E5=8A=A0data,gtask,model=E5=8C=85?=
=?UTF-8?q?=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
src/notes/data/Contact.java | 41 ++-
src/notes/data/Notes.java | 111 +++++--
src/notes/data/NotesDatabaseHelper.java | 116 ++++++--
src/notes/data/NotesProvider.java | 168 ++++++++++-
src/notes/gtask/data/MetaData.java | 37 ++-
src/notes/gtask/data/Node.java | 34 ++-
src/notes/gtask/data/SqlData.java | 45 ++-
src/notes/gtask/data/SqlNote.java | 122 ++++++--
src/notes/gtask/data/Task.java | 65 +++-
src/notes/gtask/data/TaskList.java | 67 ++++-
.../exception/ActionFailureException.java | 10 +
.../exception/NetworkFailureException.java | 6 +
src/notes/gtask/remote/GTaskASyncTask.java | 90 +++++-
src/notes/gtask/remote/GTaskClient.java | 133 +++++++--
src/notes/gtask/remote/GTaskManager.java | 280 ++++++++++++------
src/notes/gtask/remote/GTaskSyncService.java | 49 ++-
src/notes/model/Note.java | 64 +++-
src/notes/model/WorkingNote.java | 51 +++-
18 files changed, 1211 insertions(+), 278 deletions(-)
diff --git a/src/notes/data/Contact.java b/src/notes/data/Contact.java
index d97ac5d..206eaf3 100644
--- a/src/notes/data/Contact.java
+++ b/src/notes/data/Contact.java
@@ -14,6 +14,12 @@
* limitations under the License.
*/
+/*
+*文件名:Contact.java
+* 修改人:蒙程
+* 修改时间:2025-12-13
+* 修改内容:增加代码注释,标注的代码行数共有21行
+*/
package net.micode.notes.data;
import android.content.Context;
@@ -25,10 +31,22 @@ import android.util.Log;
import java.util.HashMap;
+/**
+*Contact类是联系人工具类
+*
+*
根据“提供的电话号码反向查询联系人姓名”的能力,并带内存缓存,避免重复查库。
+* 本类所有方法均为静态,无需实例化。
+*
+* @author 蒙程
+ * @version 1.0
+ * @since [起始版本]
+*/
public class Contact {
+ //HashMap表示联系人和电话号码之间的映射关系。只声明,不new,是延迟初始化的表现
private static HashMap sContactCache;
private static final String TAG = "Contact";
+ //说明电话号码格式,可兼容国际区号、前缀0等多种格式
private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER
+ ",?) AND " + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'"
+ " AND " + Data.RAW_CONTACT_ID + " IN "
@@ -36,17 +54,31 @@ public class Contact {
+ " FROM phone_lookup"
+ " WHERE min_match = '+')";
+ /**
+ * 根据电话号码获取联系人姓名
+ * 优先读取内存缓存,未命中时查询系统联系人数据库,并将结果写入缓存。
+ * @param context 上下文,用于访问ContentResolver
+ * @param phoneNumber 待查询的电话号码(可为国际格式、带前缀 0 等)
+ * @return 联系人姓名;未匹配到或者发生异常时,返回@code null
+ * @throws
+ * @see android.provider.ContactsContract.CommonDataKinds
+ */
public static String getContact(Context context, String phoneNumber) {
+ //不到真正要用的时候,不给对象分配内存。第一次被调用时才new。
if(sContactCache == null) {
sContactCache = new HashMap();
}
+ //缓存命中,直接返回电话号码
if(sContactCache.containsKey(phoneNumber)) {
return sContactCache.get(phoneNumber);
}
+ //构造匹配串,提取数字核心部分
String selection = CALLER_ID_SELECTION.replace("+",
PhoneNumberUtils.toCallerIDMinMatch(phoneNumber));
+
+ //cursor是数据库游标,初始位置是-1;query把SQL拼装好后交给系统联系人Provider
Cursor cursor = context.getContentResolver().query(
Data.CONTENT_URI,
new String [] { Phone.DISPLAY_NAME },
@@ -54,18 +86,19 @@ public class Contact {
new String[] { phoneNumber },
null);
+ //指针移到第一行,成功返回true
if (cursor != null && cursor.moveToFirst()) {
try {
String name = cursor.getString(0);
- sContactCache.put(phoneNumber, name);
+ sContactCache.put(phoneNumber, name); //将号码-姓名键值对放进内存缓存
return name;
- } catch (IndexOutOfBoundsException e) {
+ } catch (IndexOutOfBoundsException e) { //捕获异常,索引超出列范围的情况,返回错误日志
Log.e(TAG, " Cursor get string error " + e.toString());
return null;
- } finally {
+ } finally { //无论是否发生异常都必须释放cursor。
cursor.close();
}
- } else {
+ } else { //查询失败,输出日志信息
Log.d(TAG, "No contact matched with number:" + phoneNumber);
return null;
}
diff --git a/src/notes/data/Notes.java b/src/notes/data/Notes.java
index f240604..de21759 100644
--- a/src/notes/data/Notes.java
+++ b/src/notes/data/Notes.java
@@ -14,43 +14,73 @@
* limitations under the License.
*/
+/*
+*文件名:Notes.java
+* 修改人:蒙程
+* 修改时间:2025-12-06
+* 修改内容:增加代码注释,标注的代码行数共37行
+*/
package net.micode.notes.data;
import android.net.Uri;
+
+/**
+*Notes是便签数据库类
+
+* 定义了URI常量、便签/文件夹类型常量、Intent扩展字段名、数据库接口、两种与业务实体
+* 本类所有字段均用static final修饰,说明字段不会变,可以直接用
+
+* @author 蒙程
+* @since [起始版本]
+*/
public class Notes {
- public static final String AUTHORITY = "micode_notes";
- public static final String TAG = "Notes";
- public static final int TYPE_NOTE = 0;
- public static final int TYPE_FOLDER = 1;
- public static final int TYPE_SYSTEM = 2;
+
+ //一、ContentProvider权威域名
+ public static final String AUTHORITY = "micode_notes"; //拼接URI的前缀
+ public static final String TAG = "Notes"; //日志显示Notes
+
+ //二、便签/文件夹/系统文件夹 类型常量
+ public static final int TYPE_NOTE = 0; //普通文本便签类型常量为0
+ public static final int TYPE_FOLDER = 1; //文件夹类型常量为1
+ public static final int TYPE_SYSTEM = 2; //系统文件夹(如回收站)类型常量为2
/**
* Following IDs are system folders' identifiers
* {@link Notes#ID_ROOT_FOLDER } is default folder
- * {@link Notes#ID_TEMPARAY_FOLDER } is for notes belonging no folder
+ * {@link Notes#ID_TEMPORARY_FOLDER } is for notes belonging no folder
* {@link Notes#ID_CALL_RECORD_FOLDER} is to store call records
*/
- public static final int ID_ROOT_FOLDER = 0;
- public static final int ID_TEMPARAY_FOLDER = -1;
- public static final int ID_CALL_RECORD_FOLDER = -2;
- public static final int ID_TRASH_FOLER = -3;
-
- public static final String INTENT_EXTRA_ALERT_DATE = "net.micode.notes.alert_date";
- public static final String INTENT_EXTRA_BACKGROUND_ID = "net.micode.notes.background_color_id";
- public static final String INTENT_EXTRA_WIDGET_ID = "net.micode.notes.widget_id";
- public static final String INTENT_EXTRA_WIDGET_TYPE = "net.micode.notes.widget_type";
- public static final String INTENT_EXTRA_FOLDER_ID = "net.micode.notes.folder_id";
- public static final String INTENT_EXTRA_CALL_DATE = "net.micode.notes.call_date";
+ //三、系统保留文件夹 ID
+ public static final int ID_ROOT_FOLDER = 0; //默认文件夹ID为0
+ public static final int ID_TEMPORARY_FOLDER = -1; //临时文件夹
+
+ public static final int ID_CALL_RECORD_FOLDER = -2; //通话记录文件夹ID,保存由通话备忘功能生成的便签
+ public static final int ID_TRASH_FOLDER = -3;
+
+ //四、Intent是什么?
+ public static final String INTENT_EXTRA_ALERT_DATE = "net.micode.notes.alert_date"; //提醒时间戳
+ public static final String INTENT_EXTRA_BACKGROUND_ID = "net.micode.notes.background_color_id"; //便签背景颜色
+ public static final String INTENT_EXTRA_WIDGET_ID = "net.micode.notes.widget_id"; //桌面便签小部件
+ public static final String INTENT_EXTRA_WIDGET_TYPE = "net.micode.notes.widget_type"; //桌面便签小部件类型
+ public static final String INTENT_EXTRA_FOLDER_ID = "net.micode.notes.folder_id"; //便签父文件夹ID
+ public static final String INTENT_EXTRA_CALL_DATE = "net.micode.notes.call_date"; //通话记录时间戳
+
+ //五、桌面小部件类型常量
public static final int TYPE_WIDGET_INVALIDE = -1;
public static final int TYPE_WIDGET_2X = 0;
public static final int TYPE_WIDGET_4X = 1;
+ /**
+ *六、便签数据MIME汇总常量类
+ * Android 的 ContentResolver 在查询/插入/打开文件时会先问 URI 对应的 MIME:
+ */
public static class DataConstants {
- public static final String NOTE = TextNote.CONTENT_ITEM_TYPE;
- public static final String CALL_NOTE = CallNote.CONTENT_ITEM_TYPE;
+ public static final String NOTE = TextNote.CONTENT_ITEM_TYPE; //文本便签MIME类型
+ public static final String CALL_NOTE = CallNote.CONTENT_ITEM_TYPE; //通话备忘MIME类型
}
+ //七、基础URI
/**
* Uri to query all notes and folders
*/
@@ -58,12 +88,18 @@ public class Notes {
/**
* Uri to query data
+ * 包括附件、文本、通话记录
*/
public static final Uri CONTENT_DATA_URI = Uri.parse("content://" + AUTHORITY + "/data");
+ //八、数据库列名接口 —— Note 表
+ /**
+ * NoteColumns是便签数据库列名接口,只定义/声明一些方法、变量
+ * 此处声明了便签数据列名有ID,PARENT_ID,创建日期,修改日期,提醒日期等
+ */
public interface NoteColumns {
/**
- * The unique ID for a row
+ * The unique ID for a ro
* Type: INTEGER (long)
*/
public static final String ID = "_id";
@@ -167,12 +203,18 @@ public class Notes {
public static final String VERSION = "version";
}
+
+ //九、数据库列名接口 —— Data 表
+
+ /**
+ * DataColumns是数据库列名接口
+ */
public interface DataColumns {
/**
* The unique ID for a row
* Type: INTEGER (long)
*/
- public static final String ID = "_id";
+ public static final String ID = "_id"; //主键是_id
/**
* The MIME type of the item represented by this row.
@@ -206,63 +248,70 @@ public class Notes {
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
+ * Generic data column, the meaning is {@link #MIME_TYPE} specific, used for
* integer data type
* Type: INTEGER
*/
public static final String DATA1 = "data1";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
+ * Generic data column, the meaning is {@link #MIME_TYPE} specific, used for
* integer data type
* Type: INTEGER
*/
public static final String DATA2 = "data2";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
+ * Generic data column, the meaning is {@link #MIME_TYPE} specific, used for
* TEXT data type
* Type: TEXT
*/
public static final String DATA3 = "data3";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
+ * Generic data column, the meaning is {@link #MIME_TYPE} specific, used for
* TEXT data type
* Type: TEXT
*/
public static final String DATA4 = "data4";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
+ * Generic data column, the meaning is {@link #MIME_TYPE} specific, used for
* TEXT data type
* Type: TEXT
*/
public static final String DATA5 = "data5";
}
+
+ //十、文本便签实体常量类
+ //文本便签TextNote类实现DataColumns接口中声明的方法
public static final class TextNote implements DataColumns {
/**
* Mode to indicate the text in check list mode or not
* Type: Integer 1:check list mode 0: normal mode
*/
- public static final String MODE = DATA1;
+ public static final String MODE = DATA1; //清单模式or普通文本模式?
public static final int MODE_CHECK_LIST = 1;
- public static final String CONTENT_TYPE = "vnd.android.cursor.dir/text_note";
+ public static final String CONTENT_TYPE = "vnd.android.cursor.dir/text_note"; //MIME类型为集合(多条)
- public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/text_note";
+ public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/text_note"; //MIME类型为单条
public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/text_note");
}
- public static final class CallNote implements DataColumns {
+ /**
+ *通话记录便签实体常量类
+ * 通话记录CallNote类也实现了DataColumns接口,体现了接口的多实现特性。
+ */
+ public static final class CallNote implements DataColumns {
/**
* Call date for this record
* Type: INTEGER (long)
*/
- public static final String CALL_DATE = DATA1;
+ public static final String CALL_DATE = DATA1; //DATA1是数据库中的真实列名,将通话的时间戳存入DATA1列中
/**
* Phone number for this record
diff --git a/src/notes/data/NotesDatabaseHelper.java b/src/notes/data/NotesDatabaseHelper.java
index ffe5d57..82aa598 100644
--- a/src/notes/data/NotesDatabaseHelper.java
+++ b/src/notes/data/NotesDatabaseHelper.java
@@ -14,6 +14,11 @@
* limitations under the License.
*/
+/*
+*文件名:NotesDatabaseHelper.java
+ * 修改人:蒙程
+ * 修改时间:2025-12-13
+ */
package net.micode.notes.data;
import android.content.ContentValues;
@@ -26,12 +31,32 @@ import net.micode.notes.data.Notes.DataColumns;
import net.micode.notes.data.Notes.DataConstants;
import net.micode.notes.data.Notes.NoteColumns;
+/**
+*便签数据库辅助类
+
+ *负责以下功能:
+ *
+ * - 创建/升级 note 与 data 表
+ * - 建立触发器维护文件夹便签数量、便签摘要
+ * - 插入系统文件夹(根、临时、通话、回收站)
+ * - 提供单例实例
+ *
+
+ *
+ * @author 蒙程
+ * @version {@link #DB_VERSION} 4
+ * @since 2010-2011
+ */
public class NotesDatabaseHelper extends SQLiteOpenHelper {
+ /**
+ *一、数据库基础常量
+ */
private static final String DB_NAME = "note.db";
private static final int DB_VERSION = 4;
+ /**表明常量接口*/
public interface TABLE {
public static final String NOTE = "note";
@@ -40,10 +65,19 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
private static final String TAG = "NotesDatabaseHelper";
+ //类加载时不创建NotesDatabaseHelper实例(mInstance),真正需要使用数据库时才调用getInstance初始化,节省应用启动时的内存和资源开销。
private static NotesDatabaseHelper mInstance;
+
+ //二、建表SQL,初始化note和data表,同时添加note_id_index索引列
+ /**
+ * 结合在Notes中定义的NoteColumns初始化
+ * 在Notes类里定义了NoteColumns,是便签数据库列名接口,ID、PARENT_ID等都是列名,表示把Notes数据库里声明的列名拿来用
+ * NOT NULL约束强制列不接受NULL值,DEFAULT 0 表示默认值为0,如果字段设定NOT NULL,没有输入值时,DEFAULT后跟的默认值来填充
+ * 这里的strftime是SQLite内置的时间、日期格式化函数,参数为输出格式(%s表示秒级Unix时间戳)、时间源(‘now'表示现在)
+ */
private static final String CREATE_NOTE_TABLE_SQL =
- "CREATE TABLE " + TABLE.NOTE + "(" +
+ "CREATE TABLE " + TABLE.NOTE + "(" + //开始建表,表名是TABLE.NOTE(note)
NoteColumns.ID + " INTEGER PRIMARY KEY," +
NoteColumns.PARENT_ID + " INTEGER NOT NULL DEFAULT 0," +
NoteColumns.ALERTED_DATE + " INTEGER NOT NULL DEFAULT 0," +
@@ -63,6 +97,13 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
NoteColumns.VERSION + " INTEGER NOT NULL DEFAULT 0" +
")";
+ /**
+ * 创建 Data 表 SQL,结合在Notes中定义的DataColumns初始化
+ *
+ * 外键:{@link DataColumns#NOTE_ID} 指向 note.id
+ * 通用列 data1~data5 含义由 {@link DataColumns#MIME_TYPE} 决定。
+ *
+ */
private static final String CREATE_DATA_TABLE_SQL =
"CREATE TABLE " + TABLE.DATA + "(" +
DataColumns.ID + " INTEGER PRIMARY KEY," +
@@ -78,12 +119,22 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
DataColumns.DATA5 + " TEXT NOT NULL DEFAULT ''" +
")";
+ /**
+ *在data(NOTE_ID)这一列上创建名为note_id_index的索引(如果该索引不存在)
+ * 便于执行SELECT * FROM data WHERE note_id=?之类的查询语句
+ */
private static final String CREATE_DATA_NOTE_ID_INDEX_SQL =
"CREATE INDEX IF NOT EXISTS note_id_index ON " +
TABLE.DATA + "(" + DataColumns.NOTE_ID + ");";
+
+ //三、创建Note表触发器,在文件夹下便签数量变化时自动增减便签数量(notes_count)的值
/**
* Increase folder's note count when move note to the folder
+ * 创建触发器,名字叫increase_folder_count_on_update
+ * 在note表的parent_id列更新后
+ * 执行触发器体,更新Note表,设置notes_count=notes_count+1,在id=new.parent_id的地方
+ * 此处用于自动更新父文件夹下的便签数量
*/
private static final String NOTE_INCREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER =
"CREATE TRIGGER increase_folder_count_on_update "+
@@ -132,8 +183,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" AND " + NoteColumns.NOTES_COUNT + ">0;" +
" END";
+ //四、Data 表触发器:自动同步便签摘要(snippet)
/**
* Update note's content when insert data with type {@link DataConstants#NOTE}
+ * 仅当新插入的DATA记录的mime_type字段值为note(笔记)类型时,触发器才会执行后续逻辑,若插入的是其他数据类型,比如图片,则不触发
+ * 执行触发器,将note表里的snippet列值更新为新纪录的content值,且仅更新note表里主键id=新纪录note_id的行
*/
private static final String DATA_UPDATE_NOTE_CONTENT_ON_INSERT_TRIGGER =
"CREATE TRIGGER update_note_content_on_insert " +
@@ -172,7 +226,9 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" END";
/**
- * Delete datas belong to note which has been deleted
+ * Delete data belong to note which has been deleted
+ * 当从note表删除一条笔记记录后,通过data表的note_id与note表的id关联
+ * 自动删除data表中所有与这条被删笔记关联的记录,笔记-笔记内容
*/
private static final String NOTE_DELETE_DATA_ON_DELETE_TRIGGER =
"CREATE TRIGGER delete_data_on_delete " +
@@ -184,6 +240,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
/**
* Delete notes belong to folder which has been deleted
+ * 当从note表里删除一条记录后,自动级联删除note表中所有parent_id等于被删记录id的子记录
*/
private static final String FOLDER_DELETE_NOTES_ON_DELETE_TRIGGER =
"CREATE TRIGGER folder_delete_notes_on_delete " +
@@ -199,24 +256,37 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
private static final String FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER =
"CREATE TRIGGER folder_move_notes_on_trash " +
" AFTER UPDATE ON " + TABLE.NOTE +
- " WHEN new." + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLER +
+ " WHEN new." + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLDER +
" BEGIN" +
" UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLER +
+ " SET " + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLDER +
" WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
" END";
+ /**
+ * Android开发中自定义的数据库辅助类的构造方法,作用是初始化,指定要创建/管理的数据库名称、版本号等核心参数
+ * @param context 上下文,提供应用运行的环境信息,如访问资源、数据库文件路径、系统服务等。
+ */
public NotesDatabaseHelper(Context context) {
+
+ /** super是调用的父类(SQLiteOpenHelper)构造方法
+ * @param context 父类通过context确定数据库文件的存储位置
+ * @param DB_NAME 数据库文件名
+ * @param null 创建数据库查询的游标(cursor),传null表示默认
+ * @param DB_VERSION自定义常量,数据库版本号
+ */
super(context, DB_NAME, null, DB_VERSION);
}
+ //完成note表的全量初始化
public void createNoteTable(SQLiteDatabase db) {
- db.execSQL(CREATE_NOTE_TABLE_SQL);
- reCreateNoteTableTriggers(db);
- createSystemFolder(db);
- Log.d(TAG, "note table has been created");
+ db.execSQL(CREATE_NOTE_TABLE_SQL); //执行SQL语句创建note表
+ reCreateNoteTableTriggers(db); //重建该表关联的触发器
+ createSystemFolder(db); //初始化系统默认文件夹数据
+ Log.d(TAG, "note table has been created"); //打印日志,确认note表成功创建
}
+ //批量重建触发器,先删除旧的,再建立新的
private void reCreateNoteTableTriggers(SQLiteDatabase db) {
db.execSQL("DROP TRIGGER IF EXISTS increase_folder_count_on_update");
db.execSQL("DROP TRIGGER IF EXISTS decrease_folder_count_on_update");
@@ -235,7 +305,9 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.execSQL(FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER);
}
+ //向note表插入四个系统默认文件夹:通话记录、根、临时、回收站。保证应用首次启动时有基础的文件夹结构。
private void createSystemFolder(SQLiteDatabase db) {
+ //ContentValues类用于存储键值对
ContentValues values = new ContentValues();
/**
@@ -243,12 +315,12 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
*/
values.put(NoteColumns.ID, Notes.ID_CALL_RECORD_FOLDER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
- db.insert(TABLE.NOTE, null, values);
+ db.insert(TABLE.NOTE, null, values); //向note表插入通话记录文件夹数据
/**
* root folder which is default folder
*/
- values.clear();
+ values.clear(); //清空原有的所有键值对,避免复用容器时残留上一个文件夹的字段值
values.put(NoteColumns.ID, Notes.ID_ROOT_FOLDER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
@@ -257,7 +329,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
* temporary folder which is used for moving note
*/
values.clear();
- values.put(NoteColumns.ID, Notes.ID_TEMPARAY_FOLDER);
+ values.put(NoteColumns.ID, Notes.ID_TEMPORARY_FOLDER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
@@ -265,7 +337,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
* create trash folder
*/
values.clear();
- values.put(NoteColumns.ID, Notes.ID_TRASH_FOLER);
+ values.put(NoteColumns.ID, Notes.ID_TRASH_FOLDER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
}
@@ -287,17 +359,24 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER);
}
+ /**
+ * synchronized同步关键字,保证多线程安全,避免多个线程同时调用该方法时,进入if分支,创建多个实例
+ * getInstance函数用于获取唯一实例
+ */
+
static synchronized NotesDatabaseHelper getInstance(Context context) {
+ //首次调用该方法时,才创建实例;若已创建,则直接复用
if (mInstance == null) {
mInstance = new NotesDatabaseHelper(context);
}
return mInstance;
}
+ //@override是Java中的一种注解,用于明确表示子类的方法是对父类方法的重写,实现多态性
@Override
public void onCreate(SQLiteDatabase db) {
- createNoteTable(db);
- createDataTable(db);
+ createNoteTable(db); //初始化笔记表
+ createDataTable(db); //初始化数据表
}
@Override
@@ -333,13 +412,15 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
}
}
+ //v1到v2的升级,删除旧的note data表,清空所有用户数据,重建新的
private void upgradeToV2(SQLiteDatabase db) {
- db.execSQL("DROP TABLE IF EXISTS " + TABLE.NOTE);
- db.execSQL("DROP TABLE IF EXISTS " + TABLE.DATA);
+ db.execSQL("DROP TABLE IF EXISTS " + TABLE.NOTE); //执行具体的SQL语句,删除旧的note表
+ db.execSQL("DROP TABLE IF EXISTS " + TABLE.DATA); //删除旧的data表
createNoteTable(db);
createDataTable(db);
}
+ //v2到v3的升级,清除无用触发器,新增gtask_id列,新增回收站文件夹
private void upgradeToV3(SQLiteDatabase db) {
// drop unused triggers
db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_insert");
@@ -350,11 +431,12 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
+ " TEXT NOT NULL DEFAULT ''");
// add a trash system folder
ContentValues values = new ContentValues();
- values.put(NoteColumns.ID, Notes.ID_TRASH_FOLER);
+ values.put(NoteColumns.ID, Notes.ID_TRASH_FOLDER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
}
+ //v3到v4的升级,为note表新增version列,且约束非空,默认为0
private void upgradeToV4(SQLiteDatabase db) {
db.execSQL("ALTER TABLE " + TABLE.NOTE + " ADD COLUMN " + NoteColumns.VERSION
+ " INTEGER NOT NULL DEFAULT 0");
diff --git a/src/notes/data/NotesProvider.java b/src/notes/data/NotesProvider.java
index edb0a60..3ca2c60 100644
--- a/src/notes/data/NotesProvider.java
+++ b/src/notes/data/NotesProvider.java
@@ -14,6 +14,12 @@
* limitations under the License.
*/
+/*
+* 文件名:NotesProvider.java
+* 修改人:蒙程
+* 修改时间:2025-12-13
+* 修改内容:增加代码注释,标注的代码行数共68行
+ */
package net.micode.notes.data;
@@ -34,24 +40,58 @@ import net.micode.notes.data.Notes.DataColumns;
import net.micode.notes.data.Notes.NoteColumns;
import net.micode.notes.data.NotesDatabaseHelper.TABLE;
+/**
+ * 便签内容提供类
+ *继承ContentProvider类,把本地SQLite数据库(note.db)暴露给整个安卓系统,支持以下功能:
+ *
+ * - CRUD(增删改查)
+ * - 搜索建议
+ * - URI路由于权限控制
+ *
+ * 支持URI示例:
+ *
+ * content://micode_notes/note 查询所有便签
+ * content://micode_notes/note/123 查询 ID=123 的便签
+ * content://micode_notes/data 查询所有数据行(附件、文本块、通话记录)
+ * content://micode_notes/search_suggest/xxx 系统搜索框建议接口
+ *
+ *
+ * @author 蒙程
+ * @since 2010-2011
+ */
public class NotesProvider extends ContentProvider {
+ //UriMatcher用于匹配uri,在ContentProvider中分辨出查询者想要查询哪个数据表
private static final UriMatcher mMatcher;
+ //mHelper是一个便签数据库辅助类单例
private NotesDatabaseHelper mHelper;
private static final String TAG = "NotesProvider";
- private static final int URI_NOTE = 1;
- private static final int URI_NOTE_ITEM = 2;
- private static final int URI_DATA = 3;
- private static final int URI_DATA_ITEM = 4;
+ private static final int URI_NOTE = 1; //匹配所有note的uri标识
+ private static final int URI_NOTE_ITEM = 2; //匹配单条note的uri标识
+ private static final int URI_DATA = 3; //匹配所有data行的uri标识,包括文本块、附件、通话记录
+ private static final int URI_DATA_ITEM = 4; //匹配单条data行的uri标识
- private static final int URI_SEARCH = 5;
- private static final int URI_SEARCH_SUGGEST = 6;
+ private static final int URI_SEARCH = 5; //执行实际搜索请求
+ private static final int URI_SEARCH_SUGGEST = 6; //提供搜索建议,实时联想输入关键词的匹配项
+ /**
+ * static块:在这个类第一次被Android系统加载到内存时,自动执行且只执行一次,
+ * 专门用来初始化 UriMatcher实例,并把所有需要匹配的uri规则(比如 note、data、search 相关)一次性注册好
+ * 为后续 query/insert/delete/update 方法匹配 URI 做好准备
+ * 使用static块效率更高,只需要初始化一次,省内存、省时间,而且可以确保在调用query等方法之前所有类型的uri都已经注册完毕
+ */
static {
+ //初始化,常量UriMatcher.NO_MATCH表示不匹配任何路径的返回码
mMatcher = new UriMatcher(UriMatcher.NO_MATCH);
+
+ /**
+ * addURI表示添加需要匹配的uri,如果匹配就会返回匹配码(第三个参数)
+ * 完整uri格式为:content:///(/?)
+ * "note/#"中的'#'是通配符,仅匹配任意数字(这里的数字对应笔记id)
+ */
mMatcher.addURI(Notes.AUTHORITY, "note", URI_NOTE);
mMatcher.addURI(Notes.AUTHORITY, "note/#", URI_NOTE_ITEM);
mMatcher.addURI(Notes.AUTHORITY, "data", URI_DATA);
@@ -65,6 +105,15 @@ public class NotesProvider extends ContentProvider {
* x'0A' represents the '\n' character in sqlite. For title and content in the search result,
* we will trim '\n' and white space in order to show more information.
*/
+ /**
+ * 1.把note表id、snippet列名映射成SearchManager规定的搜索建议标准列名,比如把 NoteColumns.ID 改成 SearchManager.SUGGEST_COLUMN_INTENT_EXTRA_DATA;
+ * 2.格式化内容:SNIPPET中可能有换行符,首尾空格,所以用 REPLACE去掉x'0A'(十六进制,代表换行符 '\n'),避免建议文本显示错乱。
+ * TRIM去除替换后字符串的首尾空格。
+ * SUGGEST_COLUMN_TEXT_1系统规范列名,搜索建议项的主文本
+ *3.预置交互逻辑:点击建议能直接跳转到笔记
+ * R.drawable.search_result图标,Intent.ACTION_VIEW表示”查看笔记“这个动作,
+ * Notes.TextNote.CONTENT_TYPE 告诉系统要打开的是 “文本笔记” 类型的页面
+ */
private static final String NOTES_SEARCH_PROJECTION = NoteColumns.ID + ","
+ NoteColumns.ID + " AS " + SearchManager.SUGGEST_COLUMN_INTENT_EXTRA_DATA + ","
+ "TRIM(REPLACE(" + NoteColumns.SNIPPET + ", x'0A','')) AS " + SearchManager.SUGGEST_COLUMN_TEXT_1 + ","
@@ -73,30 +122,55 @@ public class NotesProvider extends ContentProvider {
+ "'" + Intent.ACTION_VIEW + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_ACTION + ","
+ "'" + Notes.TextNote.CONTENT_TYPE + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA;
+ /**
+ * 指定查询返回的列,复用上面定义的NOTES_SEARCH_PROJECTION
+ * '?'模糊匹配,占位符,关键词
+ * 筛选笔记父文件夹不等于回收站文件夹
+ * 筛选笔记类型为‘纯笔记’
+ */
private static String NOTES_SNIPPET_SEARCH_QUERY = "SELECT " + NOTES_SEARCH_PROJECTION
+ " FROM " + TABLE.NOTE
+ " WHERE " + NoteColumns.SNIPPET + " LIKE ?"
- + " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER
+ + " AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLDER
+ " AND " + NoteColumns.TYPE + "=" + Notes.TYPE_NOTE;
+ //ContentProvider 返回数据库辅助类单例
@Override
public boolean onCreate() {
mHelper = NotesDatabaseHelper.getInstance(getContext());
return true;
}
+ /**
+ * 外部组件(如 Activity、SearchView)访问应用数据库数据的统一入口。
+ * 查询接口:支持note单条/批量、data单条/批量、搜索/搜索建议几种 URI,根据URI类型,拼URI,执行SQL语句,
+ * 返回符合要求的 Cursor 结果,并绑定数据变更通知,保证 UI 能感知数据变化。
+ * @param uri 请求 URI
+ * @param projection 要查询的列
+ * @param selection 查询条件
+ * @param selectionArgs selection中?的占位符参数
+ * @param sortOrder 排序规则
+ * @return cursor 返回游标
+ */
@Override
public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
String sortOrder) {
+ //初始化游标,默认空
Cursor c = null;
+
+ //db获取只读数据库连接(查询)
SQLiteDatabase db = mHelper.getReadableDatabase();
String id = null;
+
+ //mMatcher 在静态代码块里预注册了6种 URI 模式,通过match()返回的整数常量决定走哪条分支
switch (mMatcher.match(uri)) {
case URI_NOTE:
c = db.query(TABLE.NOTE, projection, selection, selectionArgs, null, null,
sortOrder);
break;
case URI_NOTE_ITEM:
+
+ //解析uri路径中的id,getPathSegments()返回[path,#]
id = uri.getPathSegments().get(1);
c = db.query(TABLE.NOTE, projection, NoteColumns.ID + "=" + id
+ parseSelection(selection), selectionArgs, null, null, sortOrder);
@@ -117,6 +191,7 @@ public class NotesProvider extends ContentProvider {
"do not specify sortOrder, selection, selectionArgs, or projection" + "with this query");
}
+ //获取关键词
String searchString = null;
if (mMatcher.match(uri) == URI_SEARCH_SUGGEST) {
if (uri.getPathSegments().size() > 1) {
@@ -126,36 +201,54 @@ public class NotesProvider extends ContentProvider {
searchString = uri.getQueryParameter("pattern");
}
+ //空关键词时,返回null,无需查询
if (TextUtils.isEmpty(searchString)) {
return null;
}
try {
+ //关键词格式化
searchString = String.format("%%%s%%", searchString);
+
+ //执行查询
c = db.rawQuery(NOTES_SNIPPET_SEARCH_QUERY,
new String[] { searchString });
- } catch (IllegalStateException ex) {
+ } catch (IllegalStateException ex) { //捕获try中出现的异常,打印日志
Log.e(TAG, "got exception: " + ex.toString());
}
break;
+
+ //传了没注册过的uri,直接抛异常,防止误调用
default:
throw new IllegalArgumentException("Unknown URI " + uri);
}
+ //说明查询到结果,将查询返回的 Cursor 与 ContentResolver、当前 URI 绑定;
if (c != null) {
c.setNotificationUri(getContext().getContentResolver(), uri);
}
return c;
}
+ /**
+ * 是外部组件(如 Activity、Service)向应用数据库的note、data表插入数据的统一入口。
+ * 传入content URI 匹配目标表note\data,执行插入操作,校验关联字段合法性,出发数据变更通知,返回新uri
+ * @param uri 请求uri
+ * @param values 要插入的键值对,如note_id=100
+ * @return 新uri
+ *
+ * @author 蒙程
+ * @date 2025-12-13
+ */
@Override
public Uri insert(Uri uri, ContentValues values) {
- SQLiteDatabase db = mHelper.getWritableDatabase();
+ SQLiteDatabase db = mHelper.getWritableDatabase(); //获取可写数据库连接
long dataId = 0, noteId = 0, insertedId = 0;
switch (mMatcher.match(uri)) {
case URI_NOTE:
insertedId = noteId = db.insert(TABLE.NOTE, null, values);
break;
case URI_DATA:
+ //插入笔记的具体内容,因此先检查values中是否包含DATA_COLUMNS.NOTE_ID
if (values.containsKey(DataColumns.NOTE_ID)) {
noteId = values.getAsLong(DataColumns.NOTE_ID);
} else {
@@ -167,26 +260,39 @@ public class NotesProvider extends ContentProvider {
throw new IllegalArgumentException("Unknown URI " + uri);
}
// Notify the note uri
+ //通知所有监听该 URI 的 Cursor “数据已变更”
if (noteId > 0) {
getContext().getContentResolver().notifyChange(
ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId), null);
}
// Notify the data uri
+ //通知该 URI 的数据变更,比如插入笔记内容后,刷新笔记详情页的内容展示。
if (dataId > 0) {
getContext().getContentResolver().notifyChange(
ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, dataId), null);
}
+ //返回插入的单条记录的标准uri,将插入记录的ID拼接在原始URI末尾
return ContentUris.withAppendedId(uri, insertedId);
}
+ /**
+ * 删除接口:支持按条件或单 ID 删除;系统文件夹(ID≤0)禁止删除
+ * @param uri 请求 URI
+ * @param selection 要查询的列
+ * @param selectionArgs 查询条件
+ * @return count 实际删除行数
+ *
+ * @author 蒙程
+ * @date 2025-12-13
+ */
@Override
public int delete(Uri uri, String selection, String[] selectionArgs) {
int count = 0;
- String id = null;
+ String id = null; //存储单条记录的ID(从uri中解析)
SQLiteDatabase db = mHelper.getWritableDatabase();
- boolean deleteData = false;
+ boolean deleteData = false; // 标记是否删除的是DATA表数据
switch (mMatcher.match(uri)) {
case URI_NOTE:
selection = "(" + selection + ") AND " + NoteColumns.ID + ">0 ";
@@ -195,8 +301,8 @@ public class NotesProvider extends ContentProvider {
case URI_NOTE_ITEM:
id = uri.getPathSegments().get(1);
/**
- * ID that smaller than 0 is system folder which is not allowed to
- * trash
+ * ID that smaller than 0 is system folder which is not allowed to trash
+ * ID<0是系统文件夹,不能删,跳出分支
*/
long noteId = Long.valueOf(id);
if (noteId <= 0) {
@@ -213,12 +319,14 @@ public class NotesProvider extends ContentProvider {
id = uri.getPathSegments().get(1);
count = db.delete(TABLE.DATA,
DataColumns.ID + "=" + id + parseSelection(selection), selectionArgs);
- deleteData = true;
+ deleteData = true; //标记删除的是data表数据
break;
default:
throw new IllegalArgumentException("Unknown URI " + uri);
}
if (count > 0) {
+
+ //如果删除的是data表内容,需要关联note表,删除内容后刷新笔记列表
if (deleteData) {
getContext().getContentResolver().notifyChange(Notes.CONTENT_NOTE_URI, null);
}
@@ -227,6 +335,17 @@ public class NotesProvider extends ContentProvider {
return count;
}
+ /**
+ * 更新接口:支持按条件或单 ID 更新;自动累加版本号(增量同步用)
+ * @param uri 请求 URI
+ * @param values 带查询的键值对
+ * @param selection 待查询列
+ * @param selectionArgs 查询条件
+ * @return 实际更新行数
+ *
+ * @author 蒙程
+ * @date 2025-12-13
+ */
@Override
public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) {
int count = 0;
@@ -267,26 +386,44 @@ public class NotesProvider extends ContentProvider {
return count;
}
+ /**
+ * 将外部传入的SQL筛选条件拼接为AND格式(若selection非空)
+ * @param selection 用户传入的WHERE子句
+ * @return "AND(selection)" 或者空串
+ */
private String parseSelection(String selection) {
return (!TextUtils.isEmpty(selection) ? " AND (" + selection + ')' : "");
}
+ /**
+ * 根据传入的id或自定义筛选条件,把note.version字段+1,用于增量同步
+ * @param id 单条便签ID
+ * @param selection 待查询列
+ * @param selectionArgs 查询条件
+ */
private void increaseNoteVersion(long id, String selection, String[] selectionArgs) {
- StringBuilder sql = new StringBuilder(120);
+ StringBuilder sql = new StringBuilder(120); //120是初始SQL语句长度
sql.append("UPDATE ");
sql.append(TABLE.NOTE);
sql.append(" SET ");
sql.append(NoteColumns.VERSION);
sql.append("=" + NoteColumns.VERSION + "+1 ");
+ //有ID或者有selection时,才需要加WHERE子句
if (id > 0 || !TextUtils.isEmpty(selection)) {
sql.append(" WHERE ");
}
+ //场景1:仅有ID,精准更新单条笔记
if (id > 0) {
sql.append(NoteColumns.ID + "=" + String.valueOf(id));
}
+ //场景2:有自定义selection(批量/组合条件更新)
if (!TextUtils.isEmpty(selection)) {
+
+ //若已有ID,拼接为AND(selection);若没有ID,直接用selection
String selectString = id > 0 ? parseSelection(selection) : selection;
+
+ //替换selection中的?占位符为实际参数
for (String args : selectionArgs) {
selectString = selectString.replaceFirst("\\?", args);
}
@@ -296,6 +433,7 @@ public class NotesProvider extends ContentProvider {
mHelper.getWritableDatabase().execSQL(sql.toString());
}
+ //返回给定URI的MIME类型(暂未实现,返回null)
@Override
public String getType(Uri uri) {
// TODO Auto-generated method stub
diff --git a/src/notes/gtask/data/MetaData.java b/src/notes/gtask/data/MetaData.java
index 3a2050b..e09fad8 100644
--- a/src/notes/gtask/data/MetaData.java
+++ b/src/notes/gtask/data/MetaData.java
@@ -24,12 +24,31 @@ import net.micode.notes.tool.GTaskStringUtils;
import org.json.JSONException;
import org.json.JSONObject;
-
+/**
+ * gtask同步任务的元数据管理类
+ * 存储和管理笔记与gtask同步时的元数据信息
+ * MetaData是什么?描述便签属性的信息,比如创建时间、修改时间、便签ID等,而不是便签的正文内容。
+ * gid是什么?google为每个同步任务分配的唯一标识,分给远端,保证同步的一致性
+ * JSON是什么?一种数据封装格式,用于封装MetaData,可读性强,可被用户或其他应用读取/编辑
+ *
+ * 继承Task类,专门用于存储同步元数据
+ */
public class MetaData extends Task {
+ /**
+ * MetaData.class拿到MetaData的class对象
+ * getSimpleName返回类名不含包名的简短形式,这里就是’MetaData‘
+ */
private final static String TAG = MetaData.class.getSimpleName();
+ //存储当前元数据关联的gid
private String mRelatedGid = null;
+ /**
+ *设置元数据的核心方法
+ * 将关联的gtask ID封装到JSON对象中,并设置为Task的笔记内容和名称
+ * @param gid 相当于远端的身份证号
+ * @param metaInfo JSONObject对象,用来存储MetaData的JSON格式数据结构。
+ */
public void setMeta(String gid, JSONObject metaInfo) {
try {
metaInfo.put(GTaskStringUtils.META_HEAD_GTASK_ID, gid);
@@ -40,17 +59,27 @@ public class MetaData extends Task {
setName(GTaskStringUtils.META_NOTE_NAME);
}
+ /**
+ * 获取当前元数据关联的gtask ID
+ * @return 关联的远端gtask ID(返回null时,未关联)
+ */
public String getRelatedGid() {
return mRelatedGid;
}
+ //笔记内容不为空就保存
@Override
public boolean isWorthSaving() {
return getNotes() != null;
}
+ /**
+ * 从远端gtask返回的JSON数据设置当前元数据内容
+ * @param js 远端gtask返回的JSON对象
+ */
@Override
public void setContentByRemoteJSON(JSONObject js) {
+ //调用父类方法,初始化task基础属性
super.setContentByRemoteJSON(js);
if (getNotes() != null) {
try {
@@ -63,17 +92,23 @@ public class MetaData extends Task {
}
}
+ /**不会将元数据单独保存为JSON文件并保存到本地,
+ * 而是将MetaData和正文一起存储在本地的SQLite数据库,
+ * 为了防止用户篡改信息,比如便签的创建时间,导致APP读取数据时出现异常
+ */
@Override
public void setContentByLocalJSON(JSONObject js) {
// this function should not be called
throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");
}
+ //不支持生成本地JSON
@Override
public JSONObject getLocalJSONFromContent() {
throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called");
}
+ //无需计算同步动作
@Override
public int getSyncAction(Cursor c) {
throw new IllegalAccessError("MetaData:getSyncAction should not be called");
diff --git a/src/notes/gtask/data/Node.java b/src/notes/gtask/data/Node.java
index 63950e0..3b393db 100644
--- a/src/notes/gtask/data/Node.java
+++ b/src/notes/gtask/data/Node.java
@@ -20,24 +20,29 @@ import android.database.Cursor;
import org.json.JSONObject;
+/**
+ * Node类是抽象类,
+ * 声明了九种数据同步场景变量,
+ * 还声明了一些同步操作方法
+ */
public abstract class Node {
- public static final int SYNC_ACTION_NONE = 0;
+ public static final int SYNC_ACTION_NONE = 0; //无同步操作
- public static final int SYNC_ACTION_ADD_REMOTE = 1;
+ public static final int SYNC_ACTION_ADD_REMOTE = 1; //远程添加操作
- public static final int SYNC_ACTION_ADD_LOCAL = 2;
+ public static final int SYNC_ACTION_ADD_LOCAL = 2; //本地添加操作
- public static final int SYNC_ACTION_DEL_REMOTE = 3;
+ public static final int SYNC_ACTION_DEL_REMOTE = 3; //远程删除操作
- public static final int SYNC_ACTION_DEL_LOCAL = 4;
+ public static final int SYNC_ACTION_DEL_LOCAL = 4; //本地删除操作
- public static final int SYNC_ACTION_UPDATE_REMOTE = 5;
+ public static final int SYNC_ACTION_UPDATE_REMOTE = 5; //远程更新操作
- public static final int SYNC_ACTION_UPDATE_LOCAL = 6;
+ public static final int SYNC_ACTION_UPDATE_LOCAL = 6; //本地更新操作
- public static final int SYNC_ACTION_UPDATE_CONFLICT = 7;
+ public static final int SYNC_ACTION_UPDATE_CONFLICT = 7; //更新冲突
- public static final int SYNC_ACTION_ERROR = 8;
+ public static final int SYNC_ACTION_ERROR = 8; //同步出错
private String mGid;
@@ -47,23 +52,30 @@ public abstract class Node {
private boolean mDeleted;
+ //无参构造法,创建Node对象时无需传入任何参数
public Node() {
- mGid = null;
- mName = "";
+ mGid = null; //常由云端生成
+ mName = ""; //不初始化为null:避免后续调用mName.length等方法时触发空指针异常
mLastModified = 0;
mDeleted = false;
}
+ //JSONObject是JSON实例的抽象类,生成同步创建操作JSON数据,返回操作ID
public abstract JSONObject getCreateAction(int actionId);
+ //生成同步更新操作的JSON数据,返回操作ID
public abstract JSONObject getUpdateAction(int actionId);
+ //这是一个方法,根据远程JSON数据设置内容(远程数据同步到本地)(具体操作)
public abstract void setContentByRemoteJSON(JSONObject js);
+ //这是一个方法,根据本地JSON数据设置内容(本地数据处理)(具体操作)
public abstract void setContentByLocalJSON(JSONObject js);
+ //将本地内容转换成JSON数据,同步到远程
public abstract JSONObject getLocalJSONFromContent();
+ //通过游标获取同步操作类型,在前面声明为类型变量0-8
public abstract int getSyncAction(Cursor c);
public void setGid(String gid) {
diff --git a/src/notes/gtask/data/SqlData.java b/src/notes/gtask/data/SqlData.java
index d3ec3be..b1b4ff9 100644
--- a/src/notes/gtask/data/SqlData.java
+++ b/src/notes/gtask/data/SqlData.java
@@ -34,7 +34,11 @@ import net.micode.notes.gtask.exception.ActionFailureException;
import org.json.JSONException;
import org.json.JSONObject;
-
+/**
+ *管理便签应用中的数据项(如文本、图片等),
+ * 负责数据项的加载、从JSON解析数据、生成JSON数据、数据库交互(插入 / 更新)及版本冲突控制,
+ * 是便签数据在内存与数据库之间的中间层处理类。
+ */
public class SqlData {
private static final String TAG = SqlData.class.getSimpleName();
@@ -47,16 +51,21 @@ public class SqlData {
public static final int DATA_ID_COLUMN = 0;
+ //区分数据项,比如文本、图片、附件等,由此决定数据解析方式
public static final int DATA_MIME_TYPE_COLUMN = 1;
+ //存储数据项的核心内容
public static final int DATA_CONTENT_COLUMN = 2;
+ //存储content辅助信息,比如图片的宽度大小等
public static final int DATA_CONTENT_DATA_1_COLUMN = 3;
+ //更多扩展信息
public static final int DATA_CONTENT_DATA_3_COLUMN = 4;
private ContentResolver mContentResolver;
+ //false表示新创建的未入库数据项,true表示数据库中已经创建的数据项
private boolean mIsCreate;
private long mDataId;
@@ -71,6 +80,10 @@ public class SqlData {
private ContentValues mDiffDataValues;
+ /**
+ * mContentResolver是什么?
+ * @param context
+ */
public SqlData(Context context) {
mContentResolver = context.getContentResolver();
mIsCreate = true;
@@ -97,13 +110,23 @@ public class SqlData {
mDataContentData3 = c.getString(DATA_CONTENT_DATA_3_COLUMN);
}
+ /**
+ * 将JSON中的数据项属性映射到SqlData实例的成员变量,
+ * 记录变更的字段到mDifferentValues中,为后续数据库增量更新做准备
+ * 数据序列化,JSON js->实例
+ * @param js
+ * @throws JSONException
+ */
public void setContent(JSONObject js) throws JSONException {
long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID;
+
+ //新创建的未入库数据项或者是当前实例的已有ID和JSON中解析的ID不一样,说明该字段发生了变更
if (mIsCreate || mDataId != dataId) {
mDiffDataValues.put(DataColumns.ID, dataId);
}
mDataId = dataId;
+ //判断JSON中是否包含MIME_TYPE键,否则默认为纯文本
String dataMimeType = js.has(DataColumns.MIME_TYPE) ? js.getString(DataColumns.MIME_TYPE)
: DataConstants.NOTE;
if (mIsCreate || !mDataMimeType.equals(dataMimeType)) {
@@ -111,18 +134,21 @@ public class SqlData {
}
mDataMimeType = dataMimeType;
+ //判断JSON中是否包含CONTENT键,如便签文本等,否则赋值为空串
String dataContent = js.has(DataColumns.CONTENT) ? js.getString(DataColumns.CONTENT) : "";
if (mIsCreate || !mDataContent.equals(dataContent)) {
mDiffDataValues.put(DataColumns.CONTENT, dataContent);
}
mDataContent = dataContent;
+ //判断DATA1键,如图片宽度等
long dataContentData1 = js.has(DataColumns.DATA1) ? js.getLong(DataColumns.DATA1) : 0;
if (mIsCreate || mDataContentData1 != dataContentData1) {
mDiffDataValues.put(DataColumns.DATA1, dataContentData1);
}
mDataContentData1 = dataContentData1;
+ //判断DATA3键
String dataContentData3 = js.has(DataColumns.DATA3) ? js.getString(DataColumns.DATA3) : "";
if (mIsCreate || !mDataContentData3.equals(dataContentData3)) {
mDiffDataValues.put(DataColumns.DATA3, dataContentData3);
@@ -144,28 +170,39 @@ public class SqlData {
return js;
}
+ /**
+ * 将数据项提交到数据库,根据数据项是否为新建,分别执行插入或者更新操作,同时支持版本验证,
+ * 最终清理变更记录,更新实例状态
+ * @param noteId 数据项关联的便签ID
+ * @param validateVersion 版本验证布尔值,防止多人或者多设备同时改,避免改乱
+ * @param version 要验证的版本号
+ */
public void commit(long noteId, boolean validateVersion, long version) {
+ //新创建的项,“插入”
if (mIsCreate) {
+ //未入库,数据库未生成主键,所以当前数据项ID为无效值
if (mDataId == INVALID_ID && mDiffDataValues.containsKey(DataColumns.ID)) {
mDiffDataValues.remove(DataColumns.ID);
}
mDiffDataValues.put(DataColumns.NOTE_ID, noteId);
Uri uri = mContentResolver.insert(Notes.CONTENT_DATA_URI, mDiffDataValues);
- try {
+ try { //从数据库返回的地址里抠出数据项的ID
mDataId = Long.valueOf(uri.getPathSegments().get(1));
} catch (NumberFormatException e) {
Log.e(TAG, "Get note id error :" + e.toString());
throw new ActionFailureException("create note failed");
}
- } else {
+ } else { //数据库里本来就有这个项,只是更改内容
if (mDiffDataValues.size() > 0) {
int result = 0;
+
+ //不需要防止多设备更改冲突
if (!validateVersion) {
result = mContentResolver.update(ContentUris.withAppendedId(
Notes.CONTENT_DATA_URI, mDataId), mDiffDataValues, null, null);
- } else {
+ } else { //需要防止多设备更改冲突
result = mContentResolver.update(ContentUris.withAppendedId(
Notes.CONTENT_DATA_URI, mDataId), mDiffDataValues,
" ? in (SELECT " + NoteColumns.ID + " FROM " + TABLE.NOTE
diff --git a/src/notes/gtask/data/SqlNote.java b/src/notes/gtask/data/SqlNote.java
index 79a4095..a854491 100644
--- a/src/notes/gtask/data/SqlNote.java
+++ b/src/notes/gtask/data/SqlNote.java
@@ -37,12 +37,18 @@ import org.json.JSONObject;
import java.util.ArrayList;
-
+/**
+ * sqlNote类用于处理本地数据库中的笔记数据
+ * 主要负责笔记的创建、加载(从数据库读数据)、数据同步、把笔记提交到数据库。
+ * 相当于单个笔记的生命周期管家。
+ * 与Android的ContentProvider进行交互
+ */
public class SqlNote {
private static final String TAG = SqlNote.class.getSimpleName();
private static final int INVALID_ID = -99999;
+ //记录需要从小米便签数据库中查询的字段
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,6 +58,7 @@ public class SqlNote {
NoteColumns.VERSION
};
+ //将PROJECTION_NOTE中的每个字段按顺序赋索引值0-16,便于从cursor中快速获取
public static final int ID_COLUMN = 0;
public static final int ALERTED_DATE_COLUMN = 1;
@@ -86,11 +93,11 @@ public class SqlNote {
public static final int VERSION_COLUMN = 16;
- private Context mContext;
+ private Context mContext; //上下文对象,用于获取系统服务(如ContentResolver)
- private ContentResolver mContentResolver;
+ private ContentResolver mContentResolver; //操作ContentProvider(数据库交互)
- private boolean mIsCreate;
+ private boolean mIsCreate; //标记当前笔记是否为新创建(未存入数据库)
private long mId;
@@ -100,15 +107,15 @@ public class SqlNote {
private long mCreatedDate;
- private int mHasAttachment;
+ private int mHasAttachment; //是否有附件(0:无,1:有)
private long mModifiedDate;
private long mParentId;
- private String mSnippet;
+ private String mSnippet; // 笔记摘要(简短内容,用于列表展示)
- private int mType;
+ private int mType; // 笔记类型(如:Notes.TYPE_NOTE-普通笔记,TYPE_FOLDER-文件夹)
private int mWidgetId;
@@ -118,10 +125,11 @@ public class SqlNote {
private long mVersion;
- private ContentValues mDiffNoteValues;
+ private ContentValues mDiffNoteValues; //存储需要更新的字段
- private ArrayList mDataList;
+ private ArrayList mDataList; // 笔记关联的数据列表(如文本内容、图片等,由SqlData管理)
+ //初始化新笔记
public SqlNote(Context context) {
mContext = context;
mContentResolver = context.getContentResolver();
@@ -143,9 +151,12 @@ public class SqlNote {
mDataList = new ArrayList();
}
+ //从cursor加载已有笔记
public SqlNote(Context context, Cursor c) {
mContext = context;
mContentResolver = context.getContentResolver();
+
+ //从数据库加载,标记为已存在
mIsCreate = false;
loadFromCursor(c);
mDataList = new ArrayList();
@@ -154,10 +165,13 @@ public class SqlNote {
mDiffNoteValues = new ContentValues();
}
+ //通过id加载已有笔记
public SqlNote(Context context, long id) {
mContext = context;
mContentResolver = context.getContentResolver();
mIsCreate = false;
+
+ //根据id查询数据库并加载数据
loadFromCursor(id);
mDataList = new ArrayList();
if (mType == Notes.TYPE_NOTE)
@@ -169,13 +183,14 @@ public class SqlNote {
private void loadFromCursor(long id) {
Cursor c = null;
try {
+ //查询指定id的笔记
c = mContentResolver.query(Notes.CONTENT_NOTE_URI, PROJECTION_NOTE, "(_id=?)",
new String[] {
String.valueOf(id)
}, null);
if (c != null) {
- c.moveToNext();
- loadFromCursor(c);
+ c.moveToNext(); //移动到第一条记录
+ loadFromCursor(c); //从cursor加载数据
} else {
Log.w(TAG, "loadFromCursor: cursor = null");
}
@@ -200,10 +215,12 @@ public class SqlNote {
mVersion = c.getLong(VERSION_COLUMN);
}
+ //加载笔记的关联数据(如文本内容)
private void loadDataContent() {
Cursor c = null;
- mDataList.clear();
+ mDataList.clear(); //清空现有数据
try {
+ //根据(note_id=mId)查询当前笔记关联的所有数据
c = mContentResolver.query(Notes.CONTENT_DATA_URI, SqlData.PROJECTION_DATA,
"(note_id=?)", new String[] {
String.valueOf(mId)
@@ -226,15 +243,26 @@ public class SqlNote {
}
}
+ /**数据同步相关方法-从JSON对象设置笔记内容,便于同步接收数据
+ * JSON解析-内存字段映射-差异记录-持久化落地。
+ * setContent解析JSON到SqlNote对象:按照笔记类型解析-元数据映射-内容数据映射-差异记录
+ */
public boolean setContent(JSONObject js) {
try {
+ //解析JSON中的笔记元数据note
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) {
+ }
+ //文件夹类型,仅更新摘要和类型
+ 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) : "";
+
+ //如果是新创建或者内容(snippet)有变化时记录差异
if (mIsCreate || !mSnippet.equals(snippet)) {
mDiffNoteValues.put(NoteColumns.SNIPPET, snippet);
}
@@ -246,14 +274,21 @@ public class SqlNote {
mDiffNoteValues.put(NoteColumns.TYPE, type);
}
mType = type;
- } else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_NOTE) {
+ }
+
+ //普通笔记类型,更新所有元数据和关联数据
+ else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_NOTE) {
+ //关联数据数组
JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
+
+ //逐个解析元数据字段,仅仅记录变化的部分到差异容器,这里是id字段
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;
if (mIsCreate || mAlertDate != alertDate) {
@@ -261,6 +296,7 @@ public class SqlNote {
}
mAlertDate = alertDate;
+ //背景颜色字段
int bgColorId = note.has(NoteColumns.BG_COLOR_ID) ? note
.getInt(NoteColumns.BG_COLOR_ID) : ResourceParser.getDefaultBgId(mContext);
if (mIsCreate || mBgColorId != bgColorId) {
@@ -268,6 +304,7 @@ public class SqlNote {
}
mBgColorId = bgColorId;
+ //创建日期字段
long createDate = note.has(NoteColumns.CREATED_DATE) ? note
.getLong(NoteColumns.CREATED_DATE) : System.currentTimeMillis();
if (mIsCreate || mCreatedDate != createDate) {
@@ -275,6 +312,7 @@ public class SqlNote {
}
mCreatedDate = createDate;
+ //有无附件字段
int hasAttachment = note.has(NoteColumns.HAS_ATTACHMENT) ? note
.getInt(NoteColumns.HAS_ATTACHMENT) : 0;
if (mIsCreate || mHasAttachment != hasAttachment) {
@@ -282,6 +320,7 @@ public class SqlNote {
}
mHasAttachment = hasAttachment;
+ //修改日期字段
long modifiedDate = note.has(NoteColumns.MODIFIED_DATE) ? note
.getLong(NoteColumns.MODIFIED_DATE) : System.currentTimeMillis();
if (mIsCreate || mModifiedDate != modifiedDate) {
@@ -289,6 +328,7 @@ public class SqlNote {
}
mModifiedDate = modifiedDate;
+ //父文件夹字段
long parentId = note.has(NoteColumns.PARENT_ID) ? note
.getLong(NoteColumns.PARENT_ID) : 0;
if (mIsCreate || mParentId != parentId) {
@@ -296,6 +336,7 @@ public class SqlNote {
}
mParentId = parentId;
+ //内容字段
String snippet = note.has(NoteColumns.SNIPPET) ? note
.getString(NoteColumns.SNIPPET) : "";
if (mIsCreate || !mSnippet.equals(snippet)) {
@@ -303,6 +344,7 @@ public class SqlNote {
}
mSnippet = snippet;
+ //笔记类型字段
int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE)
: Notes.TYPE_NOTE;
if (mIsCreate || mType != type) {
@@ -310,6 +352,7 @@ public class SqlNote {
}
mType = type;
+ //桌面组件id字段
int widgetId = note.has(NoteColumns.WIDGET_ID) ? note.getInt(NoteColumns.WIDGET_ID)
: AppWidgetManager.INVALID_APPWIDGET_ID;
if (mIsCreate || mWidgetId != widgetId) {
@@ -317,6 +360,7 @@ public class SqlNote {
}
mWidgetId = widgetId;
+ //桌面组件类型字段
int widgetType = note.has(NoteColumns.WIDGET_TYPE) ? note
.getInt(NoteColumns.WIDGET_TYPE) : Notes.TYPE_WIDGET_INVALIDE;
if (mIsCreate || mWidgetType != widgetType) {
@@ -324,6 +368,7 @@ public class SqlNote {
}
mWidgetType = widgetType;
+ //原始父文件夹字段
long originParent = note.has(NoteColumns.ORIGIN_PARENT_ID) ? note
.getLong(NoteColumns.ORIGIN_PARENT_ID) : 0;
if (mIsCreate || mOriginParent != originParent) {
@@ -334,6 +379,8 @@ public class SqlNote {
for (int i = 0; i < dataArray.length(); i++) {
JSONObject data = dataArray.getJSONObject(i);
SqlData sqlData = null;
+
+ //查找已存在的sqlData(通过ID匹配)
if (data.has(DataColumns.ID)) {
long dataId = data.getLong(DataColumns.ID);
for (SqlData temp : mDataList) {
@@ -343,12 +390,13 @@ public class SqlNote {
}
}
+ //不存在则创建新的sqlData
if (sqlData == null) {
sqlData = new SqlData(mContext);
mDataList.add(sqlData);
}
- sqlData.setContent(data);
+ sqlData.setContent(data); //更新数据内容
}
}
} catch (JSONException e) {
@@ -359,6 +407,7 @@ public class SqlNote {
return true;
}
+ //将笔记内容转换成JSON对象(用于同步发送数据)
public JSONObject getContent() {
try {
JSONObject js = new JSONObject();
@@ -369,6 +418,7 @@ public class SqlNote {
}
JSONObject note = new JSONObject();
+ //普通笔记:所有元数据+关联数据
if (mType == Notes.TYPE_NOTE) {
note.put(NoteColumns.ID, mId);
note.put(NoteColumns.ALERTED_DATE, mAlertDate);
@@ -384,6 +434,7 @@ public class SqlNote {
note.put(NoteColumns.ORIGIN_PARENT_ID, mOriginParent);
js.put(GTaskStringUtils.META_HEAD_NOTE, note);
+ //关联数据转换成JSON数组
JSONArray dataArray = new JSONArray();
for (SqlData sqlData : mDataList) {
JSONObject data = sqlData.getContent();
@@ -392,7 +443,9 @@ public class SqlNote {
}
}
js.put(GTaskStringUtils.META_HEAD_DATA, dataArray);
- } else if (mType == Notes.TYPE_FOLDER || mType == Notes.TYPE_SYSTEM) {
+ }
+ //文件夹/系统文件夹:仅包含ID、类型、摘要
+ 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);
@@ -407,11 +460,16 @@ public class SqlNote {
return null;
}
+ /**
+ *为什么下面这些数据设置不放在上面的setContent(JSONObject js)函数里
+ */
+ //设置父文件夹ID并记录差异
public void setParentId(long id) {
mParentId = id;
mDiffNoteValues.put(NoteColumns.PARENT_ID, id);
}
+ //设置GTask ID 用于同步
public void setGtaskId(String gid) {
mDiffNoteValues.put(NoteColumns.GTASK_ID, gid);
}
@@ -420,10 +478,14 @@ public class SqlNote {
mDiffNoteValues.put(NoteColumns.SYNC_ID, syncId);
}
+ //重置本地修改标记(用于修改后)
public void resetLocalModified() {
mDiffNoteValues.put(NoteColumns.LOCAL_MODIFIED, 0);
}
+ /**
+ * 下面几个成员函数是为了获取成员变量值
+ */
public long getId() {
return mId;
}
@@ -440,14 +502,20 @@ public class SqlNote {
return mType == Notes.TYPE_NOTE;
}
+ //数据库提交方法:保存/更新笔记
public void commit(boolean validateVersion) {
+ //如果是新笔记,就插入到数据库
if (mIsCreate) {
+
+ //移除无效ID,因为数据库会自动生成ID
if (mId == INVALID_ID && mDiffNoteValues.containsKey(NoteColumns.ID)) {
mDiffNoteValues.remove(NoteColumns.ID);
}
+ //插入笔记元数据到ContentProvider
Uri uri = mContentResolver.insert(Notes.CONTENT_NOTE_URI, mDiffNoteValues);
try {
+ //从返回的uri里获取新生成的ID
mId = Long.valueOf(uri.getPathSegments().get(1));
} catch (NumberFormatException e) {
Log.e(TAG, "Get note id error :" + e.toString());
@@ -457,25 +525,34 @@ public class SqlNote {
throw new IllegalStateException("Create thread id failed");
}
+ //提交关联数据,如文本内容
if (mType == Notes.TYPE_NOTE) {
for (SqlData sqlData : mDataList) {
sqlData.commit(mId, false, -1);
}
}
- } else {
+ }
+ //不是新笔记,已经存在,就执行“更新”操作
+ else {
+ //验证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) {
result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
+ NoteColumns.ID + "=?)", new String[] {
String.valueOf(mId)
});
- } else {
+ }
+ // 验证版本:当数据库版本<=当前版本时更新
+ else {
result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
+ NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)",
new String[] {
@@ -487,6 +564,7 @@ public class SqlNote {
}
}
+ //提交关联数据
if (mType == Notes.TYPE_NOTE) {
for (SqlData sqlData : mDataList) {
sqlData.commit(mId, validateVersion, mVersion);
@@ -494,12 +572,12 @@ public class SqlNote {
}
}
- // refresh local info
+ // refresh local info,
loadFromCursor(mId);
if (mType == Notes.TYPE_NOTE)
loadDataContent();
- mDiffNoteValues.clear();
- mIsCreate = false;
+ mDiffNoteValues.clear(); //清空差异字段
+ mIsCreate = false; //标记为已创建
}
}
diff --git a/src/notes/gtask/data/Task.java b/src/notes/gtask/data/Task.java
index 6a19454..acde9c3 100644
--- a/src/notes/gtask/data/Task.java
+++ b/src/notes/gtask/data/Task.java
@@ -31,19 +31,22 @@ import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;
-
+/**
+ * 继承Node类,具体实现 Node类中定义的方法,包括更新、删除、添加操作等
+ */
public class Task extends Node {
private static final String TAG = Task.class.getSimpleName();
- private boolean mCompleted;
+ private boolean mCompleted; //Google 任务是否已完成(勾选状态)
- private String mNotes;
+ private String mNotes; //任务备注正文
- private JSONObject mMetaInfo;
+ private JSONObject mMetaInfo;//定义Task的MetaData的JSON数据格式
+ //指向当前任务点的前兄弟任务的指针/引用,用于在内存中关联当前任务的前一个任务
private Task mPriorSibling;
- private TaskList mParent;
+ private TaskList mParent; //定义所属的Google TaskList
public Task() {
super();
@@ -54,6 +57,11 @@ public class Task extends Node {
mMetaInfo = null;
}
+ /**生成“创建任务”的JSON指令,用于将本地新建任务同步到云端z
+ *
+ * @param actionId
+ * @return 一个JSON对象实例 包括“创建”操作信息和“业务”信息
+ */
public JSONObject getCreateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -68,6 +76,10 @@ public class Task extends Node {
// index
js.put(GTaskStringUtils.GTASK_JSON_INDEX, mParent.getChildTaskIndex(this));
+ /**为什么要再创建一个JSONObject实例对象?
+ * 分层设计:操作信息+业务实体信息
+ * entity存储这个业务对象的具体数据内容,比如任务标题、任务备注、完成状态、gid
+ */
// entity_delta
JSONObject entity = new JSONObject();
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
@@ -77,6 +89,7 @@ public class Task extends Node {
if (getNotes() != null) {
entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes());
}
+
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
// parent_id
@@ -95,7 +108,10 @@ public class Task extends Node {
}
} catch (JSONException e) {
+ //toString输出异常本身的类型和描述
Log.e(TAG, e.toString());
+
+ //还原异常的发生现场,通过栈进行追踪
e.printStackTrace();
throw new ActionFailureException("fail to generate task-create jsonobject");
}
@@ -103,6 +119,11 @@ public class Task extends Node {
return js;
}
+ /**生成“更新任务”的JSON指令
+ *
+ * @param actionId
+ * @return 一个JSON对象实例 包括“更新”信息+业务信息
+ */
public JSONObject getUpdateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -121,7 +142,7 @@ public class Task extends Node {
JSONObject entity = new JSONObject();
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());
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
@@ -135,7 +156,12 @@ public class Task extends Node {
return js;
}
+ /**
+ * 执行具体操作,根据远端的JSON设置本地的内容
+ * @param js 远端的JSON实例
+ */
public void setContentByRemoteJSON(JSONObject js) {
+
if (js != null) {
try {
// id
@@ -175,13 +201,23 @@ public class Task extends Node {
}
}
+ /**
+ * 将小米便签本地存储的JSON格式数据解析并映射为Task对象的核心属性,
+ * 为本地便签数据同步到云端提供数据适配和内容提取能力。
+ * @param js
+ */
public void setContentByLocalJSON(JSONObject js) {
+ //若是本地JSON不含便签元信息+内容数据,输出错误日志
if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)
|| !js.has(GTaskStringUtils.META_HEAD_DATA)) {
Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
}
try {
+ /**提取同步所需的基础数据
+ * note:小米便签存储本地的便签元数据,如便签类型、创建时间、同步状态等
+ * dataArray:便签内容数组,可能包括文本、图片、附件等多种数据类型
+ */
JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
@@ -204,6 +240,7 @@ public class Task extends Node {
}
}
+ //返回完整 JSON,供本地数据库保存或上传云端
public JSONObject getLocalJSONFromContent() {
String name = getName();
try {
@@ -247,6 +284,7 @@ public class Task extends Node {
}
}
+ //将小米便签的MetaData元数据对象中的JSON格式解析为mMetaInfo
public void setMetaInfo(MetaData metaData) {
if (metaData != null && metaData.getNotes() != null) {
try {
@@ -258,6 +296,11 @@ public class Task extends Node {
}
}
+ /**
+ * 对比本地数据库中的便签数据(cursor)和当前task对象中缓存的云端元数据信息(mMetaInfo),
+ * 从数据、修改状态、GID等多维度进行比较校验,
+ * 最终判断当前标签需要执行的同步操作类型,比如无操作、更新本地、更新远端等
+ */
public int getSyncAction(Cursor c) {
try {
JSONObject noteInfo = null;
@@ -281,6 +324,7 @@ public class Task extends Node {
return SYNC_ACTION_UPDATE_LOCAL;
}
+ //本地无修改
if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
// there is no local update
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
@@ -290,12 +334,18 @@ public class Task extends Node {
// apply remote to local
return SYNC_ACTION_UPDATE_LOCAL;
}
- } else {
+ } else { //本地有修改
// validate gtask id
if (!c.getString(SqlNote.GTASK_ID_COLUMN).equals(getGid())) {
Log.e(TAG, "gtask id doesn't match");
return SYNC_ACTION_ERROR;
}
+
+ /**SqlNote.SYNC_ID_COLUMN是本地数据库中SqlNote表的一个字段名
+ * 存储本地记录的最后一次与云端同步的时间戳。
+ * 字段名带ID是命名习惯,实际存储的是时间戳 / 同步版本号,而非普通 ID)。
+ * getLastModified()返回远端任务的最后修改时间戳
+ */
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
// local modification only
return SYNC_ACTION_UPDATE_REMOTE;
@@ -311,6 +361,7 @@ public class Task extends Node {
return SYNC_ACTION_ERROR;
}
+ //空任务、空备注、无元数据 → 不值得存/上传,直接跳过
public boolean isWorthSaving() {
return mMetaInfo != null || (getName() != null && getName().trim().length() > 0)
|| (getNotes() != null && getNotes().trim().length() > 0);
diff --git a/src/notes/gtask/data/TaskList.java b/src/notes/gtask/data/TaskList.java
index 4ea21c5..1726969 100644
--- a/src/notes/gtask/data/TaskList.java
+++ b/src/notes/gtask/data/TaskList.java
@@ -33,9 +33,9 @@ import java.util.ArrayList;
public class TaskList extends Node {
private static final String TAG = TaskList.class.getSimpleName();
- private int mIndex;
+ private int mIndex; //列表索引,找到特定的task
- private ArrayList mChildren;
+ private ArrayList mChildren; //task列表
public TaskList() {
super();
@@ -43,6 +43,7 @@ public class TaskList extends Node {
mIndex = 1;
}
+ //生成TaskList“创建任务”的JSON
public JSONObject getCreateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -74,18 +75,20 @@ public class TaskList extends Node {
return js;
}
+ //“更新操作”的JSON
public JSONObject getUpdateAction(int actionId) {
JSONObject js = new JSONObject();
try {
// action_type
+ //设置操作类型,明确告诉远端此次操作为“更新”
js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
- // action_id
+ // action_id 操作ID(追踪操作结果)
js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
- // id
+ // id(要更新的任务/任务列表GID)
js.put(GTaskStringUtils.GTASK_JSON_ID, getGid());
// entity_delta
@@ -106,7 +109,7 @@ public class TaskList extends Node {
public void setContentByRemoteJSON(JSONObject js) {
if (js != null) {
try {
- // id
+ // id(本地和远端ID一致)
if (js.has(GTaskStringUtils.GTASK_JSON_ID)) {
setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
}
@@ -130,6 +133,7 @@ public class TaskList extends Node {
}
public void setContentByLocalJSON(JSONObject js) {
+ //本地JSON为空或者是否包含核心字段META_HEAD_NOTE
if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)) {
Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
}
@@ -137,6 +141,7 @@ public class TaskList extends Node {
try {
JSONObject folder = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
+ //普通文件夹和系统文件夹
if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {
String name = folder.getString(NoteColumns.SNIPPET);
setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + name);
@@ -157,6 +162,10 @@ public class TaskList extends Node {
}
}
+ /**
+ * MIUI_FOLDER_PREFFIX 在远端区分小米便签同步的文件夹和其他应用创建的文件夹,避免命名冲突
+ * @return 本地JSON
+ */
public JSONObject getLocalJSONFromContent() {
try {
JSONObject js = new JSONObject();
@@ -164,6 +173,7 @@ public class TaskList extends Node {
String folderName = getName();
if (getName().startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX))
+ //从云端文件夹名称中去掉小米前缀,还原本地文件夹的原始名称
folderName = folderName.substring(GTaskStringUtils.MIUI_FOLDER_PREFFIX.length(),
folderName.length());
folder.put(NoteColumns.SNIPPET, folderName);
@@ -183,10 +193,11 @@ public class TaskList extends Node {
}
}
+ //使用游标判断 本地和远端状态,返回同步操作类型号
public int getSyncAction(Cursor c) {
try {
if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
- // there is no local update
+ // there is no local update 本地无更新
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
// no update both side
return SYNC_ACTION_NONE;
@@ -194,12 +205,14 @@ public class TaskList extends Node {
// apply remote to local
return SYNC_ACTION_UPDATE_LOCAL;
}
- } else {
+ } else { //本地有更新,检验本地和远端ID是否一致,再决定最终的同步策略
// validate gtask id
if (!c.getString(SqlNote.GTASK_ID_COLUMN).equals(getGid())) {
Log.e(TAG, "gtask id doesn't match");
return SYNC_ACTION_ERROR;
}
+
+ //在本地和远端ID一致前提下,进一步判断云端数据是否有更新
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
// local modification only
return SYNC_ACTION_UPDATE_REMOTE;
@@ -220,6 +233,7 @@ public class TaskList extends Node {
return mChildren.size();
}
+ //添加子任务
public boolean addChildTask(Task task) {
boolean ret = false;
if (task != null && !mChildren.contains(task)) {
@@ -234,6 +248,7 @@ public class TaskList extends Node {
return ret;
}
+ //指定位置插入子任务
public boolean addChildTask(Task task, int index) {
if (index < 0 || index > mChildren.size()) {
Log.e(TAG, "add child task: invalid index");
@@ -241,14 +256,20 @@ public class TaskList extends Node {
}
int pos = mChildren.indexOf(task);
+
+ //pos==-1说明task不在mChildren里
if (task != null && pos == -1) {
mChildren.add(index, task);
- // update the task list
+ // update the task list更新任务列表索引
Task preTask = null;
Task afterTask = null;
+
+ //如果插入位置不在第一个,前任务为index-1的位置
if (index != 0)
preTask = mChildren.get(index - 1);
+
+ //如果插入位置不在最后一个,后继任务为index+1的位置
if (index != mChildren.size() - 1)
afterTask = mChildren.get(index + 1);
@@ -260,9 +281,12 @@ public class TaskList extends Node {
return true;
}
+ //移除子任务
public boolean removeChildTask(Task task) {
boolean ret = false;
int index = mChildren.indexOf(task);
+
+ //index!=-1说明task在mChildren里,移除操作有效
if (index != -1) {
ret = mChildren.remove(task);
@@ -276,11 +300,13 @@ public class TaskList extends Node {
mChildren.get(index).setPriorSibling(
index == 0 ? null : mChildren.get(index - 1));
}
+ //当移除最后一个任务时,index==mChildren.size(),没有后续任务,无需更新
}
}
return ret;
}
+ //将指定task从当前位置移到mChildren列表指定的index位置
public boolean moveChildTask(Task task, int index) {
if (index < 0 || index >= mChildren.size()) {
@@ -294,11 +320,20 @@ public class TaskList extends Node {
return false;
}
+ //当前已经在指定位置,不用移动
if (pos == index)
return true;
return (removeChildTask(task) && addChildTask(task, index));
+
+ //这里先判断当前不在指定位置,是不是更好?至少更容易一下子看懂
+ /**
+ * if (pos!=index)
+ * return (removeChildTask(task) && addChildTask(task,index));
+ * else return true;
+ */
}
+ //给定云端gid快速查找子任务
public Task findChildTaskByGid(String gid) {
for (int i = 0; i < mChildren.size(); i++) {
Task t = mChildren.get(i);
@@ -309,10 +344,12 @@ public class TaskList extends Node {
return null;
}
+ //返回给定子任务序号
public int getChildTaskIndex(Task task) {
return mChildren.indexOf(task);
}
+ //根据列表序号返回子任务
public Task getChildTaskByIndex(int index) {
if (index < 0 || index >= mChildren.size()) {
Log.e(TAG, "getTaskByIndex: invalid index");
@@ -321,12 +358,24 @@ public class TaskList extends Node {
return mChildren.get(index);
}
- public Task getChilTaskByGid(String gid) {
+ /**根据云端gid返回子任务
+ *这个似乎和前面的findChildTaskByGid(String gid)是一样的?
+ */
+ public Task getChildTaskByGid(String gid) {
for (Task task : mChildren) {
if (task.getGid().equals(gid))
return task;
}
return null;
+ /*
+ for (int i = 0; i < mChildren.size(); i++) {
+ Task t = mChildren.get(i);
+ if (t.getGid().equals(gid)) {
+ return t;
+ }
+ }
+ return null;
+ */
}
public ArrayList getChildTaskList() {
diff --git a/src/notes/gtask/exception/ActionFailureException.java b/src/notes/gtask/exception/ActionFailureException.java
index 15504be..b8b51f1 100644
--- a/src/notes/gtask/exception/ActionFailureException.java
+++ b/src/notes/gtask/exception/ActionFailureException.java
@@ -16,6 +16,11 @@
package net.micode.notes.gtask.exception;
+/**运行异常类
+ * 继承自RuntimeException类,
+ * 专门标识“某个操作执行失败”的异常场景,
+ * 比如 GTask 同步失败、数据库操作失败、网络请求失败等
+ */
public class ActionFailureException extends RuntimeException {
private static final long serialVersionUID = 4425249765923293627L;
@@ -23,10 +28,15 @@ public class ActionFailureException extends RuntimeException {
super();
}
+ /**
+ * 调用父类的RuntimeException(String)构造方法 - super函数
+ * @param paramString 错误描述字符串
+ */
public ActionFailureException(String paramString) {
super(paramString);
}
+ //错误信息+异常原因
public ActionFailureException(String paramString, Throwable paramThrowable) {
super(paramString, paramThrowable);
}
diff --git a/src/notes/gtask/exception/NetworkFailureException.java b/src/notes/gtask/exception/NetworkFailureException.java
index b08cfb1..2a1e178 100644
--- a/src/notes/gtask/exception/NetworkFailureException.java
+++ b/src/notes/gtask/exception/NetworkFailureException.java
@@ -16,6 +16,11 @@
package net.micode.notes.gtask.exception;
+/**受检异常类
+ * 继承自Exception类
+ * 专门标识 “网络操作失败” 的异常场景,
+ * 比如 GTask 同步时的网络连接超时、请求失败、服务器无响应、网络断开等。
+ */
public class NetworkFailureException extends Exception {
private static final long serialVersionUID = 2107610287180234136L;
@@ -27,6 +32,7 @@ public class NetworkFailureException extends Exception {
super(paramString);
}
+ //自定义错误信息+底层的根异常
public NetworkFailureException(String paramString, Throwable paramThrowable) {
super(paramString, paramThrowable);
}
diff --git a/src/notes/gtask/remote/GTaskASyncTask.java b/src/notes/gtask/remote/GTaskASyncTask.java
index b3b61e7..5a4ace7 100644
--- a/src/notes/gtask/remote/GTaskASyncTask.java
+++ b/src/notes/gtask/remote/GTaskASyncTask.java
@@ -28,77 +28,137 @@ import net.micode.notes.R;
import net.micode.notes.ui.NotesListActivity;
import net.micode.notes.ui.NotesPreferenceActivity;
-
+/**
+ *异步任务类,继承AsyncTask,
+ * doInBackground(后台执行)→ onProgressUpdate(进度更新)→ onPostExecute(结果处理)
+ * 在后台执行GTask的同步逻辑,通过GTaskManager实现登录、拉取、提交等操作,
+ * 实时通过状态栏通知向用户展示同步进度(登录中、同步中),
+ * 同步完成后,根据结果(成功 / 失败 / 取消)显示对应通知,并通过回调接口通知外层组件;
+ * 支持取消同步操作,以及同步状态的广播通知。
+ */
public class GTaskASyncTask extends AsyncTask {
private static int GTASK_SYNC_NOTIFICATION_ID = 5234235;
+ //通知Activity等外层同步已结束,是接口
public interface OnCompleteListener {
void onComplete();
}
- private Context mContext;
+ private Context mContext; //上下文,用于获取系统服务、资源字符串、启动Activity等
- private NotificationManager mNotifiManager;
+ private NotificationManager mNotifiManager; //用于发送和管理状态栏通知
- private GTaskManager mTaskManager;
+ private GTaskManager mTaskManager; //真正执行同步核心逻辑(登录、拉取、对比、提交等)
- private OnCompleteListener mOnCompleteListener;
+ private OnCompleteListener mOnCompleteListener; //通知外层 Activity/Service 同步结束
+ //构造方法:初始化上下文和回调监听器,获取通知管理器和GTaskManager实例
public GTaskASyncTask(Context context, OnCompleteListener listener) {
mContext = context;
mOnCompleteListener = listener;
mNotifiManager = (NotificationManager) mContext
.getSystemService(Context.NOTIFICATION_SERVICE);
+ //获取GTaskManager单例实例 (负责实际同步逻辑)
mTaskManager = GTaskManager.getInstance();
}
+ //终止同步的方法
public void cancelSync() {
mTaskManager.cancelSync();
}
+ //反馈给用户当前进度(这里或许应该是Progress?)
public void publishProgess(String message) {
publishProgress(new String[] {
message
});
}
+// private void showNotification(int tickerId, String content) {
+// Notification notification = new Notification(R.drawable.notification, mContext
+// .getString(tickerId), System.currentTimeMillis());
+// notification.defaults = Notification.DEFAULT_LIGHTS;
+// notification.flags = Notification.FLAG_AUTO_CANCEL;
+// PendingIntent pendingIntent;
+// if (tickerId != R.string.ticker_success) {
+// pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+// NotesPreferenceActivity.class), 0);
+//
+// } else {
+// pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+// NotesListActivity.class), 0);
+// }
+// notification.setLatestEventInfo(mContext, mContext.getString(R.string.app_name), content,
+// pendingIntent);
+// mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
+// }
+
+ /**
+ * 显示状态栏通知的核心方法:根据同步状态显示不同内容和跳转意图
+ * @param tickerId 通知类型
+ * @param content
+ */
private void showNotification(int tickerId, String content) {
- Notification notification = new Notification(R.drawable.notification, mContext
- .getString(tickerId), System.currentTimeMillis());
- notification.defaults = Notification.DEFAULT_LIGHTS;
- notification.flags = Notification.FLAG_AUTO_CANCEL;
+ //延迟意图:点击通知时触发的页面跳转
PendingIntent pendingIntent;
+
+ //同步不成功,跳转到偏好设置页面
if (tickerId != R.string.ticker_success) {
pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
- NotesPreferenceActivity.class), 0);
-
- } else {
+ NotesPreferenceActivity.class), PendingIntent.FLAG_IMMUTABLE);
+ } else { //同步成功,跳转到笔记列表页
pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
- NotesListActivity.class), 0);
+ NotesListActivity.class), PendingIntent.FLAG_IMMUTABLE);
}
- notification.setLatestEventInfo(mContext, mContext.getString(R.string.app_name), content,
- pendingIntent);
+
+ //设置通知属性
+ Notification.Builder builder = new Notification.Builder(mContext)
+ .setAutoCancel(true)
+ .setContentTitle(mContext.getString(R.string.app_name)) //通知标题设置
+ .setContentText(content) //通知内容设置
+ .setContentIntent(pendingIntent) //点击通知时的跳转意图
+ .setWhen(System.currentTimeMillis()) //通知时间
+ .setOngoing(true); //持续通知,不会被滑动清除,同步过程中保持显示
+ Notification notification=builder.getNotification();
+
+ //通过通知管理器显示通知(使用固定ID,确保后续通知能覆盖之前的)
mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
}
+ /**
+ * 后台执行方法:在子线程中执行同步核心逻辑
+ * 调用GTaskManager的sync方法执行同步,传入上下文和当前任务实例(用于更新进度)
+ * @param unused
+ * @return 同步结果状态码,如成功、网络错误等
+ */
@Override
protected Integer doInBackground(Void... unused) {
+ //发布登录进度:显示"正在登录[账号]"的提示(账号从偏好设置中获取)
publishProgess(mContext.getString(R.string.sync_progress_login, NotesPreferenceActivity
.getSyncAccountName(mContext)));
return mTaskManager.sync(mContext, this);
}
+ /**
+ * 进度更新方法:在UI线程执行,接收后台发布的进度并更新通知
+ * @param progress
+ */
@Override
protected void onProgressUpdate(String... progress) {
+ // 显示"同步中"的通知,内容为后台传来的进度信息
showNotification(R.string.ticker_syncing, progress[0]);
+
+ // 若当前上下文是GTaskSyncService(同步服务),则发送广播告知进度
if (mContext instanceof GTaskSyncService) {
((GTaskSyncService) mContext).sendBroadcast(progress[0]);
}
}
+ // 任务完成方法:处理同步结果
@Override
protected void onPostExecute(Integer result) {
+ //“同步成功”,更新偏好设置中的最后同步时间
if (result == GTaskManager.STATE_SUCCESS) {
showNotification(R.string.ticker_success, mContext.getString(
R.string.success_sync_account, mTaskManager.getSyncAccount()));
diff --git a/src/notes/gtask/remote/GTaskClient.java b/src/notes/gtask/remote/GTaskClient.java
index c67dfdf..13cea91 100644
--- a/src/notes/gtask/remote/GTaskClient.java
+++ b/src/notes/gtask/remote/GTaskClient.java
@@ -60,35 +60,40 @@ import java.util.zip.GZIPInputStream;
import java.util.zip.Inflater;
import java.util.zip.InflaterInputStream;
-
+/**
+ * Google任务客户端,
+ * 负责与Google任务服务的网络通信(HTTP请求/响应处理)
+ */
public class GTaskClient {
private static final String TAG = GTaskClient.class.getSimpleName();
+ // 获取任务列表的GET请求URL
private static final String GTASK_URL = "https://mail.google.com/tasks/";
+ // 提交操作的POST请求URL
private static final String GTASK_GET_URL = "https://mail.google.com/tasks/ig";
private static final String GTASK_POST_URL = "https://mail.google.com/tasks/r/ig";
private static GTaskClient mInstance = null;
- private DefaultHttpClient mHttpClient;
+ private DefaultHttpClient mHttpClient; // HTTP客户端:用于发送HTTP请求
- private String mGetUrl;
+ private String mGetUrl; // 实际使用的GET请求URL(可能因域名变化)
- private String mPostUrl;
+ private String mPostUrl; // 实际使用的POST请求URL(可能因域名变化)
- private long mClientVersion;
+ private long mClientVersion; // 客户端版本:从Google服务获取,用于请求验证
- private boolean mLoggedin;
+ private boolean mLoggedin; // 登录状态标识
private long mLastLoginTime;
private int mActionId;
- private Account mAccount;
+ private Account mAccount; // 当前登录的Google账户
- private JSONArray mUpdateArray;
+ private JSONArray mUpdateArray; // 更新队列:批量存储待提交的更新操作(减少网络请求次数)
private GTaskClient() {
mHttpClient = null;
@@ -102,6 +107,7 @@ public class GTaskClient {
mUpdateArray = null;
}
+ //保证全局一个客户端实例
public static synchronized GTaskClient getInstance() {
if (mInstance == null) {
mInstance = new GTaskClient();
@@ -109,27 +115,33 @@ public class GTaskClient {
return mInstance;
}
+ // 登录Google任务:处理账户认证和会话建立
public boolean login(Activity activity) {
// we suppose that the cookie would expire after 5 minutes
// then we need to re-login
+ // 登录过期检查:假设Cookie 5分钟过期,过期则需要重新登录
final long interval = 1000 * 60 * 5;
if (mLastLoginTime + interval < System.currentTimeMillis()) {
mLoggedin = false;
}
// need to re-login after account switch
+ // 账户切换检查:若当前账户与设置中的账户不一致,需要重新登录
if (mLoggedin
&& !TextUtils.equals(getSyncAccount().name, NotesPreferenceActivity
.getSyncAccountName(activity))) {
mLoggedin = false;
}
+ // 已登录且有效,直接返回成功
if (mLoggedin) {
Log.d(TAG, "already logged in");
return true;
}
+ // 执行登录流程
mLastLoginTime = System.currentTimeMillis();
+ // 获取Google账户的认证token
String authToken = loginGoogleAccount(activity, false);
if (authToken == null) {
Log.e(TAG, "login google account failed");
@@ -137,21 +149,24 @@ public class GTaskClient {
}
// login with custom domain if necessary
+ // 处理自定义域名账户(非gmail/googlemail)
if (!(mAccount.name.toLowerCase().endsWith("gmail.com") || mAccount.name.toLowerCase()
.endsWith("googlemail.com"))) {
StringBuilder url = new StringBuilder(GTASK_URL).append("a/");
int index = mAccount.name.indexOf('@') + 1;
- String suffix = mAccount.name.substring(index);
+ String suffix = mAccount.name.substring(index); // 提取域名后缀
url.append(suffix + "/");
mGetUrl = url.toString() + "ig";
mPostUrl = url.toString() + "r/ig";
+ // 尝试用自定义URL登录
if (tryToLoginGtask(activity, authToken)) {
mLoggedin = true;
}
}
// try to login with google official url
+ // 若自定义域名登录失败,使用官方URL重试
if (!mLoggedin) {
mGetUrl = GTASK_GET_URL;
mPostUrl = GTASK_POST_URL;
@@ -164,16 +179,19 @@ public class GTaskClient {
return true;
}
+ // 登录Google账户:获取认证token(用于后续Google任务登录)
private String loginGoogleAccount(Activity activity, boolean invalidateToken) {
String authToken;
- AccountManager accountManager = AccountManager.get(activity);
- Account[] accounts = accountManager.getAccountsByType("com.google");
+ AccountManager accountManager = AccountManager.get(activity); // 获取账户管理器
+ Account[] accounts = accountManager.getAccountsByType("com.google"); // 获取所有Google账户
+ // 无可用Google账户
if (accounts.length == 0) {
Log.e(TAG, "there is no available google account");
return null;
}
+ // 获取设置中配置的同步账户名
String accountName = NotesPreferenceActivity.getSyncAccountName(activity);
Account account = null;
for (Account a : accounts) {
@@ -190,12 +208,13 @@ public class GTaskClient {
}
// get the token now
+ // 获取账户的auth token
AccountManagerFuture accountManagerFuture = accountManager.getAuthToken(account,
"goanna_mobile", null, activity, null, null);
try {
- Bundle authTokenBundle = accountManagerFuture.getResult();
+ Bundle authTokenBundle = accountManagerFuture.getResult(); // 获取token结果
authToken = authTokenBundle.getString(AccountManager.KEY_AUTHTOKEN);
- if (invalidateToken) {
+ if (invalidateToken) { // 若需要失效旧token,重新获取
accountManager.invalidateAuthToken("com.google", authToken);
loginGoogleAccount(activity, false);
}
@@ -207,16 +226,19 @@ public class GTaskClient {
return authToken;
}
+ // 尝试登录Google任务:使用获取的auth token建立会话
private boolean tryToLoginGtask(Activity activity, String authToken) {
if (!loginGtask(authToken)) {
// maybe the auth token is out of date, now let's invalidate the
// token and try again
+ // 可能是token过期,失效旧token并重新获取
authToken = loginGoogleAccount(activity, true);
if (authToken == null) {
Log.e(TAG, "login google account failed");
return false;
}
+ // 再次尝试登录
if (!loginGtask(authToken)) {
Log.e(TAG, "login gtask failed");
return false;
@@ -225,25 +247,29 @@ public class GTaskClient {
return true;
}
+ // 登录Google任务核心逻辑:使用auth token获取会话Cookie和客户端版本
private boolean loginGtask(String authToken) {
+ // 设置HTTP连接超时(10秒)和读取超时(15秒)
int timeoutConnection = 10000;
int timeoutSocket = 15000;
HttpParams httpParameters = new BasicHttpParams();
HttpConnectionParams.setConnectionTimeout(httpParameters, timeoutConnection);
HttpConnectionParams.setSoTimeout(httpParameters, timeoutSocket);
- mHttpClient = new DefaultHttpClient(httpParameters);
+ mHttpClient = new DefaultHttpClient(httpParameters); // 初始化HTTP客户端
BasicCookieStore localBasicCookieStore = new BasicCookieStore();
- mHttpClient.setCookieStore(localBasicCookieStore);
+ mHttpClient.setCookieStore(localBasicCookieStore); // 设置Cookie存储
HttpProtocolParams.setUseExpectContinue(mHttpClient.getParams(), false);
// login gtask
+ // 执行登录请求
try {
- String loginUrl = mGetUrl + "?auth=" + authToken;
- HttpGet httpGet = new HttpGet(loginUrl);
+ String loginUrl = mGetUrl + "?auth=" + authToken; // 构建带token的登录URL
+ HttpGet httpGet = new HttpGet(loginUrl);// 创建GET请求
HttpResponse response = null;
- response = mHttpClient.execute(httpGet);
+ response = mHttpClient.execute(httpGet); // 发送请求
// get the cookie now
+ // 检查是否获取到认证Cookie(含"GTL"标识)
List cookies = mHttpClient.getCookieStore().getCookies();
boolean hasAuthCookie = false;
for (Cookie cookie : cookies) {
@@ -256,17 +282,18 @@ public class GTaskClient {
}
// get the client version
+ // 解析响应获取客户端版本(用于后续请求)
String resString = getResponseContent(response.getEntity());
- String jsBegin = "_setup(";
- String jsEnd = ")}";
+ String jsBegin = "_setup("; // 响应中包含客户端版本的JS前缀
+ String jsEnd = ")}"; // 后缀
int begin = resString.indexOf(jsBegin);
int end = resString.lastIndexOf(jsEnd);
String jsString = null;
if (begin != -1 && end != -1 && begin < end) {
- jsString = resString.substring(begin + jsBegin.length(), end);
+ jsString = resString.substring(begin + jsBegin.length(), end);// 提取JS内容
}
JSONObject js = new JSONObject(jsString);
- mClientVersion = js.getLong("v");
+ mClientVersion = js.getLong("v"); // 获取客户端版本
} catch (JSONException e) {
Log.e(TAG, e.toString());
e.printStackTrace();
@@ -280,25 +307,29 @@ public class GTaskClient {
return true;
}
+ // 获取操作ID:每次调用递增,用于标识请求的唯一性
private int getActionId() {
return mActionId++;
}
+ // 创建POST请求:设置请求头(Content-Type等)
private HttpPost createHttpPost() {
HttpPost httpPost = new HttpPost(mPostUrl);
httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
- httpPost.setHeader("AT", "1");
+ httpPost.setHeader("AT", "1"); // 自定义头,可能用于标识客户端类型
return httpPost;
}
+ // 读取响应内容:处理压缩(gzip/deflate)并转换为字符串
private String getResponseContent(HttpEntity entity) throws IOException {
String contentEncoding = null;
if (entity.getContentEncoding() != null) {
- contentEncoding = entity.getContentEncoding().getValue();
+ contentEncoding = entity.getContentEncoding().getValue(); // 获取编码方式
Log.d(TAG, "encoding: " + contentEncoding);
}
InputStream input = entity.getContent();
+ // 根据编码方式解压
if (contentEncoding != null && contentEncoding.equalsIgnoreCase("gzip")) {
input = new GZIPInputStream(entity.getContent());
} else if (contentEncoding != null && contentEncoding.equalsIgnoreCase("deflate")) {
@@ -307,6 +338,7 @@ public class GTaskClient {
}
try {
+ // 读取输入流并转换为字符串
InputStreamReader isr = new InputStreamReader(input);
BufferedReader br = new BufferedReader(isr);
StringBuilder sb = new StringBuilder();
@@ -323,33 +355,37 @@ public class GTaskClient {
}
}
+ // 发送POST请求:封装JSON请求并处理响应
private JSONObject postRequest(JSONObject js) throws NetworkFailureException {
if (!mLoggedin) {
Log.e(TAG, "please login first");
throw new ActionFailureException("not logged in");
}
- HttpPost httpPost = createHttpPost();
+ HttpPost httpPost = createHttpPost(); // 创建POST请求
try {
+ // 构建请求参数(将JSON作为"r"参数的值)
LinkedList list = new LinkedList();
list.add(new BasicNameValuePair("r", js.toString()));
+ // 编码为表单格式
UrlEncodedFormEntity entity = new UrlEncodedFormEntity(list, "UTF-8");
httpPost.setEntity(entity);
// execute the post
+ // 执行请求并获取响应
HttpResponse response = mHttpClient.execute(httpPost);
String jsString = getResponseContent(response.getEntity());
return new JSONObject(jsString);
- } catch (ClientProtocolException e) {
+ } catch (ClientProtocolException e) { // HTTP协议异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new NetworkFailureException("postRequest failed");
- } catch (IOException e) {
+ } catch (IOException e) { // IO异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new NetworkFailureException("postRequest failed");
- } catch (JSONException e) {
+ } catch (JSONException e) { // JSON解析异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("unable to convert response content to jsonobject");
@@ -360,21 +396,27 @@ public class GTaskClient {
}
}
+ // 创建远程任务:向Google任务服务发送创建任务请求
public void createTask(Task task) throws NetworkFailureException {
+ // 先提交之前的更新队列(避免冲突)
commitUpdate();
try {
JSONObject jsPost = new JSONObject();
JSONArray actionList = new JSONArray();
// action_list
+ // 添加创建任务的操作
actionList.put(task.getCreateAction(getActionId()));
jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
// client_version
+ // 添加客户端版本(用于服务端验证)
jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
// post
+ // 发送请求并获取响应
JSONObject jsResponse = postRequest(jsPost);
+ // 从响应中获取新创建任务的GID并设置到任务对象
JSONObject jsResult = (JSONObject) jsResponse.getJSONArray(
GTaskStringUtils.GTASK_JSON_RESULTS).get(0);
task.setGid(jsResult.getString(GTaskStringUtils.GTASK_JSON_NEW_ID));
@@ -386,21 +428,27 @@ public class GTaskClient {
}
}
+ // 创建远程任务列表:向Google任务服务发送创建列表请求
public void createTaskList(TaskList tasklist) throws NetworkFailureException {
+ // 先提交之前的更新队列
commitUpdate();
try {
JSONObject jsPost = new JSONObject();
JSONArray actionList = new JSONArray();
// action_list
+ // 添加创建列表的操作
actionList.put(tasklist.getCreateAction(getActionId()));
jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
// client version
+ // 添加客户端版本
jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
// post
+ // 发送请求并获取响应
JSONObject jsResponse = postRequest(jsPost);
+ // 从响应中获取新创建列表的GID并设置
JSONObject jsResult = (JSONObject) jsResponse.getJSONArray(
GTaskStringUtils.GTASK_JSON_RESULTS).get(0);
tasklist.setGid(jsResult.getString(GTaskStringUtils.GTASK_JSON_NEW_ID));
@@ -412,19 +460,22 @@ public class GTaskClient {
}
}
+ // 提交更新队列:将缓存的更新操作批量发送到服务端
public void commitUpdate() throws NetworkFailureException {
if (mUpdateArray != null) {
try {
JSONObject jsPost = new JSONObject();
// action_list
+ // 设置更新操作列表
jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, mUpdateArray);
// client_version
+ // 设置客户端版本
jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
postRequest(jsPost);
- mUpdateArray = null;
+ mUpdateArray = null; // 清空队列
} catch (JSONException e) {
Log.e(TAG, e.toString());
e.printStackTrace();
@@ -433,10 +484,12 @@ public class GTaskClient {
}
}
+ // 添加更新节点到队列:将节点的更新操作加入缓存队列(批量提交)
public void addUpdateNode(Node node) throws NetworkFailureException {
if (node != null) {
// too many update items may result in an error
// set max to 10 items
+ // 限制队列最大长度为10(避免单次请求过大)
if (mUpdateArray != null && mUpdateArray.length() > 10) {
commitUpdate();
}
@@ -447,6 +500,7 @@ public class GTaskClient {
}
}
+ // 移动任务:将任务从原列表移动到新列表(或列表内调整位置)
public void moveTask(Task task, TaskList preParent, TaskList curParent)
throws NetworkFailureException {
commitUpdate();
@@ -456,17 +510,23 @@ public class GTaskClient {
JSONObject action = new JSONObject();
// action_list
+ // 设置操作类型为移动
action.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_MOVE);
action.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, getActionId());
action.put(GTaskStringUtils.GTASK_JSON_ID, task.getGid());
+
+ // 列表内移动且非首个任务:设置前序任务ID(调整位置)
if (preParent == curParent && task.getPriorSibling() != null) {
// put prioring_sibing_id only if moving within the tasklist and
// it is not the first one
action.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, task.getPriorSibling());
}
+ // 设置源列表和目标父节点
action.put(GTaskStringUtils.GTASK_JSON_SOURCE_LIST, preParent.getGid());
action.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT, curParent.getGid());
+
+ // 跨列表移动:设置目标列表
if (preParent != curParent) {
// put the dest_list only if moving between tasklists
action.put(GTaskStringUtils.GTASK_JSON_DEST_LIST, curParent.getGid());
@@ -486,6 +546,7 @@ public class GTaskClient {
}
}
+ // 删除远程节点:向服务端发送删除请求
public void deleteNode(Node node) throws NetworkFailureException {
commitUpdate();
try {
@@ -493,6 +554,7 @@ public class GTaskClient {
JSONArray actionList = new JSONArray();
// action_list
+ // 标记节点为已删除,并添加删除操作
node.setDeleted(true);
actionList.put(node.getUpdateAction(getActionId()));
jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
@@ -509,6 +571,7 @@ public class GTaskClient {
}
}
+ // 获取远程任务列表:从服务端获取所有任务列表
public JSONArray getTaskLists() throws NetworkFailureException {
if (!mLoggedin) {
Log.e(TAG, "please login first");
@@ -522,13 +585,13 @@ public class GTaskClient {
// get the task list
String resString = getResponseContent(response.getEntity());
- String jsBegin = "_setup(";
- String jsEnd = ")}";
+ String jsBegin = "_setup("; // 响应中任务列表的JS前缀
+ String jsEnd = ")}"; // 后缀
int begin = resString.indexOf(jsBegin);
int end = resString.lastIndexOf(jsEnd);
String jsString = null;
if (begin != -1 && end != -1 && begin < end) {
- jsString = resString.substring(begin + jsBegin.length(), end);
+ jsString = resString.substring(begin + jsBegin.length(), end); // 提取JS内容
}
JSONObject js = new JSONObject(jsString);
return js.getJSONObject("t").getJSONArray(GTaskStringUtils.GTASK_JSON_LISTS);
@@ -547,6 +610,7 @@ public class GTaskClient {
}
}
+ // 获取指定任务列表下的任务:从服务端获取某个列表的所有任务
public JSONArray getTaskList(String listGid) throws NetworkFailureException {
commitUpdate();
try {
@@ -559,13 +623,16 @@ public class GTaskClient {
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_GETALL);
action.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, getActionId());
action.put(GTaskStringUtils.GTASK_JSON_LIST_ID, listGid);
+ // 不获取已删除任务
action.put(GTaskStringUtils.GTASK_JSON_GET_DELETED, false);
actionList.put(action);
jsPost.put(GTaskStringUtils.GTASK_JSON_ACTION_LIST, actionList);
// client_version
+ // 客户端版本
jsPost.put(GTaskStringUtils.GTASK_JSON_CLIENT_VERSION, mClientVersion);
+ // 发送请求并返回任务数组
JSONObject jsResponse = postRequest(jsPost);
return jsResponse.getJSONArray(GTaskStringUtils.GTASK_JSON_TASKS);
} catch (JSONException e) {
@@ -575,10 +642,12 @@ public class GTaskClient {
}
}
+ // 获取当前同步账户:返回登录的Google账户
public Account getSyncAccount() {
return mAccount;
}
+ // 重置更新队列:清空待提交的更新操作
public void resetUpdateArray() {
mUpdateArray = null;
}
diff --git a/src/notes/gtask/remote/GTaskManager.java b/src/notes/gtask/remote/GTaskManager.java
index d2b4082..9bc0565 100644
--- a/src/notes/gtask/remote/GTaskManager.java
+++ b/src/notes/gtask/remote/GTaskManager.java
@@ -47,21 +47,24 @@ import java.util.HashSet;
import java.util.Iterator;
import java.util.Map;
-
+/**
+ * Google任务同步管理器
+ * 负责本地Note与Google任务的同步逻辑
+ */
public class GTaskManager {
private static final String TAG = GTaskManager.class.getSimpleName();
- public static final int STATE_SUCCESS = 0;
+ public static final int STATE_SUCCESS = 0; //同步成功状态
- public static final int STATE_NETWORK_ERROR = 1;
+ public static final int STATE_NETWORK_ERROR = 1; //网络错误
- public static final int STATE_INTERNAL_ERROR = 2;
+ public static final int STATE_INTERNAL_ERROR = 2; //内部错误
- public static final int STATE_SYNC_IN_PROGRESS = 3;
+ public static final int STATE_SYNC_IN_PROGRESS = 3; //同步中
- public static final int STATE_SYNC_CANCELLED = 4;
+ public static final int STATE_SYNC_CANCELLED = 4; //取消同步
- private static GTaskManager mInstance = null;
+ private static GTaskManager mInstance = null; //单例实例
private Activity mActivity;
@@ -69,24 +72,25 @@ public class GTaskManager {
private ContentResolver mContentResolver;
- private boolean mSyncing;
+ private boolean mSyncing; //同步状态标识:是否正在同步
- private boolean mCancelled;
+ private boolean mCancelled; //是否已取消
- private HashMap mGTaskListHashMap;
+ private HashMap mGTaskListHashMap; //远程任务列表(key:任务列表GID)
- private HashMap mGTaskHashMap;
+ private HashMap mGTaskHashMap; //所有远程节点(任务/列表,key:节点GID)
- private HashMap mMetaHashMap;
+ private HashMap mMetaHashMap; //元数据(key:关联的任务GID)
- private TaskList mMetaList;
+ private TaskList mMetaList; //元数据列表
- private HashSet mLocalDeleteIdMap;
+ private HashSet mLocalDeleteIdMap; //记录需要从远程删除的本地笔记ID
- private HashMap mGidToNid;
+ private HashMap mGidToNid; //远程GID到本地笔记ID的映射关系
- private HashMap mNidToGid;
+ private HashMap mNidToGid; //本地笔记ID到远程GID的映射关系
+ //初始化所有集合和状态变量(单例模式防止外部实例化)
private GTaskManager() {
mSyncing = false;
mCancelled = false;
@@ -99,6 +103,7 @@ public class GTaskManager {
mNidToGid = new HashMap();
}
+ // 单例获取方法:保证全局唯一实例
public static synchronized GTaskManager getInstance() {
if (mInstance == null) {
mInstance = new GTaskManager();
@@ -106,20 +111,26 @@ public class GTaskManager {
return mInstance;
}
+ // 设置Activity上下文:用于后续登录时获取认证token
public synchronized void setActivityContext(Activity activity) {
// used for getting authtoken
mActivity = activity;
}
+ //协调本地与远程数据同步,返回同步状态
public int sync(Context context, GTaskASyncTask asyncTask) {
+ // 检查是否正在同步,若正在同步则返回对应状态
if (mSyncing) {
Log.d(TAG, "Sync is in progress");
return STATE_SYNC_IN_PROGRESS;
}
+ // 初始化同步环境
mContext = context;
mContentResolver = mContext.getContentResolver();
mSyncing = true;
mCancelled = false;
+
+ //清空所有存储集合(避免上次同步残留数据)
mGTaskListHashMap.clear();
mGTaskHashMap.clear();
mMetaHashMap.clear();
@@ -128,8 +139,9 @@ public class GTaskManager {
mNidToGid.clear();
try {
+ // 获取GTaskClient实例
GTaskClient client = GTaskClient.getInstance();
- client.resetUpdateArray();
+ client.resetUpdateArray(); //重置客户端的更新队列
// login google task
if (!mCancelled) {
@@ -139,55 +151,61 @@ public class GTaskManager {
}
// get the task list from google
+ // 从远程获取任务列表并初始化(更新同步进度)
asyncTask.publishProgess(mContext.getString(R.string.sync_progress_init_list));
initGTaskList();
- // do content sync work
+ // do content sync work(更新同步进度)
asyncTask.publishProgess(mContext.getString(R.string.sync_progress_syncing));
syncContent();
- } catch (NetworkFailureException e) {
+ } catch (NetworkFailureException e) { // 捕获网络异常
Log.e(TAG, e.toString());
return STATE_NETWORK_ERROR;
- } catch (ActionFailureException e) {
+ } catch (ActionFailureException e) { // 捕获操作失败异常
Log.e(TAG, e.toString());
return STATE_INTERNAL_ERROR;
- } catch (Exception e) {
+ } catch (Exception e) { // 返回内部错误状态
Log.e(TAG, e.toString());
e.printStackTrace();
return STATE_INTERNAL_ERROR;
- } finally {
+ } finally { // 无论成功失败,清理资源
mGTaskListHashMap.clear();
mGTaskHashMap.clear();
mMetaHashMap.clear();
mLocalDeleteIdMap.clear();
mGidToNid.clear();
mNidToGid.clear();
- mSyncing = false;
+ mSyncing = false; // 标记为同步结束
}
return mCancelled ? STATE_SYNC_CANCELLED : STATE_SUCCESS;
}
+ // 初始化远程任务列表:从Google服务器获取任务列表和元数据
private void initGTaskList() throws NetworkFailureException {
+ // 若同步已取消,直接返回
if (mCancelled)
return;
- GTaskClient client = GTaskClient.getInstance();
+ GTaskClient client = GTaskClient.getInstance(); // 获取网络客户端
try {
+ // 1. 获取所有远程任务列表(JSON数组)
JSONArray jsTaskLists = client.getTaskLists();
- // init meta list first
+ // init meta list first(因为元数据关联其他任务)
mMetaList = null;
for (int i = 0; i < jsTaskLists.length(); i++) {
JSONObject object = jsTaskLists.getJSONObject(i);
String gid = object.getString(GTaskStringUtils.GTASK_JSON_ID);
String name = object.getString(GTaskStringUtils.GTASK_JSON_NAME);
- if (name
- .equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_META)) {
+ // 检查是否为元数据列表(名称符合特定前缀+后缀)
+ if (name.equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_META)) {
mMetaList = new TaskList();
+
+ //用远程JSON初始化元数据列表
mMetaList.setContentByRemoteJSON(object);
- // load meta data
+ // load meta data(元数据本身以任务形式存储)
JSONArray jsMetas = client.getTaskList(gid);
for (int j = 0; j < jsMetas.length(); j++) {
object = (JSONObject) jsMetas.getJSONObject(j);
@@ -196,6 +214,7 @@ public class GTaskManager {
if (metaData.isWorthSaving()) {
mMetaList.addChildTask(metaData);
if (metaData.getGid() != null) {
+ // 存储元数据(key:关联的任务GID)
mMetaHashMap.put(metaData.getRelatedGid(), metaData);
}
}
@@ -204,26 +223,29 @@ public class GTaskManager {
}
// create meta list if not existed
+ // 3. 若元数据列表不存在,则创建一个
if (mMetaList == null) {
mMetaList = new TaskList();
mMetaList.setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX
- + GTaskStringUtils.FOLDER_META);
- GTaskClient.getInstance().createTaskList(mMetaList);
+ + GTaskStringUtils.FOLDER_META); // 设置名称
+ GTaskClient.getInstance().createTaskList(mMetaList); // 调用客户端创建列表
}
// init task list
+ // 4. 初始化普通任务列表(排除元数据列表)
for (int i = 0; i < jsTaskLists.length(); i++) {
JSONObject object = jsTaskLists.getJSONObject(i);
String gid = object.getString(GTaskStringUtils.GTASK_JSON_ID);
String name = object.getString(GTaskStringUtils.GTASK_JSON_NAME);
+ // 筛选符合条件的列表:以特定前缀开头,且不是元数据列表
if (name.startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX)
&& !name.equals(GTaskStringUtils.MIUI_FOLDER_PREFFIX
+ GTaskStringUtils.FOLDER_META)) {
TaskList tasklist = new TaskList();
- tasklist.setContentByRemoteJSON(object);
- mGTaskListHashMap.put(gid, tasklist);
- mGTaskHashMap.put(gid, tasklist);
+ tasklist.setContentByRemoteJSON(object); // 用远程JSON初始化列表
+ mGTaskListHashMap.put(gid, tasklist); // 存入任务列表集合
+ mGTaskHashMap.put(gid, tasklist); // 同时存入全局节点集合
// load tasks
JSONArray jsTasks = client.getTaskList(gid);
@@ -231,27 +253,28 @@ public class GTaskManager {
object = (JSONObject) jsTasks.getJSONObject(j);
gid = object.getString(GTaskStringUtils.GTASK_JSON_ID);
Task task = new Task();
- task.setContentByRemoteJSON(object);
+ task.setContentByRemoteJSON(object); // 用远程JSON初始化任务
if (task.isWorthSaving()) {
- task.setMetaInfo(mMetaHashMap.get(gid));
+ task.setMetaInfo(mMetaHashMap.get(gid)); // 关联元数据
tasklist.addChildTask(task);
- mGTaskHashMap.put(gid, task);
+ mGTaskHashMap.put(gid, task); // 存入全局节点集合
}
}
}
}
- } catch (JSONException e) {
+ } catch (JSONException e) { // 处理JSON解析异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("initGTaskList: handing JSONObject failed");
}
}
+ // 同步内容:协调本地与远程的任务/列表数据(核心同步逻辑)
private void syncContent() throws NetworkFailureException {
- int syncType;
- Cursor c = null;
- String gid;
- Node node;
+ int syncType; // 同步类型(新增/删除/更新等)
+ Cursor c = null; // 数据库查询游标
+ String gid; // 远程GID
+ Node node; // 远程节点
mLocalDeleteIdMap.clear();
@@ -260,20 +283,23 @@ public class GTaskManager {
}
// for local deleted note
+ // 1. 处理本地已删除的笔记(在回收站中的非系统类型笔记)
try {
+ // 查询条件:不是系统类型+父ID是回收站
c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE,
"(type<>? AND parent_id=?)", new String[] {
- String.valueOf(Notes.TYPE_SYSTEM), String.valueOf(Notes.ID_TRASH_FOLER)
+ String.valueOf(Notes.TYPE_SYSTEM), String.valueOf(Notes.ID_TRASH_FOLDER)
}, null);
if (c != null) {
while (c.moveToNext()) {
- gid = c.getString(SqlNote.GTASK_ID_COLUMN);
- node = mGTaskHashMap.get(gid);
- if (node != null) {
- mGTaskHashMap.remove(gid);
- doContentSync(Node.SYNC_ACTION_DEL_REMOTE, node, c);
+ gid = c.getString(SqlNote.GTASK_ID_COLUMN); // 获取笔记关联的远程GID
+ node = mGTaskHashMap.get(gid); // 从远程节点集合中查找对应节点
+ if (node != null) { // 若远程存在该节点,需要删除远程节点
+ mGTaskHashMap.remove(gid); // 从本地缓存移除
+ doContentSync(Node.SYNC_ACTION_DEL_REMOTE, node, c); // 执行远程删除
}
+ // 记录本地已删除的笔记ID(后续会从本地彻底删除)
mLocalDeleteIdMap.add(c.getLong(SqlNote.ID_COLUMN));
}
} else {
@@ -287,32 +313,43 @@ public class GTaskManager {
}
// sync folder first
+ // 2. 优先同步文件夹(任务列表)
syncFolder();
// for note existing in database
+ // 3. 处理本地已存在的普通笔记(非回收站中的笔记类型)
try {
+ // 查询条件:Note类型 + 父ID不是回收站
c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE,
"(type=? AND parent_id<>?)", new String[] {
- String.valueOf(Notes.TYPE_NOTE), String.valueOf(Notes.ID_TRASH_FOLER)
+ String.valueOf(Notes.TYPE_NOTE), String.valueOf(Notes.ID_TRASH_FOLDER)
}, NoteColumns.TYPE + " DESC");
if (c != null) {
while (c.moveToNext()) {
- gid = c.getString(SqlNote.GTASK_ID_COLUMN);
+ gid = c.getString(SqlNote.GTASK_ID_COLUMN); // 获取关联的远程GID
node = mGTaskHashMap.get(gid);
+
+ // 远程存在对应节点
if (node != null) {
- mGTaskHashMap.remove(gid);
+ mGTaskHashMap.remove(gid); // 从本地缓存移除
+
+ // 记录GID与本地ID的映射关系
mGidToNid.put(gid, c.getLong(SqlNote.ID_COLUMN));
mNidToGid.put(c.getLong(SqlNote.ID_COLUMN), gid);
- syncType = node.getSyncAction(c);
- } else {
+ syncType = node.getSyncAction(c); // 计算同步类型(根据本地与远程的修改时间等)
+ }
+
+ // 远程不存在对应节点
+ else {
if (c.getString(SqlNote.GTASK_ID_COLUMN).trim().length() == 0) {
- // local add
+ // local add 本地GID为空:本地新增,需要同步到远程
syncType = Node.SYNC_ACTION_ADD_REMOTE;
} else {
- // remote delete
+ // remote delete 本地有GID但远程无:远程已删除,需要删除本地
syncType = Node.SYNC_ACTION_DEL_LOCAL;
}
}
+ // 执行同步操作
doContentSync(syncType, node, c);
}
} else {
@@ -327,16 +364,20 @@ public class GTaskManager {
}
// go through remaining items
+ // 4. 处理远程存在但本地不存在的节点(需要同步到本地)
Iterator> iter = mGTaskHashMap.entrySet().iterator();
while (iter.hasNext()) {
Map.Entry entry = iter.next();
node = entry.getValue();
+
+ // 执行本地新增
doContentSync(Node.SYNC_ACTION_ADD_LOCAL, node, null);
}
// mCancelled can be set by another thread, so we neet to check one by
// one
// clear local delete table
+ // 5. 清理本地已删除的笔记(若未取消同步)
if (!mCancelled) {
if (!DataUtils.batchDeleteNotes(mContentResolver, mLocalDeleteIdMap)) {
throw new ActionFailureException("failed to batch-delete local deleted notes");
@@ -344,6 +385,7 @@ public class GTaskManager {
}
// refresh local sync id
+ // 6. 提交更新并刷新本地同步ID(若未取消)
if (!mCancelled) {
GTaskClient.getInstance().commitUpdate();
refreshLocalSyncId();
@@ -351,6 +393,7 @@ public class GTaskManager {
}
+ // 同步文件夹(任务列表):处理本地与远程的文件夹数据
private void syncFolder() throws NetworkFailureException {
Cursor c = null;
String gid;
@@ -362,22 +405,30 @@ public class GTaskManager {
}
// for root folder
+ // 1. 同步根文件夹
try {
+ // 查询根文件夹(ID固定为Notes.ID_ROOT_FOLDER)
c = mContentResolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI,
Notes.ID_ROOT_FOLDER), SqlNote.PROJECTION_NOTE, null, null, null);
if (c != null) {
c.moveToNext();
gid = c.getString(SqlNote.GTASK_ID_COLUMN);
node = mGTaskHashMap.get(gid);
+
+ // 远程存在对应节点
if (node != null) {
mGTaskHashMap.remove(gid);
+ // 记录映射关系
mGidToNid.put(gid, (long) Notes.ID_ROOT_FOLDER);
mNidToGid.put((long) Notes.ID_ROOT_FOLDER, gid);
// for system folder, only update remote name if necessary
+ // 系统文件夹只在名称不匹配时更新远程
if (!node.getName().equals(
GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_DEFAULT))
doContentSync(Node.SYNC_ACTION_UPDATE_REMOTE, node, c);
- } else {
+ }
+ // 远程不存在,需要新增到远程
+ else {
doContentSync(Node.SYNC_ACTION_ADD_REMOTE, node, c);
}
} else {
@@ -391,7 +442,9 @@ public class GTaskManager {
}
// for call-note folder
+ // 2. 同步通话记录文件夹
try {
+ // 查询通话记录文件夹(ID固定为Notes.ID_CALL_RECORD_FOLDER)
c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE, "(_id=?)",
new String[] {
String.valueOf(Notes.ID_CALL_RECORD_FOLDER)
@@ -400,12 +453,14 @@ public class GTaskManager {
if (c.moveToNext()) {
gid = c.getString(SqlNote.GTASK_ID_COLUMN);
node = mGTaskHashMap.get(gid);
+
if (node != null) {
mGTaskHashMap.remove(gid);
mGidToNid.put(gid, (long) Notes.ID_CALL_RECORD_FOLDER);
mNidToGid.put((long) Notes.ID_CALL_RECORD_FOLDER, gid);
// for system folder, only update remote name if
// necessary
+ // 系统文件夹只在名称不匹配时更新远程
if (!node.getName().equals(
GTaskStringUtils.MIUI_FOLDER_PREFFIX
+ GTaskStringUtils.FOLDER_CALL_NOTE))
@@ -425,10 +480,12 @@ public class GTaskManager {
}
// for local existing folders
+ // 3. 同步本地已存在的普通文件夹(非系统类型,非回收站)
try {
+ // 查询条件:文件夹 + 父ID不是回收站
c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE,
"(type=? AND parent_id<>?)", new String[] {
- String.valueOf(Notes.TYPE_FOLDER), String.valueOf(Notes.ID_TRASH_FOLER)
+ String.valueOf(Notes.TYPE_FOLDER), String.valueOf(Notes.ID_TRASH_FOLDER)
}, NoteColumns.TYPE + " DESC");
if (c != null) {
while (c.moveToNext()) {
@@ -442,9 +499,11 @@ public class GTaskManager {
} else {
if (c.getString(SqlNote.GTASK_ID_COLUMN).trim().length() == 0) {
// local add
+ // 本地GID为空:本地新增,同步到远程
syncType = Node.SYNC_ACTION_ADD_REMOTE;
} else {
// remote delete
+ // 本地有GID但远程无:远程已删除,删除本地
syncType = Node.SYNC_ACTION_DEL_LOCAL;
}
}
@@ -461,21 +520,24 @@ public class GTaskManager {
}
// for remote add folders
+ // 4. 处理远程存在但本地不存在的文件夹(同步到本地)
Iterator> iter = mGTaskListHashMap.entrySet().iterator();
while (iter.hasNext()) {
Map.Entry entry = iter.next();
gid = entry.getKey();
node = entry.getValue();
- if (mGTaskHashMap.containsKey(gid)) {
+ if (mGTaskHashMap.containsKey(gid)) { // 若缓存中存在(未被处理)
mGTaskHashMap.remove(gid);
- doContentSync(Node.SYNC_ACTION_ADD_LOCAL, node, null);
+ doContentSync(Node.SYNC_ACTION_ADD_LOCAL, node, null); // 本地新增
}
}
+ // 若未取消,提交所有文件夹相关的远程更新
if (!mCancelled)
GTaskClient.getInstance().commitUpdate();
}
+ // 执行具体同步操作:根据同步类型处理本地/远程数据
private void doContentSync(int syncType, Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -483,52 +545,57 @@ public class GTaskManager {
MetaData meta;
switch (syncType) {
- case Node.SYNC_ACTION_ADD_LOCAL:
+ case Node.SYNC_ACTION_ADD_LOCAL: // 远程新增,同步到本地
addLocalNode(node);
break;
- case Node.SYNC_ACTION_ADD_REMOTE:
+ case Node.SYNC_ACTION_ADD_REMOTE: // 本地新增,同步到远程
addRemoteNode(node, c);
break;
- case Node.SYNC_ACTION_DEL_LOCAL:
- meta = mMetaHashMap.get(c.getString(SqlNote.GTASK_ID_COLUMN));
+ case Node.SYNC_ACTION_DEL_LOCAL: // 远程已删除,删除本地
+ meta = mMetaHashMap.get(c.getString(SqlNote.GTASK_ID_COLUMN)); // 获取关联元数据
if (meta != null) {
- GTaskClient.getInstance().deleteNode(meta);
+ GTaskClient.getInstance().deleteNode(meta); // 删除远程元数据
}
- mLocalDeleteIdMap.add(c.getLong(SqlNote.ID_COLUMN));
+ mLocalDeleteIdMap.add(c.getLong(SqlNote.ID_COLUMN)); // 记录本地ID待删除
break;
- case Node.SYNC_ACTION_DEL_REMOTE:
+ case Node.SYNC_ACTION_DEL_REMOTE: // 本地已删除,删除远程
meta = mMetaHashMap.get(node.getGid());
if (meta != null) {
GTaskClient.getInstance().deleteNode(meta);
}
GTaskClient.getInstance().deleteNode(node);
break;
- case Node.SYNC_ACTION_UPDATE_LOCAL:
+ case Node.SYNC_ACTION_UPDATE_LOCAL: // 远程更新,同步到本地
updateLocalNode(node, c);
break;
- case Node.SYNC_ACTION_UPDATE_REMOTE:
+ case Node.SYNC_ACTION_UPDATE_REMOTE: // 本地更新,同步到远程
updateRemoteNode(node, c);
break;
- case Node.SYNC_ACTION_UPDATE_CONFLICT:
+ case Node.SYNC_ACTION_UPDATE_CONFLICT: // 同步冲突(本地与远程都有修改)
// merging both modifications maybe a good idea
// right now just use local update simply
+ // 简单处理:以本地更新为准,同步到远程
updateRemoteNode(node, c);
break;
- case Node.SYNC_ACTION_NONE:
+ case Node.SYNC_ACTION_NONE: // 无同步操作
break;
- case Node.SYNC_ACTION_ERROR:
+ case Node.SYNC_ACTION_ERROR: // 同步错误
default:
throw new ActionFailureException("unkown sync action type");
}
}
+ // 本地新增节点:将远程节点同步到本地数据库
private void addLocalNode(Node node) throws NetworkFailureException {
if (mCancelled) {
return;
}
SqlNote sqlNote;
+
+ // 节点是任务列表(文件夹)
if (node instanceof TaskList) {
+ // 特殊文件夹处理:根目录或通话记录文件夹
if (node.getName().equals(
GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_DEFAULT)) {
sqlNote = new SqlNote(mContext, Notes.ID_ROOT_FOLDER);
@@ -537,13 +604,14 @@ public class GTaskManager {
sqlNote = new SqlNote(mContext, Notes.ID_CALL_RECORD_FOLDER);
} else {
sqlNote = new SqlNote(mContext);
- sqlNote.setContent(node.getLocalJSONFromContent());
+ sqlNote.setContent(node.getLocalJSONFromContent()); // 用远程数据构建本地JSON
sqlNote.setParentId(Notes.ID_ROOT_FOLDER);
}
- } else {
+ } else { // 节点是任务(笔记)
sqlNote = new SqlNote(mContext);
- JSONObject js = node.getLocalJSONFromContent();
+ JSONObject js = node.getLocalJSONFromContent(); // 用远程数据构建本地JSON
try {
+ // 处理笔记ID冲突:若远程数据中的ID已在本地存在,移除ID(让本地自动生成)
if (js.has(GTaskStringUtils.META_HEAD_NOTE)) {
JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
if (note.has(NoteColumns.ID)) {
@@ -555,6 +623,7 @@ public class GTaskManager {
}
}
+ // 处理数据ID冲突:同理移除已存在的ID
if (js.has(GTaskStringUtils.META_HEAD_DATA)) {
JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
for (int i = 0; i < dataArray.length(); i++) {
@@ -576,26 +645,31 @@ public class GTaskManager {
}
sqlNote.setContent(js);
+ // 获取父文件夹的本地ID(通过GID映射)
Long parentId = mGidToNid.get(((Task) node).getParent().getGid());
if (parentId == null) {
Log.e(TAG, "cannot find task's parent id locally");
throw new ActionFailureException("cannot add local node");
}
- sqlNote.setParentId(parentId.longValue());
+ sqlNote.setParentId(parentId.longValue()); // 设置父目录ID
}
// create the local node
+ // 提交本地新增
sqlNote.setGtaskId(node.getGid());
sqlNote.commit(false);
// update gid-nid mapping
+ // 更新映射关系
mGidToNid.put(node.getGid(), sqlNote.getId());
mNidToGid.put(sqlNote.getId(), node.getGid());
// update meta
+ // 更新远程元数据
updateRemoteMeta(node.getGid(), sqlNote);
}
+ // 更新本地节点:将远程更新同步到本地
private void updateLocalNode(Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -604,8 +678,10 @@ public class GTaskManager {
SqlNote sqlNote;
// update the note locally
sqlNote = new SqlNote(mContext, c);
+ // 用远程数据更新本地内容
sqlNote.setContent(node.getLocalJSONFromContent());
+ // 确定父目录ID(任务的父是列表,列表的父是根目录)
Long parentId = (node instanceof Task) ? mGidToNid.get(((Task) node).getParent().getGid())
: new Long(Notes.ID_ROOT_FOLDER);
if (parentId == null) {
@@ -613,12 +689,14 @@ public class GTaskManager {
throw new ActionFailureException("cannot update local node");
}
sqlNote.setParentId(parentId.longValue());
- sqlNote.commit(true);
+ sqlNote.commit(true); // 提交更新(覆盖本地数据)
// update meta info
+ // 更新远程元数据
updateRemoteMeta(node.getGid(), sqlNote);
}
+ // 远程新增节点:将本地节点同步到远程
private void addRemoteNode(Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -628,26 +706,36 @@ public class GTaskManager {
Node n;
// update remotely
+ /**
+ * 区分笔记和文件夹,执行不同远程创建逻辑
+ * 本地节点是笔记(对应远程任务)
+ */
if (sqlNote.isNoteType()) {
Task task = new Task();
- task.setContentByLocalJSON(sqlNote.getContent());
+ task.setContentByLocalJSON(sqlNote.getContent()); // 用本地JSON初始化远程任务
+ // 获取父文件夹的远程GID(通过本地ID映射)
String parentGid = mNidToGid.get(sqlNote.getParentId());
if (parentGid == null) {
Log.e(TAG, "cannot find task's parent tasklist");
throw new ActionFailureException("cannot add remote task");
}
+ // 将任务添加到父列表
mGTaskListHashMap.get(parentGid).addChildTask(task);
+ // 调用客户端创建远程任务
GTaskClient.getInstance().createTask(task);
n = (Node) task;
// add meta
updateRemoteMeta(task.getGid(), sqlNote);
- } else {
+ }
+ // 本地节点是文件夹(对应远程任务列表)
+ else {
TaskList tasklist = null;
// we need to skip folder if it has already existed
+ // 生成文件夹名称(特定前缀+文件夹标识)
String folderName = GTaskStringUtils.MIUI_FOLDER_PREFFIX;
if (sqlNote.getId() == Notes.ID_ROOT_FOLDER)
folderName += GTaskStringUtils.FOLDER_DEFAULT;
@@ -656,12 +744,14 @@ public class GTaskManager {
else
folderName += sqlNote.getSnippet();
+ // 检查远程是否已存在同名文件夹(避免重复创建)
Iterator> iter = mGTaskListHashMap.entrySet().iterator();
while (iter.hasNext()) {
Map.Entry entry = iter.next();
String gid = entry.getKey();
TaskList list = entry.getValue();
+ // 已存在同名文件夹
if (list.getName().equals(folderName)) {
tasklist = list;
if (mGTaskHashMap.containsKey(gid)) {
@@ -672,6 +762,7 @@ public class GTaskManager {
}
// no match we can add now
+ // 若远程不存在,则创建新文件夹
if (tasklist == null) {
tasklist = new TaskList();
tasklist.setContentByLocalJSON(sqlNote.getContent());
@@ -682,35 +773,40 @@ public class GTaskManager {
}
// update local note
+ // 更新本地节点的远程GID
sqlNote.setGtaskId(n.getGid());
- sqlNote.commit(false);
- sqlNote.resetLocalModified();
- sqlNote.commit(true);
+ sqlNote.commit(false); // 保存GID
+ sqlNote.resetLocalModified(); // 重置本地修改标记(避免重复同步)
+ sqlNote.commit(true); // 提交修改
// gid-id mapping
+ // 更新映射关系
mGidToNid.put(n.getGid(), sqlNote.getId());
mNidToGid.put(sqlNote.getId(), n.getGid());
}
+ // 更新远程节点:将本地更新同步到远程
private void updateRemoteNode(Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
}
- SqlNote sqlNote = new SqlNote(mContext, c);
+ SqlNote sqlNote = new SqlNote(mContext, c); // 获取本地节点数据
// update remotely
node.setContentByLocalJSON(sqlNote.getContent());
- GTaskClient.getInstance().addUpdateNode(node);
+ GTaskClient.getInstance().addUpdateNode(node); // 将更新加入客户端的更新队列
// update meta
+ // 更新远程元数据
updateRemoteMeta(node.getGid(), sqlNote);
// move task if necessary
if (sqlNote.isNoteType()) {
Task task = (Task) node;
- TaskList preParentList = task.getParent();
+ TaskList preParentList = task.getParent(); // 原父列表
+ // 获取当前父文件夹的远程GID(通过本地ID映射)
String curParentGid = mNidToGid.get(sqlNote.getParentId());
if (curParentGid == null) {
Log.e(TAG, "cannot find task's parent tasklist");
@@ -718,6 +814,7 @@ public class GTaskManager {
}
TaskList curParentList = mGTaskListHashMap.get(curParentGid);
+ // 若父列表变化,执行移动操作
if (preParentList != curParentList) {
preParentList.removeChildTask(task);
curParentList.addChildTask(task);
@@ -730,13 +827,15 @@ public class GTaskManager {
sqlNote.commit(true);
}
+ // 更新远程元数据:同步本地笔记的元数据到远程
private void updateRemoteMeta(String gid, SqlNote sqlNote) throws NetworkFailureException {
+ // 仅处理笔记类型(文件夹无元数据)
if (sqlNote != null && sqlNote.isNoteType()) {
MetaData metaData = mMetaHashMap.get(gid);
- if (metaData != null) {
+ if (metaData != null) { // 元数据已存在,更新内容
metaData.setMeta(gid, sqlNote.getContent());
- GTaskClient.getInstance().addUpdateNode(metaData);
- } else {
+ GTaskClient.getInstance().addUpdateNode(metaData); // 加入更新队列
+ } else { // 元数据不存在,创建新的
metaData = new MetaData();
metaData.setMeta(gid, sqlNote.getContent());
mMetaList.addChildTask(metaData);
@@ -746,12 +845,14 @@ public class GTaskManager {
}
}
+ // 刷新本地同步ID:将远程的最后修改时间同步到本地(用于后续同步对比)
private void refreshLocalSyncId() throws NetworkFailureException {
if (mCancelled) {
return;
}
// get the latest gtask list
+ // 重新获取最新的远程节点数据
mGTaskHashMap.clear();
mGTaskListHashMap.clear();
mMetaHashMap.clear();
@@ -759,16 +860,18 @@ public class GTaskManager {
Cursor c = null;
try {
+ // 查询所有非系统类型且不在回收站的节点
c = mContentResolver.query(Notes.CONTENT_NOTE_URI, SqlNote.PROJECTION_NOTE,
"(type<>? AND parent_id<>?)", new String[] {
- String.valueOf(Notes.TYPE_SYSTEM), String.valueOf(Notes.ID_TRASH_FOLER)
+ String.valueOf(Notes.TYPE_SYSTEM), String.valueOf(Notes.ID_TRASH_FOLDER)
}, NoteColumns.TYPE + " DESC");
if (c != null) {
- while (c.moveToNext()) {
+ while (c.moveToNext()) { // 遍历本地节点
String gid = c.getString(SqlNote.GTASK_ID_COLUMN);
Node node = mGTaskHashMap.get(gid);
if (node != null) {
mGTaskHashMap.remove(gid);
+ // 更新本地节点的同步ID(远程最后修改时间)
ContentValues values = new ContentValues();
values.put(NoteColumns.SYNC_ID, node.getLastModified());
mContentResolver.update(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI,
@@ -790,6 +893,7 @@ public class GTaskManager {
}
}
+ // 获取同步账户:返回当前登录的Google账户名
public String getSyncAccount() {
return GTaskClient.getInstance().getSyncAccount().name;
}
diff --git a/src/notes/gtask/remote/GTaskSyncService.java b/src/notes/gtask/remote/GTaskSyncService.java
index cca36f7..a34a8b4 100644
--- a/src/notes/gtask/remote/GTaskSyncService.java
+++ b/src/notes/gtask/remote/GTaskSyncService.java
@@ -23,6 +23,10 @@ import android.content.Intent;
import android.os.Bundle;
import android.os.IBinder;
+/**
+ * 继承Service类(Android系统)
+ * 用于处理GTask的同步逻辑,如启动/取消同步、发送同步状态广播等
+ */
public class GTaskSyncService extends Service {
public final static String ACTION_STRING_NAME = "sync_action_type";
@@ -32,27 +36,34 @@ public class GTaskSyncService extends Service {
public final static int ACTION_INVALID = 2;
+ //同步服务发送广播的action名称(用于标识该广播的唯一标识)
public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service";
+ //广播中用于标识"是否正在同步"的键
public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing";
+ // 广播中用于标识"同步进度消息"的键
public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg";
- private static GTaskASyncTask mSyncTask = null;
+ private static GTaskASyncTask mSyncTask = null; //当前的同步任务实例
- private static String mSyncProgress = "";
+ private static String mSyncProgress = ""; //同步进度的字符串(记录和传递进度信息)
+ //启动同步任务
private void startSync() {
+ //当前没有同步任务执行,创建新任务
+
if (mSyncTask == null) {
mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
+ //任务完成时的回调方法:清理任务实例,发送空进度广播,停止当前服务
public void onComplete() {
mSyncTask = null;
sendBroadcast("");
stopSelf();
}
});
- sendBroadcast("");
- mSyncTask.execute();
+ sendBroadcast(""); // 发送初始广播(此时任务已创建,通知外界同步开始)
+ mSyncTask.execute(); //执行
}
}
@@ -67,10 +78,27 @@ public class GTaskSyncService extends Service {
mSyncTask = null;
}
+ /**
+ * 处理启动服务的意图
+ * 解析意图中的动作类型,执行对应的启动/取消同步操作
+ * @param intent The Intent supplied to {@link android.content.Context#startService},
+ * as given. This may be null if the service is being restarted after
+ * its process has gone away, and it had previously returned anything
+ * except {@link #START_STICKY_COMPATIBILITY}.
+ * @param flags 启动标志
+ * @param startId A unique integer representing this specific request to
+ * start. Use with {@link #stopSelfResult(int)}.
+ *
+ * @return 服务的启动模式
+ */
@Override
public int onStartCommand(Intent intent, int flags, int startId) {
+ // 获取意图中携带的额外数据(键值对集合)
Bundle bundle = intent.getExtras();
+
+ // 检查bundle是否存在且包含动作类型的键
if (bundle != null && bundle.containsKey(ACTION_STRING_NAME)) {
+ //根据动作类型执行对应操作
switch (bundle.getInt(ACTION_STRING_NAME, ACTION_INVALID)) {
case ACTION_START_SYNC:
startSync();
@@ -83,9 +111,10 @@ public class GTaskSyncService extends Service {
}
return START_STICKY;
}
- return super.onStartCommand(intent, flags, startId);
+ return super.onStartCommand(intent, flags, startId); //没有有效数据,则调用父类方法
}
+ //系统内存不足时的回调方法
@Override
public void onLowMemory() {
if (mSyncTask != null) {
@@ -97,6 +126,7 @@ public class GTaskSyncService extends Service {
return null;
}
+ //向外界发送包含同步状态(是否正在同步)和进度消息的广播
public void sendBroadcast(String msg) {
mSyncProgress = msg;
Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
@@ -105,23 +135,32 @@ public class GTaskSyncService extends Service {
sendBroadcast(intent);
}
+ //供外部(如界面)调用,触发同步操作
public static void startSync(Activity activity) {
+ // 设置GTaskManager的上下文为当前Activity
GTaskManager.getInstance().setActivityContext(activity);
+
+ // 创建启动GTaskSyncService的意图,指定服务类
Intent intent = new Intent(activity, GTaskSyncService.class);
+
+ // 在意图中添加"启动同步"的动作类型
intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_START_SYNC);
activity.startService(intent);
}
+ //供外部(如界面)调用,取消正在进行的同步操作
public static void cancelSync(Context context) {
Intent intent = new Intent(context, GTaskSyncService.class);
intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_CANCEL_SYNC);
context.startService(intent);
}
+ //断是否正在同步
public static boolean isSyncing() {
return mSyncTask != null;
}
+ //获取当前同步进度字符串
public static String getProgressString() {
return mSyncProgress;
}
diff --git a/src/notes/model/Note.java b/src/notes/model/Note.java
index 6706cf6..ecf9c21 100644
--- a/src/notes/model/Note.java
+++ b/src/notes/model/Note.java
@@ -33,13 +33,24 @@ import net.micode.notes.data.Notes.TextNote;
import java.util.ArrayList;
-
+/**
+ * 笔记数据模型类,负责的底层数据操作的模型类,
+ * 封装了笔记的基础数据(文本、通话记录)和核心属性(修改时间等)
+ * 与ContentProvider交互,实现笔记数据的创建、更新、同步等底层逻辑,
+ * 仅处理数据存储逻辑,不包含UI交互或业务判断,不包含业务逻辑
+ */
public class Note {
- private ContentValues mNoteDiffValues;
- private NoteData mNoteData;
+ private ContentValues mNoteDiffValues; //存储Note属性变化,修改时间等
+ private NoteData mNoteData; //封装Note具体数据,文本内容、通话记录等
private static final String TAG = "Note";
+
/**
* Create a new note id for adding a new note to databases
+ * 静态同步方法:创建新笔记并返回其ID
+ * 作用:在数据库中初始化一条笔记记录,为后续添加内容(文本/通话记录)做准备
+ * @param context 上下文(用于获取内容解析器)
+ * @param folderId 笔记所属文件夹ID(用于归类)
+ * @return 新创建的笔记ID
*/
public static synchronized long getNewNoteId(Context context, long folderId) {
// Create a new note in the database
@@ -65,6 +76,7 @@ public class Note {
return noteId;
}
+ //初始化Note数据容器,存储属性变化和具体数据
public Note() {
mNoteDiffValues = new ContentValues();
mNoteData = new NoteData();
@@ -76,10 +88,12 @@ public class Note {
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
+ //设置Note的文本数据(如笔记内容)
public void setTextData(String key, String value) {
mNoteData.setTextData(key, value);
}
+ //设置文本数据的ID(用于更新已有文本数据时定位记录)
public void setTextDataId(long id) {
mNoteData.setTextDataId(id);
}
@@ -96,10 +110,12 @@ public class Note {
mNoteData.setCallData(key, value);
}
+ //是否有本地修改
public boolean isLocalModified() {
return mNoteDiffValues.size() > 0 || mNoteData.isLocalModified();
}
+ //同步Note数据到数据库
public boolean syncNote(Context context, long noteId) {
if (noteId <= 0) {
throw new IllegalArgumentException("Wrong note id:" + noteId);
@@ -114,6 +130,7 @@ public class Note {
* {@link NoteColumns#MODIFIED_DATE}. For data safety, though update note fails, we also update the
* note data info
*/
+ //更新笔记属性(如修改时间、本地修改标记等)
if (context.getContentResolver().update(
ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId), mNoteDiffValues, null,
null) == 0) {
@@ -122,6 +139,7 @@ public class Note {
}
mNoteDiffValues.clear();
+ //同步具体数据(文本/通话记录),若数据有修改且同步失败,返回false
if (mNoteData.isLocalModified()
&& (mNoteData.pushIntoContentResolver(context, noteId) == null)) {
return false;
@@ -130,14 +148,18 @@ public class Note {
return true;
}
+ /**内部类
+ * 管理笔记的具体数据(文本内容、通话记录)
+ * 封装文本和通话数据的存储、修改、同步逻辑,与Note类协同工作
+ */
private class NoteData {
- private long mTextDataId;
+ private long mTextDataId;// 文本数据在数据库中的ID(0表示未创建)
- private ContentValues mTextDataValues;
+ private ContentValues mTextDataValues; // 存储文本数据的变化
- private long mCallDataId;
+ private long mCallDataId; // 通话记录数据在数据库中的ID(0表示未创建)
- private ContentValues mCallDataValues;
+ private ContentValues mCallDataValues; // 存储通话数据的变化(如号码更新)
private static final String TAG = "NoteData";
@@ -178,24 +200,39 @@ public class Note {
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
+ /**
+ * 将文本/通话数据的变化同步到数据库
+ * 若数据未创建(ID=0)则插入新记录;若已创建(ID>0)则更新记录
+ * @param context 上下文
+ * @param noteId 所属笔记ID(关联数据到具体笔记)
+ * @return 同步成功返回笔记Uri;失败返回null
+ */
Uri pushIntoContentResolver(Context context, long noteId) {
/**
* Check for safety
*/
+ // 校验笔记ID有效性
if (noteId <= 0) {
throw new IllegalArgumentException("Wrong note id:" + noteId);
}
+ // 创建批量操作列表(支持同时更新文本和通话数据)
ArrayList operationList = new ArrayList();
ContentProviderOperation.Builder builder = null;
+ //处理文本数据同步
if(mTextDataValues.size() > 0) {
+ // 关联文本数据到当前笔记
mTextDataValues.put(DataColumns.NOTE_ID, noteId);
+
+ //文本数据未创建
if (mTextDataId == 0) {
+ // 插入数据到ContentProvider,获取返回的Uri
mTextDataValues.put(DataColumns.MIME_TYPE, TextNote.CONTENT_ITEM_TYPE);
Uri uri = context.getContentResolver().insert(Notes.CONTENT_DATA_URI,
mTextDataValues);
try {
+ // 从Uri解析新插入的文本数据ID并存储
setTextDataId(Long.valueOf(uri.getPathSegments().get(1)));
} catch (NumberFormatException e) {
Log.e(TAG, "Insert new text data fail with noteId" + noteId);
@@ -203,14 +240,17 @@ public class Note {
return null;
}
} else {
+ // 文本数据已存在:更新记录
+ // 构建更新操作(指定数据ID对应的Uri)
builder = ContentProviderOperation.newUpdate(ContentUris.withAppendedId(
Notes.CONTENT_DATA_URI, mTextDataId));
- builder.withValues(mTextDataValues);
- operationList.add(builder.build());
+ builder.withValues(mTextDataValues); // 设置要更新的内容
+ operationList.add(builder.build()); // 添加到批量操作列表
}
mTextDataValues.clear();
}
+ //处理通话数据同步(逻辑同处理文本数据同步)
if(mCallDataValues.size() > 0) {
mCallDataValues.put(DataColumns.NOTE_ID, noteId);
if (mCallDataId == 0) {
@@ -233,21 +273,25 @@ public class Note {
mCallDataValues.clear();
}
+ //执行批量更新操作
if (operationList.size() > 0) {
try {
+ // 应用批量操作到ContentProvider
ContentProviderResult[] results = context.getContentResolver().applyBatch(
Notes.AUTHORITY, operationList);
return (results == null || results.length == 0 || results[0] == null) ? null
: ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId);
} catch (RemoteException e) {
+ // 远程异常(如ContentProvider断开连接)
Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
return null;
} catch (OperationApplicationException e) {
+ // 操作执行异常(如数据约束冲突)
Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
return null;
}
}
- return null;
+ return null; // 无批量操作需执行(如仅插入了新数据,未更新)
}
}
}
diff --git a/src/notes/model/WorkingNote.java b/src/notes/model/WorkingNote.java
index be081e4..b86eb9e 100644
--- a/src/notes/model/WorkingNote.java
+++ b/src/notes/model/WorkingNote.java
@@ -31,14 +31,17 @@ import net.micode.notes.data.Notes.NoteColumns;
import net.micode.notes.data.Notes.TextNote;
import net.micode.notes.tool.ResourceParser.NoteBgResources;
-
+/**
+ * 与Note类之间是组合关系,WorkingNote中的所有底层数据操作(如同步、属性变更记录)均通过mNote完成
+ * 专注于业务逻辑处理,封装用户可见的业务属性,如内容、背景色等
+ */
public class WorkingNote {
// Note for the working note
private Note mNote;
// Note Id
private long mNoteId;
// Note content
- private String mContent;
+ private String mContent; //笔记模式,如普通模式、清单模式
// Note mode
private int mMode;
@@ -62,6 +65,7 @@ public class WorkingNote {
private NoteSettingChangedListener mNoteSettingStatusListener;
+ //指定查询Data表时需要返回的字段
public static final String[] DATA_PROJECTION = new String[] {
DataColumns.ID,
DataColumns.CONTENT,
@@ -72,6 +76,7 @@ public class WorkingNote {
DataColumns.DATA4,
};
+ //指定查询Note表时需要返回的字段
public static final String[] NOTE_PROJECTION = new String[] {
NoteColumns.PARENT_ID,
NoteColumns.ALERTED_DATE,
@@ -124,14 +129,19 @@ public class WorkingNote {
loadNote();
}
+ //从数据库加载Note的基本信息(从Note表查询)
private void loadNote() {
+ //构建查询URI
Cursor cursor = mContext.getContentResolver().query(
- ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, mNoteId), NOTE_PROJECTION, null,
- null, null);
+ ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, mNoteId),
+ NOTE_PROJECTION,
+ null,
+ null,
+ null);
if (cursor != null) {
if (cursor.moveToFirst()) {
- mFolderId = cursor.getLong(NOTE_PARENT_ID_COLUMN);
+ mFolderId = cursor.getLong(NOTE_PARENT_ID_COLUMN); //文件夹ID
mBgColorId = cursor.getInt(NOTE_BG_COLOR_ID_COLUMN);
mWidgetId = cursor.getInt(NOTE_WIDGET_ID_COLUMN);
mWidgetType = cursor.getInt(NOTE_WIDGET_TYPE_COLUMN);
@@ -143,9 +153,10 @@ public class WorkingNote {
Log.e(TAG, "No note with id:" + mNoteId);
throw new IllegalArgumentException("Unable to find note with id " + mNoteId);
}
- loadNoteData();
+ loadNoteData(); //继续加载笔记的详细数据(从Data表查询)
}
+ //从数据库加载笔记的详细数据(从Data表查询)
private void loadNoteData() {
Cursor cursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI, DATA_PROJECTION,
DataColumns.NOTE_ID + "=?", new String[] {
@@ -156,11 +167,16 @@ public class WorkingNote {
if (cursor.moveToFirst()) {
do {
String type = cursor.getString(DATA_MIME_TYPE_COLUMN);
+
+ //如果是text类型
if (DataConstants.NOTE.equals(type)) {
mContent = cursor.getString(DATA_CONTENT_COLUMN);
mMode = cursor.getInt(DATA_MODE_COLUMN);
mNote.setTextDataId(cursor.getLong(DATA_ID_COLUMN));
- } else if (DataConstants.CALL_NOTE.equals(type)) {
+ }
+
+ //如果是通话记录类型
+ else if (DataConstants.CALL_NOTE.equals(type)) {
mNote.setCallDataId(cursor.getLong(DATA_ID_COLUMN));
} else {
Log.d(TAG, "Wrong note type with type:" + type);
@@ -174,6 +190,7 @@ public class WorkingNote {
}
}
+ //创建空Note
public static WorkingNote createEmptyNote(Context context, long folderId, int widgetId,
int widgetType, int defaultBgColorId) {
WorkingNote note = new WorkingNote(context, folderId);
@@ -183,19 +200,24 @@ public class WorkingNote {
return note;
}
+ //加载已有Note
public static WorkingNote load(Context context, long id) {
return new WorkingNote(context, id, 0);
}
+ //保存Note到数据库(同步方法)
public synchronized boolean saveNote() {
if (isWorthSaving()) {
+ // 若笔记不存在于数据库(新笔记)
if (!existInDatabase()) {
+ // 获取新笔记ID(若失败则返回0)
if ((mNoteId = Note.getNewNoteId(mContext, mFolderId)) == 0) {
Log.e(TAG, "Create new note fail with id:" + mNoteId);
return false;
}
}
+ // 通过Note对象同步数据到数据库
mNote.syncNote(mContext, mNoteId);
/**
@@ -217,6 +239,7 @@ public class WorkingNote {
}
private boolean isWorthSaving() {
+ //若已删除、(新笔记且内容为空)、(已存在且无本地修改),则无需保存
if (mIsDeleted || (!existInDatabase() && TextUtils.isEmpty(mContent))
|| (existInDatabase() && !mNote.isLocalModified())) {
return false;
@@ -229,24 +252,32 @@ public class WorkingNote {
mNoteSettingStatusListener = l;
}
+ //设置提醒时间
public void setAlertDate(long date, boolean set) {
+ //有时间变化才更新
if (date != mAlertDate) {
mAlertDate = date;
mNote.setNoteValue(NoteColumns.ALERTED_DATE, String.valueOf(mAlertDate));
}
+
+ // 若监听器不为空,触发提醒变更回调
if (mNoteSettingStatusListener != null) {
mNoteSettingStatusListener.onClockAlertChanged(date, set);
}
}
+ // 标记笔记是否被删除
public void markDeleted(boolean mark) {
mIsDeleted = mark;
+
+ // 若存在关联的小部件且监听器不为空,通知小部件变更
if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
&& mWidgetType != Notes.TYPE_WIDGET_INVALIDE && mNoteSettingStatusListener != null) {
mNoteSettingStatusListener.onWidgetChanged();
}
}
+ // 设置背景色ID
public void setBgColorId(int id) {
if (id != mBgColorId) {
mBgColorId = id;
@@ -257,6 +288,7 @@ public class WorkingNote {
}
}
+ // 设置清单模式(切换普通/清单模式)
public void setCheckListMode(int mode) {
if (mMode != mode) {
if (mNoteSettingStatusListener != null) {
@@ -267,6 +299,7 @@ public class WorkingNote {
}
}
+ // 设置小部件类型
public void setWidgetType(int type) {
if (type != mWidgetType) {
mWidgetType = type;
@@ -274,6 +307,7 @@ public class WorkingNote {
}
}
+ //设置小部件ID
public void setWidgetId(int id) {
if (id != mWidgetId) {
mWidgetId = id;
@@ -281,6 +315,7 @@ public class WorkingNote {
}
}
+ //设置笔记内容
public void setWorkingText(String text) {
if (!TextUtils.equals(mContent, text)) {
mContent = text;
@@ -288,6 +323,7 @@ public class WorkingNote {
}
}
+ // 将笔记转换为通话笔记(设置通话相关数据)
public void convertToCallNote(String phoneNumber, long callDate) {
mNote.setCallData(CallNote.CALL_DATE, String.valueOf(callDate));
mNote.setCallData(CallNote.PHONE_NUMBER, phoneNumber);
@@ -342,6 +378,7 @@ public class WorkingNote {
return mWidgetType;
}
+ // 笔记设置变更监听器接口(定义属性变化时的回调方法)
public interface NoteSettingChangedListener {
/**
* Called when the background color of current note has just changed
--
2.34.1
From bc3beabee4939d61789310ca14ac7f631c065f0a Mon Sep 17 00:00:00 2001
From: mc19 <2716188191@qq.com>
Date: Wed, 24 Dec 2025 01:12:21 +0800
Subject: [PATCH 2/4] =?UTF-8?q?=E5=AE=8C=E5=96=84=E6=8A=A5=E5=91=8A?=
=?UTF-8?q?=E4=BB=A3=E7=A0=81=E8=A1=8C=E6=95=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
...泛读、标注和维护报告文档.docx | Bin 505448 -> 510030 bytes
1 file changed, 0 insertions(+), 0 deletions(-)
diff --git a/doc/小米便签泛读、标注和维护报告文档.docx b/doc/小米便签泛读、标注和维护报告文档.docx
index 519cf833d4554e365a1658c3a602b9749d623807..b0da0d1a4a7fc4e9070884a1a4faa6bfc30b5a95 100644
GIT binary patch
delta 29016
zcmbTcV{qWj69yRDwryi$ZLE!L+s-exZQJ(7+1MM~_QtyRe;=;ys_w(peVgg-dZxQ-
zY8ua+UJ}hD5GQcL7OO9SIDmqH1SAUL07;4t8!QMTH{ef%2s?J;ak*ch#bj<9iw%$w
z-30I==Eg>C6jIjnzVGw0dtEDAW6uG^`BDR0?>rO^r@?LJ$ymIK=o}O7>p5I!F7GLN
z<K*$!JE|H%YLghSS+iN^v
z*=nof=upZv0eW;inmdq3CWC-j!rmGOFAcoDHEMLM@pf=zG7=7ABL^>!>pg
z`gB<&cp6<1N8ASJc046pr@{cDUYRu9q
z-uiSaY%JSc{FbD|8D^wzzx#`wNc||b^1g(0OanD$#SwDG{oe73NBLy6>aNK)2|e>3
z`|~IR7kw@rLs_)B*yjrU-*FZLfs8uq!@gE`*h;eC5EvjJATS`|3j4wq;A~Bj$;+S&
zK<*q?4Mi%5n*=3Al<*~k&$>2+f@yY{(WJ;~0H1p11h40L2iADXHi;BuV^WY?%;%Fcc32)Ctm-{0NV=ESM4f~%^CoP-bn`SZ*5AcLi!P^uoZVXNb}Gq#>ClQ|8dw3M&&@#1(;UW4Tnj90{+!uHa0
zdp}_{i&d^bdsv};e4^9E@$^<2+@V*lfA4SKp5D=yb~cJhpXcxSpMr>=EZTFh#VHc=
zA}sbQz~asz61gDLk-u7LY&9Qua9YMvaI1w{xC$uMXL4?mA1n0*BJt=*W<
zp^lQ?*45qW^^+?vv(%{`TjS_b-+5h?fyQ%-%?$G76k`!-&~N76o&B5C#763G5z
zy&BpQHgy1H9Nk)q$y{u8Y_Tx43xfF@`}LKL+4Fvk`J?IglC_&d>(~us<*#nz);&w?
zUTt{99ts{m?`+_HD*w-JPW7JWEeJpR;Q%?;L%LI9^yDR-O8PmRP~L6J*zcvvd}w73
z+)Z&u`dLepm
z2ASGJ70%KD-T}3Gvlx*J-%PCJfiF@B8rOtr{||@*Yc^nxTfgjq#?)X+>y6EVbhyd;
zHj8pz0wYXrxV`K7{!9()4xz|_jfYp6o7w9&D|7`CBwBrhWW?*`#jYQVOabJH8V`L#
zYZ*j2(X7QD*WnP;vnTNlw&h#bk{G$*!cSSr4}2o$HE6tNk4qSHy4}j<8{g99A7Tq{
zSqp7!NjPv*0HB9|X7ily3_E>ODQIU`bp1x4;SEy8YifsjZk}xEPS-2j^1Ecax;9F;
zdWPjqynTW7RSx8iQpE88d|H-)fT41(6tY+;(Wo9z;B=e$7MYO9fT)oJ=qF#4YW
z^FIOC{{#(qsm}Lzd7_SGp(^~dJj}oJS%7*&hb@Xvj6;?^j>+ZYmGh9loaBu)t;EAv
z65NQ4>*UhYIB{JuNaAp0#q_tV8+^`i
zNMtc)G(q99sdpFB*|s0dR#N*2pNChI!HS+AhNnzu3KB3^aJ#{
zLk3tbi4Q;Hkdj^+VBFZ`2mEHSV5u~EVw|~up@MC%vBlwvTz7V#q1O9QRXa0Axhk3=
zCN?fckjp%qE(<4`oS=4x32iokd~Bi*Tz
rSj7?o77Ui!uQnhKi)C_GQN(yf~RJj@$@{|
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