();
diff --git a/src/data/Notes.java b/src/data/Notes.java
index f240604..4100147 100644
--- a/src/data/Notes.java
+++ b/src/data/Notes.java
@@ -17,263 +17,562 @@
package net.micode.notes.data;
import android.net.Uri;
+
+/**
+ * 便签应用的核心数据定义类，包含所有常量、URI和数据列定义
+ *
+ * 核心职责：
+ *
+ * - 定义便签和文件夹的类型常量
+ * - 定义系统文件夹的ID常量
+ * - 定义Intent传递的额外数据键
+ * - 定义Widget类型常量
+ * - 定义Content Provider的URI
+ * - 定义数据列接口和内部数据类
+ *
+ *
+ * 设计意图：
+ *
+ * - 集中管理所有数据相关的常量，提高代码的可维护性
+ * - 为Content Provider提供统一的数据定义
+ * - 为应用各组件间的通信提供标准常量
+ * - 支持多种便签类型（文本便签、通话便签）
+ * - 支持便签的分类管理（文件夹、回收站）
+ * - 支持Widget功能
+ *
+ *
+ * 与其他类的关键关联：
+ *
+ * - 被{@link NotesProvider}使用，作为Content Provider的数据源定义
+ * - 被{@link NotesDatabaseHelper}使用，用于数据库表结构定义
+ * - 被UI组件使用，用于Intent传递和数据查询
+ * - 被Widget组件使用，用于Widget类型定义和数据传递
+ *
+ *
+
+ */
public class Notes {
+ /**
+ * Content Provider的Authority，用于标识便签应用的Content Provider
+ */
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;
/**
- * 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_CALL_RECORD_FOLDER} is to store call records
+ * 系统文件夹ID：根文件夹，所有普通便签的默认父文件夹
*/
public static final int ID_ROOT_FOLDER = 0;
+
+ /**
+ * 系统文件夹ID：临时文件夹，用于存放无归属的便签
+ */
public static final int ID_TEMPARAY_FOLDER = -1;
+
+ /**
+ * 系统文件夹ID：通话记录文件夹，用于存放自动生成的通话便签
+ */
public static final int ID_CALL_RECORD_FOLDER = -2;
+
+ /**
+ * 系统文件夹ID：回收站文件夹，用于存放已删除的便签
+ */
public static final int ID_TRASH_FOLER = -3;
+ /**
+ * Intent额外数据键：提醒日期，用于传递便签的提醒时间
+ */
public static final String INTENT_EXTRA_ALERT_DATE = "net.micode.notes.alert_date";
+
+ /**
+ * Intent额外数据键：背景颜色ID，用于传递便签的背景颜色设置
+ */
public static final String INTENT_EXTRA_BACKGROUND_ID = "net.micode.notes.background_color_id";
+
+ /**
+ * Intent额外数据键：Widget ID，用于传递Widget的唯一标识
+ */
public static final String INTENT_EXTRA_WIDGET_ID = "net.micode.notes.widget_id";
+
+ /**
+ * Intent额外数据键：Widget类型，用于传递Widget的类型（2x或4x）
+ */
public static final String INTENT_EXTRA_WIDGET_TYPE = "net.micode.notes.widget_type";
+
+ /**
+ * Intent额外数据键：文件夹ID，用于传递便签所属的文件夹ID
+ */
public static final String INTENT_EXTRA_FOLDER_ID = "net.micode.notes.folder_id";
+
+ /**
+ * Intent额外数据键：通话日期，用于传递通话记录的日期
+ */
public static final String INTENT_EXTRA_CALL_DATE = "net.micode.notes.call_date";
+ /**
+ * Widget类型常量：无效Widget类型
+ */
public static final int TYPE_WIDGET_INVALIDE = -1;
+
+ /**
+ * Widget类型常量：2x尺寸Widget（2x2网格）
+ */
public static final int TYPE_WIDGET_2X = 0;
+
+ /**
+ * Widget类型常量：4x尺寸Widget（4x4网格）
+ */
public static final int TYPE_WIDGET_4X = 1;
+ /**
+ * 数据类型常量类，定义不同类型便签的MIME类型
+ *
+ * 核心职责：
+ *
+ * - 提供统一的数据类型访问入口
+ * - 封装不同类型便签的MIME类型定义
+ *
+ */
public static class DataConstants {
+ /**
+ * 文本便签的MIME类型
+ */
public static final String NOTE = TextNote.CONTENT_ITEM_TYPE;
+
+ /**
+ * 通话便签的MIME类型
+ */
public static final String CALL_NOTE = CallNote.CONTENT_ITEM_TYPE;
}
/**
- * Uri to query all notes and folders
+ * Content Provider URI：用于查询所有便签和文件夹
+ *
+ * 该URI指向Content Provider的note表，返回所有便签和文件夹的列表
*/
public static final Uri CONTENT_NOTE_URI = Uri.parse("content://" + AUTHORITY + "/note");
/**
- * Uri to query data
+ * Content Provider URI：用于查询便签详细数据
+ *
+ * 该URI指向Content Provider的data表，返回便签的具体内容数据
*/
public static final Uri CONTENT_DATA_URI = Uri.parse("content://" + AUTHORITY + "/data");
+ /**
+ * 便签和文件夹的通用列定义接口
+ *
+ * 核心职责：
+ *
+ * - 定义便签和文件夹表的通用字段
+ * - 为Content Provider提供统一的列名定义
+ * - 支持便签和文件夹的基本属性存储
+ *
+ *
+ * 设计意图：
+ *
+ * - 使用接口定义列名，便于在不同组件间共享
+ * - 支持便签和文件夹的统一管理
+ * - 包含基本的元数据字段（创建时间、修改时间、ID等）
+ * - 支持便签的提醒功能
+ * - 支持便签的Widget关联
+ * - 支持便签的背景颜色设置
+ * - 支持便签的同步功能
+ *
+ *
+ * 与其他类的关联：
+ *
+ * - 被{@link NotesProvider}使用，作为查询和操作的列名
+ * - 被{@link NotesDatabaseHelper}使用，用于创建数据库表
+ * - 被UI组件使用，用于构建查询条件和显示数据
+ *
+ */
public interface NoteColumns {
/**
- * The unique ID for a row
- * Type: INTEGER (long)
+ * 行的唯一标识符
+ * 类型: INTEGER (long)
+ * 约束: 主键，自增长
*/
public static final String ID = "_id";
/**
- * The parent's id for note or folder
- * Type: INTEGER (long)
+ * 便签或文件夹的父级ID
+ * 类型: INTEGER (long)
+ * 约束: 指向同一表中的ID字段
+ * 用途: 用于构建便签和文件夹的层级结构
*/
public static final String PARENT_ID = "parent_id";
/**
- * Created data for note or folder
- * Type: INTEGER (long)
+ * 便签或文件夹的创建时间
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级
+ * 用途: 记录创建时间，用于排序和显示
*/
public static final String CREATED_DATE = "created_date";
/**
- * Latest modified date
- * Type: INTEGER (long)
+ * 最近修改时间
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级
+ * 用途: 记录最后修改时间，用于排序、同步和显示
*/
public static final String MODIFIED_DATE = "modified_date";
-
/**
- * Alert date
- * Type: INTEGER (long)
+ * 提醒日期
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级；0表示无提醒
+ * 用途: 用于便签的提醒功能，指定提醒时间
*/
public static final String ALERTED_DATE = "alert_date";
/**
- * Folder's name or text content of note
- * Type: TEXT
+ * 文件夹名称或便签文本内容的摘要
+ * 类型: TEXT
+ * 约束: 最大长度根据数据库配置而定
+ * 用途: 快速显示便签或文件夹的基本信息
*/
public static final String SNIPPET = "snippet";
/**
- * Note's widget id
- * Type: INTEGER (long)
+ * 便签关联的Widget ID
+ * 类型: INTEGER (long)
+ * 约束: -1表示无关联Widget
+ * 用途: 用于关联便签和对应的Widget组件
*/
public static final String WIDGET_ID = "widget_id";
/**
- * Note's widget type
- * Type: INTEGER (long)
+ * 便签关联的Widget类型
+ * 类型: INTEGER (long)
+ * 约束: 取值范围为{@link Notes#TYPE_WIDGET_INVALIDE}、{@link Notes#TYPE_WIDGET_2X}、{@link Notes#TYPE_WIDGET_4X}
+ * 用途: 用于标识关联Widget的尺寸类型
*/
public static final String WIDGET_TYPE = "widget_type";
/**
- * Note's background color's id
- * Type: INTEGER (long)
+ * 便签背景颜色的ID
+ * 类型: INTEGER (long)
+ * 约束: 指向预定义的颜色资源ID
+ * 用途: 用于设置和显示便签的背景颜色
*/
public static final String BG_COLOR_ID = "bg_color_id";
/**
- * For text note, it doesn't has attachment, for multi-media
- * note, it has at least one attachment
- * Type: INTEGER
+ * 是否包含附件
+ * 类型: INTEGER
+ * 约束: 0表示无附件，1表示有附件
+ * 用途: 用于标识便签是否包含多媒体附件
*/
public static final String HAS_ATTACHMENT = "has_attachment";
/**
- * Folder's count of notes
- * Type: INTEGER (long)
+ * 文件夹包含的便签数量
+ * 类型: INTEGER (long)
+ * 约束: 非负数
+ * 用途: 用于快速显示文件夹中的便签数量
*/
public static final String NOTES_COUNT = "notes_count";
/**
- * The file type: folder or note
- * Type: INTEGER
+ * 类型：文件夹或便签
+ * 类型: INTEGER
+ * 约束: 取值范围为{@link Notes#TYPE_NOTE}、{@link Notes#TYPE_FOLDER}、{@link Notes#TYPE_SYSTEM}
+ * 用途: 用于区分便签和文件夹
*/
public static final String TYPE = "type";
/**
- * The last sync id
- * Type: INTEGER (long)
+ * 最后同步ID
+ * 类型: INTEGER (long)
+ * 约束: 用于同步机制，标识同步状态
+ * 用途: 用于便签的云同步功能，跟踪同步进度
*/
public static final String SYNC_ID = "sync_id";
/**
- * Sign to indicate local modified or not
- * Type: INTEGER
+ * 本地修改标记
+ * 类型: INTEGER
+ * 约束: 0表示未修改，1表示已修改
+ * 用途: 用于同步机制，标识本地是否有未同步的修改
*/
public static final String LOCAL_MODIFIED = "local_modified";
/**
- * Original parent id before moving into temporary folder
- * Type : INTEGER
+ * 移动到临时文件夹前的原始父ID
+ * 类型: INTEGER
+ * 约束: 指向原父文件夹的ID
+ * 用途: 用于临时文件夹中的便签，便于恢复到原位置
*/
public static final String ORIGIN_PARENT_ID = "origin_parent_id";
/**
- * The gtask id
- * Type : TEXT
+ * Google Task ID
+ * 类型: TEXT
+ * 约束: 与Google Task服务同步时使用
+ * 用途: 用于便签与Google Task的同步功能
*/
public static final String GTASK_ID = "gtask_id";
/**
- * The version code
- * Type : INTEGER (long)
+ * 版本号
+ * 类型: INTEGER (long)
+ * 约束: 用于乐观锁机制，防止并发修改冲突
+ * 用途: 用于同步和并发控制，确保数据一致性
*/
public static final String VERSION = "version";
}
+ /**
+ * 便签详细数据的列定义接口
+ *
+ * 核心职责：
+ *
+ * - 定义便签详细数据表的通用字段
+ * - 为不同类型的便签数据提供统一的存储结构
+ * - 支持便签内容的扩展存储
+ *
+ *
+ * 设计意图：
+ *
+ * - 使用接口定义列名，便于在不同组件间共享
+ * - 支持多种类型的便签数据存储（文本便签、通话便签等）
+ * - 采用通用字段设计，便于扩展新的便签类型
+ * - 包含基本的元数据字段（创建时间、修改时间、ID等）
+ * - 支持便签内容的灵活存储
+ *
+ *
+ * 与其他类的关联：
+ *
+ * - 被{@link NotesProvider}使用，作为查询和操作的列名
+ * - 被{@link NotesDatabaseHelper}使用，用于创建数据库表
+ * - 被{@link TextNote}和{@link CallNote}内部类继承，用于定义特定类型便签的字段映射
+ *
+ */
public interface DataColumns {
/**
- * The unique ID for a row
- * Type: INTEGER (long)
+ * 行的唯一标识符
+ * 类型: INTEGER (long)
+ * 约束: 主键，自增长
*/
public static final String ID = "_id";
/**
- * The MIME type of the item represented by this row.
- * Type: Text
+ * 该行数据表示的项目的MIME类型
+ * 类型: TEXT
+ * 约束: 唯一标识数据类型，如"text_note"、"call_note"等
+ * 用途: 用于区分不同类型的便签数据
*/
public static final String MIME_TYPE = "mime_type";
/**
- * The reference id to note that this data belongs to
- * Type: INTEGER (long)
+ * 该数据所属的便签ID
+ * 类型: INTEGER (long)
+ * 约束: 外键，指向note表的ID字段
+ * 用途: 建立便签基本信息与详细数据的关联关系
*/
public static final String NOTE_ID = "note_id";
/**
- * Created data for note or folder
- * Type: INTEGER (long)
+ * 数据的创建时间
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级
+ * 用途: 记录创建时间，用于排序和显示
*/
public static final String CREATED_DATE = "created_date";
/**
- * Latest modified date
- * Type: INTEGER (long)
+ * 数据的最近修改时间
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级
+ * 用途: 记录最后修改时间，用于排序、同步和显示
*/
public static final String MODIFIED_DATE = "modified_date";
/**
- * Data's content
- * Type: TEXT
+ * 数据的内容
+ * 类型: TEXT
+ * 约束: 可变长度，存储便签的实际内容
+ * 用途: 存储便签的文本内容或其他主要数据
*/
public static final String CONTENT = "content";
-
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
- * integer data type
- * Type: INTEGER
+ * 通用数据列1，含义由{@link #MIME_TYPE}决定，用于整数数据类型
+ * 类型: INTEGER
+ * 约束: 含义取决于具体的MIME类型
+ * 用途: 用于存储特定类型便签的额外整数数据
+ * 例如: 文本便签用于存储模式（普通模式/ checklist模式）
*/
public static final String DATA1 = "data1";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
- * integer data type
- * Type: INTEGER
+ * 通用数据列2，含义由{@link #MIME_TYPE}决定，用于整数数据类型
+ * 类型: INTEGER
+ * 约束: 含义取决于具体的MIME类型
+ * 用途: 用于存储特定类型便签的额外整数数据
*/
public static final String DATA2 = "data2";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
- * TEXT data type
- * Type: TEXT
+ * 通用数据列3，含义由{@link #MIME_TYPE}决定，用于文本数据类型
+ * 类型: TEXT
+ * 约束: 含义取决于具体的MIME类型
+ * 用途: 用于存储特定类型便签的额外文本数据
+ * 例如: 通话便签用于存储电话号码
*/
public static final String DATA3 = "data3";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
- * TEXT data type
- * Type: TEXT
+ * 通用数据列4，含义由{@link #MIME_TYPE}决定，用于文本数据类型
+ * 类型: TEXT
+ * 约束: 含义取决于具体的MIME类型
+ * 用途: 用于存储特定类型便签的额外文本数据
*/
public static final String DATA4 = "data4";
/**
- * Generic data column, the meaning is {@link #MIMETYPE} specific, used for
- * TEXT data type
- * Type: TEXT
+ * 通用数据列5，含义由{@link #MIME_TYPE}决定，用于文本数据类型
+ * 类型: TEXT
+ * 约束: 含义取决于具体的MIME类型
+ * 用途: 用于存储特定类型便签的额外文本数据
*/
public static final String DATA5 = "data5";
}
+ /**
+ * 文本便签的数据定义类，实现了{@link DataColumns}接口
+ *
+ * 核心职责：
+ *
+ * - 定义文本便签的特定字段映射
+ * - 定义文本便签的MIME类型
+ * - 定义文本便签的Content Provider URI
+ * - 支持普通文本模式和Checklist模式
+ *
+ *
+ * 设计意图：
+ *
+ * - 扩展{@link DataColumns}接口，为文本便签提供特定的字段映射
+ * - 使用DATA1列存储文本便签的模式（普通模式/Checklist模式）
+ * - 为Content Provider提供文本便签的访问入口
+ * - 支持多种文本便签显示模式
+ *
+ *
+ * 与其他类的关联：
+ *
+ * - 实现{@link DataColumns}接口，继承通用数据列定义
+ * - 被{@link NotesProvider}使用，作为文本便签的数据源定义
+ * - 被UI组件使用，用于查询和显示文本便签
+ *
+ */
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
+ * 文本便签的模式字段，映射到通用数据列DATA1
+ * 类型: INTEGER
+ * 约束: 0表示普通文本模式，1表示Checklist模式
+ * 用途: 用于标识文本便签的显示和编辑模式
*/
public static final String MODE = DATA1;
+ /**
+ * Checklist模式常量，表示文本便签处于Checklist编辑模式
+ */
public static final int MODE_CHECK_LIST = 1;
+ /**
+ * 文本便签集合的MIME类型，用于Content Provider返回多个文本便签时使用
+ */
public static final String CONTENT_TYPE = "vnd.android.cursor.dir/text_note";
+ /**
+ * 单个文本便签的MIME类型，用于Content Provider返回单个文本便签时使用
+ */
public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/text_note";
+ /**
+ * 文本便签的Content Provider URI，用于查询和操作文本便签数据
+ */
public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/text_note");
}
+ /**
+ * 通话便签的数据定义类，实现了{@link DataColumns}接口
+ *
+ * 核心职责：
+ *
+ * - 定义通话便签的特定字段映射
+ * - 定义通话便签的MIME类型
+ * - 定义通话便签的Content Provider URI
+ * - 支持通话记录的自动关联和存储
+ *
+ *
+ * 设计意图：
+ *
+ * - 扩展{@link DataColumns}接口，为通话便签提供特定的字段映射
+ * - 使用DATA1列存储通话日期
+ * - 使用DATA3列存储电话号码
+ * - 为Content Provider提供通话便签的访问入口
+ * - 支持通话记录的自动生成和关联
+ *
+ *
+ * 与其他类的关联：
+ *
+ * - 实现{@link DataColumns}接口，继承通用数据列定义
+ * - 被{@link NotesProvider}使用，作为通话便签的数据源定义
+ * - 被通话记录相关组件使用，用于自动生成通话便签
+ * - 被UI组件使用，用于查询和显示通话便签
+ *
+ */
public static final class CallNote implements DataColumns {
/**
- * Call date for this record
- * Type: INTEGER (long)
+ * 通话日期字段，映射到通用数据列DATA1
+ * 类型: INTEGER (long)
+ * 约束: Unix时间戳，毫秒级
+ * 用途: 存储通话发生的日期和时间
*/
public static final String CALL_DATE = DATA1;
/**
- * Phone number for this record
- * Type: TEXT
+ * 电话号码字段，映射到通用数据列DATA3
+ * 类型: TEXT
+ * 约束: 存储通话记录的电话号码
+ * 用途: 存储通话记录的电话号码，便于用户查看和回拨
*/
public static final String PHONE_NUMBER = DATA3;
+ /**
+ * 通话便签集合的MIME类型，用于Content Provider返回多个通话便签时使用
+ */
public static final String CONTENT_TYPE = "vnd.android.cursor.dir/call_note";
+ /**
+ * 单个通话便签的MIME类型，用于Content Provider返回单个通话便签时使用
+ */
public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/call_note";
+ /**
+ * 通话便签的Content Provider URI，用于查询和操作通话便签数据
+ */
public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/call_note");
}
}
diff --git a/src/data/NotesDatabaseHelper.java b/src/data/NotesDatabaseHelper.java
index ffe5d57..ab3d1ff 100644
--- a/src/data/NotesDatabaseHelper.java
+++ b/src/data/NotesDatabaseHelper.java
@@ -26,190 +26,314 @@ import net.micode.notes.data.Notes.DataColumns;
import net.micode.notes.data.Notes.DataConstants;
import net.micode.notes.data.Notes.NoteColumns;
+/**
+ * 便签应用的数据库核心帮助类，负责数据库的创建、升级和维护
+ *
+ * 核心职责：
+ *
+ * - 负责 "note.db" 数据库的创建 ({@link #onCreate})
+ * - 负责数据库版本升级与数据迁移 ({@link #onUpgrade})
+ * - 定义表名常量（如 {@link TABLE#NOTE}）供外部调用
+ * - 维护 SQL Triggers 以保证数据一致性（如文件夹计数更新）
+ * - 提供单例实例，确保数据库连接的高效管理
+ * - 创建和维护系统文件夹（根文件夹、临时文件夹、通话记录文件夹、回收站）
+ *
+ *
+ * 设计意图：
+ *
+ * - 采用单例模式，避免频繁创建和销毁数据库连接
+ * - 使用SQL Triggers自动维护数据一致性，减少应用层逻辑复杂度
+ * - 提供清晰的版本升级机制，支持平滑的数据迁移
+ * - 将数据库结构定义集中管理，便于维护和扩展
+ * - 支持多种便签类型和关联数据存储
+ *
+ *
+ * 继承关系：
+ *
+ * - 直接继承自 {@link SQLiteOpenHelper}，利用Android系统提供的数据库管理机制
+ *
+ *
+ * 与其他类的关键关联：
+ *
+ * - 被 {@link NotesProvider} 使用，作为Content Provider的底层数据存储
+ * - 使用 {@link Notes} 类中定义的常量和列名，确保数据一致性
+ * - 为整个应用提供统一的数据库访问入口
+ *
+ *
+ * 数据一致性保障：
+ *
+ * - 使用SQL Triggers自动更新文件夹的便签计数
+ * - 实现级联删除，确保数据完整性
+ * - 自动更新便签的摘要内容
+ * - 支持回收站功能，实现安全删除
+ *
+ *
+ */
public class NotesDatabaseHelper extends SQLiteOpenHelper {
+ /**
+ * 数据库名称常量
+ * 数据库文件名：note.db
+ */
private static final String DB_NAME = "note.db";
+ /**
+ * 数据库当前版本号
+ *
+ * 警告：
+ * 任何表结构的修改（如 addColumn）或 Trigger 逻辑的变更，都必须手动 +1。
+ * 这将导致系统自动调用 {@link #onUpgrade} 方法，执行相应的数据迁移操作。
+ *
+ *
+ * 版本历史：
+ *
+ * - 版本1：初始版本
+ * - 版本2：完全重建数据库
+ * - 版本3：添加Google Task ID支持并添加回收站文件夹
+ * - 版本4：添加版本号字段
+ *
+ *
+ */
private static final int DB_VERSION = 4;
+ /**
+ * 表名常量接口，定义数据库中所有表的名称
+ *
+ * 设计意图：
+ *
+ * - 集中管理表名常量，避免硬编码
+ * - 提供统一的表名访问入口，便于维护和扩展
+ * - 被外部类如{@link NotesProvider}使用，确保表名一致性
+ *
+ */
public interface TABLE {
+ /**
+ * 笔记表，存储便签和文件夹的基本信息
+ * 包含字段：ID、PARENT_ID、ALERTED_DATE、BG_COLOR_ID、CREATED_DATE等
+ */
public static final String NOTE = "note";
-
+
+ /**
+ * 数据表，存储便签的详细内容数据
+ * 包含字段：ID、MIME_TYPE、NOTE_ID、CONTENT、DATA1-DATA5等
+ */
public static final String DATA = "data";
}
+ /**
+ * 日志标签，用于调试和日志记录
+ */
private static final String TAG = "NotesDatabaseHelper";
-
+
+ /**
+ * 单例实例，确保整个应用只有一个数据库连接实例
+ *
+ * 设计意图：
+ *
+ * - 避免频繁创建和销毁数据库连接，提高性能
+ * - 确保数据库操作的线程安全
+ * - 通过{@link #getInstance(Context)}方法获取实例
+ *
+ */
private static NotesDatabaseHelper mInstance;
+ /**
+ * 创建笔记表的SQL语句
+ * 包含笔记的基本信息字段：ID、父文件夹ID、提醒日期、背景颜色、创建日期等
+ */
private static final String CREATE_NOTE_TABLE_SQL =
- "CREATE TABLE " + TABLE.NOTE + "(" +
- NoteColumns.ID + " INTEGER PRIMARY KEY," +
- NoteColumns.PARENT_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.ALERTED_DATE + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.BG_COLOR_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.CREATED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," +
- NoteColumns.HAS_ATTACHMENT + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.MODIFIED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," +
- NoteColumns.NOTES_COUNT + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.SNIPPET + " TEXT NOT NULL DEFAULT ''," +
- NoteColumns.TYPE + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.WIDGET_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.WIDGET_TYPE + " INTEGER NOT NULL DEFAULT -1," +
- NoteColumns.SYNC_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.LOCAL_MODIFIED + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.ORIGIN_PARENT_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.GTASK_ID + " TEXT NOT NULL DEFAULT ''," +
- NoteColumns.VERSION + " INTEGER NOT NULL DEFAULT 0" +
- ")";
+ "CREATE TABLE " + TABLE.NOTE + "(" +
+ NoteColumns.ID + " INTEGER PRIMARY KEY," + // 主键ID
+ NoteColumns.PARENT_ID + " INTEGER NOT NULL DEFAULT 0," + // 父文件夹ID，默认为0
+ NoteColumns.ALERTED_DATE + " INTEGER NOT NULL DEFAULT 0," + // 提醒日期时间戳
+ NoteColumns.BG_COLOR_ID + " INTEGER NOT NULL DEFAULT 0," + // 背景颜色ID
+ NoteColumns.CREATED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," + // 创建日期，默认为当前时间
+ NoteColumns.HAS_ATTACHMENT + " INTEGER NOT NULL DEFAULT 0," + // 是否有附件
+ NoteColumns.MODIFIED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," + // 修改日期，默认为当前时间
+ NoteColumns.NOTES_COUNT + " INTEGER NOT NULL DEFAULT 0," + // 笔记数量（用于文件夹）
+ NoteColumns.SNIPPET + " TEXT NOT NULL DEFAULT ''," + // 内容摘要
+ NoteColumns.TYPE + " INTEGER NOT NULL DEFAULT 0," + // 类型（笔记/文件夹/系统文件夹等）
+ NoteColumns.WIDGET_ID + " INTEGER NOT NULL DEFAULT 0," + // 关联的小部件ID
+ NoteColumns.WIDGET_TYPE + " INTEGER NOT NULL DEFAULT -1," + // 小部件类型
+ NoteColumns.SYNC_ID + " INTEGER NOT NULL DEFAULT 0," + // 同步ID
+ NoteColumns.LOCAL_MODIFIED + " INTEGER NOT NULL DEFAULT 0," + // 本地修改标记
+ NoteColumns.ORIGIN_PARENT_ID + " INTEGER NOT NULL DEFAULT 0," + // 原始父文件夹ID
+ NoteColumns.GTASK_ID + " TEXT NOT NULL DEFAULT ''," + // Google Task ID
+ NoteColumns.VERSION + " INTEGER NOT NULL DEFAULT 0" + // 版本号
+ ")";
+ /**
+ * 创建数据表的SQL语句
+ * 存储笔记的具体内容数据，支持多种MIME类型（文本、图片等）
+ */
private static final String CREATE_DATA_TABLE_SQL =
- "CREATE TABLE " + TABLE.DATA + "(" +
- DataColumns.ID + " INTEGER PRIMARY KEY," +
- DataColumns.MIME_TYPE + " TEXT NOT NULL," +
- DataColumns.NOTE_ID + " INTEGER NOT NULL DEFAULT 0," +
- NoteColumns.CREATED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," +
- NoteColumns.MODIFIED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," +
- DataColumns.CONTENT + " TEXT NOT NULL DEFAULT ''," +
- DataColumns.DATA1 + " INTEGER," +
- DataColumns.DATA2 + " INTEGER," +
- DataColumns.DATA3 + " TEXT NOT NULL DEFAULT ''," +
- DataColumns.DATA4 + " TEXT NOT NULL DEFAULT ''," +
- DataColumns.DATA5 + " TEXT NOT NULL DEFAULT ''" +
- ")";
+ "CREATE TABLE " + TABLE.DATA + "(" +
+ DataColumns.ID + " INTEGER PRIMARY KEY," + // 主键ID
+ DataColumns.MIME_TYPE + " TEXT NOT NULL," + // MIME类型，标识数据类型
+ DataColumns.NOTE_ID + " INTEGER NOT NULL DEFAULT 0," + // 关联的笔记ID
+ NoteColumns.CREATED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," + // 创建日期
+ NoteColumns.MODIFIED_DATE + " INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000)," + // 修改日期
+ DataColumns.CONTENT + " TEXT NOT NULL DEFAULT ''," + // 内容
+ DataColumns.DATA1 + " INTEGER," + // 扩展字段1（整数）
+ DataColumns.DATA2 + " INTEGER," + // 扩展字段2（整数）
+ DataColumns.DATA3 + " TEXT NOT NULL DEFAULT ''," + // 扩展字段3（文本）
+ DataColumns.DATA4 + " TEXT NOT NULL DEFAULT ''," + // 扩展字段4（文本）
+ DataColumns.DATA5 + " TEXT NOT NULL DEFAULT ''" + // 扩展字段5（文本）
+ ")";
+ /**
+ * 在数据表的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 + ");";
+ "CREATE INDEX IF NOT EXISTS note_id_index ON " +
+ TABLE.DATA + "(" + DataColumns.NOTE_ID + ");";
/**
- * Increase folder's note count when move note to the folder
+ * SQL 触发器：移动笔记时自动增加目标文件夹计数
+ *
+ * 逻辑解析：
+ * 1. 监听 {@link TABLE#NOTE} 表的 {@link NoteColumns#PARENT_ID} 字段。
+ * 2. 捕捉更新后的新文件夹 ID (new.parent_id)。
+ * 3. 将该目标文件夹的 'note_count' 字段 +1。
+ *
*/
private static final String NOTE_INCREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER =
- "CREATE TRIGGER increase_folder_count_on_update "+
- " AFTER UPDATE OF " + NoteColumns.PARENT_ID + " ON " + TABLE.NOTE +
- " BEGIN " +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + " + 1" +
- " WHERE " + NoteColumns.ID + "=new." + NoteColumns.PARENT_ID + ";" +
- " END";
+ "CREATE TRIGGER increase_folder_count_on_update "+
+ " AFTER UPDATE OF " + NoteColumns.PARENT_ID + " ON " + TABLE.NOTE +
+ " BEGIN " +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + " + 1" +
+ " WHERE " + NoteColumns.ID + "=new." + NoteColumns.PARENT_ID + ";" +
+ " END";
/**
- * Decrease folder's note count when move note from folder
+ * SQL 触发器：当笔记从文件夹移出时，减少原文件夹的笔记计数
+ * 注意：只减少计数大于0的文件夹
*/
private static final String NOTE_DECREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER =
- "CREATE TRIGGER decrease_folder_count_on_update " +
- " AFTER UPDATE OF " + NoteColumns.PARENT_ID + " ON " + TABLE.NOTE +
- " BEGIN " +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + "-1" +
- " WHERE " + NoteColumns.ID + "=old." + NoteColumns.PARENT_ID +
- " AND " + NoteColumns.NOTES_COUNT + ">0" + ";" +
- " END";
+ "CREATE TRIGGER decrease_folder_count_on_update " +
+ " AFTER UPDATE OF " + NoteColumns.PARENT_ID + " ON " + TABLE.NOTE +
+ " BEGIN " +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + "-1" +
+ " WHERE " + NoteColumns.ID + "=old." + NoteColumns.PARENT_ID +
+ " AND " + NoteColumns.NOTES_COUNT + ">0" + ";" +
+ " END";
/**
- * Increase folder's note count when insert new note to the folder
+ * SQL 触发器：插入新笔记时增加父文件夹的笔记计数
*/
private static final String NOTE_INCREASE_FOLDER_COUNT_ON_INSERT_TRIGGER =
- "CREATE TRIGGER increase_folder_count_on_insert " +
- " AFTER INSERT ON " + TABLE.NOTE +
- " BEGIN " +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + " + 1" +
- " WHERE " + NoteColumns.ID + "=new." + NoteColumns.PARENT_ID + ";" +
- " END";
+ "CREATE TRIGGER increase_folder_count_on_insert " +
+ " AFTER INSERT ON " + TABLE.NOTE +
+ " BEGIN " +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + " + 1" +
+ " WHERE " + NoteColumns.ID + "=new." + NoteColumns.PARENT_ID + ";" +
+ " END";
/**
- * Decrease folder's note count when delete note from the folder
+ * SQL 触发器：删除笔记时减少父文件夹的笔记计数
+ * 注意：只减少计数大于0的文件夹
*/
private static final String NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER =
- "CREATE TRIGGER decrease_folder_count_on_delete " +
- " AFTER DELETE ON " + TABLE.NOTE +
- " BEGIN " +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + "-1" +
- " WHERE " + NoteColumns.ID + "=old." + NoteColumns.PARENT_ID +
- " AND " + NoteColumns.NOTES_COUNT + ">0;" +
- " END";
+ "CREATE TRIGGER decrease_folder_count_on_delete " +
+ " AFTER DELETE ON " + TABLE.NOTE +
+ " BEGIN " +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.NOTES_COUNT + "=" + NoteColumns.NOTES_COUNT + "-1" +
+ " WHERE " + NoteColumns.ID + "=old." + NoteColumns.PARENT_ID +
+ " AND " + NoteColumns.NOTES_COUNT + ">0;" +
+ " END";
/**
- * Update note's content when insert data with type {@link DataConstants#NOTE}
+ * SQL 触发器：当插入类型为NOTE的数据时，更新对应笔记的摘要内容
+ * 仅当MIME_TYPE为DataConstants.NOTE时触发
*/
private static final String DATA_UPDATE_NOTE_CONTENT_ON_INSERT_TRIGGER =
- "CREATE TRIGGER update_note_content_on_insert " +
- " AFTER INSERT ON " + TABLE.DATA +
- " WHEN new." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
- " BEGIN" +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.SNIPPET + "=new." + DataColumns.CONTENT +
- " WHERE " + NoteColumns.ID + "=new." + DataColumns.NOTE_ID + ";" +
- " END";
+ "CREATE TRIGGER update_note_content_on_insert " +
+ " AFTER INSERT ON " + TABLE.DATA +
+ " WHEN new." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
+ " BEGIN" +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.SNIPPET + "=new." + DataColumns.CONTENT +
+ " WHERE " + NoteColumns.ID + "=new." + DataColumns.NOTE_ID + ";" +
+ " END";
/**
- * Update note's content when data with {@link DataConstants#NOTE} type has changed
+ * SQL 触发器：当更新类型为NOTE的数据时，更新对应笔记的摘要内容
*/
private static final String DATA_UPDATE_NOTE_CONTENT_ON_UPDATE_TRIGGER =
- "CREATE TRIGGER update_note_content_on_update " +
- " AFTER UPDATE ON " + TABLE.DATA +
- " WHEN old." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
- " BEGIN" +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.SNIPPET + "=new." + DataColumns.CONTENT +
- " WHERE " + NoteColumns.ID + "=new." + DataColumns.NOTE_ID + ";" +
- " END";
+ "CREATE TRIGGER update_note_content_on_update " +
+ " AFTER UPDATE ON " + TABLE.DATA +
+ " WHEN old." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
+ " BEGIN" +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.SNIPPET + "=new." + DataColumns.CONTENT +
+ " WHERE " + NoteColumns.ID + "=new." + DataColumns.NOTE_ID + ";" +
+ " END";
/**
- * Update note's content when data with {@link DataConstants#NOTE} type has deleted
+ * SQL 触发器：当删除类型为NOTE的数据时，清空对应笔记的摘要内容
*/
private static final String DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER =
- "CREATE TRIGGER update_note_content_on_delete " +
- " AFTER delete ON " + TABLE.DATA +
- " WHEN old." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
- " BEGIN" +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.SNIPPET + "=''" +
- " WHERE " + NoteColumns.ID + "=old." + DataColumns.NOTE_ID + ";" +
- " END";
+ "CREATE TRIGGER update_note_content_on_delete " +
+ " AFTER delete ON " + TABLE.DATA +
+ " WHEN old." + DataColumns.MIME_TYPE + "='" + DataConstants.NOTE + "'" +
+ " BEGIN" +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.SNIPPET + "=''" +
+ " WHERE " + NoteColumns.ID + "=old." + DataColumns.NOTE_ID + ";" +
+ " END";
/**
- * Delete datas belong to note which has been deleted
+ * SQL 触发器：删除笔记时，级联删除其关联的所有数据
*/
private static final String NOTE_DELETE_DATA_ON_DELETE_TRIGGER =
- "CREATE TRIGGER delete_data_on_delete " +
- " AFTER DELETE ON " + TABLE.NOTE +
- " BEGIN" +
- " DELETE FROM " + TABLE.DATA +
- " WHERE " + DataColumns.NOTE_ID + "=old." + NoteColumns.ID + ";" +
- " END";
+ "CREATE TRIGGER delete_data_on_delete " +
+ " AFTER DELETE ON " + TABLE.NOTE +
+ " BEGIN" +
+ " DELETE FROM " + TABLE.DATA +
+ " WHERE " + DataColumns.NOTE_ID + "=old." + NoteColumns.ID + ";" +
+ " END";
/**
- * Delete notes belong to folder which has been deleted
+ * SQL 触发器：删除文件夹时，级联删除其下的所有笔记
+ * 注意：这会触发delete_data_on_delete触发器，从而删除所有关联数据
*/
private static final String FOLDER_DELETE_NOTES_ON_DELETE_TRIGGER =
- "CREATE TRIGGER folder_delete_notes_on_delete " +
- " AFTER DELETE ON " + TABLE.NOTE +
- " BEGIN" +
- " DELETE FROM " + TABLE.NOTE +
- " WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
- " END";
+ "CREATE TRIGGER folder_delete_notes_on_delete " +
+ " AFTER DELETE ON " + TABLE.NOTE +
+ " BEGIN" +
+ " DELETE FROM " + TABLE.NOTE +
+ " WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
+ " END";
/**
- * Move notes belong to folder which has been moved to trash folder
+ * SQL 触发器：当文件夹被移动到回收站时，将其下的所有笔记也移动到回收站
*/
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 +
- " BEGIN" +
- " UPDATE " + TABLE.NOTE +
- " SET " + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLER +
- " WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
- " END";
+ "CREATE TRIGGER folder_move_notes_on_trash " +
+ " AFTER UPDATE ON " + TABLE.NOTE +
+ " WHEN new." + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLER +
+ " BEGIN" +
+ " UPDATE " + TABLE.NOTE +
+ " SET " + NoteColumns.PARENT_ID + "=" + Notes.ID_TRASH_FOLER +
+ " WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
+ " END";
+ /**
+ * 构造方法
+ * @param context Android上下文
+ */
public NotesDatabaseHelper(Context context) {
super(context, DB_NAME, null, DB_VERSION);
}
+ /**
+ * 创建笔记表及其相关触发器
+ * @param db SQLite数据库对象
+ */
public void createNoteTable(SQLiteDatabase db) {
db.execSQL(CREATE_NOTE_TABLE_SQL);
reCreateNoteTableTriggers(db);
@@ -217,7 +341,13 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
Log.d(TAG, "note table has been created");
}
+ /**
+ * 重建笔记表的所有触发器
+ * 先删除旧触发器（如果存在），然后创建新触发器
+ * @param db SQLite数据库对象
+ */
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");
db.execSQL("DROP TRIGGER IF EXISTS decrease_folder_count_on_delete");
@@ -226,6 +356,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.execSQL("DROP TRIGGER IF EXISTS folder_delete_notes_on_delete");
db.execSQL("DROP TRIGGER IF EXISTS folder_move_notes_on_trash");
+ // 创建新触发器
db.execSQL(NOTE_INCREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER);
db.execSQL(NOTE_DECREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER);
db.execSQL(NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER);
@@ -235,18 +366,23 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.execSQL(FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER);
}
+ /**
+ * 创建系统文件夹
+ * 包括：通话记录文件夹、根文件夹、临时文件夹、回收站
+ * @param db SQLite数据库对象
+ */
private void createSystemFolder(SQLiteDatabase db) {
ContentValues values = new ContentValues();
/**
- * call record foler for call notes
+ * 通话记录文件夹
*/
values.put(NoteColumns.ID, Notes.ID_CALL_RECORD_FOLDER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
/**
- * root folder which is default folder
+ * 根文件夹（默认文件夹）
*/
values.clear();
values.put(NoteColumns.ID, Notes.ID_ROOT_FOLDER);
@@ -254,7 +390,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.insert(TABLE.NOTE, null, values);
/**
- * temporary folder which is used for moving note
+ * 临时文件夹（用于笔记移动操作）
*/
values.clear();
values.put(NoteColumns.ID, Notes.ID_TEMPARAY_FOLDER);
@@ -262,7 +398,7 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.insert(TABLE.NOTE, null, values);
/**
- * create trash folder
+ * 回收站文件夹
*/
values.clear();
values.put(NoteColumns.ID, Notes.ID_TRASH_FOLER);
@@ -270,13 +406,22 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.insert(TABLE.NOTE, null, values);
}
+ /**
+ * 创建数据表及其相关触发器
+ * @param db SQLite数据库对象
+ */
public void createDataTable(SQLiteDatabase db) {
db.execSQL(CREATE_DATA_TABLE_SQL);
reCreateDataTableTriggers(db);
- db.execSQL(CREATE_DATA_NOTE_ID_INDEX_SQL);
+ db.execSQL(CREATE_DATA_NOTE_ID_INDEX_SQL); // 创建索引提高查询性能
Log.d(TAG, "data table has been created");
}
+ /**
+ * 重建数据表的所有触发器
+ * 先删除旧触发器（如果存在），然后创建新触发器
+ * @param db SQLite数据库对象
+ */
private void reCreateDataTableTriggers(SQLiteDatabase db) {
db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_insert");
db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_update");
@@ -287,6 +432,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER);
}
+ /**
+ * 获取单例实例（线程安全）
+ * @param context Android上下文
+ * @return NotesDatabaseHelper实例
+ */
static synchronized NotesDatabaseHelper getInstance(Context context) {
if (mInstance == null) {
mInstance = new NotesDatabaseHelper(context);
@@ -294,69 +444,103 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
return mInstance;
}
+ /**
+ * 数据库首次创建时调用
+ * 创建所有表和触发器
+ * @param db SQLite数据库对象
+ */
@Override
public void onCreate(SQLiteDatabase db) {
createNoteTable(db);
createDataTable(db);
}
+ /**
+ * 数据库版本升级时调用
+ * 处理不同版本间的数据迁移和结构变更
+ * @param db SQLite数据库对象
+ * @param oldVersion 旧版本号
+ * @param newVersion 新版本号
+ */
@Override
public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
- boolean reCreateTriggers = false;
- boolean skipV2 = false;
+ boolean reCreateTriggers = false; // 是否需要重建触发器
+ boolean skipV2 = false; // 是否跳过V2升级
+ // 从版本1升级到版本2
if (oldVersion == 1) {
upgradeToV2(db);
- skipV2 = true; // this upgrade including the upgrade from v2 to v3
+ skipV2 = true; // V1到V2的升级包含了V2到V3的内容
oldVersion++;
}
+ // 从版本2升级到版本3（如果未跳过）
if (oldVersion == 2 && !skipV2) {
upgradeToV3(db);
- reCreateTriggers = true;
+ reCreateTriggers = true; // V3升级需要重建触发器
oldVersion++;
}
+ // 从版本3升级到版本4
if (oldVersion == 3) {
upgradeToV4(db);
oldVersion++;
}
+ // 如果需要，重建所有触发器
if (reCreateTriggers) {
reCreateNoteTableTriggers(db);
reCreateDataTableTriggers(db);
}
+ // 版本号检查，确保升级完成
if (oldVersion != newVersion) {
throw new IllegalStateException("Upgrade notes database to version " + newVersion
+ "fails");
}
}
+ /**
+ * 升级到版本2：完全重建数据库
+ * @param db SQLite数据库对象
+ */
private void upgradeToV2(SQLiteDatabase db) {
+ // 删除旧表
db.execSQL("DROP TABLE IF EXISTS " + TABLE.NOTE);
db.execSQL("DROP TABLE IF EXISTS " + TABLE.DATA);
+ // 创建新表
createNoteTable(db);
createDataTable(db);
}
+ /**
+ * 升级到版本3：添加Google Task ID支持并添加回收站文件夹
+ * @param db SQLite数据库对象
+ */
private void upgradeToV3(SQLiteDatabase db) {
- // drop unused triggers
+ // 删除不再使用的触发器
db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_insert");
db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_delete");
db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_update");
- // add a column for gtask id
+
+ // 添加Google Task ID字段
db.execSQL("ALTER TABLE " + TABLE.NOTE + " ADD COLUMN " + NoteColumns.GTASK_ID
+ " TEXT NOT NULL DEFAULT ''");
- // add a trash system folder
+
+ // 添加回收站系统文件夹
ContentValues values = new ContentValues();
values.put(NoteColumns.ID, Notes.ID_TRASH_FOLER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
}
+ /**
+ * 升级到版本4：添加版本号字段
+ * @param db SQLite数据库对象
+ */
private void upgradeToV4(SQLiteDatabase db) {
+ // 添加版本号字段
db.execSQL("ALTER TABLE " + TABLE.NOTE + " ADD COLUMN " + NoteColumns.VERSION
+ " INTEGER NOT NULL DEFAULT 0");
}
-}
+}
\ No newline at end of file
diff --git a/src/data/NotesProvider.java b/src/data/NotesProvider.java
index edb0a60..e018e95 100644
--- a/src/data/NotesProvider.java
+++ b/src/data/NotesProvider.java
@@ -35,21 +35,120 @@ import net.micode.notes.data.Notes.NoteColumns;
import net.micode.notes.data.NotesDatabaseHelper.TABLE;
+/**
+ * 便签应用的Content Provider，负责处理便签数据的CRUD操作和搜索功能
+ *
+ * 核心职责：
+ *
+ * - 提供便签数据的Content Provider访问接口
+ * - 处理便签和便签详细数据的查询、插入、更新、删除操作
+ * - 支持便签搜索和搜索建议功能
+ * - 管理便签数据的版本控制
+ * - 在数据变更时通知相关组件
+ *
+ *
+ * 设计意图：
+ *
+ * - 遵循Android Content Provider设计规范，提供统一的数据访问接口
+ * - 使用UriMatcher处理不同类型的URI请求
+ * - 实现数据的封装和隔离，保护数据安全
+ * - 支持跨应用数据访问（如果需要）
+ * - 集成Android搜索框架，支持全局搜索
+ *
+ *
+ * 继承关系：
+ *
+ * - 直接继承自{@link android.content.ContentProvider}，实现标准的Content Provider接口
+ *
+ *
+ * 与其他类的关键关联：
+ *
+ * - 依赖{@link NotesDatabaseHelper}获取数据库实例，进行底层数据操作
+ * - 使用{@link Notes}类中定义的常量和URI，作为数据访问的标准
+ * - 实现{@link SearchManager}接口，支持Android全局搜索功能
+ * - 被应用的UI组件和Widget组件使用，作为数据访问的主要入口
+ *
+ *
+ * URI匹配规则：
+ *
+ * - content://micode_notes/note - 所有便签和文件夹
+ * - content://micode_notes/note/# - 单个便签或文件夹
+ * - content://micode_notes/data - 所有便签详细数据
+ * - content://micode_notes/data/# - 单个便签详细数据
+ * - content://micode_notes/search - 搜索便签
+ * - content://micode_notes/search_suggest_query - 搜索建议
+ *
+ *
+
+ */
public class NotesProvider extends ContentProvider {
+ /**
+ * UriMatcher实例，用于匹配不同类型的URI请求
+ *
+ * 用途：根据URI路径和格式，将请求分发到不同的处理逻辑
+ *
+ * 初始化：在静态代码块中初始化，添加所有支持的URI模式
+ */
private static final UriMatcher mMatcher;
+ /**
+ * 数据库辅助类实例，用于获取SQLiteDatabase对象
+ *
+ * 用途：提供底层数据库操作支持，包括创建、打开和升级数据库
+ *
+ * 初始化：在onCreate方法中通过单例模式获取实例
+ */
private NotesDatabaseHelper mHelper;
+ /**
+ * 日志标签，用于调试和日志记录
+ */
private static final String TAG = "NotesProvider";
+ /**
+ * URI类型常量：表示所有便签和文件夹的集合
+ */
private static final int URI_NOTE = 1;
+
+ /**
+ * URI类型常量：表示单个便签或文件夹
+ */
private static final int URI_NOTE_ITEM = 2;
+
+ /**
+ * URI类型常量：表示所有便签详细数据的集合
+ */
private static final int URI_DATA = 3;
+
+ /**
+ * URI类型常量：表示单个便签详细数据
+ */
private static final int URI_DATA_ITEM = 4;
+ /**
+ * URI类型常量：表示便签搜索请求
+ */
private static final int URI_SEARCH = 5;
+
+ /**
+ * URI类型常量：表示搜索建议请求
+ */
private static final int URI_SEARCH_SUGGEST = 6;
+ /**
+ * 静态代码块，初始化UriMatcher实例，添加所有支持的URI模式
+ *
+ * 注册的URI模式包括：
+ *
+ * - note - 所有便签和文件夹
+ * - note/# - 单个便签或文件夹
+ * - data - 所有便签详细数据
+ * - data/# - 单个便签详细数据
+ * - search - 便签搜索
+ * - search_suggest_query - 搜索建议
+ * - search_suggest_query/* - 带查询参数的搜索建议
+ *
+ */
static {
mMatcher = new UriMatcher(UriMatcher.NO_MATCH);
mMatcher.addURI(Notes.AUTHORITY, "note", URI_NOTE);
@@ -62,8 +161,24 @@ 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.
+ * 便签搜索的投影列定义，用于构建搜索结果
+ *
+ * 包含以下字段：
+ *
+ * - 便签ID
+ * - 搜索建议的额外数据（便签ID）
+ * - 搜索建议的文本1（便签内容，去除换行符和空格）
+ * - 搜索建议的文本2（便签内容，去除换行符和空格）
+ * - 搜索结果图标
+ * - 搜索结果的意图动作（查看）
+ * - 搜索结果的意图数据类型
+ *
+ *
+ * 特殊处理：
+ *
+ * - 使用SQLite函数TRIM和REPLACE去除便签内容中的换行符（x'0A'）和空格
+ * - 使用固定的搜索结果图标
+ *
*/
private static final String NOTES_SEARCH_PROJECTION = NoteColumns.ID + ","
+ NoteColumns.ID + " AS " + SearchManager.SUGGEST_COLUMN_INTENT_EXTRA_DATA + ","
@@ -73,18 +188,91 @@ public class NotesProvider extends ContentProvider {
+ "'" + Intent.ACTION_VIEW + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_ACTION + ","
+ "'" + Notes.TextNote.CONTENT_TYPE + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA;
+ /**
+ * 便签搜索的SQL查询语句，用于执行实际的搜索操作
+ *
+ * 查询条件：
+ *
+ * - 便签内容包含搜索关键字（LIKE ?）
+ * - 便签不在回收站中（PARENT_ID <> TRASH_FOLDER）
+ * - 便签类型为普通便签（TYPE = TYPE_NOTE）
+ *
+ *
+ * 用途：在URI_SEARCH和URI_SEARCH_SUGGEST类型的请求中执行搜索操作
+ */
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.TYPE + "=" + Notes.TYPE_NOTE;
+ /**
+ * 初始化Content Provider
+ *
+ * 业务逻辑：
+ *
+ * - 获取NotesDatabaseHelper的单例实例
+ * - 初始化数据库连接
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 调用{@link NotesDatabaseHelper#getInstance(android.content.Context)}获取数据库辅助类实例
+ *
+ *
+ * @return true 初始化成功
+ * @see android.content.ContentProvider#onCreate()
+ */
@Override
public boolean onCreate() {
mHelper = NotesDatabaseHelper.getInstance(getContext());
return true;
}
+ /**
+ * 处理查询请求，根据URI类型返回相应的Cursor对象
+ *
+ * 业务逻辑：
+ *
+ * - 根据URI类型分发到不同的查询逻辑
+ * - 获取可读数据库实例
+ * - 执行查询操作，返回Cursor对象
+ * - 为Cursor设置通知URI，以便数据变更时接收通知
+ *
+ *
+ * URI类型处理：
+ *
+ * - {@link #URI_NOTE} - 查询所有便签和文件夹
+ * - {@link #URI_NOTE_ITEM} - 查询单个便签或文件夹
+ * - {@link #URI_DATA} - 查询所有便签详细数据
+ * - {@link #URI_DATA_ITEM} - 查询单个便签详细数据
+ * - {@link #URI_SEARCH} - 执行便签搜索
+ * - {@link #URI_SEARCH_SUGGEST} - 提供搜索建议
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 使用{@link NotesDatabaseHelper#getReadableDatabase()}获取可读数据库
+ * - 使用{@link SQLiteDatabase}执行查询操作
+ * - 使用{@link SearchManager}处理搜索相关请求
+ *
+ *
+ * 特殊处理：
+ *
+ * - 搜索请求不允许指定sortOrder和projection参数
+ * - 搜索结果会去除换行符和空格，以便显示更多信息
+ * - 搜索范围不包括回收站中的便签
+ *
+ *
+ * @param uri 请求的URI
+ * @param projection 返回的列名数组
+ * @param selection 查询条件
+ * @param selectionArgs 查询条件参数
+ * @param sortOrder 排序方式
+ * @return Cursor 查询结果的Cursor对象，或null如果查询失败
+ * @throws IllegalArgumentException 如果URI无效或参数不符合要求
+ * @see android.content.ContentProvider#query(android.net.Uri, java.lang.String[], java.lang.String, java.lang.String[], java.lang.String)
+ */
@Override
public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
String sortOrder) {
@@ -147,6 +335,43 @@ public class NotesProvider extends ContentProvider {
return c;
}
+ /**
+ * 处理插入请求，根据URI类型插入数据并返回新的URI
+ *
+ * 业务逻辑：
+ *
+ * - 根据URI类型分发到不同的插入逻辑
+ * - 获取可写数据库实例
+ * - 执行插入操作，返回插入的行ID
+ * - 通知相关URI的数据变更
+ * - 返回包含新ID的URI
+ *
+ *
+ * URI类型处理：
+ *
+ * - {@link #URI_NOTE} - 插入便签或文件夹
+ * - {@link #URI_DATA} - 插入便签详细数据
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 使用{@link NotesDatabaseHelper#getWritableDatabase()}获取可写数据库
+ * - 使用{@link SQLiteDatabase}执行插入操作
+ * - 通过{@link android.content.ContentResolver#notifyChange(android.net.Uri, android.database.ContentObserver)}通知数据变更
+ *
+ *
+ * 特殊处理：
+ *
+ * - 插入数据时，记录插入的noteId和dataId
+ * - 插入成功后，通知相关URI的数据变更
+ *
+ *
+ * @param uri 请求的URI
+ * @param values 要插入的数据
+ * @return Uri 包含新插入行ID的URI
+ * @throws IllegalArgumentException 如果URI无效
+ * @see android.content.ContentProvider#insert(android.net.Uri, android.content.ContentValues)
+ */
@Override
public Uri insert(Uri uri, ContentValues values) {
SQLiteDatabase db = mHelper.getWritableDatabase();
@@ -181,6 +406,45 @@ public class NotesProvider extends ContentProvider {
return ContentUris.withAppendedId(uri, insertedId);
}
+ /**
+ * 处理删除请求，根据URI类型删除数据并返回删除的行数
+ *
+ * 业务逻辑：
+ *
+ * - 根据URI类型分发到不同的删除逻辑
+ * - 获取可写数据库实例
+ * - 执行删除操作，返回删除的行数
+ * - 通知相关URI的数据变更
+ *
+ *
+ * URI类型处理：
+ *
+ * - {@link #URI_NOTE} - 删除便签或文件夹
+ * - {@link #URI_NOTE_ITEM} - 删除单个便签或文件夹
+ * - {@link #URI_DATA} - 删除便签详细数据
+ * - {@link #URI_DATA_ITEM} - 删除单个便签详细数据
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 使用{@link NotesDatabaseHelper#getWritableDatabase()}获取可写数据库
+ * - 使用{@link SQLiteDatabase}执行删除操作
+ * - 通过{@link android.content.ContentResolver#notifyChange(android.net.Uri, android.database.ContentObserver)}通知数据变更
+ *
+ *
+ * 特殊处理：
+ *
+ * - 删除便签时，跳过ID小于等于0的系统文件夹
+ * - 删除数据时，同时通知CONTENT_NOTE_URI的数据变更
+ *
+ *
+ * @param uri 请求的URI
+ * @param selection 删除条件
+ * @param selectionArgs 删除条件参数
+ * @return int 删除的行数
+ * @throws IllegalArgumentException 如果URI无效
+ * @see android.content.ContentProvider#delete(android.net.Uri, java.lang.String, java.lang.String[])
+ */
@Override
public int delete(Uri uri, String selection, String[] selectionArgs) {
int count = 0;
@@ -227,6 +491,48 @@ public class NotesProvider extends ContentProvider {
return count;
}
+ /**
+ * 处理更新请求，根据URI类型更新数据并返回更新的行数
+ *
+ * 业务逻辑：
+ *
+ * - 根据URI类型分发到不同的更新逻辑
+ * - 获取可写数据库实例
+ * - 对于便签更新，先增加版本号
+ * - 执行更新操作，返回更新的行数
+ * - 通知相关URI的数据变更
+ *
+ *
+ * URI类型处理：
+ *
+ * - {@link #URI_NOTE} - 更新便签或文件夹
+ * - {@link #URI_NOTE_ITEM} - 更新单个便签或文件夹
+ * - {@link #URI_DATA} - 更新便签详细数据
+ * - {@link #URI_DATA_ITEM} - 更新单个便签详细数据
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 使用{@link NotesDatabaseHelper#getWritableDatabase()}获取可写数据库
+ * - 使用{@link SQLiteDatabase}执行更新操作
+ * - 调用{@link #increaseNoteVersion(long, String, String[])}增加便签版本号
+ * - 通过{@link android.content.ContentResolver#notifyChange(android.net.Uri, android.database.ContentObserver)}通知数据变更
+ *
+ *
+ * 特殊处理：
+ *
+ * - 更新便签时，自动增加版本号
+ * - 更新数据时，同时通知CONTENT_NOTE_URI的数据变更
+ *
+ *
+ * @param uri 请求的URI
+ * @param values 要更新的数据
+ * @param selection 更新条件
+ * @param selectionArgs 更新条件参数
+ * @return int 更新的行数
+ * @throws IllegalArgumentException 如果URI无效
+ * @see android.content.ContentProvider#update(android.net.Uri, android.content.ContentValues, java.lang.String, java.lang.String[])
+ */
@Override
public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) {
int count = 0;
@@ -267,10 +573,49 @@ public class NotesProvider extends ContentProvider {
return count;
}
+ /**
+ * 辅助方法，处理查询条件，将额外条件添加到现有条件中
+ *
+ * 业务逻辑：
+ *
+ * - 如果selection不为空，将其包装为" AND (selection)"格式
+ * - 否则返回空字符串
+ *
+ *
+ * @param selection 原始查询条件
+ * @return String 处理后的查询条件
+ */
private String parseSelection(String selection) {
return (!TextUtils.isEmpty(selection) ? " AND (" + selection + ')' : "");
}
+ /**
+ * 辅助方法，增加便签的版本号
+ *
+ * 业务逻辑：
+ *
+ * - 构建UPDATE语句，将版本号加1
+ * - 根据id和selection参数构建WHERE子句
+ * - 执行SQL语句，更新版本号
+ *
+ *
+ * 与其他类的交互：
+ *
+ * - 使用{@link NotesDatabaseHelper#getWritableDatabase()}获取可写数据库
+ * - 使用{@link SQLiteDatabase#execSQL(String)}执行SQL语句
+ *
+ *
+ * 特殊处理：
+ *
+ * - 直接使用字符串拼接构建SQL语句，存在SQL注入风险
+ * - 使用replaceFirst替换占位符，仅适用于简单的条件
+ * - TODO: 考虑使用PreparedStatement或参数化查询，提高安全性
+ *
+ *
+ * @param id 便签ID，-1表示更新多个便签
+ * @param selection 更新条件
+ * @param selectionArgs 更新条件参数
+ */
private void increaseNoteVersion(long id, String selection, String[] selectionArgs) {
StringBuilder sql = new StringBuilder(120);
sql.append("UPDATE ");
@@ -296,6 +641,17 @@ public class NotesProvider extends ContentProvider {
mHelper.getWritableDatabase().execSQL(sql.toString());
}
+ /**
+ * 获取URI对应的MIME类型
+ *
+ * 注意：该方法目前未实现，返回null
+ *
+ * TODO: 实现该方法，返回正确的MIME类型
+ *
+ * @param uri 请求的URI
+ * @return String URI对应的MIME类型，目前返回null
+ * @see android.content.ContentProvider#getType(android.net.Uri)
+ */
@Override
public String getType(Uri uri) {
// TODO Auto-generated method stub
diff --git a/src/gtask/data/MetaData.java b/src/gtask/data/MetaData.java
index 3a2050b..211f917 100644
--- a/src/gtask/data/MetaData.java
+++ b/src/gtask/data/MetaData.java
@@ -25,11 +25,57 @@ import org.json.JSONException;
import org.json.JSONObject;
+/**
+ *
任务元数据管理类，用于存储Google任务的元数据信息。
+ * 核心职责：
+ *
+ * - 存储和管理任务的元数据信息
+ * - 处理元数据的JSON序列化和反序列化
+ * - 管理与其他任务的关联关系
+ *
+ * 设计意图：
+ *
+ * - 继承自{@link Task}类，扩展其功能以支持元数据管理
+ * - 使用JSON格式存储元数据，便于序列化和传输
+ * - 提供元数据的设置和获取接口，简化元数据操作
+ *
+ * 关键关联：
+ *
+ * - 继承自{@link Task}类，复用任务的基本功能
+ * - 使用{@link GTaskStringUtils}提供的常量定义元数据格式
+ * - 被{@link GTaskManager}和{@link GTaskSyncService}使用，管理任务同步元数据
+ *
+ */
public class MetaData extends Task {
+ /**
+ * 日志标签。
+ * 业务含义：用于在日志中标识MetaData类的相关操作。
+ */
private final static String TAG = MetaData.class.getSimpleName();
+ /**
+ * 关联的Google任务ID。
+ * 业务含义：存储与当前元数据相关联的Google任务的唯一标识符。
+ * 约束条件：仅通过{@link #setContentByRemoteJSON(JSONObject)}方法从远程JSON数据中获取。
+ */
private String mRelatedGid = null;
+ /**
+ * 设置任务元数据信息。
+ * 业务逻辑：
+ *
+ * - 将Google任务ID添加到元数据JSON对象中
+ * - 将元数据JSON对象转换为字符串，存储到任务的notes字段中
+ * - 设置任务名称为元数据专用名称
+ *
+ * 异常处理：
+ *
+ * - 处理JSONException异常，如果添加Google任务ID失败，记录错误日志
+ *
+ *
+ * @param gid 关联的Google任务ID
+ * @param metaInfo 元数据JSON对象
+ */
public void setMeta(String gid, JSONObject metaInfo) {
try {
metaInfo.put(GTaskStringUtils.META_HEAD_GTASK_ID, gid);
@@ -40,15 +86,42 @@ public class MetaData extends Task {
setName(GTaskStringUtils.META_NOTE_NAME);
}
+ /**
+ * 获取关联的Google任务ID。
+ * 业务含义：返回与当前元数据相关联的Google任务的唯一标识符。
+ *
+ * @return 关联的Google任务ID，如果不存在则返回null
+ */
public String getRelatedGid() {
return mRelatedGid;
}
+ /**
+ * 判断元数据是否值得保存。
+ * 业务逻辑：如果元数据的notes字段不为null，则认为值得保存。
+ *
+ * @return 如果元数据值得保存则返回true，否则返回false
+ */
@Override
public boolean isWorthSaving() {
return getNotes() != null;
}
+ /**
+ * 根据远程JSON数据设置元数据内容。
+ * 业务逻辑：
+ *
+ * - 调用父类的setContentByRemoteJSON方法设置基本任务内容
+ * - 如果notes字段不为null，则解析JSON字符串获取元数据信息
+ * - 从元数据中提取关联的Google任务ID
+ *
+ * 异常处理：
+ *
+ * - 处理JSONException异常，如果解析元数据失败，记录警告日志并将mRelatedGid设置为null
+ *
+ *
+ * @param js 远程JSON数据对象
+ */
@Override
public void setContentByRemoteJSON(JSONObject js) {
super.setContentByRemoteJSON(js);
@@ -63,17 +136,42 @@ public class MetaData extends Task {
}
}
+ /**
+ * 根据本地JSON数据设置元数据内容。
+ * 业务逻辑：此方法不应被调用，直接抛出IllegalAccessError异常。
+ * 注意：MetaData类不支持从本地JSON数据设置内容。
+ *
+ * @param js 本地JSON数据对象
+ * @throws IllegalAccessError 总是抛出此异常，因为该方法不应被调用
+ */
@Override
public void setContentByLocalJSON(JSONObject js) {
// this function should not be called
throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");
}
+ /**
+ * 从元数据内容获取本地JSON对象。
+ * 业务逻辑：此方法不应被调用，直接抛出IllegalAccessError异常。
+ * 注意：MetaData类不支持获取本地JSON数据。
+ *
+ * @return 本地JSON数据对象
+ * @throws IllegalAccessError 总是抛出此异常，因为该方法不应被调用
+ */
@Override
public JSONObject getLocalJSONFromContent() {
throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called");
}
+ /**
+ * 获取元数据的同步操作类型。
+ * 业务逻辑：此方法不应被调用，直接抛出IllegalAccessError异常。
+ * 注意：MetaData类不支持获取同步操作类型。
+ *
+ * @param c 数据库游标对象
+ * @return 同步操作类型
+ * @throws IllegalAccessError 总是抛出此异常，因为该方法不应被调用
+ */
@Override
public int getSyncAction(Cursor c) {
throw new IllegalAccessError("MetaData:getSyncAction should not be called");
diff --git a/src/gtask/data/Node.java b/src/gtask/data/Node.java
index 63950e0..ea764ec 100644
--- a/src/gtask/data/Node.java
+++ b/src/gtask/data/Node.java
@@ -20,33 +20,91 @@ import android.database.Cursor;
import org.json.JSONObject;
+/**
+ * Google任务数据模型的抽象基类。
+ * 设计意图：统一定义Google任务相关数据（如任务、元数据）的核心属性和同步行为，为子类提供标准化接口。
+ * 核心职责：
+ *
+ * - 封装通用属性：Google任务ID（GID）、名称、最后修改时间、删除状态
+ * - 定义同步操作抽象方法：创建/更新动作生成、本地/远程JSON数据转换、同步动作判断
+ * - 提供同步动作常量：规范同步操作类型（无动作、添加、更新、删除、冲突等）
+ *
+ * 关键关联：
+ *
+ * - 子类需实现抽象方法以适配具体数据类型（如{@link Task}, {@link MetaData}）
+ * - 与{@link GTaskClient}配合完成Google任务服务的同步操作
+ * - 通过{@link Cursor}与本地数据库交互获取同步状态
+ *
+ */
public abstract class Node {
+ /**
+ * 无同步动作
+ */
public static final int SYNC_ACTION_NONE = 0;
+ /**
+ * 向远程添加任务
+ */
public static final int SYNC_ACTION_ADD_REMOTE = 1;
+ /**
+ * 向本地添加任务
+ */
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_LOCAL = 4;
+ /**
+ * 更新远程任务
+ */
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_CONFLICT = 7;
+ /**
+ * 同步错误状态
+ */
public static final int SYNC_ACTION_ERROR = 8;
+ /**
+ * Google任务唯一标识ID，约束条件：仅通过远程同步设置
+ */
private String mGid;
+ /**
+ * 任务名称
+ */
private String mName;
+ /**
+ * 最后修改时间戳（毫秒）
+ */
private long mLastModified;
+ /**
+ * 删除状态标记
+ */
private boolean mDeleted;
+ /**
+ * 默认构造方法，初始化默认值
+ */
public Node() {
mGid = null;
mName = "";
@@ -54,46 +112,134 @@ public abstract class Node {
mDeleted = false;
}
+ /**
+ * 生成创建动作的JSON对象。
+ * 业务逻辑：构造用于向Google任务服务添加新任务的JSON数据。
+ *
+ * @param actionId 动作ID，用于标识同步任务序列
+ * @return 创建动作的JSON对象，包含必要的元数据和内容信息
+ */
public abstract JSONObject getCreateAction(int actionId);
+ /**
+ * 生成更新动作的JSON对象。
+ * 业务逻辑：构造用于向Google任务服务更新现有任务的JSON数据。
+ *
+ * @param actionId 动作ID，用于标识同步任务序列
+ * @return 更新动作的JSON对象，包含待更新的字段和内容
+ */
public abstract JSONObject getUpdateAction(int actionId);
+ /**
+ * 从远程JSON数据解析并设置内容。
+ * 业务逻辑：将Google任务服务返回的JSON数据转换为本地对象属性。
+ *
+ * @param js 远程获取的JSON对象，包含Google任务服务返回的任务数据
+ */
public abstract void setContentByRemoteJSON(JSONObject js);
+ /**
+ * 从本地JSON数据解析并设置内容。
+ * 业务逻辑：将本地存储的JSON数据转换为对象属性。
+ *
+ * @param js 本地存储的JSON对象，包含应用内持久化的任务数据
+ */
public abstract void setContentByLocalJSON(JSONObject js);
+ /**
+ * 将当前内容转换为本地存储用的JSON对象。
+ * 业务逻辑：将对象属性转换为可持久化到本地数据库的JSON格式。
+ *
+ * @return 包含内容数据的JSON对象，用于本地持久化
+ */
public abstract JSONObject getLocalJSONFromContent();
+ /**
+ * 从数据库游标判断当前同步动作类型。
+ * 业务逻辑：比较本地数据库与远程同步状态，确定需要执行的同步操作类型。
+ * 可能的返回值：
+ *
+ * - {@link #SYNC_ACTION_NONE}：无需同步
+ * - {@link #SYNC_ACTION_ADD_REMOTE}：向远程添加
+ * - {@link #SYNC_ACTION_UPDATE_LOCAL}：更新本地
+ * - {@link #SYNC_ACTION_UPDATE_CONFLICT}：更新冲突
+ * - 等其他同步动作常量
+ *
+ *
+ *
+ * @param c 查询本地数据库得到的游标，包含任务的同步状态信息
+ * @return 同步动作类型，取值为{@link #SYNC_ACTION_NONE}至{@link #SYNC_ACTION_ERROR}
+ */
public abstract int getSyncAction(Cursor c);
+ /**
+ * 设置Google任务唯一标识ID
+ *
+ * @param gid Google任务ID
+ */
public void setGid(String gid) {
this.mGid = gid;
}
+ /**
+ * 设置任务名称
+ *
+ * @param name 任务名称
+ */
public void setName(String name) {
this.mName = name;
}
+ /**
+ * 设置最后修改时间戳
+ *
+ * @param lastModified 最后修改时间（毫秒）
+ */
public void setLastModified(long lastModified) {
this.mLastModified = lastModified;
}
+ /**
+ * 设置任务删除状态
+ *
+ * @param deleted 删除状态
+ */
public void setDeleted(boolean deleted) {
this.mDeleted = deleted;
}
+ /**
+ * 获取Google任务唯一标识ID
+ *
+ * @return Google任务ID
+ */
public String getGid() {
return this.mGid;
}
+ /**
+ * 获取任务名称
+ *
+ * @return 任务名称
+ */
public String getName() {
return this.mName;
}
+ /**
+ * 获取最后修改时间戳
+ *
+ * @return 最后修改时间（毫秒）
+ */
public long getLastModified() {
return this.mLastModified;
}
+ /**
+ * 判断任务是否已删除
+ *
+ * @return 是否已删除
+ */
public boolean getDeleted() {
return this.mDeleted;
}
diff --git a/src/gtask/data/SqlData.java b/src/gtask/data/SqlData.java
index d3ec3be..3bd6934 100644
--- a/src/gtask/data/SqlData.java
+++ b/src/gtask/data/SqlData.java
@@ -35,42 +35,103 @@ import org.json.JSONException;
import org.json.JSONObject;
+/**
+ * SQL数据操作类，用于处理便签数据的增删改查操作。
+ * 设计意图：作为Google任务同步与本地数据库之间的数据操作桥梁，封装对ContentProvider的访问。
+ * 核心职责：
+ *
+ * - 从Cursor加载数据
+ * - 与JSON数据格式的相互转换
+ * - 将数据变更提交到ContentProvider
+ * - 跟踪数据变更差异
+ *
+ */
public class SqlData {
private static final String TAG = SqlData.class.getSimpleName();
+ /**
+ * 无效ID常量
+ */
private static final int INVALID_ID = -99999;
+ /**
+ * 数据查询投影列
+ */
public static final String[] PROJECTION_DATA = new String[] {
DataColumns.ID, DataColumns.MIME_TYPE, DataColumns.CONTENT, DataColumns.DATA1,
DataColumns.DATA3
};
+ /**
+ * 数据ID列索引
+ */
public static final int DATA_ID_COLUMN = 0;
+ /**
+ * 数据MIME类型列索引
+ */
public static final int DATA_MIME_TYPE_COLUMN = 1;
+ /**
+ * 数据内容列索引
+ */
public static final int DATA_CONTENT_COLUMN = 2;
+ /**
+ * 数据内容DATA1列索引
+ */
public static final int DATA_CONTENT_DATA_1_COLUMN = 3;
+ /**
+ * 数据内容DATA3列索引
+ */
public static final int DATA_CONTENT_DATA_3_COLUMN = 4;
+ /**
+ * 内容解析器，用于访问ContentProvider
+ */
private ContentResolver mContentResolver;
+ /**
+ * 是否为新创建的数据
+ */
private boolean mIsCreate;
+ /**
+ * 数据ID
+ */
private long mDataId;
+ /**
+ * 数据MIME类型
+ */
private String mDataMimeType;
+ /**
+ * 数据内容
+ */
private String mDataContent;
+ /**
+ * 数据内容DATA1字段
+ */
private long mDataContentData1;
+ /**
+ * 数据内容DATA3字段
+ */
private String mDataContentData3;
+ /**
+ * 数据变更差异集合
+ */
private ContentValues mDiffDataValues;
+ /**
+ * 构造方法，创建新的SqlData对象。
+ *
+ * @param context 上下文对象
+ */
public SqlData(Context context) {
mContentResolver = context.getContentResolver();
mIsCreate = true;
@@ -82,6 +143,12 @@ public class SqlData {
mDiffDataValues = new ContentValues();
}
+ /**
+ * 构造方法，从Cursor创建SqlData对象。
+ *
+ * @param context 上下文对象
+ * @param c 包含数据的Cursor对象
+ */
public SqlData(Context context, Cursor c) {
mContentResolver = context.getContentResolver();
mIsCreate = false;
@@ -89,6 +156,11 @@ public class SqlData {
mDiffDataValues = new ContentValues();
}
+ /**
+ * 从Cursor加载数据到当前对象。
+ *
+ * @param c 包含数据的Cursor对象
+ */
private void loadFromCursor(Cursor c) {
mDataId = c.getLong(DATA_ID_COLUMN);
mDataMimeType = c.getString(DATA_MIME_TYPE_COLUMN);
@@ -97,6 +169,18 @@ public class SqlData {
mDataContentData3 = c.getString(DATA_CONTENT_DATA_3_COLUMN);
}
+ /**
+ * 从JSON对象设置数据内容。
+ * 业务逻辑：
+ *
+ * - 从JSON对象中提取各个字段的值
+ * - 比较当前值与新值，仅在不同时更新差异集合
+ * - 更新当前对象的字段值
+ *
+ *
+ * @param js 包含数据的JSON对象
+ * @throws JSONException 如果JSON解析失败
+ */
public void setContent(JSONObject js) throws JSONException {
long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID;
if (mIsCreate || mDataId != dataId) {
@@ -130,6 +214,18 @@ public class SqlData {
mDataContentData3 = dataContentData3;
}
+ /**
+ * 获取当前数据的JSON表示。
+ * 业务逻辑：
+ *
+ * - 检查数据是否已创建
+ * - 创建JSON对象并设置各个字段值
+ * - 返回JSON对象
+ *
+ *
+ * @return 包含数据的JSON对象，若数据未创建则返回null
+ * @throws JSONException 如果JSON创建失败
+ */
public JSONObject getContent() throws JSONException {
if (mIsCreate) {
Log.e(TAG, "it seems that we haven't created this in database yet");
@@ -144,6 +240,21 @@ public class SqlData {
return js;
}
+ /**
+ * 提交数据变更到ContentProvider。
+ * 业务逻辑：
+ *
+ * - 如果是新创建的数据，执行插入操作
+ * - 如果是已存在的数据，执行更新操作
+ * - 支持版本验证，避免并发更新冲突
+ * - 更新操作完成后清空差异集合
+ *
+ *
+ * @param noteId 所属便签ID
+ * @param validateVersion 是否验证版本
+ * @param version 版本号
+ * @throws ActionFailureException 如果操作失败
+ */
public void commit(long noteId, boolean validateVersion, long version) {
if (mIsCreate) {
@@ -183,6 +294,11 @@ public class SqlData {
mIsCreate = false;
}
+ /**
+ * 获取数据ID。
+ *
+ * @return 数据ID
+ */
public long getId() {
return mDataId;
}
diff --git a/src/gtask/data/SqlNote.java b/src/gtask/data/SqlNote.java
index 79a4095..721703c 100644
--- a/src/gtask/data/SqlNote.java
+++ b/src/gtask/data/SqlNote.java
@@ -38,11 +38,50 @@ import org.json.JSONObject;
import java.util.ArrayList;
+/**
+ * 本地便签数据操作类，用于Google任务同步时的便签元数据与内容数据管理。
+ * 核心职责：
+ *
+ * - 管理便签的元数据（如标题、类型、修改时间等）
+ * - 处理便签的内容数据集合（通过{@link SqlData}）
+ * - 实现便签数据与JSON格式的相互转换
+ * - 提供便签数据的增删改查操作
+ * - 支持版本验证以避免并发更新冲突
+ *
+ * 设计意图：
+ *
+ * - 作为Google任务同步与本地数据库之间的桥梁
+ * - 封装ContentProvider的复杂操作，提供简洁的API
+ * - 支持批量提交数据变更，提高性能
+ * - 维护数据一致性，确保元数据与内容数据同步更新
+ *
+ * 关键关联：
+ *
+ * - 使用{@link Context}访问系统ContentResolver
+ * - 使用{@link ContentProvider}进行本地数据库操作
+ * - 与{@link SqlData}协作管理便签内容
+ * - 与{@link GTaskManager}集成实现Google任务同步
+ *
+ */
public class SqlNote {
+ /**
+ * 日志标签。
+ * 业务含义：用于在日志中标识SqlNote类的相关操作，便于调试和问题追踪。
+ */
private static final String TAG = SqlNote.class.getSimpleName();
+ /**
+ * 无效ID常量。
+ * 业务含义：表示未初始化或无效的便签ID，用于边界条件判断。
+ * 取值：-99999
+ */
private static final int INVALID_ID = -99999;
+ /**
+ * 便签查询投影列。
+ * 业务含义：定义从ContentProvider查询便签数据时返回的字段集合。
+ * 包含：ID、提醒日期、背景颜色ID、创建日期、是否有附件、修改日期等关键字段。
+ */
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,76 +91,264 @@ public class SqlNote {
NoteColumns.VERSION
};
+ /**
+ * ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中ID字段的索引位置。
+ * 取值：0
+ */
public static final int ID_COLUMN = 0;
+ /**
+ * 提醒日期列索引。
+ * 业务含义：PROJECTION_NOTE数组中提醒日期字段的索引位置。
+ * 取值：1
+ */
public static final int ALERTED_DATE_COLUMN = 1;
+ /**
+ * 背景颜色ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中背景颜色ID字段的索引位置。
+ * 取值：2
+ */
public static final int BG_COLOR_ID_COLUMN = 2;
+ /**
+ * 创建日期列索引。
+ * 业务含义：PROJECTION_NOTE数组中创建日期字段的索引位置。
+ * 取值：3
+ */
public static final int CREATED_DATE_COLUMN = 3;
+ /**
+ * 是否有附件列索引。
+ * 业务含义：PROJECTION_NOTE数组中是否有附件字段的索引位置。
+ * 取值：4
+ */
public static final int HAS_ATTACHMENT_COLUMN = 4;
+ /**
+ * 修改日期列索引。
+ * 业务含义：PROJECTION_NOTE数组中修改日期字段的索引位置。
+ * 取值：5
+ */
public static final int MODIFIED_DATE_COLUMN = 5;
+ /**
+ * 便签数量列索引。
+ * 业务含义：PROJECTION_NOTE数组中便签数量字段的索引位置。
+ * 取值：6
+ */
public static final int NOTES_COUNT_COLUMN = 6;
+ /**
+ * 父ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中父ID字段的索引位置。
+ * 取值：7
+ */
public static final int PARENT_ID_COLUMN = 7;
+ /**
+ * 摘要列索引。
+ * 业务含义：PROJECTION_NOTE数组中摘要字段的索引位置。
+ * 取值：8
+ */
public static final int SNIPPET_COLUMN = 8;
+ /**
+ * 类型列索引。
+ * 业务含义：PROJECTION_NOTE数组中类型字段的索引位置。
+ * 取值：9
+ */
public static final int TYPE_COLUMN = 9;
+ /**
+ * 小组件ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中小组件ID字段的索引位置。
+ * 取值：10
+ */
public static final int WIDGET_ID_COLUMN = 10;
+ /**
+ * 小组件类型列索引。
+ * 业务含义：PROJECTION_NOTE数组中小组件类型字段的索引位置。
+ * 取值：11
+ */
public static final int WIDGET_TYPE_COLUMN = 11;
+ /**
+ * 同步ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中同步ID字段的索引位置。
+ * 取值：12
+ */
public static final int SYNC_ID_COLUMN = 12;
+ /**
+ * 本地修改列索引。
+ * 业务含义：PROJECTION_NOTE数组中本地修改字段的索引位置。
+ * 取值：13
+ */
public static final int LOCAL_MODIFIED_COLUMN = 13;
+ /**
+ * 原始父ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中原始父ID字段的索引位置。
+ * 取值：14
+ */
public static final int ORIGIN_PARENT_ID_COLUMN = 14;
+ /**
+ * Google任务ID列索引。
+ * 业务含义：PROJECTION_NOTE数组中Google任务ID字段的索引位置。
+ * 取值：15
+ */
public static final int GTASK_ID_COLUMN = 15;
+ /**
+ * 版本列索引。
+ * 业务含义：PROJECTION_NOTE数组中版本字段的索引位置。
+ * 取值：16
+ */
public static final int VERSION_COLUMN = 16;
+ /**
+ * 上下文对象。
+ * 业务含义：用于访问系统资源和ContentResolver。
+ * 使用场景：在构造函数中初始化，用于后续的ContentProvider操作。
+ */
private Context mContext;
+ /**
+ * 内容解析器。
+ * 业务含义：用于与ContentProvider进行交互，执行数据库操作。
+ * 使用场景：在构造函数中初始化，用于后续的CRUD操作。
+ */
private ContentResolver mContentResolver;
+ /**
+ * 是否为新创建的便签。
+ * 业务含义：标识当前便签对象是否已在数据库中创建。
+ * 使用场景：在构造函数中初始化，用于确定执行插入或更新操作。
+ */
private boolean mIsCreate;
+ /**
+ * 便签ID。
+ * 业务含义：便签在本地数据库中的唯一标识符。
+ * 默认值：INVALID_ID（-99999）
+ */
private long mId;
+ /**
+ * 提醒日期。
+ * 业务含义：便签的提醒时间戳。
+ * 默认值：0（表示无提醒）
+ */
private long mAlertDate;
+ /**
+ * 背景颜色ID。
+ * 业务含义：便签的背景颜色资源ID。
+ * 默认值：通过ResourceParser.getDefaultBgId(context)获取
+ */
private int mBgColorId;
+ /**
+ * 创建日期。
+ * 业务含义：便签创建的时间戳。
+ * 默认值：当前系统时间
+ */
private long mCreatedDate;
+ /**
+ * 是否有附件。
+ * 业务含义：标识便签是否包含附件。
+ * 取值：0（无附件）或1（有附件）
+ * 默认值：0
+ */
private int mHasAttachment;
+ /**
+ * 修改日期。
+ * 业务含义：便签最后一次修改的时间戳。
+ * 默认值：当前系统时间
+ */
private long mModifiedDate;
+ /**
+ * 父便签ID。
+ * 业务含义：便签所属的父文件夹ID。
+ * 默认值：0（表示根目录）
+ */
private long mParentId;
+ /**
+ * 便签摘要。
+ * 业务含义：便签的标题或简短描述。
+ * 默认值：空字符串
+ */
private String mSnippet;
+ /**
+ * 便签类型。
+ * 业务含义：便签的类型（如普通便签、文件夹等）。
+ * 默认值：Notes.TYPE_NOTE
+ */
private int mType;
+ /**
+ * 小组件ID。
+ * 业务含义：关联的桌面小组件ID。
+ * 默认值：AppWidgetManager.INVALID_APPWIDGET_ID
+ */
private int mWidgetId;
+ /**
+ * 小组件类型。
+ * 业务含义：关联的桌面小组件类型。
+ * 默认值：Notes.TYPE_WIDGET_INVALIDE
+ */
private int mWidgetType;
+ /**
+ * 原始父便签ID。
+ * 业务含义：便签原始所属的父文件夹ID，用于同步操作。
+ * 默认值：0
+ */
private long mOriginParent;
+ /**
+ * 版本号。
+ * 业务含义：便签的版本号，用于并发更新冲突检测。
+ * 默认值：0
+ */
private long mVersion;
+ /**
+ * 便签元数据变更集合。
+ * 业务含义：存储便签元数据的变更内容，用于批量更新。
+ * 使用场景：在setContent方法中记录变更，在commit方法中提交变更。
+ */
private ContentValues mDiffNoteValues;
+ /**
+ * 便签内容数据集合。
+ * 业务含义：存储便签的内容数据列表。
+ * 使用场景：与SqlData类协作，管理便签的具体内容。
+ */
private ArrayList mDataList;
+ /**
+ * 创建一个新的SqlNote实例。
+ * 功能：初始化一个新的便签对象，设置默认值。
+ * 业务逻辑：
+ *
+ * - 设置mIsCreate为true，表示这是一个新创建的便签
+ * - 初始化所有字段为默认值
+ * - 创建空的变更集合和数据列表
+ *
+ *
+ * @param context 上下文对象，用于访问系统资源和ContentResolver
+ */
public SqlNote(Context context) {
mContext = context;
mContentResolver = context.getContentResolver();
@@ -143,6 +370,20 @@ public class SqlNote {
mDataList = new ArrayList();
}
+ /**
+ * 从Cursor创建SqlNote实例。
+ * 功能：从数据库查询结果创建便签对象。
+ * 业务逻辑：
+ *
+ * - 设置mIsCreate为false，表示这是一个已存在的便签
+ * - 从Cursor加载便签数据
+ * - 如果是普通便签，加载便签内容
+ * - 创建空的变更集合
+ *
+ *
+ * @param context 上下文对象，用于访问系统资源和ContentResolver
+ * @param c 查询结果Cursor，包含便签的元数据
+ */
public SqlNote(Context context, Cursor c) {
mContext = context;
mContentResolver = context.getContentResolver();
@@ -154,6 +395,20 @@ public class SqlNote {
mDiffNoteValues = new ContentValues();
}
+ /**
+ * 通过ID创建SqlNote实例。
+ * 功能：根据便签ID从数据库加载便签对象。
+ * 业务逻辑：
+ *
+ * - 设置mIsCreate为false，表示这是一个已存在的便签
+ * - 根据ID查询数据库并加载便签数据
+ * - 如果是普通便签，加载便签内容
+ * - 创建空的变更集合
+ *
+ *
+ * @param context 上下文对象，用于访问系统资源和ContentResolver
+ * @param id 便签ID，用于从数据库加载便签数据
+ */
public SqlNote(Context context, long id) {
mContext = context;
mContentResolver = context.getContentResolver();
@@ -163,7 +418,6 @@ public class SqlNote {
if (mType == Notes.TYPE_NOTE)
loadDataContent();
mDiffNoteValues = new ContentValues();
-
}
private void loadFromCursor(long id) {
diff --git a/src/gtask/data/Task.java b/src/gtask/data/Task.java
index 6a19454..49c23b2 100644
--- a/src/gtask/data/Task.java
+++ b/src/gtask/data/Task.java
@@ -32,19 +32,55 @@ import org.json.JSONException;
import org.json.JSONObject;
+/**
+ * Google任务类，继承自{@link Node}抽象类。
+ * 设计意图：实现Google任务的具体数据模型和同步操作，处理任务的创建、更新、删除等功能。
+ * 核心职责：
+ *
+ * - 封装Google任务的特有属性：完成状态、备注、元信息、兄弟任务关系、父子任务关系
+ * - 实现同步操作方法：生成创建/更新动作、解析本地/远程JSON数据、判断同步动作类型
+ * - 提供任务关系管理：设置父任务列表、前一个兄弟任务
+ * - 实现任务元信息管理：设置和解析任务的元数据
+ *
+ * 关键关联：
+ *
+ * - 继承自{@link Node}抽象类，实现Google任务数据模型的标准化接口
+ * - 与{@link TaskList}类关联，任务必须属于某个任务列表
+ * - 与{@link MetaData}类关联，管理任务的元信息
+ * - 与{@link GTaskStringUtils}类配合使用，处理Google任务的JSON字段名
+ *
+ */
public class Task extends Node {
private static final String TAG = Task.class.getSimpleName();
+ /**
+ * 任务完成状态标记
+ */
private boolean mCompleted;
+ /**
+ * 任务备注信息
+ */
private String mNotes;
+ /**
+ * 任务元信息JSON对象，包含本地任务的详细信息
+ */
private JSONObject mMetaInfo;
+ /**
+ * 前一个兄弟任务，用于维护任务的顺序
+ */
private Task mPriorSibling;
+ /**
+ * 父任务列表，任务所属的任务列表
+ */
private TaskList mParent;
+ /**
+ * 默认构造方法，初始化任务属性
+ */
public Task() {
super();
mCompleted = false;
@@ -54,6 +90,26 @@ public class Task extends Node {
mMetaInfo = null;
}
+ /**
+ * 生成创建任务的JSON动作对象。
+ * 业务逻辑：构造用于向Google任务服务添加新任务的JSON数据，包含任务的基本信息和关系。
+ * JSON结构说明：
+ *
+ * - action_type: 动作类型，固定为"create"
+ * - action_id: 动作ID，用于标识同步任务序列
+ * - index: 任务在父列表中的位置索引
+ * - entity_delta: 任务实体信息，包含任务名称、创建者ID、实体类型、备注等
+ * - parent_id: 父任务列表ID
+ * - dest_parent_type: 目标父类型，固定为"group"
+ * - list_id: 任务列表ID
+ * - prior_sibling_id: 前一个兄弟任务ID（可选）
+ *
+ *
+ *
+ * @param actionId 动作ID，用于标识同步任务序列
+ * @return 创建动作的JSON对象，包含任务创建所需的所有信息
+ * @throws ActionFailureException 如果生成JSON对象失败，抛出此异常
+ */
public JSONObject getCreateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -103,6 +159,22 @@ public class Task extends Node {
return js;
}
+ /**
+ * 生成更新任务的JSON动作对象。
+ * 业务逻辑：构造用于向Google任务服务更新现有任务的JSON数据，包含任务的更新信息。
+ * JSON结构说明：
+ *
+ * - action_type: 动作类型，固定为"update"
+ * - action_id: 动作ID，用于标识同步任务序列
+ * - id: 任务ID，标识要更新的任务
+ * - entity_delta: 任务实体更新信息，包含任务名称、备注、删除状态等
+ *
+ *
+ *
+ * @param actionId 动作ID，用于标识同步任务序列
+ * @return 更新动作的JSON对象，包含任务更新所需的所有信息
+ * @throws ActionFailureException 如果生成JSON对象失败，抛出此异常
+ */
public JSONObject getUpdateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -135,6 +207,23 @@ public class Task extends Node {
return js;
}
+ /**
+ * 从远程JSON数据解析并设置任务内容。
+ * 业务逻辑：将Google任务服务返回的JSON数据转换为任务对象的属性值。
+ * 解析的JSON字段：
+ *
+ * - id: 任务ID，设置为GID
+ * - last_modified: 最后修改时间戳
+ * - name: 任务名称
+ * - notes: 任务备注
+ * - deleted: 删除状态
+ * - completed: 完成状态
+ *
+ *
+ *
+ * @param js 远程获取的JSON对象，包含Google任务服务返回的任务数据
+ * @throws ActionFailureException 如果解析JSON对象失败，抛出此异常
+ */
public void setContentByRemoteJSON(JSONObject js) {
if (js != null) {
try {
@@ -175,6 +264,18 @@ public class Task extends Node {
}
}
+ /**
+ * 从本地JSON数据解析并设置任务内容。
+ * 业务逻辑：将本地存储的JSON数据转换为任务对象的属性值。
+ * 解析的JSON结构：
+ *
+ * - meta_note: 包含笔记类型信息
+ * - meta_data: 包含笔记内容数组，其中MIME类型为NOTE的数据项的内容被设置为任务名称
+ *
+ *
+ *
+ * @param js 本地存储的JSON对象，包含应用内持久化的任务数据
+ */
public void setContentByLocalJSON(JSONObject js) {
if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)
|| !js.has(GTaskStringUtils.META_HEAD_DATA)) {
@@ -204,6 +305,24 @@ public class Task extends Node {
}
}
+ /**
+ * 从任务内容生成本地JSON对象。
+ * 业务逻辑：根据任务名称和元信息生成本地存储所需的JSON数据结构。
+ * JSON结构说明：
+ *
+ * - meta_note: 包含笔记类型信息
+ * - meta_data: 包含笔记内容数组，其中MIME类型为NOTE的数据项存储任务名称
+ *
+ *
+ * 处理流程：
+ *
+ * - 如果没有元信息，生成新的JSON结构（适用于从Web创建的新任务）
+ * - 如果有元信息，更新现有结构中的任务名称（适用于已同步的任务）
+ *
+ *
+ *
+ * @return 本地存储的JSON对象，包含任务的完整数据结构
+ */
public JSONObject getLocalJSONFromContent() {
String name = getName();
try {
@@ -247,6 +366,19 @@ public class Task extends Node {
}
}
+ /**
+ * 设置任务的元信息。
+ * 业务逻辑：从MetaData对象中解析JSON字符串，获取任务的元信息。
+ * 处理流程：
+ *
+ * - 检查MetaData对象及其notes字段是否为空
+ * - 将notes字段的JSON字符串解析为JSONObject
+ * - 如果解析失败，将元信息设置为null
+ *
+ *
+ *
+ * @param metaData 包含元信息的MetaData对象
+ */
public void setMetaInfo(MetaData metaData) {
if (metaData != null && metaData.getNotes() != null) {
try {
@@ -258,6 +390,30 @@ public class Task extends Node {
}
}
+ /**
+ * 获取同步动作类型。
+ * 业务逻辑：通过比较本地任务和远程任务的状态，确定需要执行的同步动作。
+ * 同步动作类型说明：
+ *
+ * - {@link Node#SYNC_ACTION_NONE}: 无同步动作，本地和远程数据一致
+ * - {@link Node#SYNC_ACTION_UPDATE_LOCAL}: 更新本地数据，应用远程变更
+ * - {@link Node#SYNC_ACTION_UPDATE_REMOTE}: 更新远程数据，应用本地变更
+ * - {@link Node#SYNC_ACTION_UPDATE_CONFLICT}: 同步冲突，本地和远程都有变更
+ * - {@link Node#SYNC_ACTION_ERROR}: 同步错误，数据验证失败
+ *
+ *
+ * 处理流程：
+ *
+ * - 验证元信息和笔记ID的有效性
+ * - 比较本地和远程的最后修改时间
+ * - 检查本地修改标记和GTASK ID的一致性
+ * - 根据比较结果返回相应的同步动作类型
+ *
+ *
+ *
+ * @param c 包含本地任务数据的游标对象
+ * @return 同步动作类型，对应Node类中定义的SYNC_ACTION_*常量
+ */
public int getSyncAction(Cursor c) {
try {
JSONObject noteInfo = null;
@@ -311,39 +467,92 @@ public class Task extends Node {
return SYNC_ACTION_ERROR;
}
+ /**
+ * 判断任务是否值得保存。
+ * 业务逻辑：检查任务是否包含有价值的信息，用于决定是否需要保存到数据库或同步到远程。
+ * 判断条件：满足以下任一条件则认为值得保存：
+ *
+ * - 任务包含元信息（mMetaInfo不为null）
+ * - 任务名称不为空且长度大于0
+ * - 任务备注不为空且长度大于0
+ *
+ *
+ *
+ * @return true表示任务值得保存，false表示任务为空或无价值信息
+ */
public boolean isWorthSaving() {
return mMetaInfo != null || (getName() != null && getName().trim().length() > 0)
|| (getNotes() != null && getNotes().trim().length() > 0);
}
+ /**
+ * 设置任务的完成状态。
+ *
+ * @param completed 任务的完成状态，true表示已完成，false表示未完成
+ */
public void setCompleted(boolean completed) {
this.mCompleted = completed;
}
+ /**
+ * 设置任务的备注信息。
+ *
+ * @param notes 任务的备注信息字符串
+ */
public void setNotes(String notes) {
this.mNotes = notes;
}
+ /**
+ * 设置任务的前一个兄弟任务，用于维护任务的顺序。
+ *
+ * @param priorSibling 前一个兄弟任务对象
+ */
public void setPriorSibling(Task priorSibling) {
this.mPriorSibling = priorSibling;
}
+ /**
+ * 设置任务的父任务列表。
+ *
+ * @param parent 父任务列表对象
+ */
public void setParent(TaskList parent) {
this.mParent = parent;
}
+ /**
+ * 获取任务的完成状态。
+ *
+ * @return 任务的完成状态，true表示已完成，false表示未完成
+ */
public boolean getCompleted() {
return this.mCompleted;
}
+ /**
+ * 获取任务的备注信息。
+ *
+ * @return 任务的备注信息字符串
+ */
public String getNotes() {
return this.mNotes;
}
+ /**
+ * 获取任务的前一个兄弟任务。
+ *
+ * @return 前一个兄弟任务对象，如果没有则返回null
+ */
public Task getPriorSibling() {
return this.mPriorSibling;
}
+ /**
+ * 获取任务的父任务列表。
+ *
+ * @return 父任务列表对象，如果没有则返回null
+ */
public TaskList getParent() {
return this.mParent;
}
diff --git a/src/gtask/data/TaskList.java b/src/gtask/data/TaskList.java
index 4ea21c5..5ff7438 100644
--- a/src/gtask/data/TaskList.java
+++ b/src/gtask/data/TaskList.java
@@ -30,19 +30,53 @@ import org.json.JSONObject;
import java.util.ArrayList;
+/**
+ * Google任务列表的数据模型类，继承自Node类。
+ *
+ * 负责管理任务列表的元数据信息和子任务集合，支持与Google Tasks服务的同步操作。
+ * 主要功能包括：
+ *
+ * - 生成创建/更新任务列表的JSON动作对象
+ * - 从本地/远程JSON数据加载任务列表内容
+ * - 管理子任务集合（添加、删除、移动、查找）
+ * - 确定同步动作类型
+ *
+ *
+ */
public class TaskList extends Node {
private static final String TAG = TaskList.class.getSimpleName();
+ /**
+ * 任务列表在Google任务中的索引位置，用于排序
+ */
private int mIndex;
+ /**
+ * 子任务集合，存储该任务列表下的所有任务对象
+ */
private ArrayList mChildren;
+ /**
+ * 构造函数，初始化任务列表对象
+ *
+ * 创建空的子任务集合，并将索引初始化为1
+ *
+ */
public TaskList() {
super();
mChildren = new ArrayList();
mIndex = 1;
}
+ /**
+ * 生成创建任务列表的JSON动作对象
+ *
+ * 用于向Google Tasks服务发送创建任务列表的请求
+ *
+ * @param actionId 动作ID，用于标识该创建操作
+ * @return 创建任务列表的JSON对象
+ * @throws ActionFailureException 如果生成JSON对象失败
+ */
public JSONObject getCreateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -74,6 +108,15 @@ public class TaskList extends Node {
return js;
}
+ /**
+ * 生成更新任务列表的JSON动作对象
+ *
+ * 用于向Google Tasks服务发送更新任务列表的请求
+ *
+ * @param actionId 动作ID，用于标识该更新操作
+ * @return 更新任务列表的JSON对象
+ * @throws ActionFailureException 如果生成JSON对象失败
+ */
public JSONObject getUpdateAction(int actionId) {
JSONObject js = new JSONObject();
@@ -103,6 +146,14 @@ public class TaskList extends Node {
return js;
}
+ /**
+ * 从远程JSON数据加载任务列表内容
+ *
+ * 将Google Tasks服务返回的JSON数据解析到当前任务列表对象中
+ *
+ * @param js 包含任务列表信息的JSON对象
+ * @throws ActionFailureException 如果解析JSON对象失败
+ */
public void setContentByRemoteJSON(JSONObject js) {
if (js != null) {
try {
@@ -129,6 +180,13 @@ public class TaskList extends Node {
}
}
+ /**
+ * 从本地JSON数据加载任务列表内容
+ *
+ * 将本地数据库中的JSON数据解析到当前任务列表对象中
+ *
+ * @param js 包含本地任务列表信息的JSON对象
+ */
public void setContentByLocalJSON(JSONObject js) {
if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)) {
Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
@@ -157,6 +215,13 @@ public class TaskList extends Node {
}
}
+ /**
+ * 将任务列表内容转换为本地JSON格式
+ *
+ * 生成用于存储到本地数据库的JSON对象
+ *
+ * @return 包含任务列表本地信息的JSON对象，解析失败时返回null
+ */
public JSONObject getLocalJSONFromContent() {
try {
JSONObject js = new JSONObject();
@@ -183,6 +248,20 @@ public class TaskList extends Node {
}
}
+ /**
+ * 根据本地数据库游标确定同步动作类型
+ *
+ * 比较本地和远程数据的状态，决定执行哪种同步操作
+ *
+ * @param c 本地数据库游标，包含任务列表的本地状态信息
+ * @return 同步动作类型，可能的值：
+ *
+ * - {@link Node#SYNC_ACTION_NONE} - 无需同步
+ * - {@link Node#SYNC_ACTION_UPDATE_LOCAL} - 更新本地数据
+ * - {@link Node#SYNC_ACTION_UPDATE_REMOTE} - 更新远程数据
+ * - {@link Node#SYNC_ACTION_ERROR} - 同步错误
+ *
+ */
public int getSyncAction(Cursor c) {
try {
if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
@@ -216,10 +295,22 @@ public class TaskList extends Node {
return SYNC_ACTION_ERROR;
}
+ /**
+ * 获取子任务数量
+ * @return 子任务集合的大小
+ */
public int getChildTaskCount() {
return mChildren.size();
}
+ /**
+ * 添加子任务到任务列表末尾
+ *
+ * 设置任务的前一个兄弟任务和父任务列表
+ *
+ * @param task 要添加的子任务对象
+ * @return true if the task was added successfully, false otherwise
+ */
public boolean addChildTask(Task task) {
boolean ret = false;
if (task != null && !mChildren.contains(task)) {
@@ -234,6 +325,15 @@ public class TaskList extends Node {
return ret;
}
+ /**
+ * 在指定索引位置添加子任务
+ *
+ * 更新相关任务的前一个兄弟任务引用
+ *
+ * @param task 要添加的子任务对象
+ * @param index 要添加的位置索引
+ * @return true if the task was added successfully, false otherwise
+ */
public boolean addChildTask(Task task, int index) {
if (index < 0 || index > mChildren.size()) {
Log.e(TAG, "add child task: invalid index");
@@ -260,6 +360,14 @@ public class TaskList extends Node {
return true;
}
+ /**
+ * 从任务列表中移除指定的子任务
+ *
+ * 重置被移除任务的前一个兄弟任务和父任务列表引用
+ *
+ * @param task 要移除的子任务对象
+ * @return true if the task was removed successfully, false otherwise
+ */
public boolean removeChildTask(Task task) {
boolean ret = false;
int index = mChildren.indexOf(task);
@@ -281,6 +389,15 @@ public class TaskList extends Node {
return ret;
}
+ /**
+ * 移动子任务到新的索引位置
+ *
+ * 通过先移除后添加的方式实现移动操作
+ *
+ * @param task 要移动的子任务对象
+ * @param index 新的位置索引
+ * @return true if the task was moved successfully, false otherwise
+ */
public boolean moveChildTask(Task task, int index) {
if (index < 0 || index >= mChildren.size()) {
@@ -299,6 +416,11 @@ public class TaskList extends Node {
return (removeChildTask(task) && addChildTask(task, index));
}
+ /**
+ * 根据Google任务ID查找子任务
+ * @param gid Google任务ID
+ * @return 找到的任务对象，未找到时返回null
+ */
public Task findChildTaskByGid(String gid) {
for (int i = 0; i < mChildren.size(); i++) {
Task t = mChildren.get(i);
@@ -309,10 +431,20 @@ public class TaskList extends Node {
return null;
}
+ /**
+ * 获取子任务在列表中的索引位置
+ * @param task 子任务对象
+ * @return 子任务的索引位置，未找到时返回-1
+ */
public int getChildTaskIndex(Task task) {
return mChildren.indexOf(task);
}
+ /**
+ * 根据索引位置获取子任务
+ * @param index 子任务的索引位置
+ * @return 对应的任务对象，索引无效时返回null
+ */
public Task getChildTaskByIndex(int index) {
if (index < 0 || index >= mChildren.size()) {
Log.e(TAG, "getTaskByIndex: invalid index");
@@ -321,6 +453,14 @@ public class TaskList extends Node {
return mChildren.get(index);
}
+ /**
+ * 根据Google任务ID查找子任务
+ *
+ * 与{@link #findChildTaskByGid(String)}功能相同，是该方法的别名
+ *
+ * @param gid Google任务ID
+ * @return 找到的任务对象，未找到时返回null
+ */
public Task getChilTaskByGid(String gid) {
for (Task task : mChildren) {
if (task.getGid().equals(gid))
@@ -329,14 +469,26 @@ public class TaskList extends Node {
return null;
}
+ /**
+ * 获取所有子任务的集合
+ * @return 子任务集合的引用
+ */
public ArrayList getChildTaskList() {
return this.mChildren;
}
+ /**
+ * 设置任务列表的索引位置
+ * @param index 新的索引位置
+ */
public void setIndex(int index) {
this.mIndex = index;
}
+ /**
+ * 获取任务列表的索引位置
+ * @return 当前索引位置
+ */
public int getIndex() {
return this.mIndex;
}
diff --git a/src/gtask/exception/ActionFailureException.java b/src/gtask/exception/ActionFailureException.java
index 15504be..4574dbb 100644
--- a/src/gtask/exception/ActionFailureException.java
+++ b/src/gtask/exception/ActionFailureException.java
@@ -16,17 +16,37 @@
package net.micode.notes.gtask.exception;
+/**
+ * Google任务操作失败异常类。
+ * 设计意图：用于表示Google任务相关操作（如创建、更新、删除等）执行失败的情况。
+ * 核心职责：封装Google任务操作失败的异常信息，提供多种构造方式以适应不同的错误场景。
+ * 关键关联：继承自{@link RuntimeException}，属于非检查型异常，用于表示可恢复的操作失败。
+ */
public class ActionFailureException extends RuntimeException {
private static final long serialVersionUID = 4425249765923293627L;
+ /**
+ * 默认构造方法，创建一个空的操作失败异常。
+ */
public ActionFailureException() {
super();
}
+ /**
+ * 使用指定的错误信息创建操作失败异常。
+ *
+ * @param paramString 错误信息字符串，描述操作失败的原因
+ */
public ActionFailureException(String paramString) {
super(paramString);
}
+ /**
+ * 使用指定的错误信息和根原因创建操作失败异常。
+ *
+ * @param paramString 错误信息字符串，描述操作失败的原因
+ * @param paramThrowable 根原因异常，包含导致操作失败的详细错误信息
+ */
public ActionFailureException(String paramString, Throwable paramThrowable) {
super(paramString, paramThrowable);
}
diff --git a/src/gtask/exception/NetworkFailureException.java b/src/gtask/exception/NetworkFailureException.java
index b08cfb1..05924cf 100644
--- a/src/gtask/exception/NetworkFailureException.java
+++ b/src/gtask/exception/NetworkFailureException.java
@@ -16,17 +16,37 @@
package net.micode.notes.gtask.exception;
+/**
+ * 网络连接失败异常类。
+ * 设计意图：用于表示与Google任务服务通信时网络连接失败的情况。
+ * 核心职责：封装网络连接失败的异常信息，提供多种构造方式以适应不同的错误场景。
+ * 关键关联：继承自{@link Exception}，属于检查型异常，用于表示需要显式处理的网络问题。
+ */
public class NetworkFailureException extends Exception {
private static final long serialVersionUID = 2107610287180234136L;
+ /**
+ * 默认构造方法，创建一个空的网络失败异常。
+ */
public NetworkFailureException() {
super();
}
+ /**
+ * 使用指定的错误信息创建网络失败异常。
+ *
+ * @param paramString 错误信息字符串，描述网络失败的原因
+ */
public NetworkFailureException(String paramString) {
super(paramString);
}
+ /**
+ * 使用指定的错误信息和根原因创建网络失败异常。
+ *
+ * @param paramString 错误信息字符串，描述网络失败的原因
+ * @param paramThrowable 根原因异常，包含导致网络失败的详细错误信息
+ */
public NetworkFailureException(String paramString, Throwable paramThrowable) {
super(paramString, paramThrowable);
}
diff --git a/src/gtask/remote/GTaskASyncTask.java b/src/gtask/remote/GTaskASyncTask.java
index b3b61e7..ed7d6c0 100644
--- a/src/gtask/remote/GTaskASyncTask.java
+++ b/src/gtask/remote/GTaskASyncTask.java
@@ -28,23 +28,68 @@ import net.micode.notes.R;
import net.micode.notes.ui.NotesListActivity;
import net.micode.notes.ui.NotesPreferenceActivity;
-
+/**
+ * Google任务异步同步任务类。
+ * 设计意图：使用AsyncTask实现Google任务的异步同步操作，避免阻塞主线程，并提供用户友好的通知反馈。
+ * 核心职责：
+ *
+ * - 在后台线程执行Google任务的同步操作
+ * - 显示同步进度和结果的通知
+ * - 处理同步完成后的回调
+ * - 支持取消同步操作
+ *
+ * 关键关联：
+ *
+ * - 继承自{@link AsyncTask}，实现异步任务框架
+ * - 使用{@link GTaskManager}执行实际的同步逻辑
+ * - 与{@link GTaskSyncService}配合，支持服务环境下的广播通知
+ * - 通过{@link OnCompleteListener}提供同步完成回调
+ *
+ */
public class GTaskASyncTask extends AsyncTask {
+ /**
+ * Google任务同步通知的唯一ID
+ */
private static int GTASK_SYNC_NOTIFICATION_ID = 5234235;
+ /**
+ * 同步完成监听器接口。
+ * 设计意图：提供Google任务同步完成后的回调机制。
+ */
public interface OnCompleteListener {
+ /**
+ * 同步完成时调用的方法
+ */
void onComplete();
}
+ /**
+ * 上下文对象，用于访问系统服务和资源
+ */
private Context mContext;
+ /**
+ * 通知管理器，用于显示同步进度和结果通知
+ */
private NotificationManager mNotifiManager;
+ /**
+ * Google任务管理器，用于执行实际的同步逻辑
+ */
private GTaskManager mTaskManager;
+ /**
+ * 同步完成监听器，用于处理同步完成后的回调
+ */
private OnCompleteListener mOnCompleteListener;
+ /**
+ * 构造方法，初始化Google任务异步同步任务。
+ *
+ * @param context 上下文对象，用于访问系统服务和资源
+ * @param listener 同步完成监听器，用于处理同步完成后的回调
+ */
public GTaskASyncTask(Context context, OnCompleteListener listener) {
mContext = context;
mOnCompleteListener = listener;
@@ -53,35 +98,81 @@ public class GTaskASyncTask extends AsyncTask {
mTaskManager = GTaskManager.getInstance();
}
+ /**
+ * 取消正在进行的同步操作。
+ */
public void cancelSync() {
mTaskManager.cancelSync();
}
+ /**
+ * 发布同步进度信息。
+ *
+ * @param message 进度信息消息
+ */
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);
+// 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 通知标题资源ID
+ * @param content 通知内容字符串
+ */
+private void showNotification(int tickerId, String content) {
+ PendingIntent pendingIntent;
+ if (tickerId != R.string.ticker_success) {
+ pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+ NotesPreferenceActivity.class), PendingIntent.FLAG_IMMUTABLE);
+ } else {
+ pendingIntent = PendingIntent.getActivity(mContext, 0, new Intent(mContext,
+ NotesListActivity.class), PendingIntent.FLAG_IMMUTABLE);
}
-
+ 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();
+ mNotifiManager.notify(GTASK_SYNC_NOTIFICATION_ID, notification);
+}
+ /**
+ * 在后台线程执行同步操作。
+ * 业务逻辑：初始化同步进度通知，调用GTaskManager执行实际的同步逻辑。
+ *
+ * @param unused 未使用的参数
+ * @return 同步结果状态码，对应GTaskManager中的STATE_*常量
+ */
@Override
protected Integer doInBackground(Void... unused) {
publishProgess(mContext.getString(R.string.sync_progress_login, NotesPreferenceActivity
@@ -89,6 +180,12 @@ public class GTaskASyncTask extends AsyncTask {
return mTaskManager.sync(mContext, this);
}
+ /**
+ * 更新同步进度。
+ * 业务逻辑：显示当前同步进度通知，如果在服务环境下，还会发送广播通知。
+ *
+ * @param progress 进度信息数组，其中第一个元素为进度消息
+ */
@Override
protected void onProgressUpdate(String... progress) {
showNotification(R.string.ticker_syncing, progress[0]);
@@ -97,6 +194,20 @@ public class GTaskASyncTask extends AsyncTask {
}
}
+ /**
+ * 处理同步结果。
+ * 业务逻辑：根据同步结果显示相应的通知，更新最后同步时间，并调用完成监听器。
+ * 同步结果处理：
+ *
+ * - STATE_SUCCESS：显示成功通知，更新最后同步时间
+ * - STATE_NETWORK_ERROR：显示网络错误通知
+ * - STATE_INTERNAL_ERROR：显示内部错误通知
+ * - STATE_SYNC_CANCELLED：显示同步取消通知
+ *
+ *
+ *
+ * @param result 同步结果状态码，对应GTaskManager中的STATE_*常量
+ */
@Override
protected void onPostExecute(Integer result) {
if (result == GTaskManager.STATE_SUCCESS) {
diff --git a/src/gtask/remote/GTaskClient.java b/src/gtask/remote/GTaskClient.java
index c67dfdf..a161ef4 100644
--- a/src/gtask/remote/GTaskClient.java
+++ b/src/gtask/remote/GTaskClient.java
@@ -61,35 +61,108 @@ import java.util.zip.Inflater;
import java.util.zip.InflaterInputStream;
+/**
+ * Google任务API客户端类。
+ * 设计意图：提供与Google任务API交互的核心功能，实现任务的创建、更新、删除等操作。
+ * 核心职责：
+ *
+ * - 处理Google账号的登录认证
+ * - 执行Google任务的CRUD操作
+ * - 管理API请求的Cookie和会话状态
+ * - 处理网络请求和响应，包括压缩数据的解压
+ * - 将本地任务模型转换为Google任务API的JSON格式
+ *
+ * 关键关联：
+ *
+ * - 与{@link GTaskManager}配合，提供任务同步的底层支持
+ * - 使用{@link Task}和{@link TaskList}类封装Google任务数据
+ * - 通过{@link NetworkFailureException}和{@link ActionFailureException}处理异常
+ * - 依赖{@link GTaskStringUtils}提供API交互所需的常量
+ *
+ * 设计特点：
+ *
+ * - 采用单例模式，确保全局只有一个Google任务API客户端实例
+ * - 实现会话管理，避免频繁登录认证
+ * - 支持批量更新操作，提高API调用效率
+ * - 处理不同类型的网络压缩格式（gzip、deflate）
+ *
+ */
public class GTaskClient {
+ /**
+ * 日志标签，用于调试和错误跟踪
+ */
private static final String TAG = GTaskClient.class.getSimpleName();
+ /**
+ * Google任务的基本URL
+ */
private static final String GTASK_URL = "https://mail.google.com/tasks/";
+ /**
+ * Google任务的GET请求URL
+ */
private static final String GTASK_GET_URL = "https://mail.google.com/tasks/ig";
+ /**
+ * Google任务的POST请求URL
+ */
private static final String GTASK_POST_URL = "https://mail.google.com/tasks/r/ig";
+ /**
+ * GTaskClient的单例实例
+ */
private static GTaskClient mInstance = null;
+ /**
+ * HTTP客户端，用于执行与Google任务API的网络请求
+ */
private DefaultHttpClient mHttpClient;
+ /**
+ * 当前使用的GET请求URL
+ */
private String mGetUrl;
+ /**
+ * 当前使用的POST请求URL
+ */
private String mPostUrl;
+ /**
+ * Google任务客户端版本号
+ */
private long mClientVersion;
+ /**
+ * 登录状态标志
+ */
private boolean mLoggedin;
+ /**
+ * 最后一次登录时间
+ */
private long mLastLoginTime;
+ /**
+ * 请求操作ID，用于跟踪API请求
+ */
private int mActionId;
+ /**
+ * 当前登录的Google账号
+ */
private Account mAccount;
+ /**
+ * 批量更新的JSON数组，用于累积多次更新操作
+ */
private JSONArray mUpdateArray;
+ /**
+ * 私有构造方法。
+ * 设计意图：实现单例模式，防止外部直接实例化。
+ * 初始化所有成员变量，设置默认值。
+ */
private GTaskClient() {
mHttpClient = null;
mGetUrl = GTASK_GET_URL;
@@ -102,6 +175,12 @@ public class GTaskClient {
mUpdateArray = null;
}
+ /**
+ * 获取GTaskClient的单例实例。
+ * 业务逻辑：使用双重检查锁定实现线程安全的单例模式。
+ *
+ * @return GTaskClient的单例实例
+ */
public static synchronized GTaskClient getInstance() {
if (mInstance == null) {
mInstance = new GTaskClient();
@@ -109,6 +188,19 @@ public class GTaskClient {
return mInstance;
}
+ /**
+ * 登录Google账号并验证Google任务API。
+ * 业务逻辑：
+ *
+ * - 检查登录状态，如果Cookie过期或账号切换则重新登录
+ * - 获取Google账号的认证令牌
+ * - 如果是自定义域名邮箱，使用自定义URL尝试登录
+ * - 如果自定义域名登录失败，使用官方URL尝试登录
+ *
+ *
+ * @param activity 当前活动的Activity，用于获取账号信息和显示认证界面
+ * @return true表示登录成功，false表示登录失败
+ */
public boolean login(Activity activity) {
// we suppose that the cookie would expire after 5 minutes
// then we need to re-login
@@ -164,6 +256,20 @@ public class GTaskClient {
return true;
}
+ /**
+ * 登录Google账号并获取认证令牌。
+ * 业务逻辑：
+ *
+ * - 获取设备上所有的Google账号
+ * - 根据设置中选择的账号名查找对应的Account对象
+ * - 使用AccountManager获取该账号的认证令牌
+ * - 如果需要，可以使现有令牌失效并重新获取
+ *
+ *
+ * @param activity 当前活动的Activity，用于获取AccountManager
+ * @param invalidateToken 是否使现有令牌失效
+ * @return 认证令牌字符串，如果获取失败则返回null
+ */
private String loginGoogleAccount(Activity activity, boolean invalidateToken) {
String authToken;
AccountManager accountManager = AccountManager.get(activity);
@@ -207,6 +313,19 @@ public class GTaskClient {
return authToken;
}
+ /**
+ * 尝试登录Google任务API。
+ * 业务逻辑：
+ *
+ * - 首先使用提供的认证令牌尝试登录
+ * - 如果登录失败，可能是令牌过期，此时使令牌失效并重新获取
+ * - 使用新的认证令牌再次尝试登录
+ *
+ *
+ * @param activity 当前活动的Activity，用于重新获取认证令牌
+ * @param authToken Google账号的认证令牌
+ * @return true表示登录成功，false表示登录失败
+ */
private boolean tryToLoginGtask(Activity activity, String authToken) {
if (!loginGtask(authToken)) {
// maybe the auth token is out of date, now let's invalidate the
@@ -225,6 +344,20 @@ public class GTaskClient {
return true;
}
+ /**
+ * 登录Google任务API的核心方法。
+ * 业务逻辑：
+ *
+ * - 配置HTTP客户端的连接和套接字超时时间
+ * - 创建Cookie存储以保存认证信息
+ * - 发送HTTP GET请求进行登录认证
+ * - 检查响应中是否包含认证Cookie
+ * - 从响应中解析出客户端版本号
+ *
+ *
+ * @param authToken Google账号的认证令牌
+ * @return true表示登录成功，false表示登录失败
+ */
private boolean loginGtask(String authToken) {
int timeoutConnection = 10000;
int timeoutSocket = 15000;
@@ -280,10 +413,22 @@ public class GTaskClient {
return true;
}
+ /**
+ * 获取操作ID。
+ * 业务逻辑：返回当前操作ID并自增，用于跟踪API请求。
+ *
+ * @return 当前操作ID
+ */
private int getActionId() {
return mActionId++;
}
+ /**
+ * 创建HTTP POST请求。
+ * 业务逻辑：配置POST请求的URL和请求头。
+ *
+ * @return 配置好的HttpPost对象
+ */
private HttpPost createHttpPost() {
HttpPost httpPost = new HttpPost(mPostUrl);
httpPost.setHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
@@ -291,6 +436,19 @@ public class GTaskClient {
return httpPost;
}
+ /**
+ * 获取HTTP响应内容。
+ * 业务逻辑：
+ *
+ * - 检查响应内容的编码方式
+ * - 如果是gzip或deflate压缩格式，进行解压处理
+ * - 将响应内容转换为字符串
+ *
+ *
+ * @param entity HTTP响应实体
+ * @return 响应内容字符串
+ * @throws IOException 如果读取或解压响应内容时发生错误
+ */
private String getResponseContent(HttpEntity entity) throws IOException {
String contentEncoding = null;
if (entity.getContentEncoding() != null) {
@@ -323,6 +481,21 @@ public class GTaskClient {
}
}
+ /**
+ * 发送POST请求到Google任务API。
+ * 业务逻辑：
+ *
+ * - 检查登录状态，未登录则抛出异常
+ * - 创建并配置HTTP POST请求
+ * - 将JSON数据转换为请求实体
+ * - 发送请求并获取响应
+ * - 将响应内容转换为JSON对象
+ *
+ *
+ * @param js 要发送的JSON对象
+ * @return 响应的JSON对象
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private JSONObject postRequest(JSONObject js) throws NetworkFailureException {
if (!mLoggedin) {
Log.e(TAG, "please login first");
@@ -360,6 +533,19 @@ public class GTaskClient {
}
}
+ /**
+ * 创建新的Google任务。
+ * 业务逻辑：
+ *
+ * - 提交当前累积的更新操作
+ * - 创建任务的JSON表示
+ * - 发送创建任务的POST请求
+ * - 从响应中获取新创建任务的GID并设置到任务对象中
+ *
+ *
+ * @param task 要创建的任务对象
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public void createTask(Task task) throws NetworkFailureException {
commitUpdate();
try {
@@ -386,6 +572,19 @@ public class GTaskClient {
}
}
+ /**
+ * 创建新的Google任务列表。
+ * 业务逻辑：
+ *
+ * - 提交当前累积的更新操作
+ * - 创建任务列表的JSON表示
+ * - 发送创建任务列表的POST请求
+ * - 从响应中获取新创建任务列表的GID并设置到任务列表对象中
+ *
+ *
+ * @param tasklist 要创建的任务列表对象
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public void createTaskList(TaskList tasklist) throws NetworkFailureException {
commitUpdate();
try {
@@ -412,6 +611,12 @@ public class GTaskClient {
}
}
+ /**
+ * 提交累积的更新操作。
+ * 业务逻辑：将累积在mUpdateArray中的所有更新操作发送到Google任务API。
+ *
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public void commitUpdate() throws NetworkFailureException {
if (mUpdateArray != null) {
try {
@@ -433,6 +638,17 @@ public class GTaskClient {
}
}
+ /**
+ * 添加节点更新操作到累积列表。
+ * 业务逻辑：
+ *
+ * - 如果累积的更新操作超过10个，先提交这些更新
+ * - 将节点的更新操作添加到累积列表中
+ *
+ *
+ * @param node 要更新的节点对象
+ * @throws NetworkFailureException 如果网络请求失败（当提交累积更新时）
+ */
public void addUpdateNode(Node node) throws NetworkFailureException {
if (node != null) {
// too many update items may result in an error
@@ -447,6 +663,21 @@ public class GTaskClient {
}
}
+ /**
+ * 移动任务到新的父任务列表或在同一列表中重新排序。
+ * 业务逻辑：
+ *
+ * - 提交当前累积的更新操作
+ * - 创建移动任务的JSON表示
+ * - 如果在同一列表内移动且不是第一个任务，设置前一个兄弟任务的ID
+ * - 发送移动任务的POST请求
+ *
+ *
+ * @param task 要移动的任务
+ * @param preParent 任务的当前父任务列表
+ * @param curParent 任务的新父任务列表
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public void moveTask(Task task, TaskList preParent, TaskList curParent)
throws NetworkFailureException {
commitUpdate();
@@ -486,6 +717,20 @@ public class GTaskClient {
}
}
+ /**
+ * 删除节点。
+ * 业务逻辑：
+ *
+ * - 提交当前累积的更新操作
+ * - 将节点标记为已删除
+ * - 创建删除节点的JSON表示
+ * - 发送删除节点的POST请求
+ * - 清空累积的更新列表
+ *
+ *
+ * @param node 要删除的节点
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public void deleteNode(Node node) throws NetworkFailureException {
commitUpdate();
try {
@@ -509,6 +754,18 @@ public class GTaskClient {
}
}
+ /**
+ * 获取所有的Google任务列表。
+ * 业务逻辑：
+ *
+ * - 检查登录状态
+ * - 发送获取任务列表的GET请求
+ * - 解析响应内容，提取任务列表数据
+ *
+ *
+ * @return 任务列表的JSON数组
+ * @throws NetworkFailureException 如果网络请求失败
+ */
public JSONArray getTaskLists() throws NetworkFailureException {
if (!mLoggedin) {
Log.e(TAG, "please login first");
diff --git a/src/gtask/remote/GTaskManager.java b/src/gtask/remote/GTaskManager.java
index d2b4082..9f76fdd 100644
--- a/src/gtask/remote/GTaskManager.java
+++ b/src/gtask/remote/GTaskManager.java
@@ -48,45 +48,121 @@ import java.util.Iterator;
import java.util.Map;
+/**
+ * Google任务同步管理器类。
+ * 设计意图：作为Google任务与本地便签之间的同步协调中心，管理同步流程和数据转换。
+ * 核心职责：
+ *
+ * - 管理Google任务的登录认证
+ * - 初始化和维护Google任务列表
+ * - 协调本地便签与Google任务之间的内容同步
+ * - 处理同步冲突和异常情况
+ * - 提供同步状态管理和取消机制
+ *
+ * 与其他类的关键关联：
+ *
+ * - 依赖{@link GTaskClient}执行与Google任务API的实际通信
+ * - 使用{@link SqlNote}进行本地便签数据的CRUD操作
+ * - 管理{@link TaskList}和{@link Task}对象的同步状态
+ * - 通过{@link MetaData}存储扩展的任务元数据
+ *
+ */
public class GTaskManager {
private static final String TAG = GTaskManager.class.getSimpleName();
+ /**
+ * 同步状态：成功
+ */
public static final int STATE_SUCCESS = 0;
+ /**
+ * 同步状态：网络错误
+ */
public static final int STATE_NETWORK_ERROR = 1;
+ /**
+ * 同步状态：内部错误
+ */
public static final int STATE_INTERNAL_ERROR = 2;
+ /**
+ * 同步状态：同步进行中
+ */
public static final int STATE_SYNC_IN_PROGRESS = 3;
+ /**
+ * 同步状态：同步已取消
+ */
public static final int STATE_SYNC_CANCELLED = 4;
+ /**
+ * GTaskManager的单例实例
+ */
private static GTaskManager mInstance = null;
+ /**
+ * 用于获取Google认证令牌的Activity上下文
+ */
private Activity mActivity;
+ /**
+ * 应用上下文
+ */
private Context mContext;
+ /**
+ * 内容解析器，用于访问本地便签数据库
+ */
private ContentResolver mContentResolver;
+ /**
+ * 同步状态标志：是否正在同步
+ */
private boolean mSyncing;
+ /**
+ * 同步取消标志：是否已取消同步
+ */
private boolean mCancelled;
+ /**
+ * Google任务列表映射表，key为任务列表的GID
+ */
private HashMap mGTaskListHashMap;
+ /**
+ * Google任务节点映射表，key为节点的GID
+ */
private HashMap mGTaskHashMap;
+ /**
+ * 元数据映射表，key为关联任务的GID
+ */
private HashMap mMetaHashMap;
+ /**
+ * 存储元数据的任务列表
+ */
private TaskList mMetaList;
+ /**
+ * 本地已删除便签的ID集合
+ */
private HashSet mLocalDeleteIdMap;
+ /**
+ * GID到本地ID的映射表
+ */
private HashMap mGidToNid;
+ /**
+ * 本地ID到GID的映射表
+ */
private HashMap mNidToGid;
+ /**
+ * 私有构造函数，初始化同步管理器的内部状态和数据结构。
+ */
private GTaskManager() {
mSyncing = false;
mCancelled = false;
@@ -99,6 +175,11 @@ public class GTaskManager {
mNidToGid = new HashMap();
}
+ /**
+ * 获取GTaskManager的单例实例。
+ *
+ * @return GTaskManager的单例实例
+ */
public static synchronized GTaskManager getInstance() {
if (mInstance == null) {
mInstance = new GTaskManager();
@@ -106,11 +187,41 @@ public class GTaskManager {
return mInstance;
}
+ /**
+ * 设置用于获取Google认证令牌的Activity上下文。
+ *
+ * @param activity 用于获取认证令牌的Activity
+ */
public synchronized void setActivityContext(Activity activity) {
// used for getting authtoken
mActivity = activity;
}
+ /**
+ * 执行Google任务与本地便签的同步操作。
+ *
+ * 业务逻辑：
+ *
+ * - 检查是否已有同步任务在进行中
+ * - 初始化同步上下文和数据结构
+ * - 登录Google任务服务
+ * - 初始化Google任务列表
+ * - 执行内容同步工作
+ * - 处理同步过程中的异常情况
+ * - 清理资源并返回同步结果状态
+ *
+ *
+ * @param context 应用上下文
+ * @param asyncTask 异步任务实例，用于发布同步进度
+ * @return 同步结果状态：
+ *
+ * - {@link #STATE_SUCCESS}：同步成功
+ * - {@link #STATE_NETWORK_ERROR}：网络错误
+ * - {@link #STATE_INTERNAL_ERROR}：内部错误
+ * - {@link #STATE_SYNC_IN_PROGRESS}：已有同步任务在进行中
+ * - {@link #STATE_SYNC_CANCELLED}：同步已取消
+ *
+ */
public int sync(Context context, GTaskASyncTask asyncTask) {
if (mSyncing) {
Log.d(TAG, "Sync is in progress");
@@ -168,6 +279,19 @@ public class GTaskManager {
return mCancelled ? STATE_SYNC_CANCELLED : STATE_SUCCESS;
}
+ /**
+ * 初始化Google任务列表，从Google服务器获取任务列表和任务数据。
+ *
+ * 业务逻辑：
+ *
+ * - 获取所有任务列表
+ * - 初始化元数据列表（如果不存在则创建）
+ * - 加载所有任务列表及其包含的任务
+ * - 将任务列表和任务数据存储到内部映射表中
+ *
+ *
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void initGTaskList() throws NetworkFailureException {
if (mCancelled)
return;
@@ -247,6 +371,21 @@ public class GTaskManager {
}
}
+ /**
+ * 执行内容同步工作，协调本地便签与Google任务之间的数据同步。
+ *
+ * 业务逻辑：
+ *
+ * - 处理本地已删除的便签
+ * - 优先同步文件夹
+ * - 同步本地存在的便签
+ * - 同步Google服务器上新增的任务
+ * - 清理本地已删除的便签
+ * - 提交更新并刷新本地同步ID
+ *
+ *
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void syncContent() throws NetworkFailureException {
int syncType;
Cursor c = null;
@@ -351,6 +490,19 @@ public class GTaskManager {
}
+ /**
+ * 同步文件夹（任务列表）数据。
+ *
+ * 业务逻辑：
+ *
+ * - 同步根文件夹
+ * - 同步通话记录文件夹
+ * - 同步本地存在的文件夹
+ * - 同步Google服务器上新增的文件夹
+ *
+ *
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void syncFolder() throws NetworkFailureException {
Cursor c = null;
String gid;
@@ -476,6 +628,21 @@ public class GTaskManager {
GTaskClient.getInstance().commitUpdate();
}
+ /**
+ * 根据同步类型执行具体的内容同步操作。
+ *
+ * 业务逻辑：
+ *
+ * - 根据同步类型执行不同的同步操作
+ * - 支持添加本地节点、添加远程节点、删除本地节点、删除远程节点、更新本地节点、更新远程节点等操作
+ * - 处理同步冲突情况
+ *
+ *
+ * @param syncType 同步类型
+ * @param node Google任务节点
+ * @param c 本地便签的游标
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void doContentSync(int syncType, Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -522,6 +689,21 @@ public class GTaskManager {
}
}
+ /**
+ * 将Google任务节点添加到本地便签数据库。
+ *
+ * 业务逻辑：
+ *
+ * - 根据节点类型创建对应的SqlNote对象
+ * - 处理JSON数据中的ID冲突
+ * - 设置节点的父ID
+ * - 创建本地节点并更新映射表
+ * - 更新元数据
+ *
+ *
+ * @param node 要添加的Google任务节点
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void addLocalNode(Node node) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -596,6 +778,21 @@ public class GTaskManager {
updateRemoteMeta(node.getGid(), sqlNote);
}
+ /**
+ * 更新本地便签数据库中的节点数据。
+ *
+ * 业务逻辑：
+ *
+ * - 创建SqlNote对象并更新内容
+ * - 设置节点的父ID
+ * - 提交更新并更新映射表
+ * - 更新元数据
+ *
+ *
+ * @param node 要更新的Google任务节点
+ * @param c 本地便签的游标
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void updateLocalNode(Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -619,6 +816,21 @@ public class GTaskManager {
updateRemoteMeta(node.getGid(), sqlNote);
}
+ /**
+ * 将本地便签添加到Google服务器。
+ *
+ * 业务逻辑：
+ *
+ * - 根据本地便签类型创建对应的Google任务或任务列表
+ * - 处理已存在的文件夹
+ * - 创建远程节点并更新本地便签的GID
+ * - 更新映射表
+ *
+ *
+ * @param node Google任务节点
+ * @param c 本地便签的游标
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void addRemoteNode(Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -692,6 +904,21 @@ public class GTaskManager {
mNidToGid.put(sqlNote.getId(), n.getGid());
}
+ /**
+ * 更新Google服务器上的节点数据。
+ *
+ * 业务逻辑：
+ *
+ * - 更新远程节点的内容
+ * - 更新元数据
+ * - 处理任务移动情况
+ * - 清除本地修改标志
+ *
+ *
+ * @param node 要更新的Google任务节点
+ * @param c 本地便签的游标
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void updateRemoteNode(Node node, Cursor c) throws NetworkFailureException {
if (mCancelled) {
return;
@@ -730,6 +957,19 @@ public class GTaskManager {
sqlNote.commit(true);
}
+ /**
+ * 更新远程服务器上的元数据。
+ *
+ * 业务逻辑：
+ *
+ * - 检查元数据是否已存在
+ * - 如果已存在则更新，否则创建新的元数据
+ *
+ *
+ * @param gid 任务的GID
+ * @param sqlNote 本地便签对象
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void updateRemoteMeta(String gid, SqlNote sqlNote) throws NetworkFailureException {
if (sqlNote != null && sqlNote.isNoteType()) {
MetaData metaData = mMetaHashMap.get(gid);
@@ -746,6 +986,17 @@ public class GTaskManager {
}
}
+ /**
+ * 刷新本地便签的同步ID。
+ *
+ * 业务逻辑：
+ *
+ * - 重新初始化Google任务列表
+ * - 更新本地便签的同步ID
+ *
+ *
+ * @throws NetworkFailureException 如果网络请求失败
+ */
private void refreshLocalSyncId() throws NetworkFailureException {
if (mCancelled) {
return;
@@ -790,10 +1041,18 @@ public class GTaskManager {
}
}
+ /**
+ * 获取当前同步账户的名称。
+ *
+ * @return 当前同步账户的名称
+ */
public String getSyncAccount() {
return GTaskClient.getInstance().getSyncAccount().name;
}
+ /**
+ * 取消正在进行的同步操作。
+ */
public void cancelSync() {
mCancelled = true;
}
diff --git a/src/gtask/remote/GTaskSyncService.java b/src/gtask/remote/GTaskSyncService.java
index cca36f7..9b215a9 100644
--- a/src/gtask/remote/GTaskSyncService.java
+++ b/src/gtask/remote/GTaskSyncService.java
@@ -23,25 +23,81 @@ import android.content.Intent;
import android.os.Bundle;
import android.os.IBinder;
+/**
+ * Google任务同步服务类。
+ * 设计意图：作为Android服务组件，管理Google任务的同步操作，提供同步的启动和取消功能。
+ * 核心职责：
+ *
+ * - 接收同步操作的启动和取消指令
+ * - 管理异步同步任务的生命周期
+ * - 通过广播通知同步状态和进度
+ * - 处理低内存情况
+ *
+ * 与其他类的关键关联：
+ *
+ * - 使用{@link GTaskASyncTask}执行实际的同步操作
+ * - 依赖{@link GTaskManager}进行同步逻辑处理
+ * - 通过广播与UI组件通信
+ *
+ */
public class GTaskSyncService extends Service {
+ /**
+ * 操作类型的Intent extra键名
+ */
public final static String ACTION_STRING_NAME = "sync_action_type";
+ /**
+ * 启动同步操作的动作类型
+ */
public final static int ACTION_START_SYNC = 0;
+ /**
+ * 取消同步操作的动作类型
+ */
public final static int ACTION_CANCEL_SYNC = 1;
+ /**
+ * 无效的动作类型
+ */
public final static int ACTION_INVALID = 2;
+ /**
+ * 同步服务广播的名称
+ */
public final static String GTASK_SERVICE_BROADCAST_NAME = "net.micode.notes.gtask.remote.gtask_sync_service";
+ /**
+ * 广播中表示是否正在同步的extra键名
+ */
public final static String GTASK_SERVICE_BROADCAST_IS_SYNCING = "isSyncing";
+ /**
+ * 广播中表示同步进度消息的extra键名
+ */
public final static String GTASK_SERVICE_BROADCAST_PROGRESS_MSG = "progressMsg";
+ /**
+ * 当前正在执行的同步任务实例
+ */
private static GTaskASyncTask mSyncTask = null;
+ /**
+ * 当前同步进度消息
+ */
private static String mSyncProgress = "";
+ /**
+ * 启动Google任务同步操作。
+ *
+ * 业务逻辑：
+ *
+ * - 检查是否已有同步任务在执行
+ * - 如果没有，则创建新的异步同步任务
+ * - 设置任务完成监听器
+ * - 发送同步开始的广播
+ * - 执行异步同步任务
+ *
+ */
private void startSync() {
if (mSyncTask == null) {
mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
@@ -56,17 +112,49 @@ public class GTaskSyncService extends Service {
}
}
+ /**
+ * 取消正在执行的Google任务同步操作。
+ *
+ * 业务逻辑：
+ *
+ * - 检查是否有同步任务在执行
+ * - 如果有，则调用任务的取消方法
+ *
+ */
private void cancelSync() {
if (mSyncTask != null) {
mSyncTask.cancelSync();
}
}
+ /**
+ * 创建服务时的回调方法。
+ *
+ * 业务逻辑：
+ *
+ */
@Override
public void onCreate() {
mSyncTask = null;
}
+ /**
+ * 服务启动时的回调方法，处理启动服务的Intent。
+ *
+ * 业务逻辑：
+ *
+ * - 解析Intent中的操作类型
+ * - 根据操作类型执行相应的同步操作（启动或取消）
+ * - 返回START_STICKY表示服务被系统终止后会尝试重新启动
+ *
+ *
+ * @param intent 启动服务的Intent
+ * @param flags 启动标志
+ * @param startId 启动ID
+ * @return 服务的启动模式
+ */
@Override
public int onStartCommand(Intent intent, int flags, int startId) {
Bundle bundle = intent.getExtras();
@@ -86,6 +174,14 @@ public class GTaskSyncService extends Service {
return super.onStartCommand(intent, flags, startId);
}
+ /**
+ * 系统内存不足时的回调方法。
+ *
+ * 业务逻辑：
+ *
+ * - 在内存不足的情况下，取消正在执行的同步任务以释放资源
+ *
+ */
@Override
public void onLowMemory() {
if (mSyncTask != null) {
@@ -93,10 +189,33 @@ public class GTaskSyncService extends Service {
}
}
+ /**
+ * 绑定服务时的回调方法。
+ *
+ * 业务逻辑：
+ *
+ *
+ * @param intent 绑定服务的Intent
+ * @return 绑定接口，此处返回null
+ */
public IBinder onBind(Intent intent) {
return null;
}
+ /**
+ * 发送同步状态的广播。
+ *
+ * 业务逻辑：
+ *
+ * - 更新同步进度消息
+ * - 创建广播Intent并设置同步状态和进度信息
+ * - 发送广播通知UI组件同步状态的变化
+ *
+ *
+ * @param msg 同步进度消息
+ */
public void sendBroadcast(String msg) {
mSyncProgress = msg;
Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
@@ -105,6 +224,18 @@ public class GTaskSyncService extends Service {
sendBroadcast(intent);
}
+ /**
+ * 静态方法：启动Google任务同步服务。
+ *
+ * 业务逻辑：
+ *
+ * - 设置GTaskManager的Activity上下文
+ * - 创建启动服务的Intent并设置操作类型
+ * - 启动同步服务
+ *
+ *
+ * @param activity 调用该方法的Activity实例
+ */
public static void startSync(Activity activity) {
GTaskManager.getInstance().setActivityContext(activity);
Intent intent = new Intent(activity, GTaskSyncService.class);
@@ -112,16 +243,47 @@ public class GTaskSyncService extends Service {
activity.startService(intent);
}
+ /**
+ * 静态方法：取消Google任务同步服务。
+ *
+ * 业务逻辑：
+ *
+ * - 创建启动服务的Intent并设置取消操作类型
+ * - 启动同步服务以执行取消操作
+ *
+ *
+ * @param context 调用该方法的上下文
+ */
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);
}
+ /**
+ * 静态方法：检查是否正在进行同步操作。
+ *
+ * 业务逻辑：
+ *
+ * - 通过检查同步任务引用是否为null来判断同步状态
+ *
+ *
+ * @return true表示正在同步，false表示没有同步操作进行
+ */
public static boolean isSyncing() {
return mSyncTask != null;
}
+ /**
+ * 静态方法：获取当前同步进度消息。
+ *
+ * 业务逻辑：
+ *
+ *
+ * @return 当前同步进度消息
+ */
public static String getProgressString() {
return mSyncProgress;
}
diff --git a/src/model/Note.java b/src/model/Note.java
index 6706cf6..b4f190f 100644
--- a/src/model/Note.java
+++ b/src/model/Note.java
@@ -34,12 +34,61 @@ import net.micode.notes.data.Notes.TextNote;
import java.util.ArrayList;
+/**
+ * 核心笔记数据模型类，负责管理笔记的基本信息和数据变更。
+ * 设计意图：将笔记的元数据变更和具体内容数据分离管理，提高数据操作的灵活性和效率。
+ *
+ * - 通过{@link #mNoteDiffValues}跟踪笔记元数据的变更
+ * - 通过内部类{@link NoteData}管理笔记的具体内容数据（文本、通话记录等）
+ * - 提供与ContentResolver的交互接口，实现数据持久化和同步
+ *
+ * 关键关联：
+ *
+ * - 与{@link net.micode.notes.data.NotesProvider}交互，实现数据的CRUD操作
+ * - 使用{@link android.content.ContentValues}存储数据变更
+ * - 通过{@link android.content.ContentProviderOperation}执行批量数据更新
+ *
+ */
public class Note {
+ /**
+ * 存储笔记元数据的变更记录。
+ * 业务含义：记录笔记的基本信息变更，如标题、创建时间、修改时间等。
+ * 约束条件：仅包含需要更新到数据库的字段变更，不包含笔记的具体内容数据。
+ */
private ContentValues mNoteDiffValues;
+
+ /**
+ * 管理笔记的具体内容数据。
+ * 业务含义：处理笔记的文本内容、通话记录等具体数据的存储和变更。
+ */
private NoteData mNoteData;
+
+ /**
+ * 日志标签。
+ * 业务含义：用于在日志中标识Note类的相关操作。
+ */
private static final String TAG = "Note";
/**
- * Create a new note id for adding a new note to databases
+ * 生成新的笔记ID，用于向数据库添加新笔记。
+ * 业务逻辑：在数据库中创建一条新的笔记记录，返回其生成的ID。
+ * 线程安全：方法使用synchronized关键字确保在多线程环境下的安全性。
+ *
+ * @param context 上下文对象，用于获取ContentResolver
+ * @param folderId 文件夹ID，新笔记将被添加到该文件夹下
+ * @return 生成的新笔记ID
+ * @throws IllegalStateException 当生成的笔记ID为-1时抛出
+ *
+ * 跨类调用：
+ *
+ * - 通过{@link Context#getContentResolver()}获取ContentResolver
+ * - 调用{@link android.content.ContentResolver#insert(Uri, ContentValues)}向{@link Notes#CONTENT_NOTE_URI}插入新笔记
+ *
+ *
+ * 错误处理：
+ *
+ * - 捕获NumberFormatException异常，记录日志并返回0
+ * - 当生成的笔记ID为-1时，抛出IllegalStateException异常
+ *
*/
public static synchronized long getNewNoteId(Context context, long folderId) {
// Create a new note in the database
@@ -65,41 +114,143 @@ public class Note {
return noteId;
}
+ /**
+ * Note类的默认构造函数。
+ * 功能：初始化笔记的元数据变更记录和内容数据管理对象。
+ *
+ * - 初始化{@link #mNoteDiffValues}为新的ContentValues对象，用于跟踪元数据变更
+ * - 初始化{@link #mNoteData}为新的NoteData对象，用于管理具体内容数据
+ *
+ */
public Note() {
mNoteDiffValues = new ContentValues();
mNoteData = new NoteData();
}
+ /**
+ * 设置笔记的元数据字段值。
+ * 业务逻辑：更新笔记的元数据变更记录，并标记为本地已修改。
+ *
+ * @param key 元数据字段名
+ * @param value 元数据字段值
+ *
+ * 自动更新的字段：
+ *
+ * - {@link NoteColumns#LOCAL_MODIFIED}：标记为1（已修改）
+ * - {@link NoteColumns#MODIFIED_DATE}：更新为当前时间戳
+ *
+ */
public void setNoteValue(String key, String value) {
mNoteDiffValues.put(key, value);
mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
+ /**
+ * 设置笔记的文本数据字段值。
+ * 业务逻辑：通过{@link NoteData}对象更新笔记的文本内容数据。
+ *
+ * @param key 文本数据字段名
+ * @param value 文本数据字段值
+ */
public void setTextData(String key, String value) {
mNoteData.setTextData(key, value);
}
+ /**
+ * 设置笔记文本数据的ID。
+ * 业务逻辑：通过{@link NoteData}对象设置文本数据的ID。
+ *
+ * @param id 文本数据ID
+ */
public void setTextDataId(long id) {
mNoteData.setTextDataId(id);
}
+ /**
+ * 获取笔记文本数据的ID。
+ * 业务逻辑：通过{@link NoteData}对象获取文本数据的ID。
+ *
+ * @return 文本数据ID
+ */
public long getTextDataId() {
return mNoteData.mTextDataId;
}
+ /**
+ * 设置笔记通话数据的ID。
+ * 业务逻辑：通过{@link NoteData}对象设置通话数据的ID。
+ *
+ * @param id 通话数据ID
+ */
public void setCallDataId(long id) {
mNoteData.setCallDataId(id);
}
+ /**
+ * 设置笔记的通话数据字段值。
+ * 业务逻辑：通过{@link NoteData}对象更新笔记的通话记录数据。
+ *
+ * @param key 通话数据字段名
+ * @param value 通话数据字段值
+ */
public void setCallData(String key, String value) {
mNoteData.setCallData(key, value);
}
+ /**
+ * 检查笔记是否在本地已修改。
+ * 业务逻辑：判断笔记的元数据或内容数据是否发生了变更。
+ *
+ * @return true表示笔记已修改，false表示未修改
+ *
+ * 判断条件：
+ *
+ * - 元数据变更：{@link #mNoteDiffValues}的大小大于0
+ * - 内容数据变更：通过{@link NoteData#isLocalModified()}判断
+ *
+ */
public boolean isLocalModified() {
return mNoteDiffValues.size() > 0 || mNoteData.isLocalModified();
}
+ /**
+ * 将笔记的变更同步到ContentResolver。
+ * 业务逻辑：将笔记的元数据变更和内容数据变更持久化到数据库。
+ *
+ * @param context 上下文对象，用于获取ContentResolver
+ * @param noteId 笔记ID，指定要同步的笔记
+ * @return true表示同步成功，false表示同步失败
+ * @throws IllegalArgumentException 当noteId无效（<=0）时抛出
+ *
+ * 同步流程：
+ *
+ * - 检查noteId是否有效
+ * - 检查笔记是否已修改，未修改则直接返回true
+ * - 更新笔记的元数据变更到ContentResolver
+ * - 如果内容数据已修改，将其同步到ContentResolver
+ * - 返回同步结果
+ *
+ *
+ * 数据流转换：
+ *
+ * - 元数据变更：从{@link #mNoteDiffValues}转换为ContentResolver.update()的参数
+ * - 内容数据变更：通过{@link NoteData#pushIntoContentResolver(Context, long)}方法处理
+ *
+ *
+ * 错误处理：
+ *
+ * - 元数据更新失败：记录日志，但继续执行内容数据同步（为了数据安全性）
+ * - 内容数据同步失败：返回false表示同步失败
+ *
+ *
+ * 跨类调用：
+ *
+ * - 通过{@link Context#getContentResolver()}获取ContentResolver
+ * - 调用{@link android.content.ContentResolver#update(Uri, ContentValues, String, String[])}更新元数据
+ * - 调用{@link NoteData#pushIntoContentResolver(Context, long)}同步内容数据
+ *
+ */
public boolean syncNote(Context context, long noteId) {
if (noteId <= 0) {
throw new IllegalArgumentException("Wrong note id:" + noteId);
@@ -130,17 +281,65 @@ public class Note {
return true;
}
+ /**
+ * 笔记内容数据管理类，处理笔记的具体内容存储和变更。
+ * 设计意图：将笔记的内容数据与元数据分离管理，提高数据操作的灵活性和效率。
+ * 作为{@link Note}类的内部类，专门负责处理：
+ *
+ * - 笔记的文本内容数据
+ * - 笔记的通话记录数据
+ * - 内容数据的变更跟踪
+ * - 内容数据与ContentResolver的同步
+ *
+ * 关键关联：
+ *
+ * - 与{@link Note}类紧密协作，共享笔记元数据变更的跟踪
+ * - 使用{@link ContentValues}存储内容数据的变更
+ * - 通过{@link ContentProviderOperation}执行批量数据更新
+ *
+ */
private class NoteData {
+ /**
+ * 文本数据的ID。
+ * 业务含义：唯一标识笔记的文本内容数据记录。
+ * 约束条件：0表示文本数据尚未保存到数据库。
+ */
private long mTextDataId;
+ /**
+ * 存储文本数据的变更记录。
+ * 业务含义：记录笔记文本内容的变更，如正文、标题等。
+ */
private ContentValues mTextDataValues;
+ /**
+ * 通话数据的ID。
+ * 业务含义：唯一标识笔记的通话记录数据记录。
+ * 约束条件：0表示通话数据尚未保存到数据库。
+ */
private long mCallDataId;
+ /**
+ * 存储通话数据的变更记录。
+ * 业务含义：记录笔记通话记录的变更，如通话号码、通话时间等。
+ */
private ContentValues mCallDataValues;
+ /**
+ * 日志标签。
+ * 业务含义：用于在日志中标识NoteData类的相关操作。
+ */
private static final String TAG = "NoteData";
+ /**
+ * NoteData类的默认构造函数。
+ * 功能：初始化笔记内容数据的变更记录和ID。
+ *
+ * - 初始化{@link #mTextDataValues}为新的ContentValues对象
+ * - 初始化{@link #mCallDataValues}为新的ContentValues对象
+ * - 将{@link #mTextDataId}和{@link #mCallDataId}初始化为0
+ *
+ */
public NoteData() {
mTextDataValues = new ContentValues();
mCallDataValues = new ContentValues();
@@ -148,10 +347,29 @@ public class Note {
mCallDataId = 0;
}
+ /**
+ * 检查内容数据是否在本地已修改。
+ * 业务逻辑：判断文本数据或通话数据是否发生了变更。
+ *
+ * @return true表示内容数据已修改，false表示未修改
+ *
+ * 判断条件：
+ *
+ * - 文本数据变更：{@link #mTextDataValues}的大小大于0
+ * - 通话数据变更：{@link #mCallDataValues}的大小大于0
+ *
+ */
boolean isLocalModified() {
return mTextDataValues.size() > 0 || mCallDataValues.size() > 0;
}
+ /**
+ * 设置文本数据的ID。
+ * 业务逻辑：更新文本数据的唯一标识符。
+ *
+ * @param id 文本数据ID
+ * @throws IllegalArgumentException 当id无效（<=0）时抛出
+ */
void setTextDataId(long id) {
if(id <= 0) {
throw new IllegalArgumentException("Text data id should larger than 0");
@@ -159,6 +377,13 @@ public class Note {
mTextDataId = id;
}
+ /**
+ * 设置通话数据的ID。
+ * 业务逻辑：更新通话数据的唯一标识符。
+ *
+ * @param id 通话数据ID
+ * @throws IllegalArgumentException 当id无效（<=0）时抛出
+ */
void setCallDataId(long id) {
if (id <= 0) {
throw new IllegalArgumentException("Call data id should larger than 0");
@@ -166,18 +391,82 @@ public class Note {
mCallDataId = id;
}
+ /**
+ * 设置通话数据的字段值。
+ * 业务逻辑：更新通话数据的变更记录，并标记笔记为本地已修改。
+ *
+ * @param key 通话数据字段名
+ * @param value 通话数据字段值
+ *
+ * 自动更新的字段：
+ *
+ * - 通过外部类{@link Note}的{@link Note#mNoteDiffValues}更新{@link NoteColumns#LOCAL_MODIFIED}为1
+ * - 通过外部类{@link Note}的{@link Note#mNoteDiffValues}更新{@link NoteColumns#MODIFIED_DATE}为当前时间戳
+ *
+ */
void setCallData(String key, String value) {
mCallDataValues.put(key, value);
mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
+ /**
+ * 设置文本数据的字段值。
+ * 业务逻辑：更新文本数据的变更记录，并标记笔记为本地已修改。
+ *
+ * @param key 文本数据字段名
+ * @param value 文本数据字段值
+ *
+ * 自动更新的字段：
+ *
+ * - 通过外部类{@link Note}的{@link Note#mNoteDiffValues}更新{@link NoteColumns#LOCAL_MODIFIED}为1
+ * - 通过外部类{@link Note}的{@link Note#mNoteDiffValues}更新{@link NoteColumns#MODIFIED_DATE}为当前时间戳
+ *
+ */
void setTextData(String key, String value) {
mTextDataValues.put(key, value);
mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
+ /**
+ * 将内容数据的变更同步到ContentResolver。
+ * 业务逻辑：处理文本数据和通话数据的插入或更新操作。
+ *
+ * @param context 上下文对象，用于获取ContentResolver
+ * @param noteId 笔记ID，指定内容数据所属的笔记
+ * @return 成功时返回笔记的Uri，失败时返回null
+ * @throws IllegalArgumentException 当noteId无效（<=0）时抛出
+ *
+ * 同步流程：
+ *
+ * - 检查noteId是否有效
+ * - 处理文本数据：
+ *
+ * - 如果{@link #mTextDataId}为0，执行插入操作
+ * - 否则，执行更新操作
+ *
+ * - 处理通话数据：
+ *
+ * - 如果{@link #mCallDataId}为0，执行插入操作
+ * - 否则，执行更新操作
+ *
+ * - 通过ContentProviderOperation批量执行所有操作
+ *
+ *
+ * 跨类调用：
+ *
+ * - 通过{@link Context#getContentResolver()}获取ContentResolver
+ * - 调用{@link android.content.ContentResolver#insert(Uri, ContentValues)}插入新数据
+ * - 调用{@link android.content.ContentResolver#applyBatch(String, ArrayList)}执行批量操作
+ *
+ *
+ * 错误处理：
+ *
+ * - 插入文本数据失败：记录日志并返回null
+ * - 批量操作失败：捕获RemoteException和OperationApplicationException，记录日志并返回null
+ *
+ */
Uri pushIntoContentResolver(Context context, long noteId) {
/**
* Check for safety
diff --git a/src/model/WorkingNote.java b/src/model/WorkingNote.java
index be081e4..e142def 100644
--- a/src/model/WorkingNote.java
+++ b/src/model/WorkingNote.java
@@ -32,36 +32,116 @@ import net.micode.notes.data.Notes.TextNote;
import net.micode.notes.tool.ResourceParser.NoteBgResources;
+/**
+ * 工作笔记管理类，负责处理笔记的编辑、保存、加载等操作。
+ * 设计意图：作为Note类的包装类，提供更便捷的笔记操作接口，处理用户交互和数据同步。
+ *
+ * - 管理笔记的元数据和内容数据
+ * - 提供笔记的加载、保存、删除等功能
+ * - 处理笔记的设置变更（如背景颜色、提醒时间、清单模式）
+ * - 支持小组件交互和通知
+ *
+ * 关键关联：
+ *
+ * - 与{@link Note}类紧密协作，管理笔记的核心数据
+ * - 通过{@link Context}与系统服务交互
+ * - 使用{@link NotesProvider}进行数据持久化
+ * - 通过{@link NoteSettingChangedListener}接口回调设置变更事件
+ *
+ */
public class WorkingNote {
- // Note for the working note
+ /**
+ * 笔记的核心数据管理对象。
+ * 业务含义：封装笔记的元数据和内容数据的变更管理。
+ */
private Note mNote;
- // Note Id
+
+ /**
+ * 笔记的唯一标识符。
+ * 业务含义：在数据库中唯一标识一条笔记记录。
+ * 约束条件：0表示笔记尚未保存到数据库。
+ */
private long mNoteId;
- // Note content
+
+ /**
+ * 笔记的内容文本。
+ * 业务含义：笔记的主要内容数据。
+ */
private String mContent;
- // Note mode
+
+ /**
+ * 笔记的模式。
+ * 业务含义：表示笔记的显示模式，如普通文本模式或清单模式。
+ */
private int mMode;
+ /**
+ * 笔记的提醒时间。
+ * 业务含义：笔记的闹钟提醒时间戳。
+ * 约束条件：0表示无提醒。
+ */
private long mAlertDate;
+ /**
+ * 笔记的最后修改时间。
+ * 业务含义：记录笔记最后一次修改的时间戳。
+ */
private long mModifiedDate;
+ /**
+ * 笔记的背景颜色ID。
+ * 业务含义：标识笔记使用的背景颜色资源。
+ */
private int mBgColorId;
+ /**
+ * 笔记关联的小组件ID。
+ * 业务含义：与笔记关联的桌面小组件的唯一标识符。
+ * 约束条件：{@link AppWidgetManager#INVALID_APPWIDGET_ID}表示无关联小组件。
+ */
private int mWidgetId;
+ /**
+ * 笔记关联的小组件类型。
+ * 业务含义：标识与笔记关联的桌面小组件的类型。
+ * 约束条件：{@link Notes#TYPE_WIDGET_INVALIDE}表示无关联小组件。
+ */
private int mWidgetType;
+ /**
+ * 笔记所在的文件夹ID。
+ * 业务含义：标识笔记所属的文件夹。
+ */
private long mFolderId;
+ /**
+ * 上下文对象。
+ * 业务含义：用于访问系统服务和资源。
+ */
private Context mContext;
+ /**
+ * 日志标签。
+ * 业务含义：用于在日志中标识WorkingNote类的相关操作。
+ */
private static final String TAG = "WorkingNote";
+ /**
+ * 笔记是否已删除的标记。
+ * 业务含义：标识笔记是否已被标记为删除。
+ */
private boolean mIsDeleted;
+ /**
+ * 笔记设置变更监听器。
+ * 业务含义：用于监听笔记设置的变更事件。
+ */
private NoteSettingChangedListener mNoteSettingStatusListener;
+ /**
+ * 笔记内容数据的查询投影。
+ * 业务含义：定义从Notes.CONTENT_DATA_URI查询时需要获取的列。
+ */
public static final String[] DATA_PROJECTION = new String[] {
DataColumns.ID,
DataColumns.CONTENT,
@@ -72,6 +152,10 @@ public class WorkingNote {
DataColumns.DATA4,
};
+ /**
+ * 笔记元数据的查询投影。
+ * 业务含义：定义从Notes.CONTENT_NOTE_URI查询时需要获取的列。
+ */
public static final String[] NOTE_PROJECTION = new String[] {
NoteColumns.PARENT_ID,
NoteColumns.ALERTED_DATE,
@@ -81,27 +165,73 @@ public class WorkingNote {
NoteColumns.MODIFIED_DATE
};
+ /**
+ * DATA_PROJECTION中ID列的索引。
+ */
private static final int DATA_ID_COLUMN = 0;
+ /**
+ * DATA_PROJECTION中CONTENT列的索引。
+ */
private static final int DATA_CONTENT_COLUMN = 1;
+ /**
+ * DATA_PROJECTION中MIME_TYPE列的索引。
+ */
private static final int DATA_MIME_TYPE_COLUMN = 2;
+ /**
+ * DATA_PROJECTION中DATA1列的索引，用于存储模式信息。
+ */
private static final int DATA_MODE_COLUMN = 3;
+ /**
+ * NOTE_PROJECTION中PARENT_ID列的索引。
+ */
private static final int NOTE_PARENT_ID_COLUMN = 0;
+ /**
+ * NOTE_PROJECTION中ALERTED_DATE列的索引。
+ */
private static final int NOTE_ALERTED_DATE_COLUMN = 1;
+ /**
+ * NOTE_PROJECTION中BG_COLOR_ID列的索引。
+ */
private static final int NOTE_BG_COLOR_ID_COLUMN = 2;
+ /**
+ * NOTE_PROJECTION中WIDGET_ID列的索引。
+ */
private static final int NOTE_WIDGET_ID_COLUMN = 3;
+ /**
+ * NOTE_PROJECTION中WIDGET_TYPE列的索引。
+ */
private static final int NOTE_WIDGET_TYPE_COLUMN = 4;
+ /**
+ * NOTE_PROJECTION中MODIFIED_DATE列的索引。
+ */
private static final int NOTE_MODIFIED_DATE_COLUMN = 5;
- // New note construct
+ /**
+ * 创建新笔记的构造函数。
+ * 功能：初始化一个新的工作笔记对象，设置默认值。
+ *
+ * @param context 上下文对象，用于访问系统服务
+ * @param folderId 文件夹ID，新笔记将被添加到该文件夹
+ *
+ * 默认初始化：
+ *
+ * - 提醒时间：0（无提醒）
+ * - 修改时间：当前时间戳
+ * - 笔记ID：0（未保存）
+ * - 删除标记：false
+ * - 模式：0（普通文本模式）
+ * - 小组件类型：无效
+ *
+ */
private WorkingNote(Context context, long folderId) {
mContext = context;
mAlertDate = 0;
@@ -114,7 +244,21 @@ public class WorkingNote {
mWidgetType = Notes.TYPE_WIDGET_INVALIDE;
}
- // Existing note construct
+ /**
+ * 加载现有笔记的构造函数。
+ * 功能：初始化一个工作笔记对象，并从数据库加载现有笔记数据。
+ *
+ * @param context 上下文对象，用于访问系统服务
+ * @param noteId 笔记ID，要加载的现有笔记
+ * @param folderId 文件夹ID，笔记所属的文件夹
+ *
+ * 加载流程：
+ *
+ * - 初始化基本字段
+ * - 调用{@link #loadNote()}加载笔记元数据
+ * - 调用{@link #loadNoteData()}加载笔记内容数据
+ *
+ */
private WorkingNote(Context context, long noteId, long folderId) {
mContext = context;
mNoteId = noteId;
@@ -124,6 +268,35 @@ public class WorkingNote {
loadNote();
}
+ /**
+ * 加载笔记的元数据。
+ * 功能：从数据库查询并加载笔记的元数据信息。
+ *
+ * 加载流程：
+ *
+ * - 通过ContentResolver查询{@link Notes#CONTENT_NOTE_URI}获取笔记元数据
+ * - 如果查询成功，提取并保存元数据字段
+ * - 关闭Cursor
+ * - 如果查询失败，记录日志并抛出异常
+ * - 调用{@link #loadNoteData()}加载笔记内容数据
+ *
+ *
+ * 加载的元数据字段：
+ *
+ * - 文件夹ID
+ * - 背景颜色ID
+ * - 小组件ID
+ * - 小组件类型
+ * - 提醒时间
+ * - 修改时间
+ *
+ *
+ * 错误处理：
+ *
+ * - 如果查询失败，记录错误日志
+ * - 抛出IllegalArgumentException异常
+ *
+ */
private void loadNote() {
Cursor cursor = mContext.getContentResolver().query(
ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, mNoteId), NOTE_PROJECTION, null,
@@ -146,6 +319,30 @@ public class WorkingNote {
loadNoteData();
}
+ /**
+ * 加载笔记的内容数据。
+ * 功能：从数据库查询并加载笔记的内容数据信息。
+ *
+ * 加载流程：
+ *
+ * - 通过ContentResolver查询{@link Notes#CONTENT_DATA_URI}获取笔记内容数据
+ * - 如果查询成功，遍历所有结果
+ * - 根据数据类型处理不同类型的内容数据：
+ *
+ * - 普通笔记：保存内容、模式、文本数据ID
+ * - 通话笔记：保存通话数据ID
+ * - 其他类型：记录日志
+ *
+ * - 关闭Cursor
+ * - 如果查询失败，记录日志并抛出异常
+ *
+ *
+ * 错误处理：
+ *
+ * - 如果查询失败，记录错误日志
+ * - 抛出IllegalArgumentException异常
+ *
+ */
private void loadNoteData() {
Cursor cursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI, DATA_PROJECTION,
DataColumns.NOTE_ID + "=?", new String[] {
@@ -174,6 +371,27 @@ public class WorkingNote {
}
}
+ /**
+ * 创建一个空的工作笔记。
+ * 功能：创建一个新的工作笔记对象，并设置默认属性。
+ *
+ * @param context 上下文对象，用于访问系统服务
+ * @param folderId 文件夹ID，新笔记将被添加到该文件夹
+ * @param widgetId 小组件ID，如果笔记关联到小组件
+ * @param widgetType 小组件类型，如果笔记关联到小组件
+ * @param defaultBgColorId 默认背景颜色ID
+ *
+ * @return 创建的工作笔记对象
+ *
+ * 初始化步骤：
+ *
+ * - 创建新的WorkingNote实例
+ * - 设置默认背景颜色
+ * - 设置小组件ID（如果有）
+ * - 设置小组件类型（如果有）
+ * - 返回创建的笔记对象
+ *
+ */
public static WorkingNote createEmptyNote(Context context, long folderId, int widgetId,
int widgetType, int defaultBgColorId) {
WorkingNote note = new WorkingNote(context, folderId);
@@ -183,10 +401,50 @@ public class WorkingNote {
return note;
}
+ /**
+ * 从数据库加载现有笔记。
+ * 功能：根据笔记ID从数据库加载笔记数据，并创建工作笔记对象。
+ *
+ * @param context 上下文对象，用于访问系统服务
+ * @param id 笔记ID，要加载的现有笔记
+ *
+ * @return 加载的工作笔记对象
+ *
+ * 加载流程：
+ *
+ * - 调用构造函数创建WorkingNote实例
+ * - 在构造函数中调用{@link #loadNote()}加载元数据
+ * - 在loadNote()中调用{@link #loadNoteData()}加载内容数据
+ *
+ */
public static WorkingNote load(Context context, long id) {
return new WorkingNote(context, id, 0);
}
+ /**
+ * 保存笔记到数据库。
+ * 功能：将工作笔记的内容和设置保存到数据库中。
+ *
+ * @return 保存是否成功
+ *
+ * 保存流程：
+ *
+ * - 检查笔记是否值得保存（{@link #isWorthSaving()}）
+ * - 如果笔记不存在于数据库：
+ *
+ * - 调用{@link Note#getNewNoteId(Context, long)}获取新笔记ID
+ * - 如果获取失败，记录日志并返回false
+ *
+ * - 调用{@link Note#syncNote(Context, long)}同步笔记数据到数据库
+ * - 如果笔记关联到小组件，通知小组件更新
+ * - 返回保存结果
+ *
+ *
+ * 线程安全：
+ *
+ * - 使用synchronized关键字保证多线程环境下的安全
+ *
+ */
public synchronized boolean saveNote() {
if (isWorthSaving()) {
if (!existInDatabase()) {
@@ -212,10 +470,42 @@ public class WorkingNote {
}
}
+ /**
+ * 检查笔记是否存在于数据库中。
+ * 功能：根据笔记ID判断笔记是否已保存到数据库。
+ *
+ * @return 如果笔记存在于数据库返回true，否则返回false
+ *
+ * 判断逻辑：
+ *
+ * - 笔记ID大于0表示已保存到数据库
+ * - 笔记ID等于0表示未保存到数据库
+ *
+ */
public boolean existInDatabase() {
return mNoteId > 0;
}
+ /**
+ * 检查笔记是否值得保存。
+ * 功能：判断笔记是否需要保存到数据库。
+ *
+ * @return 如果笔记值得保存返回true，否则返回false
+ *
+ * 判断条件：
+ *
+ * - 如果笔记已标记为删除 → 不值得保存
+ * - 如果笔记不存在于数据库且内容为空 → 不值得保存
+ * - 如果笔记存在于数据库但没有本地修改 → 不值得保存
+ * - 其他情况 → 值得保存
+ *
+ *
+ * 优化作用：
+ *
+ * - 避免保存空笔记或未修改的笔记
+ * - 减少不必要的数据库操作
+ *
+ */
private boolean isWorthSaving() {
if (mIsDeleted || (!existInDatabase() && TextUtils.isEmpty(mContent))
|| (existInDatabase() && !mNote.isLocalModified())) {
@@ -225,10 +515,33 @@ public class WorkingNote {
}
}
+ /**
+ * 设置笔记设置变更监听器。
+ * 功能：注册一个监听器，用于接收笔记设置变更的通知。
+ *
+ * @param l 笔记设置变更监听器
+ */
public void setOnSettingStatusChangedListener(NoteSettingChangedListener l) {
mNoteSettingStatusListener = l;
}
+ /**
+ * 设置笔记的提醒时间。
+ * 功能：更新笔记的提醒时间，并通知监听器。
+ *
+ * @param date 提醒时间戳
+ * @param set 是否设置提醒（true表示设置，false表示取消）
+ *
+ * 处理流程：
+ *
+ * - 如果提醒时间发生变化：
+ *
+ * - 更新内部提醒时间字段
+ * - 调用{@link Note#setNoteValue(String, String)}更新笔记元数据
+ *
+ * - 通知监听器提醒时间已变更
+ *
+ */
public void setAlertDate(long date, boolean set) {
if (date != mAlertDate) {
mAlertDate = date;
@@ -239,6 +552,18 @@ public class WorkingNote {
}
}
+ /**
+ * 标记笔记是否已删除。
+ * 功能：设置笔记的删除标记，并通知关联的小组件。
+ *
+ * @param mark 删除标记（true表示已删除，false表示未删除）
+ *
+ * 处理流程：
+ *
+ * - 更新内部删除标记字段
+ * - 如果笔记关联到小组件，通知小组件更新
+ *
+ */
public void markDeleted(boolean mark) {
mIsDeleted = mark;
if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
@@ -288,56 +613,126 @@ public class WorkingNote {
}
}
+ /**
+ * 将笔记转换为通话笔记。
+ * 功能：设置笔记为通话笔记类型，并添加通话相关信息。
+ *
+ * @param phoneNumber 电话号码
+ * @param callDate 通话时间戳
+ *
+ * 转换流程：
+ *
+ * - 设置通话日期
+ * - 设置电话号码
+ * - 将笔记移动到通话记录文件夹
+ *
+ */
public void convertToCallNote(String phoneNumber, long callDate) {
mNote.setCallData(CallNote.CALL_DATE, String.valueOf(callDate));
mNote.setCallData(CallNote.PHONE_NUMBER, phoneNumber);
mNote.setNoteValue(NoteColumns.PARENT_ID, String.valueOf(Notes.ID_CALL_RECORD_FOLDER));
}
+ /**
+ * 检查笔记是否有提醒。
+ * 功能：判断笔记是否设置了提醒时间。
+ *
+ * @return 如果有提醒返回true，否则返回false
+ *
+ * 判断逻辑：
+ *
+ * - 提醒时间大于0表示有提醒
+ * - 提醒时间等于0表示无提醒
+ *
+ */
public boolean hasClockAlert() {
return (mAlertDate > 0 ? true : false);
}
+ /**
+ * 获取笔记内容。
+ * @return 笔记的内容文本
+ */
public String getContent() {
return mContent;
}
+ /**
+ * 获取笔记的提醒时间。
+ * @return 笔记的提醒时间戳
+ */
public long getAlertDate() {
return mAlertDate;
}
+ /**
+ * 获取笔记的最后修改时间。
+ * @return 笔记的最后修改时间戳
+ */
public long getModifiedDate() {
return mModifiedDate;
}
+ /**
+ * 获取笔记背景颜色的资源ID。
+ * @return 背景颜色的资源ID
+ */
public int getBgColorResId() {
return NoteBgResources.getNoteBgResource(mBgColorId);
}
+ /**
+ * 获取笔记背景颜色的ID。
+ * @return 背景颜色的ID
+ */
public int getBgColorId() {
return mBgColorId;
}
+ /**
+ * 获取笔记标题背景的资源ID。
+ * @return 标题背景的资源ID
+ */
public int getTitleBgResId() {
return NoteBgResources.getNoteTitleBgResource(mBgColorId);
}
+ /**
+ * 获取笔记的清单模式。
+ * @return 清单模式（0表示普通模式，1表示清单模式）
+ */
public int getCheckListMode() {
return mMode;
}
+ /**
+ * 获取笔记的ID。
+ * @return 笔记的唯一标识符
+ */
public long getNoteId() {
return mNoteId;
}
+ /**
+ * 获取笔记所属的文件夹ID。
+ * @return 文件夹ID
+ */
public long getFolderId() {
return mFolderId;
}
+ /**
+ * 获取笔记关联的小组件ID。
+ * @return 小组件ID（无效时返回{@link AppWidgetManager#INVALID_APPWIDGET_ID}）
+ */
public int getWidgetId() {
return mWidgetId;
}
+ /**
+ * 获取笔记关联的小组件类型。
+ * @return 小组件类型（无效时返回{@link Notes#TYPE_WIDGET_INVALIDE}）
+ */
public int getWidgetType() {
return mWidgetType;
}