prwohun7f
/
minotes-lyzx
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

更新完善

Browse Source
master
刘焱 3 months ago
parent efc373cd74
commit 76ff74ca12
22 changed files with 4140 additions and 2986 deletions
Show Stats Download Patch File Download Diff File

111
src/Notes-master/src/net/micode/notes/data/Contact.java
Unescape View File

@ -25,61 +25,104 @@ import android.util.Log;
import java.util.HashMap;
/**
* 联系人查询工具类 (Data Layer - External Data Access)
* <p>
* 核心职责：通过电话号码从系统联系人数据库查询对应的联系人姓名。
* 架构说明：该类属于数据访问层，用于桥接便签应用与系统联系人ContentProvider。
* 设计要点：实现了一级内存缓存机制，避免对同一电话号码的重复查询。
*/
public class Contact {
private static HashMap<String, String> sContactCache;//定义sContactCache是一个缓存电话号码和相应联系人名字的哈希表
private static final String TAG = "Contact";//定义用于日志输出的标识（TAG）
/**
* 联系人姓名缓存 (电话号码 -> 联系人姓名)
* <p>
* 使用静态HashMap实现应用级别的缓存，避免重复查询系统联系人数据库。
* 缓存键为原始电话号码字符串，值为从系统联系人查询到的显示名称。
*/
private static HashMap<String, String> sContactCache;
private static final String CALLER_ID_SELECTION = "PHONE_NUMBERS_EQUAL(" + Phone.NUMBER
+ ",?) AND " + Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'"
+ " AND " + Data.RAW_CONTACT_ID + " IN "
+ "(SELECT raw_contact_id "
+ " FROM phone_lookup"
+ " WHERE min_match = '+')";
//用于构建数据库查询条件的字符串常量
public static String getContact(Context context, String phoneNumber)
//参数:Context对象:用于访问系统服务和应用资源 phoneNumber:需要查询的联系人电话号码
{
if(sContactCache == null) {
sContactCache = new HashMap<String, String>();
/**
* 日志标识，统一使用类名作为TAG
*/
private static final String TAG = "Contact";
/**
* 系统联系人查询的SQL Selection条件模板
* <p>
* 技术说明：该模板包含三个关键条件：
* 1. PHONE_NUMBERS_EQUAL：使用Android的电话号码匹配算法（支持不同格式的号码匹配）
* 2. MIMETYPE='phone'：限定查询电话类型的联系人数据
* 3. RAW_CONTACT_ID IN phone_lookup子查询：利用系统预建的phone_lookup索引表提升查询性能
*
* 注意：其中的"+"号为占位符，将在运行时替换为电话号码的最小匹配长度。
*/
private static final String CALLER_ID_SELECTION =
"PHONE_NUMBERS_EQUAL(" + Phone.NUMBER + ",?) AND " +
Data.MIMETYPE + "='" + Phone.CONTENT_ITEM_TYPE + "'" +
" AND " + Data.RAW_CONTACT_ID + " IN " +
"(SELECT raw_contact_id " +
" FROM phone_lookup" +
" WHERE min_match = '+')";
// 没映射表就建表，有就查缓存中有没有这个联系人
/**
* 根据电话号码获取联系人姓名 (公开查询接口)
* <p>
* 查询策略：采用两级查询策略，优先查询内存缓存，缓存未命中则查询系统联系人数据库。
* 性能优化：查询结果会缓存到静态HashMap中，后续相同电话号码的查询将直接返回缓存结果。
* 异常处理：对数据库查询和结果解析进行了异常保护，确保应用稳定性。
*
* @param context 应用上下文，用于访问ContentResolver
* @param phoneNumber 需要查询的电话号码（支持国际格式和本地格式）
* @return 匹配的联系人显示名称，如果未找到匹配的联系人或发生异常则返回null
*/
public static String getContact(Context context, String phoneNumber) {
// 1. 延迟初始化缓存：首次调用时创建缓存容器
if (sContactCache == null) {
sContactCache = new HashMap<String, String>();
}
if(sContactCache.containsKey(phoneNumber)) {
// 2. 缓存命中检查：如果缓存中存在该电话号码，直接返回缓存的姓名
if (sContactCache.containsKey(phoneNumber)) {
return sContactCache.get(phoneNumber);
}
//返回从表里查询到的对应名字
// 3. 构建查询条件：将占位符"+"替换为电话号码的最小匹配长度
// 最小匹配长度是Android电话号码匹配算法的一部分，用于处理不同格式的电话号码
String selection = CALLER_ID_SELECTION.replace("+",
PhoneNumberUtils.toCallerIDMinMatch(phoneNumber));
//构造一个SQL查询条件：CALLER_ID_SELECTION中的"+"被替换为电话号码的最小匹配值
//然后执行查询语句
// 4. DB操作：查询系统联系人数据库
Cursor cursor = context.getContentResolver().query(
Data.CONTENT_URI,
new String [] { Phone.DISPLAY_NAME },
selection,
new String[] { phoneNumber },
null);
//判断查询结果：
//查询结果不为空，且能够移动到第一条记录：
// 那么就尝试从Cursor中获取联系人姓名，并将其存入缓存sContactCache。然后返回联系人姓名。
// 异常情况：如果在获取字符串时发生数组越界异常，则记录一个错误日志并返回null。
// 最后都要确保关闭Cursor对象，以避免内存泄漏。
//如果查询结果为空或者没有记录可以移动到（即没有找到匹配的联系人）：
// 则记录一条调试日志并返回null
Data.CONTENT_URI, // URI：系统联系人的数据表
new String[] { Phone.DISPLAY_NAME }, // Projection：仅查询显示名称列
selection, // Selection：动态构建的查询条件
new String[] { phoneNumber }, // SelectionArgs：查询参数
null // SortOrder：无需排序
);
// 5. 结果处理：如果查询到匹配的联系人，提取姓名并更新缓存
if (cursor != null && cursor.moveToFirst()) {
try {
// 从Cursor的第一列获取联系人姓名
String name = cursor.getString(0);
// 更新缓存：将电话号码-姓名映射加入缓存
sContactCache.put(phoneNumber, name);
Log.d(TAG, "Contact found for number: " + phoneNumber + ", name: " + name);
return name;
} catch (IndexOutOfBoundsException e) {
Log.e(TAG, " Cursor get string error " + e.toString());
// 异常保护：当Cursor列索引越界时记录错误日志
Log.e(TAG, "Cursor get string error: " + e.toString());
return null;
} finally {
// 资源清理：无论是否发生异常，都确保关闭Cursor
cursor.close();
}
} else {
Log.d(TAG, "No contact matched with number:" + phoneNumber);
// 查询结果为空：未找到匹配的联系人
Log.d(TAG, "No contact matched with number: " + phoneNumber);
return null;
}
}
}
}

298
src/Notes-master/src/net/micode/notes/data/Notes.java
Unescape View File

@ -17,34 +17,56 @@
package net.micode.notes.data;
import android.net.Uri;
/**
* 便签数据模型常量定义类 (Data Layer - Schema Definition)
* <p>
* 核心职责：定义便签应用的所有核心数据模型、ContentProvider URI、列定义和常量。
* 架构说明：该类是数据层的元数据定义中心，为整个应用提供统一的常量接口。
* 设计要点：使用内部类和接口进行逻辑分组，便于维护和扩展。
*/
public class Notes {
//用于表示笔记应用中的各种类型、标识符以及Intent的额外数据
/**
* ContentProvider 权限标识符
* <p>
* 用于构建 ContentProvider URI，必须与 AndroidManifest.xml 中的声明保持一致。
*/
public static final String AUTHORITY = "micode_notes";
/**
* 日志标识，统一使用类名作为TAG
*/
public static final String TAG = "Notes";
//对NoteColumns.TYPE的值进行设置时使用：
//即不同种类：笔记、文件夹和系统文件夹
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
* 便签实体类型常量
* <p>
* 架构说明：这些常量定义了便签系统中实体的分类方式，
* 用于在数据库的 {@code type} 列中标识记录的类型。
*/
public static final int TYPE_NOTE = 0; // 普通便签
public static final int TYPE_FOLDER = 1; // 文件夹（用于组织便签）
public static final int TYPE_SYSTEM = 2; // 系统文件夹（特殊用途）
/**
* 系统文件夹标识符 (System Folder Identifiers)
* <p>
* 架构说明：这些负数的ID代表系统级别的虚拟文件夹，
* 它们在数据库中没有实际的存储行，而是在查询时动态处理。
* 这种设计避免了对数据库结构的频繁修改，提高了系统扩展性。
*/
public static final int ID_ROOT_FOLDER = 0; // 根文件夹：默认文件夹，显示所有便签
public static final int ID_TEMPARAY_FOLDER = -1; // 临时文件夹：存储未分类的便签
public static final int ID_CALL_RECORD_FOLDER = -2; // 通话记录文件夹：存储来自通话的便签
public static final int ID_TRASH_FOLER = -3; // 回收站：软删除的便签临时存放处
/**
* Intent 额外数据键定义 (Intent Extra Keys)
* <p>
* 架构说明：这些常量定义了Activity之间传递数据的键名，
* 使用全限定名（包名作为前缀）确保键的唯一性，避免与其他应用冲突。
*/
//以下id是系统文件夹的标识符（即系统文件夹的分类）
//ID_ROOT_FOLDER：默认文件夹
//ID_TEMPARAY_FOLDER：不属于文件夹的笔记
//ID_CALL_RECORD_FOLDER：用于存储通话记录，以便返回
//ID_TRASH_FOLER：垃圾回收站
public static final int ID_ROOT_FOLDER = 0;
public static final int ID_TEMPARAY_FOLDER = -1;
public static final int ID_CALL_RECORD_FOLDER = -2;
public static final int ID_TRASH_FOLER = -3;
// 额外的数据键，个人理解为就是定义一些布局的ID
// 这部分就是用于设置UI界面的一些布局或小组件的id，给它定义成常量了。
// （这样的封装性可能比较好？因为如果有部分要修改，则直接来这边修改即可，不用在activity部分一个一个修改。）
public static final String INTENT_EXTRA_ALERT_DATE = "net.micode.notes.alert_date";
public static final String INTENT_EXTRA_BACKGROUND_ID = "net.micode.notes.background_color_id";
public static final String INTENT_EXTRA_WIDGET_ID = "net.micode.notes.widget_id";
@ -52,258 +74,332 @@ public class Notes {
public static final String INTENT_EXTRA_FOLDER_ID = "net.micode.notes.folder_id";
public static final String INTENT_EXTRA_CALL_DATE = "net.micode.notes.call_date";
public static final int TYPE_WIDGET_INVALIDE = -1;
public static final int TYPE_WIDGET_2X = 0;
public static final int TYPE_WIDGET_4X = 1;
// 数据常量：里面定义了两种类型：文本便签和通话记录
/**
* 桌面小部件类型常量
* <p>
* 功能说明：定义了便签桌面小部件的类型，
* TYPE_WIDGET_INVALIDE 表示无效或未设置小部件。
*/
public static final int TYPE_WIDGET_INVALIDE = -1; // 无效的小部件类型
public static final int TYPE_WIDGET_2X = 0; // 2x2 小部件尺寸
public static final int TYPE_WIDGET_4X = 1; // 4x4 小部件尺寸
/**
* 数据内容类型常量
* <p>
* 架构说明：这些常量定义了便签内容的MIME类型，
* 用于ContentProvider的MIME_TYPE列，区分不同类型的便签数据。
*/
public static class DataConstants {
public static final String NOTE = TextNote.CONTENT_ITEM_TYPE;
public static final String CALL_NOTE = CallNote.CONTENT_ITEM_TYPE;
public static final String NOTE = TextNote.CONTENT_ITEM_TYPE; // 普通文本便签
public static final String CALL_NOTE = CallNote.CONTENT_ITEM_TYPE; // 通话记录便签
}
//定义一堆访问笔记和文件的uri
//GPT：Android开发中常见的用于定义内容提供者（Content Provider）URI
//内容提供者是一种Android组件，它允许应用程序共享和存储数据。这里定义了一个URI来查询数据
/**
* Uri to query all notes and folders
* ContentProvider URI 定义
* <p>
* 架构说明：这些URI定义了应用内部数据访问的入口点，
* ContentProvider通过这些URI提供对便签数据的增删改查操作。
*/
/**
* 便签主表查询URI
* <p>
* 查询notes表的所有记录，包括便签和文件夹。
*/
public static final Uri CONTENT_NOTE_URI = Uri.parse("content://" + AUTHORITY + "/note");
/**
* Uri to query data
* 便签数据表查询URI
* <p>
* 查询data表的记录，存储便签的详细内容。
*/
public static final Uri CONTENT_DATA_URI = Uri.parse("content://" + AUTHORITY + "/data");
/**
* Notes表列定义接口 (Database Schema - Notes Table)
* <p>
* 架构说明：该接口定义了notes表的所有列名及其数据类型，
* 是数据库架构的核心定义部分。
*/
public interface NoteColumns {
/**
* The unique ID for a row
* 主键，自增长ID
* <P> Type: INTEGER (long) </P>
*/
public static final String ID = "_id";
/**
* The parent's id for note or folder
* 父节点ID，用于构建文件夹层级结构
* <P> Type: INTEGER (long) </P>
*/
public static final String PARENT_ID = "parent_id";
/**
* Created data for note or folder
* 创建时间戳（毫秒）
* <P> Type: INTEGER (long) </P>
*/
public static final String CREATED_DATE = "created_date";
/**
* Latest modified date
* 最后修改时间戳（毫秒）
* <P> Type: INTEGER (long) </P>
*/
public static final String MODIFIED_DATE = "modified_date";
/**
* Alert date
* 提醒时间戳（毫秒）
* <P> Type: INTEGER (long) </P>
*/
public static final String ALERTED_DATE = "alert_date";
/**
* Folder's name or text content of note
* 便签摘要或文件夹名称
* <P> Type: TEXT </P>
* <p>
* 业务逻辑：对于便签，存储内容的预览摘要；
* 对于文件夹，存储文件夹名称。
*/
// 摘要
public static final String SNIPPET = "snippet";
/**
* Note's widget id
* 关联的桌面小部件ID
* <P> Type: INTEGER (long) </P>
*/
public static final String WIDGET_ID = "widget_id";
/**
* Note's widget type
* 桌面小部件类型（2x2或4x4）
* <P> Type: INTEGER (long) </P>
*/
public static final String WIDGET_TYPE = "widget_type";
/**
* Note's background color's id
* 便签背景颜色ID
* <P> Type: INTEGER (long) </P>
* <p>
* [2025 AI智能分类特性]：
* 此字段现在不仅存储用户手动设置的背景颜色，
* 还存储AI智能分类自动分配的颜色标识。
*/
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
* 是否有附件标记
* <P> Type: INTEGER </P>
* <p>
* 设计说明：0表示没有附件，1表示有附件。
* 用于快速筛选多媒体便签，避免全表扫描。
*/
public static final String HAS_ATTACHMENT = "has_attachment";
/**
* Folder's count of notes
* 文件夹内的便签数量（仅对文件夹类型有效）
* <P> Type: INTEGER (long) </P>
*/
public static final String NOTES_COUNT = "notes_count";
/**
* The file type: folder or note
* 记录类型（便签/文件夹/系统）
* <P> Type: INTEGER </P>
* <p>
* 取值：{@link Notes#TYPE_NOTE}, {@link Notes#TYPE_FOLDER}, {@link Notes#TYPE_SYSTEM}
*/
public static final String TYPE = "type";
/**
* The last sync id
* 同步ID，用于数据同步操作
* <P> Type: INTEGER (long) </P>
* <p>
* 架构说明：用于标识云端同步的版本，实现增量同步和冲突解决。
*/
//在数据同步过程中，这个ID可能用来跟踪和识别每次同步操作的唯一性，确保数据的一致性。
public static final String SYNC_ID = "sync_id";
/**
* Sign to indicate local modified or not
* 本地修改标记
* <P> Type: INTEGER </P>
* <p>
* 设计说明：0表示已同步到云端，1表示有本地修改需要同步。
* 用于优化同步操作，减少不必要的数据传输。
*/
public static final String LOCAL_MODIFIED = "local_modified";
/**
* Original parent id before moving into temporary folder
* 原始父节点ID（用于回收站恢复）
* <P> Type : INTEGER </P>
* <p>
* 业务逻辑：当便签被移动到回收站时，记录其原始父节点ID，
* 以便从回收站恢复时能够回到正确位置。
*/
public static final String ORIGIN_PARENT_ID = "origin_parent_id";
/**
* The gtask id
* Google任务ID（用于Google Tasks集成）
* <P> Type : TEXT </P>
*/
public static final String GTASK_ID = "gtask_id";
/**
* The version code
* 数据版本号（用于乐观锁控制）
* <P> Type : INTEGER (long) </P>
* <p>
* 设计说明：每次更新时递增，用于检测并发修改冲突。
*/
public static final String VERSION = "version";
}
/**
* Data表列定义接口 (Database Schema - Data Table)
* <p>
* 架构说明：该接口定义了data表的所有列名及其数据类型，
* data表存储便签的详细内容，支持多种MIME类型。
*/
public interface DataColumns {
// DataColumns的接口，这个接口包含了一系列静态常量，这些常量代表了数据库表中用于存储数据的列名。
// 每个常量都有相应的注释，说明该列的作用和数据类型。
/**
* The unique ID for a row
* 主键，自增长ID
* <P> Type: INTEGER (long) </P>
*/
public static final String ID = "_id";
/**
* The MIME type of the item represented by this row.
* MIME类型，标识数据的具体类型
* <P> Type: Text </P>
* <p>
* 架构说明：通过MIME类型区分不同种类的便签内容，
* 如普通文本便签、通话记录便签等，支持灵活扩展。
*/
//MIME类型是一种标准，用于标识文档、文件或字节流的性质和格式。在数据库中，这个字段可以用来识别不同类型的数据，例如文本、图片、音频或视频等。
public static final String MIME_TYPE = "mime_type";
/**
* The reference id to note that this data belongs to
* 关联的便签ID（外键，指向notes表）
* <P> Type: INTEGER (long) </P>
*/
//归属的Note的ID
public static final String NOTE_ID = "note_id";
/**
* Created data for note or folder
* 创建时间戳（毫秒）
* <P> Type: INTEGER (long) </P>
*/
//创建日期
public static final String CREATED_DATE = "created_date";
/**
* Latest modified date
* 最后修改时间戳（毫秒）
* <P> Type: INTEGER (long) </P>
*/
//最近修改日期
public static final String MODIFIED_DATE = "modified_date";
/**
* Data's content
* 便签内容（核心数据）
* <P> Type: TEXT </P>
*/
//数据内容
public static final String CONTENT = "content";
// 以下5个是通用数据列，它们的具体意义取决于MIME类型（由MIME_TYPE字段指定）。
// 不同的MIME类型可能需要存储不同类型的数据，这五个字段提供了灵活性，允许根据MIME类型来存储相应的数据。
// 读后面的代码感觉这部分是在表示内容的不同状态
/**
* Generic data column, the meaning is {@link #MIMETYPE} specific, used for
* integer data type
* 通用数据列1（MIME类型特定的整数数据）
* <P> Type: INTEGER </P>
* <p>
* 设计说明：这些通用数据列提供灵活的数据存储方案，
* 具体含义由MIME_TYPE决定，避免为每种数据类型创建单独的表。
*/
public static final String DATA1 = "data1";
/**
* Generic data column, the meaning is {@link #MIMETYPE} specific, used for
* integer data type
* 通用数据列2（MIME类型特定的整数数据）
* <P> Type: INTEGER </P>
*/
public static final String DATA2 = "data2";
/**
* Generic data column, the meaning is {@link #MIMETYPE} specific, used for
* TEXT data type
* 通用数据列3（MIME类型特定的文本数据）
* <P> Type: TEXT </P>
*/
public static final String DATA3 = "data3";
/**
* Generic data column, the meaning is {@link #MIMETYPE} specific, used for
* TEXT data type
* 通用数据列4（MIME类型特定的文本数据）
* <P> Type: TEXT </P>
*/
public static final String DATA4 = "data4";
/**
* Generic data column, the meaning is {@link #MIMETYPE} specific, used for
* TEXT data type
* 通用数据列5（MIME类型特定的文本数据）
* <P> Type: TEXT </P>
*/
public static final String DATA5 = "data5";
}
//以下是文本便签的定义
/**
* 文本便签数据定义 (Text Note Data Definition)
* <p>
* 架构说明：该类定义了普通文本便签的数据结构，
* 使用DataColumns中的通用数据列存储特定字段。
*/
public static final class TextNote implements DataColumns {
/**
* Mode to indicate the text in check list mode or not
* 便签模式（普通模式或待办清单模式）
* <P> Type: Integer 1:check list mode 0: normal mode </P>
* <p>
* 业务逻辑：通过DATA1列存储，实现模式切换功能。
*/
public static final String MODE = DATA1;//模式？这个被存在DATA1列中
public static final String MODE = DATA1;
public static final int MODE_CHECK_LIST = 1;//所处检查列表模式
/**
* 待办清单模式常量
*/
public static final int MODE_CHECK_LIST = 1;
public static final String CONTENT_TYPE = "vnd.android.cursor.dir/text_note";// 定义了MIME类型，用于标识文本标签的目录
/**
* 文本便签目录的MIME类型
*/
public static final String CONTENT_TYPE = "vnd.android.cursor.dir/text_note";
public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/text_note";// 定义了MIME类型，用于标识文本标签的单个项
/**
* 单个文本便签项的MIME类型
*/
public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/text_note";
public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/text_note");//文本标签内容提供者（Content Provider）的URI，用于访问文本标签数据
/**
* 文本便签数据查询URI
*/
public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/text_note");
}
// 通话记录的定义
/**
* 通话记录便签数据定义 (Call Note Data Definition)
* <p>
* 架构说明：该类定义了来自通话记录的便签数据结构，
* 使用DataColumns中的通用数据列存储特定字段。
*/
public static final class CallNote implements DataColumns {
/**
* Call date for this record
* 通话时间戳（毫秒）
* <P> Type: INTEGER (long) </P>
* <p>
* 业务逻辑：通过DATA1列存储通话时间，用于按时间排序和显示。
*/
public static final String CALL_DATE = DATA1;//一个字符串常量，表示通话记录的日期
public static final String CALL_DATE = DATA1;
/**
* Phone number for this record
* 电话号码
* <P> Type: TEXT </P>
* <p>
* 业务逻辑：通过DATA3列存储电话号码，用于显示和联系人匹配。
*/
public static final String PHONE_NUMBER = DATA3;//意味着在数据库表中，这个电话号码信息将被存储在DATA3列中
public static final String PHONE_NUMBER = DATA3;
public static final String CONTENT_TYPE = "vnd.android.cursor.dir/call_note";// 同样定义了MIME类型，是用于标识通话记录的目录。
/**
* 通话记录便签目录的MIME类型
*/
public static final String CONTENT_TYPE = "vnd.android.cursor.dir/call_note";
public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/call_note";// 同样定义了MIME类型，是用于标识通话记录的单个项
/**
* 单个通话记录便签项的MIME类型
*/
public static final String CONTENT_ITEM_TYPE = "vnd.android.cursor.item/call_note";
public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/call_note");//定义了通话记录内容提供者的URI，用于访问通话记录数据
/**
* 通话记录便签数据查询URI
*/
public static final Uri CONTENT_URI = Uri.parse("content://" + AUTHORITY + "/call_note");
}
}
}

372
src/Notes-master/src/net/micode/notes/data/NotesDatabaseHelper.java
Unescape View File

@ -10,30 +10,63 @@ import net.micode.notes.data.Notes.DataColumns;
import net.micode.notes.data.Notes.DataConstants;
import net.micode.notes.data.Notes.NoteColumns;
/**
* 便签数据库辅助类 (Data Layer - Database Management)
* <p>
* 核心职责：管理便签应用的SQLite数据库创建、升级和表结构维护。
* 架构说明：作为数据持久化层的核心组件，封装所有数据库操作逻辑，
* 使用SQLiteOpenHelper框架自动处理数据库版本迁移。
* 设计要点：采用触发器维护数据一致性，实现文件夹计数、数据同步等复杂业务逻辑。
*/
public class NotesDatabaseHelper extends SQLiteOpenHelper {
// 数据库帮助类，用于管理名为 note.db 的 SQLite 数据库。
// 它继承自 SQLiteOpenHelper 类，这是 Android提供的一个方便的工具类，用于管理数据库的创建和版本更新.
// 数据库的基本信息；数据库名称和版本信息（在创建实例对象时会用到）
/**
* 数据库名称常量
*/
private static final String DB_NAME = "note.db";
/**
* 数据库版本号
* <p>
* 架构说明：每次数据库架构变更都需要递增此版本号，
* 触发onUpgrade方法执行相应的迁移逻辑。
*/
private static final int DB_VERSION = 4;
//内部接口：个人理解为两个表名，一个note，一个data
/**
* 数据库表名常量定义
*/
public interface TABLE {
/**
* 便签主表：存储便签和文件夹的元数据
*/
public static final String NOTE = "note";
/**
* 便签数据表：存储便签的具体内容
*/
public static final String DATA = "data";
}
//一个标签，方便日志输出时识别出信息来自哪里
/**
* 日志标识，统一使用类名作为TAG
*/
private static final String TAG = "NotesDatabaseHelper";
//静态所有变量，提供一个全局访问点来获取数据库辅助类的唯一实例，使得在应用的任何地方都可以方便地使用它
/**
* 单例实例引用
* <p>
* 设计说明：使用静态变量持有单例实例，确保整个应用只有一个数据库连接，
* 避免多个连接导致的并发冲突和性能问题。
*/
private static NotesDatabaseHelper mInstance;
/* 以下都是一些SQL语句，辅助我们来对数据库进行操作 */
//创建note表的语句，这里的NoteColumns就是我们刚刚在Notes中定义的一个接口，里面定义了一系列静态的数据库表中的列名
/**
* 创建NOTE表的SQL语句
* <p>
* 架构说明：定义了NOTE表的所有列及其数据类型、约束条件，
* 包括主键、外键、默认值和索引等。
*/
private static final String CREATE_NOTE_TABLE_SQL =
"CREATE TABLE " + TABLE.NOTE + "(" +
NoteColumns.ID + " INTEGER PRIMARY KEY," +
@ -55,7 +88,12 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
NoteColumns.VERSION + " INTEGER NOT NULL DEFAULT 0" +
")";
//同上，创建data表的语句，这里的DataColumns就是我们刚刚在Notes中定义的一个接口，里面定义了一系列静态的数据库表中的列名
/**
* 创建DATA表的SQL语句
* <p>
* 架构说明：定义了DATA表的所有列，存储便签的具体内容，
* 通过NOTE_ID与NOTE表建立外键关系。
*/
private static final String CREATE_DATA_TABLE_SQL =
"CREATE TABLE " + TABLE.DATA + "(" +
DataColumns.ID + " INTEGER PRIMARY KEY," +
@ -71,31 +109,22 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
DataColumns.DATA5 + " TEXT NOT NULL DEFAULT ''" +
")";
// 功能简介：
// 创建一个以note的ID为索引
// 解读：
// 用于在TABLE.DATA表上创建一个名为note_id_index的索引。
// 这个索引是基于DataColumns.NOTE_ID列的。IF NOT EXISTS确保了如果索引已经存在，那么就不会尝试重新创建它，避免了可能的错误。
// 索引通常用于提高查询性能，特别是在对某个字段进行频繁查询时。
/**
* 创建DATA表NOTE_ID索引的SQL语句
* <p>
* 性能优化：为DATA表的NOTE_ID列创建索引，加速基于便签ID的查询操作。
* 设计说明：IF NOT EXISTS确保幂等性，避免重复创建索引导致错误。
*/
private static final String CREATE_DATA_NOTE_ID_INDEX_SQL =
"CREATE INDEX IF NOT EXISTS note_id_index ON " +
TABLE.DATA + "(" + DataColumns.NOTE_ID + ");";
/* 以下是一些对便签增删改定义的触发器 */
/* 总结
* 这些触发器都是用来维护NOTE表和与之相关联的DATA表之间数据一致性的。
* 当在NOTE表中发生删除或更新操作时，这些触发器会自动执行相应的数据清理或更新操作，确保数据库中的数据保持正确和一致。
* 特别是在处理文件夹和回收站等逻辑时，这些触发器起到了非常重要的作用，可以自动管理数据的移动和删除。*/
/**
* Increase folder's note count when move note to the folder
* NOTE表触发器：更新时增加文件夹计数
* <p>
* 业务逻辑：当便签的父文件夹ID（PARENT_ID）更新时，自动增加新文件夹的便签计数。
* 设计说明：使用AFTER UPDATE触发器确保数据一致性。
*/
// 功能简介：
// 添加触发器：增加文件夹的便签个数记录（因为我们会移动便签进入文件夹，这时候文件夹的计数要进行更新）
// 解读：
// 定义了一个SQL触发器increase_folder_count_on_update。
// 触发器是一种特殊的存储过程，它会在指定表上的指定事件（如INSERT、UPDATE、DELETE）发生时自动执行。
// 这个触发器会在TABLE.NOTE表的NoteColumns.PARENT_ID字段更新后执行。
// 触发器的逻辑是：当某个笔记的PARENT_ID（即父文件夹ID）被更新时，它会找到对应的文件夹（通过新的PARENT_ID），并将该文件夹的NOTES_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 +
@ -106,10 +135,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" END";
/**
* Decrease folder's note count when move note from folder
* NOTE表触发器：更新时减少文件夹计数
* <p>
* 业务逻辑：当便签的父文件夹ID（PARENT_ID）更新时，自动减少旧文件夹的便签计数。
* 安全设计：添加AND条件确保计数不会变为负数。
*/
// 功能简介：（触发器和上面的 “增加文件夹的便签个数记录” 同理，就不细节解读了）
// 添加触发器：减少文件夹的便签个数记录（因为我们会移动便签移出文件夹，这时候文件夹的计数要进行更新）
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 +
@ -121,10 +151,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" END";
/**
* Increase folder's note count when insert new note to the folder
* NOTE表触发器：插入时增加文件夹计数
* <p>
* 业务逻辑：当插入新便签时，自动增加其父文件夹的便签计数。
*/
// 功能简介：（触发器原理和上面的 “增加文件夹的便签个数记录” 同理，就不细节解读了）
// 添加触发器：当我们在文件夹插入便签时，增加文件夹的便签个数记录
private static final String NOTE_INCREASE_FOLDER_COUNT_ON_INSERT_TRIGGER =
"CREATE TRIGGER increase_folder_count_on_insert " +
" AFTER INSERT ON " + TABLE.NOTE +
@ -135,10 +165,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" END";
/**
* Decrease folder's note count when delete note from the folder
* NOTE表触发器：删除时减少文件夹计数
* <p>
* 业务逻辑：当删除便签时，自动减少其父文件夹的便签计数。
* 安全设计：添加AND条件确保计数不会变为负数。
*/
// 功能简介：（触发器原理和上面的 “增加文件夹的便签个数记录” 同理，就不细节解读了）
// 添加触发器：当我们在文件夹删除便签时，减少文件夹的便签个数记录
private static final String NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER =
"CREATE TRIGGER decrease_folder_count_on_delete " +
" AFTER DELETE ON " + TABLE.NOTE +
@ -150,13 +181,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" END";
/**
* Update note's content when insert data with type {@link DataConstants#NOTE}
* DATA表触发器：插入时更新便签摘要
* <p>
* 业务逻辑：当向DATA表插入类型为普通便签的数据时，自动更新NOTE表的摘要字段。
* 设计说明：通过触发器实现NOTE表和DATA表的实时同步。
*/
// 功能简介：
// 添加触发器：当向DATA表中插入类型为NOTE（便签）的数据时，更新note表对应的笔记内容。
// 解读：
// 在DATA表上进行INSERT操作后，如果新插入的数据的MIME_TYPE为NOTE，则触发此操作。
// 它会更新NOTE表，将与新插入数据相关联的标签的SNIPPET（摘要）字段设置为新插入数据的CONTENT字段的值
private static final String DATA_UPDATE_NOTE_CONTENT_ON_INSERT_TRIGGER =
"CREATE TRIGGER update_note_content_on_insert " +
" AFTER INSERT ON " + TABLE.DATA +
@ -168,13 +197,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" END";
/**
* Update note's content when data with {@link DataConstants#NOTE} type has changed
* DATA表触发器：更新时更新便签摘要
* <p>
* 业务逻辑：当更新DATA表中类型为普通便签的数据时，自动更新NOTE表的摘要字段。
*/
// 功能简介：
// 添加触发器：当DATA表中，类型为NOTE（便签）的数据更改时，更新note表对应的笔记内容。
// 解读：
// 在DATA表上进行UPDATE操作后，如果更新前的数据的MIME_TYPE为NOTE，则触发此操作。
// 它会更新NOTE表，将与更新后的数据相关联的笔记的SNIPPET字段设置为新数据的CONTENT字段的值
private static final String DATA_UPDATE_NOTE_CONTENT_ON_UPDATE_TRIGGER =
"CREATE TRIGGER update_note_content_on_update " +
" AFTER UPDATE ON " + TABLE.DATA +
@ -186,13 +212,10 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" END";
/**
* Update note's content when data with {@link DataConstants#NOTE} type has deleted
* DATA表触发器：删除时清空便签摘要
* <p>
* 业务逻辑：当删除DATA表中类型为普通便签的数据时，自动清空NOTE表的摘要字段。
*/
// 功能简介：
// 添加触发器：当DATA表中，类型为NOTE（便签）的数据删除时，更新note表对应的笔记内容（置空）。
// 解读：
// 在DATA表上进行DELETE操作后，如果删除的数据的MIME_TYPE为NOTE，则触发此操作。
// 它会更新NOTE表，将与删除的数据相关联的笔记的SNIPPET字段设置为空字符串。
private static final String DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER =
"CREATE TRIGGER update_note_content_on_delete " +
" AFTER delete ON " + TABLE.DATA +
@ -204,13 +227,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" END";
/**
* Delete datas belong to note which has been deleted
* NOTE表触发器：删除时级联删除数据
* <p>
* 业务逻辑：当删除NOTE表中的便签记录时，自动删除DATA表中关联的数据。
* 设计说明：实现级联删除，维护数据完整性。
*/
// 功能简介：
// 添加触发器：当从NOTE表中删除笔记时，删除与该笔记相关联的数据（就是删除data表中为该note的数据）
// 解读：
// 在NOTE表上进行DELETE操作后，此触发器被激活。
// 它会从DATA表中删除所有与已删除的笔记（由old.ID表示）相关联的数据行（通过比较DATA表中的NOTE_ID字段与已删除笔记的ID来实现）
private static final String NOTE_DELETE_DATA_ON_DELETE_TRIGGER =
"CREATE TRIGGER delete_data_on_delete " +
" AFTER DELETE ON " + TABLE.NOTE +
@ -220,13 +241,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" END";
/**
* Delete notes belong to folder which has been deleted
* NOTE表触发器：删除文件夹时级联删除子便签
* <p>
* 业务逻辑：当删除文件夹时，自动删除该文件夹下的所有便签。
* 设计说明：实现文件夹与便签的级联删除。
*/
// 功能简介：
// 添加触发器：当从NOTE表中删除一个文件夹时，删除该文件夹下的所有笔记。
// 解读：
// 在NOTE表上进行DELETE操作后，如果删除的是一个文件夹（由old.ID表示）
// 触发器会删除所有以该文件夹为父级（PARENT_ID）的笔记（通过比较NOTE表中的PARENT_ID字段与已删除文件夹的ID来实现）
private static final String FOLDER_DELETE_NOTES_ON_DELETE_TRIGGER =
"CREATE TRIGGER folder_delete_notes_on_delete " +
" AFTER DELETE ON " + TABLE.NOTE +
@ -236,13 +255,11 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" END";
/**
* Move notes belong to folder which has been moved to trash folder
* NOTE表触发器：移动文件夹到回收站时移动子便签
* <p>
* 业务逻辑：当移动文件夹到回收站时，自动将该文件夹下的所有便签也移动到回收站。
* 设计说明：确保文件夹移动操作的一致性。
*/
// 功能简介：
// 添加触发器：当某个文件夹被移动到回收站时，移动该文件夹下的所有笔记到回收站
// 解读：
// 在NOTE表上进行UPDATE操作后，如果某个文件夹的新PARENT_ID字段值等于回收站的ID（Notes.ID_TRASH_FOLER）
// 触发器会更新所有以该文件夹为父级（PARENT_ID）的笔记，将它们也移动到回收站。
private static final String FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER =
"CREATE TRIGGER folder_move_notes_on_trash " +
" AFTER UPDATE ON " + TABLE.NOTE +
@ -253,23 +270,46 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
" WHERE " + NoteColumns.PARENT_ID + "=old." + NoteColumns.ID + ";" +
" END";
// 构造器
/**
* 构造函数
*
* @param context 应用上下文，用于数据库路径定位
*/
public NotesDatabaseHelper(Context context) {
super(context, DB_NAME, null, DB_VERSION);
}
// 创建note（标签）表
/**
* 创建NOTE表及相关触发器
* <p>
* DB操作：执行CREATE TABLE语句创建NOTE表，然后创建所有相关的触发器。
* 设计说明：该方法在数据库创建和升级时被调用，确保表结构正确。
*
* @param db SQLite数据库实例
*/
public void createNoteTable(SQLiteDatabase db) {
// 1. 创建NOTE表
db.execSQL(CREATE_NOTE_TABLE_SQL);
// 2. 重建NOTE表的所有触发器
reCreateNoteTableTriggers(db);
// 3. 创建系统文件夹（根文件夹、临时文件夹、回收站等）
createSystemFolder(db);
Log.d(TAG, "note table has been created");
}
// 重新创建或更新与笔记表相关的触发器。
// 首先，使用DROP TRIGGER IF EXISTS语句删除已存在的触发器。确保在重新创建触发器之前，不存在同名的触发器。
// 然后，使用db.execSQL()方法执行预定义的SQL语句，这些语句用于创建新的触发器。
/**
* 重建NOTE表的所有触发器
* <p>
* DB操作：先删除已存在的触发器，然后重新创建所有NOTE表触发器。
* 设计说明：确保触发器定义与当前表结构保持一致。
*
* @param db SQLite数据库实例
*/
private void reCreateNoteTableTriggers(SQLiteDatabase db) {
// 1. 删除所有已存在的NOTE表触发器（幂等性设计）
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");
@ -278,6 +318,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");
// 2. 重新创建所有NOTE表触发器
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);
@ -287,89 +328,103 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
db.execSQL(FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER);
}
/* 以下部分是操作SQLite数据库部分 */
// 功能简介：
// 创建通话记录文件夹、默认文件夹、临时文件夹和回收站，并插入相关数据
// 具体解读：
// ContentValues是一个用于存储键值对的类，常用于SQLite数据库的插入操作
// values.put方法可以向ContentValues对象中添加数据。
// NoteColumns.ID是存储文件夹ID的列名，Notes.ID_CALL_RECORD_FOLDER是通话记录文件夹的ID。
// NoteColumns.TYPE是存储文件夹类型的列名，Notes.TYPE_SYSTEM表示这是一个系统文件夹。
// 使用db.insert方法将values中的数据插入到TABLE.NOTE（即标签表）中。
// 每次插入新数据前，都使用values.clear()方法清除ContentValues对象中的旧数据，确保不会重复插入旧数据。
// 然后分别创建默认文件夹、临时文件夹和回收站，并以同样的方法插入数据。
/**
* 创建系统文件夹
* <p>
* DB操作：向NOTE表插入系统文件夹记录，包括通话记录文件夹、根文件夹、临时文件夹和回收站。
* 架构说明：系统文件夹具有特殊的ID（负整数），在业务逻辑中具有特定用途。
*
* @param db SQLite数据库实例
*/
private void createSystemFolder(SQLiteDatabase db) {
ContentValues values = new ContentValues();
/**
* call record foler for call notes
* 1. 创建通话记录文件夹
* 用途：存储来自通话的便签记录
*/
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
* 2. 创建根文件夹（默认文件夹）
* 用途：作为所有便签的默认父文件夹
*/
// 创建默认文件夹：重复上述步骤，但这次是为根文件夹插入数据。
values.clear();
values.put(NoteColumns.ID, Notes.ID_ROOT_FOLDER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
/**
* temporary folder which is used for moving note
* 3. 创建临时文件夹
* 用途：在便签移动过程中作为临时存储位置
*/
// 创建“临时”文件夹：同样地，为临时文件夹插入数据。
values.clear();
values.put(NoteColumns.ID, Notes.ID_TEMPARAY_FOLDER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
/**
* create trash folder
* 4. 创建回收站文件夹
* 用途：存储已删除但未永久清除的便签
*/
// 创建“回收站”文件夹：最后，为回收站文件夹插入数据。
values.clear();
values.put(NoteColumns.ID, Notes.ID_TRASH_FOLER);
values.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
db.insert(TABLE.NOTE, null, values);
}
//功能简介：
//创建data（数据）表
//解读：
//这个方法用于创建数据表，以及与之相关的触发器。
//创建数据表：使用db.execSQL方法执行预定义的SQL语句CREATE_DATA_TABLE_SQL，用于创建数据表。
//重新创建数据表触发器：调用reCreateDataTableTriggers方法，用于删除并重新创建与数据表相关的触发器。
//创建索引：使用db.execSQL方法执行CREATE_DATA_NOTE_ID_INDEX_SQL语句，为数据表创建索引。
//记录日志：使用Log.d方法记录一条调试级别的日志，表示数据表已经创建。
/**
* 创建DATA表及相关触发器和索引
* <p>
* DB操作：执行CREATE TABLE语句创建DATA表，然后创建所有相关的触发器和索引。
* 设计说明：该方法在数据库创建和升级时被调用，确保表结构正确。
*
* @param db SQLite数据库实例
*/
public void createDataTable(SQLiteDatabase db) {
// 1. 创建DATA表
db.execSQL(CREATE_DATA_TABLE_SQL);
// 2. 重建DATA表的所有触发器
reCreateDataTableTriggers(db);
// 3. 创建NOTE_ID索引，提升查询性能
db.execSQL(CREATE_DATA_NOTE_ID_INDEX_SQL);
Log.d(TAG, "data table has been created");
}
//和上面的note表的reCreate...同理
//重新创建或更新与笔记表相关的触发器。
//首先，使用DROP TRIGGER IF EXISTS语句删除已存在的触发器。确保在重新创建触发器之前，不存在同名的触发器。
//然后，使用db.execSQL()方法执行预定义的SQL语句，这些语句用于创建新的触发器。
/**
* 重建DATA表的所有触发器
* <p>
* DB操作：先删除已存在的触发器，然后重新创建所有DATA表触发器。
* 设计说明：确保触发器定义与当前表结构保持一致。
*
* @param db SQLite数据库实例
*/
private void reCreateDataTableTriggers(SQLiteDatabase db) {
// 1. 删除所有已存在的DATA表触发器（幂等性设计）
db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_insert");
db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_update");
db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_delete");
// 2. 重新创建所有DATA表触发器
db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_INSERT_TRIGGER);
db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_UPDATE_TRIGGER);
db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER);
}
//解读：
//synchronized关键字确保在多线程环境下，只有一个线程能够进入这个方法，防止了同时创建多个实例的情况
//getInstance(Context context)方法使用了单例模式来确保整个应用程序中只有一个NotesDatabaseHelper实例。
//它首先检查mInstance（类的静态成员变量，没有在代码片段中显示）是否为null。
//如果是null，则创建一个新的NotesDatabaseHelper实例，并将其赋值给mInstance。最后返回mInstance。
/**
* 获取NotesDatabaseHelper单例实例
* <p>
* 设计说明：使用双重检查锁定模式确保线程安全的单例创建。
* 架构说明：在整个应用中共享同一个数据库实例，避免资源浪费和并发冲突。
*
* @param context 应用上下文
* @return NotesDatabaseHelper单例实例
*/
static synchronized NotesDatabaseHelper getInstance(Context context) {
if (mInstance == null) {
mInstance = new NotesDatabaseHelper(context);
@ -377,90 +432,125 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper {
return mInstance;
}
//功能简介：
//当数据库首次创建时，onCreate方法会被调用。
//这里重写onCreate方法，它调用了上述createNoteTable(db)和createDataTable(db)两个方法
//这样首次创建数据库时就多出了两张表。
/**
* 数据库创建回调方法
* <p>
* 生命周期：当数据库首次创建时由SQLiteOpenHelper框架调用。
* DB操作：创建所有表和触发器，初始化系统数据。
*
* @param db SQLite数据库实例
*/
@Override
public void onCreate(SQLiteDatabase db) {
// 1. 创建NOTE表及相关对象
createNoteTable(db);
// 2. 创建DATA表及相关对象
createDataTable(db);
}
//功能简介：
//当数据库需要升级时（即数据库的版本号改变），onUpgrade方法会被调用。
//该方法会根据当前的oldVersion和新的newVersion来执行相应的升级操作
/**
* 数据库升级回调方法
* <p>
* 生命周期：当数据库版本号增加时由SQLiteOpenHelper框架调用。
* 架构说明：支持渐进式升级，每个版本对应特定的升级逻辑。
* 设计说明：使用版本号判断升级路径，确保数据迁移的完整性。
*
* @param db SQLite数据库实例
* @param oldVersion 当前数据库版本号
* @param newVersion 目标数据库版本号
*/
@Override
public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) {
boolean reCreateTriggers = false;
boolean skipV2 = false;
// 版本1 -> 版本2的升级逻辑
if (oldVersion == 1) {
upgradeToV2(db);
skipV2 = true; // this upgrade including the upgrade from v2 to v3
skipV2 = true; // 此升级已包含版本2到版本3的升级
oldVersion++;
}
// 版本2 -> 版本3的升级逻辑（如果未跳过）
if (oldVersion == 2 && !skipV2) {
upgradeToV3(db);
reCreateTriggers = true;
oldVersion++;
}
// 版本3 -> 版本4的升级逻辑
if (oldVersion == 3) {
upgradeToV4(db);
oldVersion++;
}
// 如果需要，重新创建触发器
if (reCreateTriggers) {
reCreateNoteTableTriggers(db);
reCreateDataTableTriggers(db);
}
if (oldVersion != newVersion) { //数据库升级失败，抛出一个异常，表示数据库升级失败
// 版本号检查：确保升级过程正确执行
if (oldVersion != newVersion) {
throw new IllegalStateException("Upgrade notes database to version " + newVersion
+ "fails");
}
}
//功能简介：
// 将数据库从版本1升级到版本2。
//解读：
// 首先，它删除了已经存在的NOTE和DATA表（如果存在的话）。DROP TABLE IF EXISTS语句确保了即使这些表不存在，也不会抛出错误。
// 然后，它调用了createNoteTable(db)和createDataTable(db)方法来重新创建这两个表。这意味着在升级到版本2时，这两个表的内容会被完全清除，并重新创建新的空表。
/**
* 数据库版本1到版本2的升级逻辑
* <p>
* DB操作：删除旧表并重新创建，实现完全重构。
* 设计说明：此升级方式会丢失所有数据，适用于早期版本或架构重大变更。
*
* @param db SQLite数据库实例
*/
private void upgradeToV2(SQLiteDatabase db) {
// 1. 删除旧表（如果存在）
db.execSQL("DROP TABLE IF EXISTS " + TABLE.NOTE);
db.execSQL("DROP TABLE IF EXISTS " + TABLE.DATA);
// 2. 重新创建所有表
createNoteTable(db);
createDataTable(db);
}
//功能简介：
// 将数据库从版本2（或可能是跳过版本2的某个状态）升级到版本3。
//解读：
// 首先，删除了三个不再使用的触发器（如果存在的话）。触发器是数据库中的一种对象，可以在插入、更新或删除记录时自动执行某些操作。
// 然后，使用ALTER TABLE语句修改表结构，向NOTE表中添加了一个名为GTASK_ID的新列，并设置默认值为空字符串。
// 最后，向NOTE表中插入了一条新的系统文件夹记录，表示一个名为“trash folder”的系统文件夹。这可能是用于存储已删除笔记的回收站功能。
/**
* 数据库版本2到版本3的升级逻辑
* <p>
* DB操作：删除无用触发器、添加新列、插入新系统文件夹。
* 架构说明：此版本引入了Google Tasks集成和回收站功能。
*
* @param db SQLite数据库实例
*/
private void upgradeToV3(SQLiteDatabase db) {
// drop unused triggers
// 1. 删除不再使用的旧触发器
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
// 2. 向NOTE表添加GTASK_ID列（用于Google Tasks集成）
db.execSQL("ALTER TABLE " + TABLE.NOTE + " ADD COLUMN " + NoteColumns.GTASK_ID
+ " TEXT NOT NULL DEFAULT ''");
// add a trash system folder
// 3. 向NOTE表插入回收站系统文件夹
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);
}
//功能简介：
// 这个方法负责将数据库从版本3升级到版本4。
//解读：
// 它向NOTE表中添加了一个名为VERSION的新列，并设置了默认值为0。这个新列用于记录标签版本信息。
/**
* 数据库版本3到版本4的升级逻辑
* <p>
* DB操作：向NOTE表添加VERSION列。
* 架构说明：此版本引入了乐观锁机制，用于处理并发修改冲突。
*
* @param db SQLite数据库实例
*/
private void upgradeToV4(SQLiteDatabase db) {
// 向NOTE表添加VERSION列（用于乐观锁控制）
db.execSQL("ALTER TABLE " + TABLE.NOTE + " ADD COLUMN " + NoteColumns.VERSION
+ " INTEGER NOT NULL DEFAULT 0");
}

377
src/Notes-master/src/net/micode/notes/data/NotesProvider.java
Unescape View File

@ -1,6 +1,5 @@
package net.micode.notes.data;
import android.app.SearchManager;
import android.content.ContentProvider;
import android.content.ContentUris;
@ -18,156 +17,189 @@ import net.micode.notes.data.Notes.DataColumns;
import net.micode.notes.data.Notes.NoteColumns;
import net.micode.notes.data.NotesDatabaseHelper.TABLE;
/**
* 便签数据内容提供者 (Data Layer - Content Provider)
* <p>
* 核心职责：作为Android ContentProvider提供便签数据的标准访问接口，
* 封装所有CRUD操作，支持数据变更通知、搜索建议和内容观察者模式。
* 架构说明：该组件是MVC架构中数据层的核心入口，通过ContentResolver为UI层提供统一的数据访问接口。
* 设计要点：支持URI模式匹配，实现便签和数据的精细化管理，集成Android全局搜索功能。
*/
public class NotesProvider extends ContentProvider {
// Android 应用程序中的一部分：内容提供者（ContentProvider）。
// 内容提供者是 Android 四大组件之一，它允许应用程序之间共享数据。
//概述：
//NotesProvider的主要功能是作为一个内容提供者，为其他应用程序或组件提供对“Notes”数据的访问。
//它允许其他应用程序查询、插入、更新或删除标签数据。
//通过URI匹配，NotesProvider能够区分对哪种数据类型的请求（例如，单独的标签、标签的数据、文件夹操作等），并执行相应的操作。
//用于匹配不同URI的UriMatcher对象，通常用于解析传入的URI，并确定应该执行哪种操作。
/**
* URI匹配器，用于解析和分发不同的URI请求
* <p>
* 架构说明：通过预定义的URI模式，将不同的URI映射到不同的操作类型，
* 实现对便签和数据表的精确访问控制。
*/
private static final UriMatcher mMatcher;
//NotesDatabaseHelper实类，用来操作SQLite数据库，负责创建、更新和查询数据库。
/**
* 数据库辅助类实例，负责数据库的创建和版本管理
*/
private NotesDatabaseHelper mHelper;
//标签，输出日志时用来表示是该类发出的消息
/**
* 日志标识，统一使用类名作为TAG
*/
private static final String TAG = "NotesProvider";
//6个URI的匹配码，用于区分不同的URI类型
private static final int URI_NOTE = 1;
private static final int URI_NOTE_ITEM = 2;
private static final int URI_DATA = 3;
private static final int URI_DATA_ITEM = 4;
private static final int URI_SEARCH = 5;
private static final int URI_SEARCH_SUGGEST = 6;
/**
* URI匹配码常量定义
* <p>
* 设计说明：每个匹配码对应一种特定的数据访问场景，
* 支持对便签、数据项、搜索和搜索建议的差异化处理。
*/
private static final int URI_NOTE = 1; // 便签表（集合）
private static final int URI_NOTE_ITEM = 2; // 单个便签项
private static final int URI_DATA = 3; // 数据表（集合）
private static final int URI_DATA_ITEM = 4; // 单个数据项
private static final int URI_SEARCH = 5; // 便签搜索
private static final int URI_SEARCH_SUGGEST = 6; // 搜索建议
//进一步定义了URI匹配规则和搜索查询的投影
//功能概述：
//初始化了一个UriMatcher对象mMatcher，并添加了一系列的URI匹配规则。
//解读：
/**
* 静态初始化块：构建URI匹配规则表
* <p>
* 架构说明：在类加载时初始化URI匹配器，定义所有支持的URI模式，
* 每个模式对应一个唯一的匹配码，用于在后续操作中识别请求类型。
*/
static {
//创建了一个UriMatcher实例，并设置默认匹配码为NO_MATCH，表示如果没有任何URI匹配，则返回这个码。
// 创建UriMatcher实例，设置默认匹配码为NO_MATCH
mMatcher = new UriMatcher(UriMatcher.NO_MATCH);
//添加规则，当URI的authority为Notes.AUTHORITY，路径为note时，返回匹配码URI_NOTE。
mMatcher.addURI(Notes.AUTHORITY, "note", URI_NOTE);
//添加规则，当URI的authority为Notes.AUTHORITY，路径为note/后跟一个数字（#代表数字）时，返回匹配码URI_NOTE_ITEM。
mMatcher.addURI(Notes.AUTHORITY, "note/#", URI_NOTE_ITEM);
//和上面两句同理，但用于匹配数据相关的URI
mMatcher.addURI(Notes.AUTHORITY, "data", URI_DATA);
mMatcher.addURI(Notes.AUTHORITY, "data/#", URI_DATA_ITEM);
//用于匹配搜索相关的URI
mMatcher.addURI(Notes.AUTHORITY, "search", URI_SEARCH);
//这两行用于匹配搜索建议相关的URI
mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY, URI_SEARCH_SUGGEST);
mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY + "/*", URI_SEARCH_SUGGEST);
// 添加便签表相关URI规则
mMatcher.addURI(Notes.AUTHORITY, "note", URI_NOTE); // content://micode_notes/note
mMatcher.addURI(Notes.AUTHORITY, "note/#", URI_NOTE_ITEM); // content://micode_notes/note/{id}
// 添加数据表相关URI规则
mMatcher.addURI(Notes.AUTHORITY, "data", URI_DATA); // content://micode_notes/data
mMatcher.addURI(Notes.AUTHORITY, "data/#", URI_DATA_ITEM); // content://micode_notes/data/{id}
// 添加搜索相关URI规则
mMatcher.addURI(Notes.AUTHORITY, "search", URI_SEARCH); // content://micode_notes/search
mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY, URI_SEARCH_SUGGEST); // content://micode_notes/search_suggest_query
mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY + "/*", URI_SEARCH_SUGGEST); // content://micode_notes/search_suggest_query/*
}
/**
* 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.
* 便签搜索查询投影定义
* <p>
* 架构说明：为Android全局搜索建议功能定制的投影列，
* 按照SearchManager的规范返回搜索建议所需的数据格式。
*
* 设计要点：
* 1. 使用SQLite的REPLACE函数去除换行符，确保搜索结果显示整洁
* 2. 通过TRIM函数去除首尾空格，优化显示效果
* 3. 返回统一的搜索图标和Intent配置，提供一致的用户体验
*
* 注意：x'0A'在SQLite中代表换行符'\n'
*/
private static final String NOTES_SEARCH_PROJECTION =
NoteColumns.ID + "," // 便签ID
+ NoteColumns.ID + " AS " + SearchManager.SUGGEST_COLUMN_INTENT_EXTRA_DATA + "," // Intent额外数据
+ "TRIM(REPLACE(" + NoteColumns.SNIPPET + ", x'0A','')) AS " + SearchManager.SUGGEST_COLUMN_TEXT_1 + "," // 建议文本行1
+ "TRIM(REPLACE(" + NoteColumns.SNIPPET + ", x'0A','')) AS " + SearchManager.SUGGEST_COLUMN_TEXT_2 + "," // 建议文本行2
+ R.drawable.search_result + " AS " + SearchManager.SUGGEST_COLUMN_ICON_1 + "," // 建议图标
+ "'" + Intent.ACTION_VIEW + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_ACTION + "," // Intent动作
+ "'" + Notes.TextNote.CONTENT_TYPE + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA; // Intent数据类型
/**
* 便签片段搜索查询SQL语句
* <p>
* 业务逻辑：根据便签片段内容进行模糊搜索，支持Android全局搜索功能。
* 查询条件：
* 1. 内容匹配：使用LIKE进行模糊匹配
* 2. 排除回收站：不显示已移动到回收站的便签
* 3. 类型过滤：只搜索普通便签，排除文件夹等特殊类型
*/
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;
/**
* ContentProvider初始化方法
* <p>
* 生命周期：在ContentProvider创建时被系统调用，用于初始化数据源。
* 架构说明：获取数据库辅助类的单例实例，确保整个应用共享同一个数据库连接。
*
* @return 总是返回true，表示初始化成功
*/
//功能概述：
//一个 SQL 查询的投影部分，用于定义查询返回的结果集中应该包含哪些列。
//解读：（每行对应）
//返回笔记的 ID。
//笔记的 ID 也被重命名为 SUGGEST_COLUMN_INTENT_EXTRA_DATA，这通常用于 Android 的搜索建议中，作为传递给相关 Intent 的额外数据。
//对 SNIPPET 列的处理：首先使用 REPLACE 函数将 x'0A'（即换行符 \n）替换为空字符串，然后使用 TRIM 函数删除前后的空白字符，处理后的结果分别重命名为 SUGGEST_COLUMN_TEXT_1
//对 SNIPPET 列的处理：首先使用 REPLACE 函数将 x'0A'（即换行符 \n）替换为空字符串，然后使用 TRIM 函数删除前后的空白字符，处理后的结果分别重命名为 SUGGEST_COLUMN_TEXT_2
//返回一个用于搜索建议图标的资源 ID，并命名为 SUGGEST_COLUMN_ICON_1。
//返回一个固定的 Intent 动作 ACTION_VIEW，并命名为 SUGGEST_COLUMN_INTENT_ACTION。
//返回一个内容类型，并命名为 SUGGEST_COLUMN_INTENT_DATA。
private static final String NOTES_SEARCH_PROJECTION = NoteColumns.ID + "," //返回笔记的 ID
+ NoteColumns.ID + " AS " + SearchManager.SUGGEST_COLUMN_INTENT_EXTRA_DATA + ","
+ "TRIM(REPLACE(" + NoteColumns.SNIPPET + ", x'0A','')) AS " + SearchManager.SUGGEST_COLUMN_TEXT_1 + ","
+ "TRIM(REPLACE(" + NoteColumns.SNIPPET + ", x'0A','')) AS " + SearchManager.SUGGEST_COLUMN_TEXT_2 + ","
+ R.drawable.search_result + " AS " + SearchManager.SUGGEST_COLUMN_ICON_1 + ","
+ "'" + Intent.ACTION_VIEW + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_ACTION + ","
+ "'" + Notes.TextNote.CONTENT_TYPE + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA;
//功能概述：
//完整的 SQL 查询语句，用于从 TABLE.NOTE 表中检索信息
//解读：
// 使用上面定义的投影来选择数据。
// 并指定从哪个表中选择数据。
//WHERE子句包含三个条件：
// ①搜索 SNIPPET 列中包含特定模式的行（? 是一个占位符，实际查询时会用具体的值替换）。
// ②父ID不为回收站的ID：排除那些父 ID 为回收站的行。
// ③只选择类型为note（标签）的行。
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;
//重写onCreate方法：
//getContext() 方法被调用以获取当前组件的上下文（Context），以便 NotesDatabaseHelper 能够访问应用程序的资源和其他功能
//mHelper用于存储从 NotesDatabaseHelper.getInstance 方法返回的实例。这样，该实例就可以在整个组件的其他方法中被访问和使用。
@Override
public boolean onCreate() {
// 获取NotesDatabaseHelper单例实例
mHelper = NotesDatabaseHelper.getInstance(getContext());
return true;
}
//功能：查询数据
/**
* 查询数据 (核心查询接口)
* <p>
* 架构说明：支持多种查询场景，包括便签查询、数据查询、搜索和搜索建议。
* 设计要点：根据URI匹配码执行不同的查询逻辑，支持投影、筛选、排序等标准参数。
*
* @param uri 查询的目标URI，决定查询哪张表或哪个具体项
* @param projection 查询返回的列，null表示返回所有列
* @param selection WHERE条件子句，null表示无筛选条件
* @param selectionArgs WHERE条件参数，用于替换selection中的'?'
* @param sortOrder 排序规则，null表示使用默认排序
* @return 查询结果的Cursor对象，如果没有匹配结果则返回null
*/
@Override
public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs,
String sortOrder) {
//初始化变量：
//Cursor对象 c，用来存储查询结果
//使用 NotesDatabaseHelper 的实例 mHelper来获取一个可读的数据库实例
//定义一个字符串id，用来存储从URI中解析出的ID
Cursor c = null;
SQLiteDatabase db = mHelper.getReadableDatabase();
String id = null;
//根据匹配不同的URI来进行不同的查询
// 根据URI匹配码执行不同的查询逻辑
switch (mMatcher.match(uri)) {
// URI_NOTE：查询整个 NOTE 表。
// URI_NOTE_ITEM：查询 NOTE 表中的特定项。ID 从 URI 的路径段中获取，并添加到查询条件中。
// URI_DATA：查询整个 DATA 表。
// URI_DATA_ITEM：查询 DATA 表中的特定项。ID 的获取和处理方式与 URI_NOTE_ITEM 相同。
case URI_NOTE:
// 查询便签表（集合查询）
c = db.query(TABLE.NOTE, projection, selection, selectionArgs, null, null,
sortOrder);
break;
case URI_NOTE_ITEM:
id = uri.getPathSegments().get(1);
// 查询单个便签项（ID查询）
id = uri.getPathSegments().get(1); // 从URI路径中提取ID
c = db.query(TABLE.NOTE, projection, NoteColumns.ID + "=" + id
+ parseSelection(selection), selectionArgs, null, null, sortOrder);
break;
case URI_DATA:
// 查询数据表（集合查询）
c = db.query(TABLE.DATA, projection, selection, selectionArgs, null, null,
sortOrder);
break;
case URI_DATA_ITEM:
id = uri.getPathSegments().get(1);
// 查询单个数据项（ID查询）
id = uri.getPathSegments().get(1); // 从URI路径中提取ID
c = db.query(TABLE.DATA, projection, DataColumns.ID + "=" + id
+ parseSelection(selection), selectionArgs, null, null, sortOrder);
break;
//URI_SEARCH 和 URI_SEARCH_SUGGEST：处理搜索查询。
// 代码首先检查是否提供了不应与搜索查询一起使用的参数（如 sortOrder, selection, selectionArgs, 或 projection）。
// 如果提供了这些参数，则抛出一个 IllegalArgumentException。
// 根据 URI 类型，从 URI 的路径段或查询参数中获取搜索字符串 searchString。
// 如果 searchString 为空或无效，则返回 null，表示没有搜索结果。
case URI_SEARCH:
case URI_SEARCH_SUGGEST:
// 处理搜索和搜索建议查询
if (sortOrder != null || projection != null) {
throw new IllegalArgumentException(
"do not specify sortOrder, selection, selectionArgs, or projection" + "with this query");
"do not specify sortOrder, selection, selectionArgs, or projection" +
"with this query");
}
String searchString = null;
if (mMatcher.match(uri) == URI_SEARCH_SUGGEST) {
// 搜索建议：从URI路径段获取搜索词
if (uri.getPathSegments().size() > 1) {
searchString = uri.getPathSegments().get(1);
}
} else {
// 普通搜索：从查询参数获取搜索模式
searchString = uri.getQueryParameter("pattern");
}
@ -175,9 +207,9 @@ public class NotesProvider extends ContentProvider {
return null;
}
//字符串格式化：格式化后的字符串就会是 "%s%"，即包含s是任何文本
//然后执行原始SQL查询
// DB操作：执行原始SQL查询进行模糊匹配
try {
// 格式化为SQL LIKE模式的搜索字符串
searchString = String.format("%%%s%%", searchString);
c = db.rawQuery(NOTES_SNIPPET_SEARCH_QUERY,
new String[] { searchString });
@ -186,92 +218,104 @@ public class NotesProvider extends ContentProvider {
}
break;
//未知URI处理：
default:
// 未知URI类型，抛出异常
throw new IllegalArgumentException("Unknown URI " + uri);
}
//如果查询结果不为空（即 Cursor 对象 c 不是 null），则为其设置一个通知 URI。
//这意味着当与这个 URI 关联的数据发生变化时，任何注册了监听这个 URI 的 ContentObserver 都会被通知。
// 注册内容观察：当查询结果对应的数据发生变化时，Cursor会自动收到通知
if (c != null) {
c.setNotificationUri(getContext().getContentResolver(), uri);
}
return c;
}
//功能：插入数据
//参数：Uri 用来标识要插入数据的表，ContentValues对象包含要插入的键值对
/**
* 插入数据 (核心插入接口)
* <p>
* 架构说明：支持向便签表和数据表插入新记录，自动处理外键关联。
* 设计要点：插入后发送数据变更通知，确保UI及时刷新。
*
* @param uri 插入的目标URI，决定插入到哪张表
* @param values 要插入的数据键值对
* @return 新插入数据的完整URI，包含生成的ID
*/
@Override
public Uri insert(Uri uri, ContentValues values) {
//获取数据库
//三个长整型变量，分别用来存储数据项ID、便签ID 和插入行的ID
SQLiteDatabase db = mHelper.getWritableDatabase();
long dataId = 0, noteId = 0, insertedId = 0;
//对于 URI_NOTE，将values插入到 TABLE.NOTE 表中，并返回插入行的 ID。
//对于 URI_DATA，首先检查values是否包含 DataColumns.NOTE_ID，如果包含，则获取其值。如果不包含，记录一条日志信息。然后，将 values 插入到 TABLE.DATA 表中，并返回插入行的 ID。
//如果 uri 不是已知的 URI 类型，则抛出一个 IllegalArgumentException。
// 根据URI匹配码执行不同的插入逻辑
switch (mMatcher.match(uri)) {
case URI_NOTE:
// DB操作：向便签表插入新记录
insertedId = noteId = db.insert(TABLE.NOTE, null, values);
break;
case URI_DATA:
// 检查是否包含关联的便签ID
if (values.containsKey(DataColumns.NOTE_ID)) {
noteId = values.getAsLong(DataColumns.NOTE_ID);
} else {
Log.d(TAG, "Wrong data format without note id:" + values.toString());
}
// DB操作：向数据表插入新记录
insertedId = dataId = db.insert(TABLE.DATA, null, values);
break;
default:
throw new IllegalArgumentException("Unknown URI " + uri);
}
//功能：通知变化
//如果noteId 或 dataId 大于 0（即成功插入了数据），则使用 ContentResolver 的 notifyChange 方法通知监听这些 URI 的观察者，告知数据已经改变。
//ContentUris.withAppendedId 方法用于在基本 URI 后面追加一个 ID，形成完整的 URI。
// Notify the note uri
// 数据变更通知机制：通知所有观察者数据已更新
// 通知便签URI的观察者
if (noteId > 0) {
getContext().getContentResolver().notifyChange(
ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId), null);
}
// Notify the data uri
// 通知数据URI的观察者
if (dataId > 0) {
getContext().getContentResolver().notifyChange(
ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, dataId), null);
}
//返回包含新插入数据项ID 的 Uri。允许调用者知道新插入的数据项的位置
// 返回新插入数据的完整URI
return ContentUris.withAppendedId(uri, insertedId);
}
//功能：删除数据项
//参数：uri：标识要删除数据的表或数据项。 selection：一个可选的 WHERE 子句，用于指定删除条件。 selectionArgs：一个可选的字符串数组，用于替换 selection 中的占位符
/**
* 删除数据 (核心删除接口)
* <p>
* 架构说明：支持从便签表和数据表删除记录，支持条件删除和ID删除。
* 业务逻辑：包含安全检查，防止删除系统文件夹（ID<=0）。
*
* @param uri 删除的目标URI，决定删除哪张表或哪个具体项
* @param selection WHERE条件子句，null表示删除所有匹配记录
* @param selectionArgs WHERE条件参数
* @return 实际删除的记录数量
*/
@Override
public int delete(Uri uri, String selection, String[] selectionArgs) {
//count：记录被删除的行数。
//id：用于存储从 URI 中解析出的数据项 ID。
//db：可写的数据库对象，用于执行删除操作。
//deleteData：一个布尔值，用于标记是否删除了 DATA 表中的数据。
int count = 0;
String id = null;
SQLiteDatabase db = mHelper.getWritableDatabase();
boolean deleteData = false;
// 根据URI匹配码执行不同的删除逻辑
switch (mMatcher.match(uri)) {
//URI_NOTE: 修改 selection 语句：确保只删除 ID 大于 0 的笔记。然后执行删除操作并返回被删除的行数。
//URI_NOTE_ITEM: 从 URI 中解析出 ID。检查 ID 是否小于等于 0，如果是，则不执行删除操作；否则执行删除操作并返回被删除的行数
//URI_DATA： 执行删除操作并返回被删除的行数。设置 deleteData 为 true，表示删除了 DATA 表中的数据。
//URI_DATA_ITEM： 先从 URI 中解析出 ID，然后执行删除操作并返回被删除的行数，并设置 deleteData 为 true，表示删除了 DATA 表中的数据。
case URI_NOTE:
// 便签表集合删除：确保不删除系统文件夹（ID>0）
selection = "(" + selection + ") AND " + NoteColumns.ID + ">0 ";
count = db.delete(TABLE.NOTE, selection, selectionArgs);
break;
case URI_NOTE_ITEM:
// 单个便签项删除
id = uri.getPathSegments().get(1);
/**
* ID that smaller than 0 is system folder which is not allowed to
* trash
* 安全限制：ID小于等于0的是系统文件夹，不允许删除
* 这保护了通话记录文件夹、根文件夹、临时文件夹和回收站
*/
long noteId = Long.valueOf(id);
if (noteId <= 0) {
@ -280,94 +324,126 @@ public class NotesProvider extends ContentProvider {
count = db.delete(TABLE.NOTE,
NoteColumns.ID + "=" + id + parseSelection(selection), selectionArgs);
break;
case URI_DATA:
// 数据表集合删除
count = db.delete(TABLE.DATA, selection, selectionArgs);
deleteData = true;
break;
case URI_DATA_ITEM:
// 单个数据项删除
id = uri.getPathSegments().get(1);
count = db.delete(TABLE.DATA,
DataColumns.ID + "=" + id + parseSelection(selection), selectionArgs);
deleteData = true;
break;
default:
throw new IllegalArgumentException("Unknown URI " + uri);
}
//如果 count 大于 0，说明有数据被删除。
//如果 deleteData 为 true，则通知监听 Notes.CONTENT_NOTE_URI 的观察者，数据已改变。
//通知监听传入 uri 的观察者数据已改变。
// 数据变更通知机制
if (count > 0) {
if (deleteData) {
// 数据表删除需要通知便签观察者，因为便签摘要可能受影响
getContext().getContentResolver().notifyChange(Notes.CONTENT_NOTE_URI, null);
}
// 通知当前URI的观察者
getContext().getContentResolver().notifyChange(uri, null);
}
return count;
}
//功能：更新数据库的数据
//参数：uri：标识要更新数据的表或数据项。 values：一个包含新值的键值对集合。
// selection：一个可选的 WHERE 子句，用于指定更新条件。 selectionArgs：一个可选的字符串数组，用于替换 selection 中的占位符。
/**
* 更新数据 (核心更新接口)
* <p>
* 架构说明：支持便签表和数据表的更新操作，包含乐观锁控制。
* 设计要点：更新便签时会自动增加版本号，用于冲突检测和同步管理。
*
* @param uri 更新的目标URI，决定更新哪张表或哪个具体项
* @param values 要更新的数据键值对
* @param selection WHERE条件子句，null表示更新所有匹配记录
* @param selectionArgs WHERE条件参数
* @return 实际更新的记录数量
*/
@Override
public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) {
//count：记录被更新的行数。
//id：用于存储从 URI 中解析出的数据项 ID。
//db：可写的 SQLite 数据库对象，用于执行更新操作。
//updateData：用于标记是否更新了 data 表中的数据。
int count = 0;
String id = null;
SQLiteDatabase db = mHelper.getWritableDatabase();
boolean updateData = false;
// 根据URI匹配码执行不同的更新逻辑
switch (mMatcher.match(uri)) {
//URI_NOTE：调用 increaseNoteVersion 方法（用于增加便签版本），然后在note表执行更新操作并返回被更新的行数。
//URI_NOTE_ITEM：从 URI 中解析出 ID，并调用 increaseNoteVersion 方法，传入解析出的 ID，最后在note表执行更新操作并返回被更新的行数。
//URI_DATA：在data表执行更新操作并返回被更新的行数。设置 updateData 为 true，表示更新了 DATA 表中的数据。
//URI_DATA_ITEM：从 URI 中解析出 ID。执行更新操作并返回被更新的行数。置 updateData 为 true，表示更新了 DATA 表中的数据。
case URI_NOTE:
// 便签表集合更新：增加版本号并执行更新
increaseNoteVersion(-1, selection, selectionArgs);
count = db.update(TABLE.NOTE, values, selection, selectionArgs);
break;
case URI_NOTE_ITEM:
// 单个便签项更新：增加版本号并执行更新
id = uri.getPathSegments().get(1);
increaseNoteVersion(Long.valueOf(id), selection, selectionArgs);
count = db.update(TABLE.NOTE, values, NoteColumns.ID + "=" + id
+ parseSelection(selection), selectionArgs);
break;
case URI_DATA:
// 数据表集合更新
count = db.update(TABLE.DATA, values, selection, selectionArgs);
updateData = true;
break;
case URI_DATA_ITEM:
// 单个数据项更新
id = uri.getPathSegments().get(1);
count = db.update(TABLE.DATA, values, DataColumns.ID + "=" + id
+ parseSelection(selection), selectionArgs);
updateData = true;
break;
default:
throw new IllegalArgumentException("Unknown URI " + uri);
}
//如果 count 大于 0，说明有数据被更新。
//如果 updateData 为 true，则通知监听 Notes.CONTENT_NOTE_URI 的观察者数据已改变。
//通知监听传入 uri 的观察者数据已改变。
// 数据变更通知机制
if (count > 0) {
if (updateData) {
// 数据表更新需要通知便签观察者
getContext().getContentResolver().notifyChange(Notes.CONTENT_NOTE_URI, null);
}
// 通知当前URI的观察者
getContext().getContentResolver().notifyChange(uri, null);
}
return count;
}
//解析传入的条件语句：一个 SQL WHERE 子句的一部分
/**
* 解析筛选条件，构建AND连接的WHERE子句片段
* <p>
* 设计说明：将用户提供的筛选条件与ID条件组合，构建完整的WHERE子句。
* 如果用户条件为空，返回空字符串；否则返回" AND (条件)"格式。
*
* @param selection 用户提供的筛选条件
* @return 格式化后的WHERE子句片段
*/
private String parseSelection(String selection) {
return (!TextUtils.isEmpty(selection) ? " AND (" + selection + ')' : "");
}
//更新note表的version列，将其值增加 1。
/**
* 增加便签版本号 (乐观锁控制)
* <p>
* 架构说明：每次更新便签时自动增加版本号，实现乐观锁机制。
* 设计要点：通过版本号检测并发修改冲突，支持数据同步和冲突解决。
*
* @param id 便签ID，-1表示批量更新（使用selection条件）
* @param selection 批量更新的筛选条件
* @param selectionArgs 筛选条件参数
*/
private void increaseNoteVersion(long id, String selection, String[] selectionArgs) {
StringBuilder sql = new StringBuilder(120);
sql.append("UPDATE ");
@ -376,6 +452,7 @@ public class NotesProvider extends ContentProvider {
sql.append(NoteColumns.VERSION);
sql.append("=" + NoteColumns.VERSION + "+1 ");
// 构建WHERE子句
if (id > 0 || !TextUtils.isEmpty(selection)) {
sql.append(" WHERE ");
}
@ -383,6 +460,7 @@ public class NotesProvider extends ContentProvider {
sql.append(NoteColumns.ID + "=" + String.valueOf(id));
}
if (!TextUtils.isEmpty(selection)) {
// 处理参数替换
String selectString = id > 0 ? parseSelection(selection) : selection;
for (String args : selectionArgs) {
selectString = selectString.replaceFirst("\\?", args);
@ -390,13 +468,24 @@ public class NotesProvider extends ContentProvider {
sql.append(selectString);
}
// DB操作：执行版本号更新
mHelper.getWritableDatabase().execSQL(sql.toString());
}
/**
* 获取URI对应的MIME类型
* <p>
* 架构说明：返回URI对应的数据类型，用于Intent过滤和数据类型识别。
* 当前实现返回null，但可以根据业务需求扩展支持。
*
* @param uri 要查询的URI
* @return URI对应的MIME类型，当前返回null
*/
@Override
public String getType(Uri uri) {
// TODO Auto-generated method stub
// TODO: 根据URI返回相应的MIME类型
// 例如：对于单个便签返回vnd.android.cursor.item/text_note
// 对于便签列表返回vnd.android.cursor.dir/text_note
return null;
}
}

135
src/Notes-master/src/net/micode/notes/gtask/data/MetaData.java
Unescape View File

@ -16,86 +16,111 @@
package net.micode.notes.gtask.data;
import android.database.Cursor; // 数据库查询游标：父类方法参数，此类未实际使用
import android.util.Log; // 日志工具：打印错误/警告日志
import android.database.Cursor;
import android.util.Log;
import net.micode.notes.tool.GTaskStringUtils; // GTask字符串工具类：存储元数据相关常量（如Gid字段名）
import net.micode.notes.tool.GTaskStringUtils;
import org.json.JSONException; // JSON解析异常：JSON操作失败时抛出
import org.json.JSONObject; // JSON对象：存储和解析元数据键值对
import org.json.JSONException;
import org.json.JSONObject;
/**
* GTask元数据封装类
* 通俗说：这个类是GTask的“关联信息管家”，继承自GTask任务类（Task），
* 专门用来存储本地便签和远程GTask任务之间的关联元信息（核心是远程GTask的唯一ID），
* 负责元信息的JSON序列化（转为字符串存储）和反序列化（从字符串解析出关联ID）
* GTask元数据任务类 (Data Layer - Google Tasks Integration)
* <p>
* 核心职责：作为便签应用与Google Tasks服务之间的元数据桥梁，
* 存储和管理本地便签与远程Google Tasks任务的关联关系。
* 架构说明：继承自Task基类，实现GTask数据模型规范，
* 通过JSON格式在notes字段中封装元数据信息。
* 设计要点：使用特殊任务类型标识元数据，避免与普通便签任务混淆。
*/
public class MetaData extends Task {
// 日志标签：使用类名作为标签，方便定位该类的日志信息
/**
* 日志标识，使用类名作为TAG
*/
private final static String TAG = MetaData.class.getSimpleName();
// 关联的远程GTask唯一ID：用来绑定本地便签和远程GTask任务（null表示未关联）
/**
* 关联的Google Tasks任务ID
* <p>
* 架构说明：该字段存储远程Google Tasks任务的唯一标识符，
* 用于建立本地便签与云端任务的一对一映射关系。
*/
private String mRelatedGid = null;
/**
* 设置元数据（绑定远程GTask ID并序列化）
* 通俗说：把远程GTask的唯一ID存入元信息JSON对象，再将JSON转为字符串作为任务备注，
* 同时把任务名称设为元数据专用名称，方便GTask识别这是元数据任务
* @param gid 远程GTask任务的唯一ID（关联标识）
* @param metaInfo 元信息JSON对象（用于存储额外元数据）
* 设置元数据（关联关系绑定）
* <p>
* 业务逻辑：将远程Google Tasks任务ID与额外元信息组合为JSON格式，
* 存储到当前任务的notes字段中，同时将任务名称标记为元数据类型。
* 设计说明：notes字段作为元数据载体，避免修改GTask标准数据模型。
*
* @param gid 远程Google Tasks任务的唯一标识符
* @param metaInfo 额外元信息JSON对象（可扩展存储其他关联信息）
*/
public void setMeta(String gid, JSONObject metaInfo) {
try {
// 将远程GTask ID存入JSON对象，键为元数据头部GTask ID常量
// 将Google Tasks任务ID添加到元信息JSON对象中
metaInfo.put(GTaskStringUtils.META_HEAD_GTASK_ID, gid);
} catch (JSONException e) {
// JSON存入失败，打印错误日志
// 异常处理：JSON操作失败记录错误日志
Log.e(TAG, "failed to put related gid");
}
// 将元信息JSON对象转为字符串，设置为当前任务的备注（存储元数据）
// 将JSON对象序列化为字符串，存储到notes字段
setNotes(metaInfo.toString());
// 将任务名称设为元数据专用名称，标识这是元数据任务
// 设置任务名称为元数据标识，便于GTask服务器识别
setName(GTaskStringUtils.META_NOTE_NAME);
}
/**
* 获取关联的远程GTask唯一ID
* 通俗说：外部调用该方法，获取本地便签绑定的远程GTask任务ID
* @return 远程GTask ID（null表示未关联）
* 获取关联的Google Tasks任务ID
* <p>
* 架构说明：外部接口用于查询本地便签关联的云端任务标识，
* 用于同步操作中的任务匹配和数据关联。
*
* @return 关联的Google Tasks任务ID，null表示未建立关联
*/
public String getRelatedGid() {
return mRelatedGid;
}
/**
* 重写父类方法：判断元数据是否值得保存
* 通俗说：只要元数据的备注（JSON字符串）不为空，就表示有有效元信息，值得保存到GTask
* @return true=值得保存，false=无需保存
* 判断元数据是否值得保存到Google Tasks
* <p>
* 重写说明：覆盖父类方法，定义元数据任务的保存条件。
* 业务逻辑：只要notes字段包含有效的元数据JSON字符串，
* 就认为该元数据任务需要同步到Google Tasks服务器。
*
* @return true表示需要保存到云端，false表示无需保存
*/
@Override
public boolean isWorthSaving() {
// 只要有元数据内容就值得保存
return getNotes() != null;
}
/**
* 重写父类方法：从远程GTask的JSON数据中解析元信息
* 通俗说：当从GTask服务器拉取数据时，用该方法解析元数据任务，提取出关联的GTask ID
* @param js 远程GTask返回的JSON对象（包含元数据任务信息）
* 从远程Google Tasks JSON数据解析元数据内容
* <p>
* 重写说明：实现Task基类的数据解析接口，用于从云端拉取数据时初始化元数据。
* 业务逻辑：解析notes字段中的JSON字符串，提取关联的Google Tasks任务ID。
*
* @param js Google Tasks服务返回的JSON对象，包含元数据任务信息
*/
@Override
public void setContentByRemoteJSON(JSONObject js) {
// 先调用父类方法，解析通用的GTask任务内容（如名称、备注等）
// 1. 调用父类方法解析基础任务信息
super.setContentByRemoteJSON(js);
// 如果任务备注（元数据JSON字符串）不为空
// 2. 如果notes字段包含元数据，解析其中的关联ID
if (getNotes() != null) {
try {
// 将备注字符串转为JSON对象（去除首尾空白字符，避免解析失败）
// JSON解析：将notes字符串转换为JSON对象（去除首尾空格）
JSONObject metaInfo = new JSONObject(getNotes().trim());
// 从JSON对象中提取关联的远程GTask ID
// 提取关联的Google Tasks任务ID
mRelatedGid = metaInfo.getString(GTaskStringUtils.META_HEAD_GTASK_ID);
} catch (JSONException e) {
// JSON解析失败，打印警告日志，并将关联ID置为null
// 异常处理：JSON解析失败，清除关联ID并记录警告日志
Log.w(TAG, "failed to get related gid");
mRelatedGid = null;
}
@ -103,37 +128,51 @@ public class MetaData extends Task {
}
/**
* 重写父类方法：从本地JSON设置内容（禁止调用）
* 通俗说：MetaData只处理远程GTask的元数据，不需要从本地JSON加载内容，
* 一旦调用该方法，直接抛出异常提示非法访问
* 从本地JSON设置内容（禁止调用）
* <p>
* 重写说明：覆盖父类方法，明确禁止从本地JSON初始化元数据。
* 设计说明：MetaData仅用于处理远程Google Tasks数据，
* 本地数据操作应由其他业务类处理，确保职责分离。
*
* @param js 本地JSON对象
* @throws IllegalAccessError 总是抛出此异常，提示方法调用错误
*/
@Override
public void setContentByLocalJSON(JSONObject js) {
// 抛出非法访问错误，提示该方法不应该被调用
// 防御性设计：防止错误的调用路径
throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");
}
/**
* 重写父类方法：从内容生成本地JSON（禁止调用）
* 通俗说：MetaData不需要生成本地JSON数据，一旦调用该方法，直接抛出异常提示非法访问
* @return 无返回值（直接抛出异常）
* 从内容生成本地JSON（禁止调用）
* <p>
* 重写说明：覆盖父类方法，明确禁止生成本地JSON数据。
* 设计说明：MetaData不需要参与本地数据序列化，
* 其数据存储已在setMeta方法中通过JSON格式完成。
*
* @return 总是抛出异常，无返回值
* @throws IllegalAccessError 总是抛出此异常，提示方法调用错误
*/
@Override
public JSONObject getLocalJSONFromContent() {
// 抛出非法访问错误，提示该方法不应该被调用
// 防御性设计：防止错误的调用路径
throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called");
}
/**
* 重写父类方法：获取同步动作（禁止调用）
* 通俗说：MetaData不需要处理本地数据库的同步动作判断，一旦调用该方法，直接抛出异常提示非法访问
* @param c 数据库查询游标（此类未使用）
* @return 无返回值（直接抛出异常）
* 获取同步动作（禁止调用）
* <p>
* 重写说明：覆盖父类方法，明确禁止检查同步动作。
* 设计说明：MetaData的同步逻辑由上层业务控制，
* 该类仅负责元数据存储和解析，不参与同步决策。
*
* @param c 数据库游标（未使用）
* @return 总是抛出异常，无返回值
* @throws IllegalAccessError 总是抛出此异常，提示方法调用错误
*/
@Override
public int getSyncAction(Cursor c) {
// 抛出非法访问错误，提示该方法不应该被调用
// 防御性设计：防止错误的调用路径
throw new IllegalAccessError("MetaData:getSyncAction should not be called");
}
}

238
src/Notes-master/src/net/micode/notes/gtask/data/Node.java
Unescape View File

@ -16,147 +16,259 @@
package net.micode.notes.gtask.data;
import android.database.Cursor; // 数据库查询游标：用于子类查询本地数据库，判断同步动作
import android.database.Cursor;
import org.json.JSONObject; // JSON对象：用于封装GTask接口所需参数，或存储本地数据
import org.json.JSONObject;
/**
* GTask同步抽象基类
* 通俗说：这个类是所有GTask同步数据（如任务、元数据、文件夹）的“通用模板”，
* 定义了同步所需的所有动作常量（比如新增、删除、更新）、通用属性（远程ID、名称等），
* 还约定了子类必须实现的同步相关抽象方法，统一了GTask同步的核心流程规范
* GTask同步数据模型抽象基类 (Data Layer - Google Tasks Synchronization)
* <p>
* 核心职责：定义Google Tasks同步系统中所有数据节点的通用接口和同步状态机，
* 实现本地便签数据与云端Google Tasks数据的双向同步协议。
* 架构说明：作为所有GTask同步实体（任务、文件夹、元数据）的抽象基类，
* 定义了同步操作的核心算法模板和数据转换规范。
* 设计要点：采用模板方法模式，统一同步流程，支持多态数据模型处理。
*/
public abstract class Node {
// 同步动作常量：表示无任何同步操作（本地和远程数据一致）
/**
* 同步动作：无需同步（本地和云端数据状态一致）
*/
public static final int SYNC_ACTION_NONE = 0;
// 同步动作常量：往远程GTask服务器添加新数据（本地有新增，远程没有）
/**
* 同步动作：向云端添加数据（本地有新增数据）
*/
public static final int SYNC_ACTION_ADD_REMOTE = 1;
// 同步动作常量：往本地数据库添加新数据（远程有新增，本地没有）
/**
* 同步动作：向本地添加数据（云端有新增数据）
*/
public static final int SYNC_ACTION_ADD_LOCAL = 2;
// 同步动作常量：删除远程GTask服务器上的数据（本地已删除，远程还存在）
/**
* 同步动作：从云端删除数据（本地已删除，云端需要同步删除）
*/
public static final int SYNC_ACTION_DEL_REMOTE = 3;
// 同步动作常量：删除本地数据库里的数据（远程已删除，本地还存在）
/**
* 同步动作：从本地删除数据（云端已删除，本地需要同步删除）
*/
public static final int SYNC_ACTION_DEL_LOCAL = 4;
// 同步动作常量：更新远程GTask服务器上的数据（本地修改比远程新）
/**
* 同步动作：更新云端数据（本地数据比云端更新）
*/
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;
// 远程GTask唯一标识（Gid）：每个同步数据在GTask服务器上的唯一ID（null表示未上传到远程）
/**
* Google Tasks唯一标识符（GID）
* <p>
* 架构说明：云端数据在Google Tasks服务中的全局唯一标识，
* 用于在同步过程中建立本地数据与云端数据的映射关系。
* 设计要点：null表示该节点尚未同步到云端（本地新增）。
*/
private String mGid;
// 节点名称：同步数据的名称（比如便签标题、文件夹名称）
/**
* 节点显示名称
* <p>
* 业务逻辑：对于便签表示标题，对于文件夹表示文件夹名称，
* 是同步过程中需要对比和更新的核心字段之一。
*/
private String mName;
// 最后修改时间戳：数据最后一次被修改的时间（用于判断本地和远程哪个更新）
/**
* 最后修改时间戳（毫秒）
* <p>
* 架构说明：用于实现基于时间戳的冲突检测算法，
* 在双向同步中判断哪一方数据更新，决定同步方向。
*/
private long mLastModified;
// 删除标记：是否被标记为删除（true=已删除，需要同步删除操作）
/**
* 删除标记
* <p>
* 业务逻辑：标记节点是否已被软删除，用于实现级联删除和回收站功能。
* 设计要点：同步时会根据此标记决定是否执行物理删除操作。
*/
private boolean mDeleted;
/**
* 构造方法：初始化同步节点的默认属性
* 通俗说：创建Node对象时，给所有通用属性设置默认值（未关联远程、空名称、无修改、未删除）
* 默认构造函数
* <p>
* 设计说明：初始化所有字段为默认值，确保节点对象的初始状态一致。
* 架构说明：所有子类必须调用此构造函数进行基础字段初始化。
*/
public Node() {
mGid = null; // 默认未关联远程GTask，无Gid
mName = ""; // 默认名称为空字符串
mLastModified = 0; // 默认最后修改时间为0（未修改）
mDeleted = false; // 默认未被删除
mGid = null; // 默认未关联云端
mName = ""; // 默认名称为空
mLastModified = 0; // 默认从未修改
mDeleted = false; // 默认未删除
}
/**
* 抽象方法：获取创建动作的JSON对象
* 通俗说：子类必须实现该方法，封装往GTask服务器创建数据所需的参数（转为JSON格式），
* 供GTask接口调用（比如创建新便签任务）
* @param actionId 动作ID（GTask接口所需的唯一动作标识）
* @return 创建动作的JSON参数对象
* 抽象方法：获取创建动作的JSON参数
* <p>
* 架构说明：子类必须实现此方法，封装创建节点所需的全部参数。
* 业务逻辑：将本地数据转换为Google Tasks API要求的JSON格式，
* 用于向云端发起创建请求。
*
* @param actionId Google Tasks API要求的动作标识符，确保操作幂等性
* @return 符合Google Tasks API规范的JSON参数对象
*/
public abstract JSONObject getCreateAction(int actionId);
/**
* 抽象方法：获取更新动作的JSON对象
* 通俗说：子类必须实现该方法，封装往GTask服务器更新数据所需的参数（转为JSON格式），
* 供GTask接口调用（比如更新已有的便签内容）
* @param actionId 动作ID（GTask接口所需的唯一动作标识）
* @return 更新动作的JSON参数对象
* 抽象方法：获取更新动作的JSON参数
* <p>
* 架构说明：子类必须实现此方法，封装更新节点所需的全部参数。
* 设计要点：只包含需要更新的字段，避免不必要的数据传输。
*
* @param actionId Google Tasks API要求的动作标识符
* @return 符合Google Tasks API规范的JSON参数对象
*/
public abstract JSONObject getUpdateAction(int actionId);
/**
* 抽象方法：从远程GTask的JSON数据中设置内容
* 通俗说：子类必须实现该方法，当从GTask服务器拉取数据后，
* 解析返回的JSON对象，把数据赋值给本地属性（比如解析远程便签内容，存入本地对象）
* @param js 远程GTask返回的JSON数据对象
* 抽象方法：从云端JSON数据解析节点内容
* <p>
* 架构说明：子类必须实现此方法，将云端返回的JSON数据解析为本地对象模型。
* 业务逻辑：处理Google Tasks API的数据格式，转换为便签应用内部格式。
*
* @param js Google Tasks API返回的JSON数据对象
*/
public abstract void setContentByRemoteJSON(JSONObject js);
/**
* 抽象方法：从本地JSON数据中设置内容
* 通俗说：子类必须实现该方法，解析本地存储的JSON数据，
* 把数据赋值给当前节点的属性（比如从本地数据库读取JSON格式的便签数据，初始化对象）
* @param js 本地存储的JSON数据对象
* 抽象方法：从本地JSON数据解析节点内容
* <p>
* 架构说明：子类必须实现此方法，将本地存储的JSON数据解析为内存对象。
* 设计要点：用于应用启动时从数据库恢复数据，或处理本地数据导入。
*
* @param js 本地存储的JSON数据对象（通常来自数据库或文件）
*/
public abstract void setContentByLocalJSON(JSONObject js);
/**
* 抽象方法：从节点内容生成本地JSON对象
* 通俗说：子类必须实现该方法，把当前节点的属性（比如便签内容、修改时间）
* 封装为JSON对象，用于存储到本地数据库（方便后续同步对比）
* @return 包含节点内容的本地JSON对象
* 抽象方法：生成本地存储的JSON数据
* <p>
* 架构说明：子类必须实现此方法，将内存对象序列化为JSON格式，
* 用于持久化存储到本地数据库或文件。
* 设计要点：JSON结构应与setContentByLocalJSON方法对应，实现双向转换。
*
* @return 包含节点所有本地属性的JSON对象
*/
public abstract JSONObject getLocalJSONFromContent();
/**
* 抽象方法：判断当前节点的同步动作类型
* 通俗说：子类必须实现该方法，通过查询本地数据库（Cursor），
* 对比本地数据和远程数据的状态（是否新增、修改、删除），返回对应的同步动作常量（比如新增远程、更新本地等）
* @param c 本地数据库查询游标（包含本地数据的查询结果）
* @return 同步动作类型（对应上面定义的SYNC_ACTION_XXX常量）
* 抽象方法：获取同步动作类型
* <p>
* 架构说明：子类必须实现此方法，实现具体的同步决策逻辑。
* 业务逻辑：通过对比本地数据库记录与当前内存状态，
* 判断需要执行的同步动作类型（新增、更新、删除等）。
* 设计要点：这是双向同步算法的核心决策点。
*
* @param c 数据库游标，指向本地数据库中的对应记录
* @return 同步动作类型常量（SYNC_ACTION_XXX）
*/
public abstract int getSyncAction(Cursor c);
// 以下是通用属性的Setter方法：设置对应的属性值，供子类或外部调用
/** 设置远程GTask的唯一标识（Gid） */
// ==================== 通用属性访问器 ====================
/**
* 设置Google Tasks唯一标识符
* <p>
* 架构说明：通常在从云端拉取数据或创建成功后调用，
* 建立本地数据与云端数据的关联关系。
*
* @param gid Google Tasks服务分配的唯一标识符
*/
public void setGid(String gid) {
this.mGid = gid;
}
/** 设置节点名称（如便签标题、文件夹名称） */
/**
* 设置节点显示名称
*
* @param name 节点名称
*/
public void setName(String name) {
this.mName = name;
}
/** 设置最后修改时间戳（用于同步对比新旧） */
/**
* 设置最后修改时间戳
* <p>
* 架构说明：更新时间戳是同步算法的重要输入，
* 每次本地修改都必须更新此字段，确保同步准确性。
*
* @param lastModified 最后修改时间戳（毫秒）
*/
public void setLastModified(long lastModified) {
this.mLastModified = lastModified;
}
/** 设置删除标记（标记是否需要同步删除操作） */
/**
* 设置删除标记
* <p>
* 业务逻辑：软删除实现，标记节点为已删除状态，
* 实际删除操作由同步引擎在适当时机执行。
*
* @param deleted 删除标记，true表示已删除
*/
public void setDeleted(boolean deleted) {
this.mDeleted = deleted;
}
// 以下是通用属性的Getter方法：获取对应的属性值，供子类或外部调用
/** 获取远程GTask的唯一标识（Gid） */
/**
* 获取Google Tasks唯一标识符
*
* @return Google Tasks唯一标识符，null表示尚未同步到云端
*/
public String getGid() {
return this.mGid;
}
/** 获取节点名称（如便签标题、文件夹名称） */
/**
* 获取节点显示名称
*
* @return 节点名称
*/
public String getName() {
return this.mName;
}
/** 获取最后修改时间戳（用于同步对比新旧） */
/**
* 获取最后修改时间戳
*
* @return 最后修改时间戳（毫秒）
*/
public long getLastModified() {
return this.mLastModified;
}
/** 获取删除标记（判断是否需要同步删除操作） */
/**
* 获取删除标记
*
* @return 删除标记，true表示已删除
*/
public boolean getDeleted() {
return this.mDeleted;
}
}

279
src/Notes-master/src/net/micode/notes/gtask/data/SqlData.java
Unescape View File

@ -34,259 +34,306 @@ import net.micode.notes.gtask.exception.ActionFailureException;
import org.json.JSONException;
import org.json.JSONObject;
/**
* 本地便签数据库（数据明细表）操作工具
* 通俗说：这个类专门用来处理本地便签数据库里“数据明细”表的内容，
* 负责创建新数据、加载已有数据、记录数据变更、把变更保存到数据库
* 便签详细数据实体类 (Data Layer - Note Details Management)
* <p>
* 核心职责：封装便签详细数据（data表）的CRUD操作，实现JSON与数据库的双向转换，
* 支持增量更新和版本控制，为便签同步提供数据层支持。
* 架构说明：作为本地数据库访问的封装类，屏蔽底层数据库操作细节，
* 提供面向对象的数据访问接口。
* 设计要点：采用差异跟踪机制，只更新有变化的字段，优化数据库性能。
*/
public class SqlData {
// 日志标签：打印这个类的日志时，用来标识日志来源
/**
* 日志标识，使用类名作为TAG
*/
private static final String TAG = SqlData.class.getSimpleName();
// 无效的编号：用来标记数据还没有有效的唯一ID
/**
* 无效ID常量，表示数据尚未在数据库中存在
*/
private static final int INVALID_ID = -99999;
// 查询数据明细表时，要获取的字段清单（相当于要查的列名）
/**
* 数据表查询投影列定义
* <p>
* 架构说明：定义查询data表时需要返回的列，
* 仅包含业务逻辑必需的字段，避免全列查询带来的性能开销。
*/
public static final String[] PROJECTION_DATA = new String[] {
DataColumns.ID, // 数据唯一ID
DataColumns.MIME_TYPE, // 数据类型（比如普通便签、通话便签）
DataColumns.CONTENT, // 数据内容（比如便签正文）
DataColumns.DATA1, // 扩展字段1（存一些额外信息，比如便签模式）
DataColumns.DATA3 // 扩展字段3（存一些额外信息）
DataColumns.ID, // 数据记录ID
DataColumns.MIME_TYPE, // 数据类型标识
DataColumns.CONTENT, // 便签核心内容
DataColumns.DATA1, // 扩展字段1（用于存储模式等整型数据）
DataColumns.DATA3 // 扩展字段3（用于存储电话号码等文本数据）
};
// 上面字段清单对应的索引位置，方便从查询结果里快速取值
public static final int DATA_ID_COLUMN = 0; // 数据ID在查询结果里的位置
public static final int DATA_MIME_TYPE_COLUMN = 1; // 数据类型在查询结果里的位置
public static final int DATA_CONTENT_COLUMN = 2; // 数据内容在查询结果里的位置
public static final int DATA_CONTENT_DATA_1_COLUMN = 3; // 扩展字段1在查询结果里的位置
public static final int DATA_CONTENT_DATA_3_COLUMN = 4; // 扩展字段3在查询结果里的位置
/**
* 查询结果列索引常量
* <p>
* 设计说明：定义PROJECTION_DATA数组中各列的索引位置，
* 避免硬编码数字索引，提高代码可读性和可维护性。
*/
public static final int DATA_ID_COLUMN = 0;
public static final int DATA_MIME_TYPE_COLUMN = 1;
public static final int DATA_CONTENT_COLUMN = 2;
public static final int DATA_CONTENT_DATA_1_COLUMN = 3;
public static final int DATA_CONTENT_DATA_3_COLUMN = 4;
// 数据库操作工具：用来和本地便签数据库打交道（增删改查）
/**
* ContentResolver实例，用于访问ContentProvider
*/
private ContentResolver mContentResolver;
// 是否是新数据：true=新创建的（还没存到数据库），false=已存在的（从数据库加载的）
/**
* 创建标记，true表示新数据（未提交到数据库）
*/
private boolean mIsCreate;
// 这条数据的唯一ID
/**
* 数据记录ID
*/
private long mDataId;
// 这条数据的类型（比如普通便签、通话便签）
/**
* 数据类型（MIME类型）
*/
private String mDataMimeType;
// 这条数据的内容（比如便签的正文文字）
/**
* 数据内容（便签正文）
*/
private String mDataContent;
// 扩展字段1的值（存额外信息，比如便签是普通模式还是清单模式）
/**
* 扩展字段1的值
*/
private long mDataContentData1;
// 扩展字段3的值（存额外信息）
/**
* 扩展字段3的值
*/
private String mDataContentData3;
// 数据变更记录：用来存和原来不一样的内容（只更新有变化的部分，提高效率）
/**
* 差异数据值容器
* <p>
* 设计说明：记录与原始数据不同的字段，
* 用于实现增量更新，减少不必要的数据库操作。
*/
private ContentValues mDiffDataValues;
/**
* 构造方法：创建一条新的数据（还没存到数据库）
* @param context 上下文（用来获取数据库操作工具）
* 构造函数：创建新数据实例
* <p>
* 业务逻辑：初始化一个未保存到数据库的数据对象，
* 设置默认值为普通便签类型，等待后续赋值和提交。
*
* @param context 应用上下文，用于获取ContentResolver
*/
public SqlData(Context context) {
// 获取数据库操作工具
// 获取ContentResolver，用于数据库访问
mContentResolver = context.getContentResolver();
// 标记为新数据（还没存数据库）
mIsCreate = true;
// 初始化为无效ID（还没有数据库分配的唯一ID）
mDataId = INVALID_ID;
// 初始数据类型为普通便签
mDataMimeType = DataConstants.NOTE;
// 初始内容为空字符串
mDataContent = "";
// 初始扩展字段1的值为0
mDataContentData1 = 0;
// 初始扩展字段3的值为空字符串
mDataContentData3 = "";
// 初始化数据变更记录容器
mDiffDataValues = new ContentValues();
// 设置初始状态
mIsCreate = true; // 标记为新建数据
mDataId = INVALID_ID; // ID设为无效值（未保存）
mDataMimeType = DataConstants.NOTE; // 默认类型为普通便签
mDataContent = ""; // 默认内容为空
mDataContentData1 = 0; // 扩展字段1默认值
mDataContentData3 = ""; // 扩展字段3默认值
mDiffDataValues = new ContentValues(); // 初始化差异容器
}
/**
* 构造方法：加载数据库里已有的数据
* @param context 上下文（用来获取数据库操作工具）
* @param c 数据库查询结果（里面存着已有的数据信息）
* 构造函数：从数据库游标加载数据实例
* <p>
* 业务逻辑：从已有数据库记录创建对象，
* 用于编辑或更新已存在的便签数据。
*
* @param context 应用上下文
* @param c 数据库查询游标，指向data表的记录
*/
public SqlData(Context context, Cursor c) {
// 获取数据库操作工具
// 获取ContentResolver，用于数据库访问
mContentResolver = context.getContentResolver();
// 标记为已有数据（不是新创建的）
mIsCreate = false;
// 从查询结果里加载数据到当前对象
// 设置初始状态
mIsCreate = false; // 标记为已存在数据
mDiffDataValues = new ContentValues(); // 初始化差异容器
// 从游标加载数据
loadFromCursor(c);
// 初始化数据变更记录容器
mDiffDataValues = new ContentValues();
}
/**
* 从数据库查询结果里加载数据
* 通俗说：把查询结果里的各项信息取出来，赋值给当前对象的属性
* @param c 数据库查询结果
* 从数据库游标加载数据字段
* <p>
* DB操作：从Cursor对象提取data表的字段值，
* 填充到当前对象的成员变量中。
*
* @param c 数据库查询游标，必须包含PROJECTION_DATA定义的列
*/
private void loadFromCursor(Cursor c) {
// 从查询结果里取数据ID
// 提取并设置所有字段值
mDataId = c.getLong(DATA_ID_COLUMN);
// 从查询结果里取数据类型
mDataMimeType = c.getString(DATA_MIME_TYPE_COLUMN);
// 从查询结果里取数据内容
mDataContent = c.getString(DATA_CONTENT_COLUMN);
// 从查询结果里取扩展字段1的值
mDataContentData1 = c.getLong(DATA_CONTENT_DATA_1_COLUMN);
// 从查询结果里取扩展字段3的值
mDataContentData3 = c.getString(DATA_CONTENT_DATA_3_COLUMN);
}
/**
* 从JSON数据包里设置数据内容，并记录变更
* 通俗说：把JSON里的信息解析出来，更新当前对象的属性，
* 只有和原来不一样的内容，才记录到变更容器里（准备后续更新数据库）
* @param js 包含数据信息的JSON数据包
* @throws JSONException JSON解析失败时抛出异常
* 从JSON对象设置数据内容
* <p>
* 架构说明：将JSON格式的数据转换为本地对象，
* 同时记录发生变化的字段，用于后续的增量更新。
* 业务逻辑：支持GTask同步和本地数据导入场景。
*
* @param js 包含数据字段的JSON对象
* @throws JSONException JSON解析或格式错误时抛出
*/
public void setContent(JSONObject js) throws JSONException {
// 从JSON里取数据ID，没有的话就用无效ID
// 1. 处理ID字段
long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID;
// 如果是新数据，或者当前ID和JSON里的ID不一样，就记录这个变更
if (mIsCreate || mDataId != dataId) {
mDiffDataValues.put(DataColumns.ID, dataId);
}
// 更新当前数据ID
mDataId = dataId;
// 从JSON里取数据类型，没有的话就默认是普通便签
String dataMimeType = js.has(DataColumns.MIME_TYPE) ? js.getString(DataColumns.MIME_TYPE)
: DataConstants.NOTE;
// 如果是新数据，或者当前类型和JSON里的类型不一样，就记录这个变更
// 2. 处理MIME类型字段
String dataMimeType = js.has(DataColumns.MIME_TYPE) ?
js.getString(DataColumns.MIME_TYPE) : DataConstants.NOTE;
if (mIsCreate || !mDataMimeType.equals(dataMimeType)) {
mDiffDataValues.put(DataColumns.MIME_TYPE, dataMimeType);
}
// 更新当前数据类型
mDataMimeType = dataMimeType;
// 从JSON里取数据内容，没有的话就为空字符串
String dataContent = js.has(DataColumns.CONTENT) ? js.getString(DataColumns.CONTENT) : "";
// 如果是新数据，或者当前内容和JSON里的内容不一样，就记录这个变更
// 3. 处理内容字段
String dataContent = js.has(DataColumns.CONTENT) ?
js.getString(DataColumns.CONTENT) : "";
if (mIsCreate || !mDataContent.equals(dataContent)) {
mDiffDataValues.put(DataColumns.CONTENT, dataContent);
}
// 更新当前数据内容
mDataContent = dataContent;
// 从JSON里取扩展字段1的值，没有的话就为0
long dataContentData1 = js.has(DataColumns.DATA1) ? js.getLong(DataColumns.DATA1) : 0;
// 如果是新数据，或者当前扩展字段1和JSON里的不一样，就记录这个变更
// 4. 处理扩展字段1（通常用于存储模式等整型数据）
long dataContentData1 = js.has(DataColumns.DATA1) ?
js.getLong(DataColumns.DATA1) : 0;
if (mIsCreate || mDataContentData1 != dataContentData1) {
mDiffDataValues.put(DataColumns.DATA1, dataContentData1);
}
// 更新当前扩展字段1的值
mDataContentData1 = dataContentData1;
// 从JSON里取扩展字段3的值，没有的话就为空字符串
String dataContentData3 = js.has(DataColumns.DATA3) ? js.getString(DataColumns.DATA3) : "";
// 如果是新数据，或者当前扩展字段3和JSON里的不一样，就记录这个变更
// 5. 处理扩展字段3（通常用于存储电话号码等文本数据）
String dataContentData3 = js.has(DataColumns.DATA3) ?
js.getString(DataColumns.DATA3) : "";
if (mIsCreate || !mDataContentData3.equals(dataContentData3)) {
mDiffDataValues.put(DataColumns.DATA3, dataContentData3);
}
// 更新当前扩展字段3的值
mDataContentData3 = dataContentData3;
}
/**
* 把当前数据打包成JSON格式
* 通俗说：把当前对象里的所有属性信息，整理成JSON数据包，方便后续使用
* @return 包含当前数据信息的JSON数据包
* @throws JSONException JSON打包失败时抛出异常
* 将数据内容转换为JSON对象
* <p>
* 架构说明：将本地对象序列化为JSON格式，
* 用于数据导出、GTask同步或网络传输。
*
* @return 包含所有数据字段的JSON对象
* @throws JSONException JSON构建错误时抛出
*/
public JSONObject getContent() throws JSONException {
// 如果是新数据（还没存到数据库），打印错误日志并返回null
// 安全检查：新建数据不能转换为JSON（未保存到数据库）
if (mIsCreate) {
Log.e(TAG, "it seems that we haven't created this in database yet");
return null;
}
// 创建空的JSON数据包
// 构建JSON对象，包含所有数据字段
JSONObject js = new JSONObject();
// 把数据ID存入JSON
js.put(DataColumns.ID, mDataId);
// 把数据类型存入JSON
js.put(DataColumns.MIME_TYPE, mDataMimeType);
// 把数据内容存入JSON
js.put(DataColumns.CONTENT, mDataContent);
// 把扩展字段1的值存入JSON
js.put(DataColumns.DATA1, mDataContentData1);
// 把扩展字段3的值存入JSON
js.put(DataColumns.DATA3, mDataContentData3);
// 返回打包好的JSON
return js;
}
/**
* 把数据变更提交到数据库
* 通俗说：新数据就插入到数据库，已有数据就更新变更的部分，最后清空变更记录
* @param noteId 这条数据所属的便签ID（关联便签主表）
* @param validateVersion 是否验证便签版本（避免同步时多人同时修改导致冲突）
* @param version 要验证的便签版本号
* 提交数据到数据库
* <p>
* DB操作：根据数据状态执行插入或更新操作，
* 支持版本验证，确保数据一致性。
* 设计说明：采用差异更新策略，只修改有变化的字段。
*
* @param noteId 关联的便签ID（外键约束）
* @param validateVersion 是否验证版本号（用于并发控制）
* @param version 期望的版本号（validateVersion为true时有效）
*/
public void commit(long noteId, boolean validateVersion, long version) {
// 如果是新数据（要插入数据库）
if (mIsCreate) {
// 如果数据ID是无效的，就把ID从变更记录里移除（数据库会自动生成唯一ID）
// Case A: 新建数据，执行插入操作
// 如果ID为无效值且差异容器中包含ID，移除ID让数据库自动生成
if (mDataId == INVALID_ID && mDiffDataValues.containsKey(DataColumns.ID)) {
mDiffDataValues.remove(DataColumns.ID);
}
// 把所属的便签ID存入变更记录（关联到便签主表）
// 设置关联的便签ID
mDiffDataValues.put(DataColumns.NOTE_ID, noteId);
// 把变更记录里的内容插入到数据明细表，返回新数据的URI
// DB操作：插入新记录
Uri uri = mContentResolver.insert(Notes.CONTENT_DATA_URI, mDiffDataValues);
try {
// 从返回的URI里提取数据库分配的唯一数据ID
// 从返回的URI中提取新生成的ID
mDataId = Long.valueOf(uri.getPathSegments().get(1));
} catch (NumberFormatException e) {
// 提取ID失败，打印错误日志并抛出异常
// 异常处理：插入失败，记录错误并抛出业务异常
Log.e(TAG, "Get note id error :" + e.toString());
throw new ActionFailureException("create note failed");
}
} else {
// 如果是已有数据（要更新数据库），且有变更内容
// Case B: 更新已有数据，执行更新操作
// 只有当有字段变化时才执行更新
if (mDiffDataValues.size() > 0) {
int result = 0;
// 如果不需要验证便签版本，直接更新数据
if (!validateVersion) {
// 无需版本验证，直接更新
result = mContentResolver.update(
ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, mDataId),
mDiffDataValues, null, null);
} else {
// 如果需要验证便签版本，只有版本匹配时才更新（避免冲突）
// 需要版本验证：只有版本匹配时才更新（乐观锁控制）
result = mContentResolver.update(
ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, mDataId),
mDiffDataValues,
// 子查询：检查关联的便签版本是否匹配
" ? in (SELECT " + NoteColumns.ID + " FROM " + TABLE.NOTE
+ " WHERE " + NoteColumns.VERSION + "=?)",
new String[] { String.valueOf(noteId), String.valueOf(version) });
}
// 如果更新结果为0，说明没有更新成功（可能版本不匹配或数据已被修改）
// 更新结果检查：0表示没有记录被更新（可能版本不匹配或数据已被删除）
if (result == 0) {
Log.w(TAG, "there is no update. maybe user updates note when syncing");
}
}
}
// 清空变更记录（本次提交完成，下次变更重新记录）
// 重置状态：清空差异容器，标记为已存在数据
mDiffDataValues.clear();
// 标记为非新数据（就算是刚插入的，现在也已经存到数据库了）
mIsCreate = false;
}
/**
* 获取这条数据的唯一ID
* @return 数据唯一ID
* 获取数据记录ID
*
* @return 数据记录ID
*/
public long getId() {
return mDataId;

604
src/Notes-master/src/net/micode/notes/gtask/data/SqlNote.java
Unescape View File

@ -37,304 +37,369 @@ import org.json.JSONObject;
import java.util.ArrayList;
/**
* 本地便签（主表）操作工具
* 通俗说：这个类专门管本地便签数据库里“便签主表”的内容，
* 包含便签的基本信息（比如标题、背景色、创建时间），还关联着便签的明细内容（比如正文），
* 负责新便签创建、已有便签加载、内容修改记录、打包和保存到数据库
* 本地便签实体类 (Data Layer - Note Master Table Management)
* <p>
* 核心职责：封装便签主表（note表）的CRUD操作，管理与便签相关的所有元数据，
* 包括便签的基本属性、文件夹关系、桌面Widget关联以及详细内容数据。
* 架构说明：作为便签数据的核心业务对象，实现JSON序列化/反序列化，
* 支持增量更新和版本控制，为GTask同步提供数据支撑。
* 设计要点：采用差异跟踪机制，支持离线编辑和批量同步。
*/
public class SqlNote {
// 日志标签：打印这个类的日志时，用来标识日志来自这个类
/**
* 日志标识，使用类名作为TAG
*/
private static final String TAG = SqlNote.class.getSimpleName();
// 无效的便签ID：用来标记便签还没有有效的唯一编号
/**
* 无效ID常量，表示便签尚未在数据库中存在
*/
private static final int INVALID_ID = -99999;
// 查询便签主表时，要获取的字段清单（相当于要查的列名，对应便签的各项基本信息）
/**
* 便签表查询投影列定义
* <p>
* 架构说明：定义查询note表时需要返回的所有列，
* 完整覆盖便签的所有业务属性，用于数据恢复和同步对比。
*/
public static final String[] PROJECTION_NOTE = new String[] {
NoteColumns.ID, // 便签唯一ID
NoteColumns.ALERTED_DATE, // 提醒时间
NoteColumns.BG_COLOR_ID, // 背景颜色ID
NoteColumns.CREATED_DATE, // 创建时间
NoteColumns.HAS_ATTACHMENT, // 是否有附件（0=没有，1=有）
NoteColumns.MODIFIED_DATE, // 最后修改时间
NoteColumns.NOTES_COUNT, // 子便签数量
NoteColumns.PARENT_ID, // 所属文件夹ID
NoteColumns.SNIPPET, // 便签摘要（标题/部分正文）
NoteColumns.TYPE, // 便签类型（普通便签/文件夹/系统文件夹）
NoteColumns.WIDGET_ID, // 桌面小组件ID
NoteColumns.WIDGET_TYPE, // 桌面小组件类型
NoteColumns.SYNC_ID, // 同步编号
NoteColumns.LOCAL_MODIFIED, // 本地修改标记
NoteColumns.ORIGIN_PARENT_ID, // 原始所属文件夹ID
NoteColumns.GTASK_ID, // 对应云端GTask的ID
NoteColumns.VERSION // 便签版本号（用来避免同步冲突）
NoteColumns.ID, // 便签ID
NoteColumns.ALERTED_DATE, // 提醒时间戳
NoteColumns.BG_COLOR_ID, // 背景颜色ID
NoteColumns.CREATED_DATE, // 创建时间戳
NoteColumns.HAS_ATTACHMENT, // 附件标记
NoteColumns.MODIFIED_DATE, // 最后修改时间戳
NoteColumns.NOTES_COUNT, // 子便签数量
NoteColumns.PARENT_ID, // 父文件夹ID
NoteColumns.SNIPPET, // 便签摘要
NoteColumns.TYPE, // 便签类型
NoteColumns.WIDGET_ID, // 桌面Widget ID
NoteColumns.WIDGET_TYPE, // 桌面Widget类型
NoteColumns.SYNC_ID, // 同步ID
NoteColumns.LOCAL_MODIFIED, // 本地修改标记
NoteColumns.ORIGIN_PARENT_ID, // 原始父文件夹ID
NoteColumns.GTASK_ID, // Google Tasks关联ID
NoteColumns.VERSION // 数据版本号
};
// 上面字段清单对应的索引位置，方便从查询结果里快速取值
public static final int ID_COLUMN = 0; // 便签ID在查询结果里的位置
public static final int ALERTED_DATE_COLUMN = 1; // 提醒时间在查询结果里的位置
public static final int BG_COLOR_ID_COLUMN = 2; // 背景颜色ID在查询结果里的位置
public static final int CREATED_DATE_COLUMN = 3; // 创建时间在查询结果里的位置
public static final int HAS_ATTACHMENT_COLUMN = 4; // 是否有附件在查询结果里的位置
public static final int MODIFIED_DATE_COLUMN = 5; // 最后修改时间在查询结果里的位置
public static final int NOTES_COUNT_COLUMN = 6; // 子便签数量在查询结果里的位置
public static final int PARENT_ID_COLUMN = 7; // 所属文件夹ID在查询结果里的位置
public static final int SNIPPET_COLUMN = 8; // 便签摘要在查询结果里的位置
public static final int TYPE_COLUMN = 9; // 便签类型在查询结果里的位置
public static final int WIDGET_ID_COLUMN = 10; // 桌面小组件ID在查询结果里的位置
public static final int WIDGET_TYPE_COLUMN = 11; // 桌面小组件类型在查询结果里的位置
public static final int SYNC_ID_COLUMN = 12; // 同步编号在查询结果里的位置
public static final int LOCAL_MODIFIED_COLUMN = 13; // 本地修改标记在查询结果里的位置
public static final int ORIGIN_PARENT_ID_COLUMN = 14; // 原始所属文件夹ID在查询结果里的位置
public static final int GTASK_ID_COLUMN = 15; // 云端GTaskID在查询结果里的位置
public static final int VERSION_COLUMN = 16; // 便签版本号在查询结果里的位置
// 上下文：用来获取数据库操作工具、默认配置等
/**
* 查询结果列索引常量
*/
public static final int ID_COLUMN = 0;
public static final int ALERTED_DATE_COLUMN = 1;
public static final int BG_COLOR_ID_COLUMN = 2;
public static final int CREATED_DATE_COLUMN = 3;
public static final int HAS_ATTACHMENT_COLUMN = 4;
public static final int MODIFIED_DATE_COLUMN = 5;
public static final int NOTES_COUNT_COLUMN = 6;
public static final int PARENT_ID_COLUMN = 7;
public static final int SNIPPET_COLUMN = 8;
public static final int TYPE_COLUMN = 9;
public static final int WIDGET_ID_COLUMN = 10;
public static final int WIDGET_TYPE_COLUMN = 11;
public static final int SYNC_ID_COLUMN = 12;
public static final int LOCAL_MODIFIED_COLUMN = 13;
public static final int ORIGIN_PARENT_ID_COLUMN = 14;
public static final int GTASK_ID_COLUMN = 15;
public static final int VERSION_COLUMN = 16;
/**
* 应用上下文，用于访问系统服务和资源
*/
private Context mContext;
// 数据库操作工具：用来和本地便签数据库打交道（增删改查）
/**
* ContentResolver实例，用于访问ContentProvider
*/
private ContentResolver mContentResolver;
// 是否是新便签：true=新创建的（还没存到数据库），false=已存在的（从数据库加载的）
/**
* 创建标记，true表示新便签（未提交到数据库）
*/
private boolean mIsCreate;
// 便签唯一ID
/**
* 便签ID
*/
private long mId;
// 提醒时间（比如设置了早上8点提醒，这里存的是对应的时间戳）
/**
* 提醒时间戳
*/
private long mAlertDate;
// 背景颜色ID（对应不同的便签背景色，比如白色、黄色）
/**
* 背景颜色ID
*/
private int mBgColorId;
// 创建时间（存的是时间戳，记录便签什么时候被创建）
/**
* 创建时间戳
*/
private long mCreatedDate;
// 是否有附件（0=没有附件，1=有附件）
/**
* 附件标记（0=无附件，1=有附件）
*/
private int mHasAttachment;
// 最后修改时间（存的是时间戳，记录便签最后一次被修改的时间）
/**
* 最后修改时间戳
*/
private long mModifiedDate;
// 所属文件夹ID（标记这个便签在哪个文件夹里）
/**
* 父文件夹ID
*/
private long mParentId;
// 便签摘要（一般是便签的标题，或者正文的前几句）
/**
* 便签摘要（用于列表显示）
*/
private String mSnippet;
// 便签类型（普通便签/文件夹/系统文件夹）
/**
* 便签类型（TYPE_NOTE/TYPE_FOLDER/TYPE_SYSTEM）
*/
private int mType;
// 桌面小组件ID（如果这个便签添加到桌面，这里存小组件的编号）
/**
* 桌面Widget ID
*/
private int mWidgetId;
// 桌面小组件类型（标记桌面小组件的样式）
/**
* 桌面Widget类型
*/
private int mWidgetType;
// 原始所属文件夹ID（记录便签最初在哪个文件夹里）
/**
* 原始父文件夹ID（用于回收站恢复）
*/
private long mOriginParent;
// 便签版本号（每次修改都会递增，用来避免同步时多人同时修改导致冲突）
/**
* 数据版本号（用于乐观锁控制）
*/
private long mVersion;
// 便签主表的变更记录：只存和原来不一样的内容，后续只更新这些变更，提高效率
/**
* 便签主表差异数据值容器
*/
private ContentValues mDiffNoteValues;
// 便签的明细数据列表（比如普通便签的正文内容，用SqlData对象存储）
/**
* 便签详细数据列表（data表记录）
*/
private ArrayList<SqlData> mDataList;
/**
* 构造方法：创建一条新的便签（还没存到数据库）
* @param context 上下文（用来获取数据库操作工具、默认背景色等）
* 构造函数：创建新便签实例
* <p>
* 业务逻辑：初始化一个未保存到数据库的便签对象，
* 设置默认属性值，包括默认背景色、当前时间戳等。
*
* @param context 应用上下文
*/
public SqlNote(Context context) {
mContext = context;
// 获取数据库操作工具
mContentResolver = context.getContentResolver();
// 标记为新便签（还没存数据库）
// 初始化默认值
mIsCreate = true;
// 初始化为无效ID（还没有数据库分配的唯一ID）
mId = INVALID_ID;
// 初始提醒时间为0（没有设置提醒）
mAlertDate = 0;
// 初始背景色为系统默认背景色
mBgColorId = ResourceParser.getDefaultBgId(context);
// 初始创建时间为当前时间（获取系统当前时间戳）
mCreatedDate = System.currentTimeMillis();
// 初始没有附件
mHasAttachment = 0;
// 初始最后修改时间为当前时间
mModifiedDate = System.currentTimeMillis();
// 初始所属文件夹ID为0（默认在根目录）
mParentId = 0;
// 初始摘要为空字符串
mSnippet = "";
// 初始类型为普通便签
mType = Notes.TYPE_NOTE;
// 初始桌面小组件ID为无效ID（没有添加到桌面）
mWidgetId = AppWidgetManager.INVALID_APPWIDGET_ID;
// 初始桌面小组件类型为无效类型
mWidgetType = Notes.TYPE_WIDGET_INVALIDE;
// 初始原始所属文件夹ID为0
mOriginParent = 0;
// 初始版本号为0
mVersion = 0;
// 初始化便签主表的变更记录容器
mDiffNoteValues = new ContentValues();
// 初始化明细数据列表
mDataList = new ArrayList<SqlData>();
}
/**
* 构造方法：从数据库查询结果里加载已有便签
* @param context 上下文（用来获取数据库操作工具）
* @param c 数据库查询结果（里面存着已有便签的基本信息）
* 构造函数：从数据库游标加载便签实例
* <p>
* 业务逻辑：从已有数据库记录创建对象，自动加载便签详细数据。
*
* @param context 应用上下文
* @param c 数据库查询游标，指向note表的记录
*/
public SqlNote(Context context, Cursor c) {
mContext = context;
// 获取数据库操作工具
mContentResolver = context.getContentResolver();
// 标记为已有便签（不是新创建的）
mIsCreate = false;
// 从查询结果里加载便签基本信息
loadFromCursor(c);
// 初始化明细数据列表
mDataList = new ArrayList<SqlData>();
// 如果是普通便签，加载对应的明细内容（比如正文）
if (mType == Notes.TYPE_NOTE)
loadDataContent();
// 初始化便签主表的变更记录容器
mDiffNoteValues = new ContentValues();
// 加载基础数据
loadFromCursor(c);
// 如果是普通便签，加载详细数据内容
if (mType == Notes.TYPE_NOTE) {
loadDataContent();
}
}
/**
* 构造方法：通过便签ID加载数据库里已有的便签
* @param context 上下文（用来获取数据库操作工具）
* @param id 要加载的便签ID
* 构造函数：通过便签ID加载便签实例
* <p>
* 业务逻辑：根据便签ID查询数据库，创建便签对象。
* 用于通过ID直接获取便签数据的场景。
*
* @param context 应用上下文
* @param id 便签ID
*/
public SqlNote(Context context, long id) {
mContext = context;
// 获取数据库操作工具
mContentResolver = context.getContentResolver();
// 标记为已有便签（不是新创建的）
mIsCreate = false;
// 通过便签ID查询数据库，再加载便签基本信息
loadFromCursor(id);
// 初始化明细数据列表
mDataList = new ArrayList<SqlData>();
// 如果是普通便签，加载对应的明细内容（比如正文）
if (mType == Notes.TYPE_NOTE)
loadDataContent();
// 初始化便签主表的变更记录容器
mDiffNoteValues = new ContentValues();
// 通过ID加载便签
loadFromCursor(id);
// 如果是普通便签，加载详细数据内容
if (mType == Notes.TYPE_NOTE) {
loadDataContent();
}
}
/**
* 通过便签ID查询数据库，再加载便签基本信息
* @param id 要查询的便签ID
* 通过便签ID从数据库加载数据
* <p>
* DB操作：根据便签ID查询数据库，并调用loadFromCursor(Cursor)加载数据。
* 设计说明：封装数据库查询逻辑，提供统一的数据加载入口。
*
* @param id 便签ID
*/
private void loadFromCursor(long id) {
Cursor c = null; // 数据库查询结果容器
Cursor c = null;
try {
// 根据便签ID查询便签主表，获取该便签的基本信息
// DB操作：根据ID查询便签
c = mContentResolver.query(Notes.CONTENT_NOTE_URI, PROJECTION_NOTE, "(_id=?)",
new String[] { String.valueOf(id) }, null);
if (c != null) {
// 移动到查询结果的第一条（因为ID是唯一的，只有一条结果）
c.moveToNext();
// 从查询结果里加载数据到当前对象
loadFromCursor(c);
if (c.moveToNext()) {
loadFromCursor(c);
} else {
Log.w(TAG, "loadFromCursor: cursor = null");
}
} else {
// 查询结果为空，打印警告日志
Log.w(TAG, "loadFromCursor: cursor = null");
}
} finally {
// 不管查询成功与否，最后都关闭查询结果，避免占用资源
if (c != null)
if (c != null) {
c.close();
}
}
}
/**
* 从数据库查询结果里加载便签基本信息
* 通俗说：把查询结果里的各项便签信息取出来，赋值给当前对象的属性
* @param c 数据库查询结果
* 从数据库游标加载便签字段
* <p>
* DB操作：从Cursor对象提取note表的字段值，
* 填充到当前对象的成员变量中。
*
* @param c 数据库查询游标，必须包含PROJECTION_NOTE定义的列
*/
private void loadFromCursor(Cursor c) {
mId = c.getLong(ID_COLUMN); // 取便签ID
mAlertDate = c.getLong(ALERTED_DATE_COLUMN); // 取提醒时间
mBgColorId = c.getInt(BG_COLOR_ID_COLUMN); // 取背景颜色ID
mCreatedDate = c.getLong(CREATED_DATE_COLUMN); // 取创建时间
mHasAttachment = c.getInt(HAS_ATTACHMENT_COLUMN); // 取是否有附件
mModifiedDate = c.getLong(MODIFIED_DATE_COLUMN); // 取最后修改时间
mParentId = c.getLong(PARENT_ID_COLUMN); // 取所属文件夹ID
mSnippet = c.getString(SNIPPET_COLUMN); // 取便签摘要
mType = c.getInt(TYPE_COLUMN); // 取便签类型
mWidgetId = c.getInt(WIDGET_ID_COLUMN); // 取桌面小组件ID
mWidgetType = c.getInt(WIDGET_TYPE_COLUMN); // 取桌面小组件类型
mVersion = c.getLong(VERSION_COLUMN); // 取便签版本号
mId = c.getLong(ID_COLUMN);
mAlertDate = c.getLong(ALERTED_DATE_COLUMN);
mBgColorId = c.getInt(BG_COLOR_ID_COLUMN);
mCreatedDate = c.getLong(CREATED_DATE_COLUMN);
mHasAttachment = c.getInt(HAS_ATTACHMENT_COLUMN);
mModifiedDate = c.getLong(MODIFIED_DATE_COLUMN);
mParentId = c.getLong(PARENT_ID_COLUMN);
mSnippet = c.getString(SNIPPET_COLUMN);
mType = c.getInt(TYPE_COLUMN);
mWidgetId = c.getInt(WIDGET_ID_COLUMN);
mWidgetType = c.getInt(WIDGET_TYPE_COLUMN);
mVersion = c.getLong(VERSION_COLUMN);
}
/**
* 加载当前便签关联的明细内容（比如普通便签的正文）
* 通俗说：根据便签ID查询数据明细表，把关联的明细数据加载到mDataList里
* 加载便签详细数据内容
* <p>
* DB操作：查询data表，加载与当前便签关联的所有详细数据。
* 架构说明：便签内容采用主从表设计，note表存储元数据，data表存储详细内容。
*/
private void loadDataContent() {
Cursor c = null; // 数据库查询结果容器
// 先清空现有的明细数据列表
Cursor c = null;
mDataList.clear();
try {
// 根据便签ID查询数据明细表，获取该便签的明细内容
// DB操作：查询关联的详细数据
c = mContentResolver.query(Notes.CONTENT_DATA_URI, SqlData.PROJECTION_DATA,
"(note_id=?)", new String[] { String.valueOf(mId) }, null);
if (c != null) {
// 如果没有查询到明细数据，打印警告日志并返回
if (c.getCount() == 0) {
Log.w(TAG, "it seems that the note has not data");
return;
}
// 遍历所有明细数据，逐个加载到mDataList
while (c.moveToNext()) {
SqlData data = new SqlData(mContext, c); // 从查询结果创建明细数据对象
mDataList.add(data); // 添加到明细数据列表
SqlData data = new SqlData(mContext, c);
mDataList.add(data);
}
} else {
// 查询结果为空，打印警告日志
Log.w(TAG, "loadDataContent: cursor = null");
}
} finally {
// 不管查询成功与否，最后都关闭查询结果，避免占用资源
if (c != null)
if (c != null) {
c.close();
}
}
}
/**
* 从JSON数据包里设置便签内容，并记录变更
* 通俗说：把JSON里的便签信息解析出来，更新当前对象的属性，
* 有变更的内容就记录到变更容器里，同时处理明细数据（正文）
* @param js 包含便签信息的JSON数据包
* @return true=设置成功，false=设置失败（JSON解析出错）
* 从JSON对象设置便签内容
* <p>
* 架构说明：将JSON格式的数据转换为本地对象，
* 根据便签类型（普通便签/文件夹/系统文件夹）进行差异化处理。
* 业务逻辑：支持GTask同步和本地数据导入场景。
*
* @param js 包含便签数据的JSON对象
* @return true表示设置成功，false表示设置失败
*/
public boolean setContent(JSONObject js) {
try {
// 从JSON里取出便签基本信息的数据包
JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
// 如果是系统文件夹，不允许修改，打印警告日志
// Case 1: 系统文件夹 - 禁止修改
if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM) {
Log.w(TAG, "cannot set system folder");
}
// 如果是普通文件夹，只能更新摘要和类型
// Case 2: 文件夹 - 只能更新摘要和类型
else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {
// 从JSON里取文件夹摘要，没有的话为空字符串
String snippet = note.has(NoteColumns.SNIPPET) ? note
.getString(NoteColumns.SNIPPET) : "";
// 如果是新文件夹，或者摘要有变化，记录变更
String snippet = note.has(NoteColumns.SNIPPET) ?
note.getString(NoteColumns.SNIPPET) : "";
if (mIsCreate || !mSnippet.equals(snippet)) {
mDiffNoteValues.put(NoteColumns.SNIPPET, snippet);
}
// 更新当前文件夹摘要
mSnippet = snippet;
// 从JSON里取文件夹类型，没有的话默认是普通便签
int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE)
: Notes.TYPE_NOTE;
// 如果是新文件夹，或者类型有变化，记录变更
int type = note.has(NoteColumns.TYPE) ?
note.getInt(NoteColumns.TYPE) : Notes.TYPE_NOTE;
if (mIsCreate || mType != type) {
mDiffNoteValues.put(NoteColumns.TYPE, type);
}
// 更新当前文件夹类型
mType = type;
}
// 如果是普通便签，更新所有基本信息和明细内容
// Case 3: 普通便签 - 更新所有字段和详细数据
else if (note.getInt(NoteColumns.TYPE) == Notes.TYPE_NOTE) {
// 取出明细数据的JSON数组（比如正文内容）
JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
// 处理便签ID
@ -344,149 +409,149 @@ public class SqlNote {
}
mId = id;
// 处理提醒时间
long alertDate = note.has(NoteColumns.ALERTED_DATE) ? note
.getLong(NoteColumns.ALERTED_DATE) : 0;
// 处理提醒日期
long alertDate = note.has(NoteColumns.ALERTED_DATE) ?
note.getLong(NoteColumns.ALERTED_DATE) : 0;
if (mIsCreate || mAlertDate != alertDate) {
mDiffNoteValues.put(NoteColumns.ALERTED_DATE, alertDate);
}
mAlertDate = alertDate;
// 处理背景颜色ID
int bgColorId = note.has(NoteColumns.BG_COLOR_ID) ? note
.getInt(NoteColumns.BG_COLOR_ID) : ResourceParser.getDefaultBgId(mContext);
int bgColorId = note.has(NoteColumns.BG_COLOR_ID) ?
note.getInt(NoteColumns.BG_COLOR_ID) : ResourceParser.getDefaultBgId(mContext);
if (mIsCreate || mBgColorId != bgColorId) {
mDiffNoteValues.put(NoteColumns.BG_COLOR_ID, bgColorId);
}
mBgColorId = bgColorId;
// 处理创建时间
long createDate = note.has(NoteColumns.CREATED_DATE) ? note
.getLong(NoteColumns.CREATED_DATE) : System.currentTimeMillis();
// 处理创建日期
long createDate = note.has(NoteColumns.CREATED_DATE) ?
note.getLong(NoteColumns.CREATED_DATE) : System.currentTimeMillis();
if (mIsCreate || mCreatedDate != createDate) {
mDiffNoteValues.put(NoteColumns.CREATED_DATE, createDate);
}
mCreatedDate = createDate;
// 处理是否有附件
int hasAttachment = note.has(NoteColumns.HAS_ATTACHMENT) ? note
.getInt(NoteColumns.HAS_ATTACHMENT) : 0;
// 处理附件标记
int hasAttachment = note.has(NoteColumns.HAS_ATTACHMENT) ?
note.getInt(NoteColumns.HAS_ATTACHMENT) : 0;
if (mIsCreate || mHasAttachment != hasAttachment) {
mDiffNoteValues.put(NoteColumns.HAS_ATTACHMENT, hasAttachment);
}
mHasAttachment = hasAttachment;
// 处理最后修改时间
long modifiedDate = note.has(NoteColumns.MODIFIED_DATE) ? note
.getLong(NoteColumns.MODIFIED_DATE) : System.currentTimeMillis();
// 处理修改日期
long modifiedDate = note.has(NoteColumns.MODIFIED_DATE) ?
note.getLong(NoteColumns.MODIFIED_DATE) : System.currentTimeMillis();
if (mIsCreate || mModifiedDate != modifiedDate) {
mDiffNoteValues.put(NoteColumns.MODIFIED_DATE, modifiedDate);
}
mModifiedDate = modifiedDate;
// 处理所属文件夹ID
long parentId = note.has(NoteColumns.PARENT_ID) ? note
.getLong(NoteColumns.PARENT_ID) : 0;
// 处理父文件夹ID
long parentId = note.has(NoteColumns.PARENT_ID) ?
note.getLong(NoteColumns.PARENT_ID) : 0;
if (mIsCreate || mParentId != parentId) {
mDiffNoteValues.put(NoteColumns.PARENT_ID, parentId);
}
mParentId = parentId;
// 处理便签摘要
String snippet = note.has(NoteColumns.SNIPPET) ? note
.getString(NoteColumns.SNIPPET) : "";
String snippet = note.has(NoteColumns.SNIPPET) ?
note.getString(NoteColumns.SNIPPET) : "";
if (mIsCreate || !mSnippet.equals(snippet)) {
mDiffNoteValues.put(NoteColumns.SNIPPET, snippet);
}
mSnippet = snippet;
// 处理便签类型
int type = note.has(NoteColumns.TYPE) ? note.getInt(NoteColumns.TYPE)
: Notes.TYPE_NOTE;
int type = note.has(NoteColumns.TYPE) ?
note.getInt(NoteColumns.TYPE) : Notes.TYPE_NOTE;
if (mIsCreate || mType != type) {
mDiffNoteValues.put(NoteColumns.TYPE, type);
}
mType = type;
// 处理桌面小组件ID
int widgetId = note.has(NoteColumns.WIDGET_ID) ? note.getInt(NoteColumns.WIDGET_ID)
: AppWidgetManager.INVALID_APPWIDGET_ID;
// 处理Widget ID
int widgetId = note.has(NoteColumns.WIDGET_ID) ?
note.getInt(NoteColumns.WIDGET_ID) : AppWidgetManager.INVALID_APPWIDGET_ID;
if (mIsCreate || mWidgetId != widgetId) {
mDiffNoteValues.put(NoteColumns.WIDGET_ID, widgetId);
}
mWidgetId = widgetId;
// 处理桌面小组件类型
int widgetType = note.has(NoteColumns.WIDGET_TYPE) ? note
.getInt(NoteColumns.WIDGET_TYPE) : Notes.TYPE_WIDGET_INVALIDE;
// 处理Widget类型
int widgetType = note.has(NoteColumns.WIDGET_TYPE) ?
note.getInt(NoteColumns.WIDGET_TYPE) : Notes.TYPE_WIDGET_INVALIDE;
if (mIsCreate || mWidgetType != widgetType) {
mDiffNoteValues.put(NoteColumns.WIDGET_TYPE, widgetType);
}
mWidgetType = widgetType;
// 处理原始所属文件夹ID
long originParent = note.has(NoteColumns.ORIGIN_PARENT_ID) ? note
.getLong(NoteColumns.ORIGIN_PARENT_ID) : 0;
// 处理原始父文件夹ID
long originParent = note.has(NoteColumns.ORIGIN_PARENT_ID) ?
note.getLong(NoteColumns.ORIGIN_PARENT_ID) : 0;
if (mIsCreate || mOriginParent != originParent) {
mDiffNoteValues.put(NoteColumns.ORIGIN_PARENT_ID, originParent);
}
mOriginParent = originParent;
// 处理明细数据（比如正文内容）
// 处理详细数据
for (int i = 0; i < dataArray.length(); i++) {
JSONObject data = dataArray.getJSONObject(i);
SqlData sqlData = null;
// 如果明细数据有ID，先在现有列表里找对应的明细对象
// 查找已存在的详细数据
if (data.has(DataColumns.ID)) {
long dataId = data.getLong(DataColumns.ID);
for (SqlData temp : mDataList) {
if (dataId == temp.getId()) {
sqlData = temp;
break;
}
}
}
// 如果没找到对应的明细对象，创建新的并加入列表
// 如果未找到，创建新的详细数据
if (sqlData == null) {
sqlData = new SqlData(mContext);
mDataList.add(sqlData);
}
// 给明细对象设置内容，并记录变更
// 设置详细数据内容
sqlData.setContent(data);
}
}
} catch (JSONException e) {
// JSON解析出错，打印错误日志并返回false
Log.e(TAG, e.toString());
e.printStackTrace();
return false;
}
// 设置成功，返回true
return true;
}
/**
* 把当前便签内容打包成JSON格式
* 通俗说：把便签的基本信息和明细内容整理成JSON数据包，方便后续同步或存储
* @return 包含便签信息的JSON数据包（新便签/打包失败返回null）
* 将便签内容转换为JSON对象
* <p>
* 架构说明：将本地对象序列化为JSON格式，
* 用于数据导出、GTask同步或网络传输。
*
* @return 包含所有便签数据的JSON对象，失败返回null
*/
public JSONObject getContent() {
try {
// 创建空的JSON数据包
JSONObject js = new JSONObject();
// 如果是新便签（还没存到数据库），打印错误日志并返回null
// 安全检查：新建便签不能转换为JSON
if (mIsCreate) {
Log.e(TAG, "it seems that we haven't created this in database yet");
return null;
}
// 创建存储便签基本信息的JSON对象
JSONObject note = new JSONObject();
// 如果是普通便签，打包所有基本信息和明细内容
// Case 1: 普通便签 - 包含所有字段和详细数据
if (mType == Notes.TYPE_NOTE) {
note.put(NoteColumns.ID, mId);
note.put(NoteColumns.ALERTED_DATE, mAlertDate);
@ -500,44 +565,41 @@ public class SqlNote {
note.put(NoteColumns.WIDGET_ID, mWidgetId);
note.put(NoteColumns.WIDGET_TYPE, mWidgetType);
note.put(NoteColumns.ORIGIN_PARENT_ID, mOriginParent);
// 把便签基本信息存入总JSON
js.put(GTaskStringUtils.META_HEAD_NOTE, note);
// 创建存储明细数据的JSON数组
JSONArray dataArray = new JSONArray();
for (SqlData sqlData : mDataList) {
// 把每个明细数据打包成JSON
JSONObject data = sqlData.getContent();
if (data != null) {
dataArray.put(data);
}
}
// 把明细数据数组存入总JSON
js.put(GTaskStringUtils.META_HEAD_DATA, dataArray);
}
// 如果是文件夹/系统文件夹，只打包ID、类型和摘要
// Case 2: 文件夹或系统文件夹 - 仅包含ID、类型和摘要
else if (mType == Notes.TYPE_FOLDER || mType == Notes.TYPE_SYSTEM) {
note.put(NoteColumns.ID, mId);
note.put(NoteColumns.TYPE, mType);
note.put(NoteColumns.SNIPPET, mSnippet);
// 把文件夹信息存入总JSON
js.put(GTaskStringUtils.META_HEAD_NOTE, note);
}
// 返回打包好的JSON
return js;
} catch (JSONException e) {
// JSON打包出错，打印错误日志
Log.e(TAG, e.toString());
e.printStackTrace();
return null;
}
// 打包失败，返回null
return null;
}
/**
* 设置便签所属的文件夹ID，并记录变更
* @param id 文件夹ID
* 设置便签的父文件夹ID
* <p>
* 业务逻辑：修改便签的归属关系，同时记录变更用于后续提交。
*
* @param id 父文件夹ID
*/
public void setParentId(long id) {
mParentId = id;
@ -545,30 +607,39 @@ public class SqlNote {
}
/**
* 设置便签对应的云端GTask ID，并记录变更
* @param gid 云端GTask的唯一ID
* 设置Google Tasks关联ID
* <p>
* 架构说明：用于建立本地便签与云端Google Tasks任务的关联。
*
* @param gid Google Tasks任务ID
*/
public void setGtaskId(String gid) {
mDiffNoteValues.put(NoteColumns.GTASK_ID, gid);
}
/**
* 设置便签的同步编号，并记录变更
* @param syncId 同步编号
* 设置同步ID
* <p>
* 业务逻辑：用于标识便签在同步系统中的版本，支持增量同步。
*
* @param syncId 同步ID
*/
public void setSyncId(long syncId) {
mDiffNoteValues.put(NoteColumns.SYNC_ID, syncId);
}
/**
* 重置本地修改标记（标记为未修改），并记录变更
* 重置本地修改标记
* <p>
* 业务逻辑：在同步完成后调用，将便签标记为"已同步"状态。
*/
public void resetLocalModified() {
mDiffNoteValues.put(NoteColumns.LOCAL_MODIFIED, 0);
}
/**
* 获取便签的唯一ID
* 获取便签ID
*
* @return 便签ID
*/
public long getId() {
@ -576,15 +647,17 @@ public class SqlNote {
}
/**
* 获取便签所属的文件夹ID
* @return 文件夹ID
* 获取父文件夹ID
*
* @return 父文件夹ID
*/
public long getParentId() {
return mParentId;
}
/**
* 获取便签的摘要
* 获取便签摘要
*
* @return 便签摘要
*/
public String getSnippet() {
@ -592,82 +665,91 @@ public class SqlNote {
}
/**
* 判断当前是否是普通便签类型
* @return true=普通便签，false=文件夹/系统文件夹
* 判断是否为普通便签类型
*
* @return true表示普通便签，false表示文件夹或系统文件夹
*/
public boolean isNoteType() {
return mType == Notes.TYPE_NOTE;
}
/**
* 把便签的变更提交到数据库
* 通俗说：新便签就插入到主表，再插入明细数据；已有便签就更新变更的部分，
* 之后刷新便签信息，清空变更记录
* @param validateVersion 是否验证便签版本（避免同步时多人同时修改导致冲突）
* 提交便签到数据库
* <p>
* DB操作：根据便签状态执行插入或更新操作，
* 支持版本验证，确保数据一致性。
* 设计说明：采用差异更新策略，只修改有变化的字段。
*
* @param validateVersion 是否验证版本号（用于并发控制）
*/
public void commit(boolean validateVersion) {
// 如果是新便签（要插入数据库）
if (mIsCreate) {
// 如果便签ID是无效的，就把ID从变更记录里移除（数据库会自动生成唯一ID）
// Case A: 新建便签，执行插入操作
// 移除无效ID，让数据库自动生成
if (mId == INVALID_ID && mDiffNoteValues.containsKey(NoteColumns.ID)) {
mDiffNoteValues.remove(NoteColumns.ID);
}
// 把便签基本信息插入到便签主表，返回新便签的URI
// DB操作：插入新便签
Uri uri = mContentResolver.insert(Notes.CONTENT_NOTE_URI, mDiffNoteValues);
try {
// 从返回的URI里提取数据库分配的唯一便签ID
// 从返回的URI中提取新生成的ID
mId = Long.valueOf(uri.getPathSegments().get(1));
} catch (NumberFormatException e) {
// 提取ID失败，打印错误日志并抛出异常
Log.e(TAG, "Get note id error :" + e.toString());
throw new ActionFailureException("create note failed");
}
// 如果提取的ID为0，说明创建失败，抛出异常
// ID为0表示创建失败
if (mId == 0) {
throw new IllegalStateException("Create thread id failed");
}
// 如果是普通便签，把明细数据也插入到数据明细表
// 如果是普通便签，提交详细数据
if (mType == Notes.TYPE_NOTE) {
for (SqlData sqlData : mDataList) {
sqlData.commit(mId, false, -1);
}
}
}
// 如果是已有便签（要更新数据库）
else {
// 验证便签ID是否有效（除了根文件夹和通话记录文件夹，其他ID不能<=0）
} else {
// Case B: 更新已有便签
// ID验证：除了特殊系统文件夹，ID必须大于0
if (mId <= 0 && mId != Notes.ID_ROOT_FOLDER && mId != Notes.ID_CALL_RECORD_FOLDER) {
Log.e(TAG, "No such note");
throw new IllegalStateException("Try to update note with invalid id");
}
// 如果有变更内容，才执行更新操作
// 如果有字段变化才执行更新
if (mDiffNoteValues.size() > 0) {
// 版本号递增（每次修改都升级版本）
mVersion ++;
// 递增版本号
mVersion++;
int result = 0;
// 如果不需要验证版本，直接更新便签主表
if (!validateVersion) {
result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
+ NoteColumns.ID + "=?)", new String[] { String.valueOf(mId) });
}
// 如果需要验证版本，只有版本匹配时才更新（避免同步冲突）
else {
result = mContentResolver.update(Notes.CONTENT_NOTE_URI, mDiffNoteValues, "("
+ NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)",
// 无需版本验证的直接更新
result = mContentResolver.update(
Notes.CONTENT_NOTE_URI,
mDiffNoteValues,
"(" + NoteColumns.ID + "=?)",
new String[] { String.valueOf(mId) });
} else {
// 需要版本验证的更新（乐观锁控制）
result = mContentResolver.update(
Notes.CONTENT_NOTE_URI,
mDiffNoteValues,
"(" + NoteColumns.ID + "=?) AND (" + NoteColumns.VERSION + "<=?)",
new String[] { String.valueOf(mId), String.valueOf(mVersion) });
}
// 如果更新结果为0，说明没有更新成功（可能版本不匹配或数据已被修改）
// 更新结果为0表示没有记录被更新
if (result == 0) {
Log.w(TAG, "there is no update. maybe user updates note when syncing");
}
}
// 如果是普通便签，更新对应的明细数据
// 如果是普通便签，提交详细数据更新
if (mType == Notes.TYPE_NOTE) {
for (SqlData sqlData : mDataList) {
sqlData.commit(mId, validateVersion, mVersion);
@ -675,14 +757,14 @@ public class SqlNote {
}
}
// 刷新便签信息（重新从数据库加载最新数据）
// 重新加载数据，确保内存状态与数据库一致
loadFromCursor(mId);
if (mType == Notes.TYPE_NOTE)
if (mType == Notes.TYPE_NOTE) {
loadDataContent();
}
// 清空便签主表的变更记录（本次提交完成，下次变更重新记录）
// 重置状态
mDiffNoteValues.clear();
// 标记为非新便签（就算是刚插入的，现在也已经存到数据库了）
mIsCreate = false;
}
}

370
src/Notes-master/src/net/micode/notes/gtask/data/Task.java
Unescape View File

@ -31,175 +31,216 @@ import org.json.JSONArray;
import org.json.JSONException;
import org.json.JSONObject;
/**
* GTask云端任务处理类（对应本地普通便签）
* 通俗说：这个类是用来处理和GTask云端交互的“任务”（对应本地的普通便签），
* 继承自同步基础模板Node，负责打包创建/更新云端任务的请求、解析云端/本地数据、
* 判断同步操作类型，还关联着任务的所属列表和兄弟任务
* Google Tasks任务实体类 (Data Layer - Google Tasks Task Management)
* <p>
* 核心职责：实现Google Tasks任务数据的双向同步逻辑，将云端任务与本地便签进行映射转换，
* 处理任务创建、更新、删除等同步操作，实现云端任务到本地便签的数据格式适配。
* 架构说明：作为Node基类的具体实现，封装了Google Tasks API的标准任务模型，
* 负责云端任务数据与本地便签JSON格式的相互转换。
* 设计要点：支持任务层级结构、兄弟任务排序和双向冲突检测机制。
*/
public class Task extends Node {
// 日志标签：打印这个类的日志时，用来标识日志来自这个类
/**
* 日志标识，使用类名作为TAG
*/
private static final String TAG = Task.class.getSimpleName();
// 任务是否完成（true=已完成，false=未完成）
/**
* 任务完成状态
* <p>
* 业务逻辑：标记任务是否已完成，同步时会更新到Google Tasks云端。
* 设计说明：本地便签系统不直接支持完成状态，此字段专为GTask同步设计。
*/
private boolean mCompleted;
// 任务备注（额外的说明信息）
/**
* 任务备注（JSON格式）
* <p>
* 架构说明：存储任务的补充说明信息，也可用于存储同步元数据，
* 采用JSON格式以支持结构化数据存储。
*/
private String mNotes;
// 本地便签的元信息（存储便签的详细配置，是个JSON数据包）
/**
* 本地便签元信息
* <p>
* 架构说明：存储与云端任务关联的本地便签的完整元数据，
* 用于在双向同步中保持数据一致性和冲突检测。
*/
private JSONObject mMetaInfo;
// 上一个兄弟任务（当前任务在列表里的前一个任务，用来确定任务顺序）
/**
* 前一个兄弟任务
* <p>
* 设计说明：用于维护任务列表中的顺序关系，确保任务在列表中的位置正确。
* 业务逻辑：通过兄弟任务ID建立顺序链，实现云端任务的排序同步。
*/
private Task mPriorSibling;
// 所属任务列表（对应本地的文件夹，当前任务在哪个列表/文件夹里）
/**
* 父任务列表
* <p>
* 架构说明：指向任务所属的TaskList对象，建立任务与列表的关联关系。
* 设计要点：支持任务的层级组织和归属管理。
*/
private TaskList mParent;
/**
* 构造方法：初始化任务的默认状态
* 通俗说：创建任务对象时，设置默认值，同时调用父类的初始化方法
* 默认构造函数
* <p>
* 设计说明：初始化所有字段为默认值，创建一个未完成、无备注的新任务。
*/
public Task() {
super(); // 调用父类Node的构造方法，初始化同步相关的默认属性
mCompleted = false; // 默认任务未完成
mNotes = null; // 默认没有任务备注
mPriorSibling = null; // 默认没有上一个兄弟任务
mParent = null; // 默认没有所属任务列表
mMetaInfo = null; // 默认没有本地便签元信息
super();
mCompleted = false;
mNotes = null;
mPriorSibling = null;
mParent = null;
mMetaInfo = null;
}
/**
* 打包“创建云端任务”的请求参数
* 通俗说：把本地新便签的信息整理成云端能识别的JSON格式，传给云端用来创建新任务
* @param actionId 动作编号（云端用来识别这次操作的唯一标记）
* @return 整理好的创建任务请求参数（JSON格式）
* 生成创建云端任务的JSON动作参数
* <p>
* 架构说明：构建符合Google Tasks API规范的创建任务请求参数，
* 包含任务的基本信息、位置信息和关联关系。
*
* @param actionId Google Tasks API要求的动作标识符，确保操作幂等性
* @return 符合Google Tasks API规范的创建任务JSON对象
* @throws ActionFailureException 生成JSON失败时抛出业务异常
*/
public JSONObject getCreateAction(int actionId) {
JSONObject js = new JSONObject(); // 创建空的JSON数据包
JSONObject js = new JSONObject();
try {
// 1. 设置动作类型：告诉云端这次是“创建任务”
// 1. 设置动作类型：创建任务
js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);
// 2. 设置动作ID：给这次创建操作一个唯一编号，方便云端识别
// 2. 设置动作ID：确保请求幂等性
js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
// 3. 设置任务位置：告诉云端这个新任务在所属列表里的排序位置
// 3. 设置任务索引位置：在父列表中的顺序
js.put(GTaskStringUtils.GTASK_JSON_INDEX, mParent.getChildTaskIndex(this));
// 4. 设置任务核心信息：打包任务的名称、创建者等信息
// 4. 构建任务实体数据
JSONObject entity = new JSONObject();
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName()); // 任务名称（对应便签摘要/内容）
entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null"); // 创建者ID（这里默认传null）
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null"); // GTask API要求此字段
entity.put(GTaskStringUtils.GTASK_JSON_ENTITY_TYPE,
GTaskStringUtils.GTASK_JSON_TYPE_TASK); // 实体类型：告诉云端这是一个“任务”
if (getNotes() != null) { // 如果有任务备注，就把备注也传过去
GTaskStringUtils.GTASK_JSON_TYPE_TASK);
// 如果有备注，添加到实体数据
if (getNotes() != null) {
entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes());
}
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity); // 把任务核心信息存入总JSON
// 5. 设置所属列表ID：告诉云端这个任务属于哪个列表（对应本地文件夹）
js.put(GTaskStringUtils.GTASK_JSON_PARENT_ID, mParent.getGid());
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
// 6. 设置所属列表类型：告诉云端父级是“任务列表”（文件夹类型）
// 5. 设置父列表信息
js.put(GTaskStringUtils.GTASK_JSON_PARENT_ID, mParent.getGid());
js.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT_TYPE,
GTaskStringUtils.GTASK_JSON_TYPE_GROUP);
// 7. 设置列表ID：和所属列表ID一致，确认任务归属
js.put(GTaskStringUtils.GTASK_JSON_LIST_ID, mParent.getGid());
// 8. 设置上一个兄弟任务ID：如果有前一个任务，就传过去，保证任务排序
// 6. 设置前一个兄弟任务ID（用于确定任务顺序）
if (mPriorSibling != null) {
js.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, mPriorSibling.getGid());
}
} catch (JSONException e) {
// JSON打包出错，打印错误日志并抛出异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("fail to generate task-create jsonobject");
}
return js; // 返回打包好的创建请求参数
return js;
}
/**
* 打包“更新云端任务”的请求参数
* 通俗说：把本地修改后的便签信息整理成云端能识别的JSON格式，传给云端用来更新已有任务
* @param actionId 动作编号（云端用来识别这次操作的唯一标记）
* @return 整理好的更新任务请求参数（JSON格式）
* 生成更新云端任务的JSON动作参数
* <p>
* 架构说明：构建符合Google Tasks API规范的更新任务请求参数，
* 只包含需要更新的字段，支持部分更新以减少网络传输。
*
* @param actionId Google Tasks API要求的动作标识符
* @return 符合Google Tasks API规范的更新任务JSON对象
* @throws ActionFailureException 生成JSON失败时抛出业务异常
*/
public JSONObject getUpdateAction(int actionId) {
JSONObject js = new JSONObject(); // 创建空的JSON数据包
JSONObject js = new JSONObject();
try {
// 1. 设置动作类型：告诉云端这次是“更新任务”
// 1. 设置动作类型：更新任务
js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
// 2. 设置动作ID：给这次更新操作一个唯一编号，方便云端识别
// 2. 设置动作ID
js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
// 3. 设置任务ID：告诉云端要更新哪个任务（用云端给的唯一ID）
// 3. 设置任务ID：指定要更新的任务
js.put(GTaskStringUtils.GTASK_JSON_ID, getGid());
// 4. 设置要更新的任务信息：打包修改后的名称、备注、删除状态
// 4. 构建更新实体数据
JSONObject entity = new JSONObject();
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName()); // 更新后的任务名称
if (getNotes() != null) { // 如果有备注，就更新备注
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
if (getNotes() != null) {
entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes());
}
entity.put(GTaskStringUtils.GTASK_JSON_DELETED, getDeleted()); // 任务是否被删除（标记云端是否要删除该任务）
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity); // 把更新信息存入总JSON
entity.put(GTaskStringUtils.GTASK_JSON_DELETED, getDeleted());
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
} catch (JSONException e) {
// JSON打包出错，打印错误日志并抛出异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("fail to generate task-update jsonobject");
}
return js; // 返回打包好的更新请求参数
return js;
}
/**
* 解析云端返回的任务数据，赋值给当前任务对象
* 通俗说：从云端获取到任务信息后，把数据拆解开，存到当前对象的属性里（同步到本地）
* @param js 云端返回的任务数据包（JSON格式）
* 从云端JSON数据解析任务内容
* <p>
* 架构说明：将Google Tasks API返回的JSON数据解析为本地任务对象，
* 支持增量更新，只处理有变化的字段。
*
* @param js Google Tasks API返回的任务JSON数据
* @throws ActionFailureException JSON解析失败时抛出业务异常
*/
@Override
public void setContentByRemoteJSON(JSONObject js) {
if (js != null) { // 如果云端返回的数据不为空
if (js != null) {
try {
// 1. 提取任务ID（云端给的唯一编号），设置到当前对象
// 提取并设置所有可用字段
if (js.has(GTaskStringUtils.GTASK_JSON_ID)) {
setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
}
// 2. 提取任务最后修改时间，设置到当前对象
if (js.has(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED)) {
setLastModified(js.getLong(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED));
}
// 3. 提取任务名称，设置到当前对象
if (js.has(GTaskStringUtils.GTASK_JSON_NAME)) {
setName(js.getString(GTaskStringUtils.GTASK_JSON_NAME));
}
// 4. 提取任务备注，设置到当前对象
if (js.has(GTaskStringUtils.GTASK_JSON_NOTES)) {
setNotes(js.getString(GTaskStringUtils.GTASK_JSON_NOTES));
}
// 5. 提取任务删除状态，设置到当前对象
if (js.has(GTaskStringUtils.GTASK_JSON_DELETED)) {
setDeleted(js.getBoolean(GTaskStringUtils.GTASK_JSON_DELETED));
}
// 6. 提取任务完成状态，设置到当前对象
if (js.has(GTaskStringUtils.GTASK_JSON_COMPLETED)) {
setCompleted(js.getBoolean(GTaskStringUtils.GTASK_JSON_COMPLETED));
}
} catch (JSONException e) {
// JSON解析出错，打印错误日志并抛出异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("fail to get task content from jsonobject");
@ -208,95 +249,101 @@ public class Task extends Node {
}
/**
* 解析本地便签的JSON数据，设置任务内容
* 通俗说：把本地便签的JSON数据拆解开，提取便签内容作为任务名称（同步到云端任务）
* @param js 本地便签的JSON数据包
* 从本地JSON数据解析任务内容
* <p>
* 业务逻辑：将本地便签的JSON数据解析为任务对象，提取便签内容作为任务名称。
* 设计说明：此方法用于从本地数据创建或更新任务，支持离线编辑后的同步。
*
* @param js 本地便签的JSON数据对象
*/
@Override
public void setContentByLocalJSON(JSONObject js) {
// 如果JSON数据为空，或者缺少便签信息/明细内容，打印警告日志
// 数据验证：确保JSON包含必要的结构
if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)
|| !js.has(GTaskStringUtils.META_HEAD_DATA)) {
Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
Log.w(TAG, "setContentByLocalJSON: nothing is available");
}
try {
// 1. 提取本地便签的基本信息
JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
// 2. 提取本地便签的明细内容（比如正文）
JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
// 3. 如果不是普通便签类型，打印错误日志并返回
// 类型验证：只处理普通便签类型
if (note.getInt(NoteColumns.TYPE) != Notes.TYPE_NOTE) {
Log.e(TAG, "invalid type");
return;
}
// 4. 遍历明细内容，提取普通便签的正文作为任务名称
// 遍历数据数组，查找便签内容
for (int i = 0; i < dataArray.length(); i++) {
JSONObject data = dataArray.getJSONObject(i);
// 判断是否是普通便签的明细内容
// 只处理普通便签类型的数据
if (TextUtils.equals(data.getString(DataColumns.MIME_TYPE), DataConstants.NOTE)) {
setName(data.getString(DataColumns.CONTENT)); // 把便签正文设为任务名称
break; // 找到后就停止遍历
// 将便签内容设置为任务名称
setName(data.getString(DataColumns.CONTENT));
break;
}
}
} catch (JSONException e) {
// JSON解析出错，打印错误日志
Log.e(TAG, e.toString());
e.printStackTrace();
}
}
/**
* 把当前任务数据打包成本地便签的JSON格式
* 通俗说：把云端任务的信息整理成本地便签能识别的JSON格式，方便保存到本地数据库
* @return 本地便签格式的JSON数据包（打包失败返回null）
* 从任务内容生成本地JSON数据
* <p>
* 架构说明：将任务对象转换为本地便签的JSON格式，
* 支持两种情况：有本地元信息时更新，无本地元信息时创建。
*
* @return 本地便签格式的JSON对象，失败返回null
*/
@Override
public JSONObject getLocalJSONFromContent() {
String name = getName(); // 获取任务名称（对应便签内容）
String name = getName();
try {
// 情况1：没有本地元信息（云端新建的任务，要同步到本地）
// Case 1: 无本地元信息（云端新建任务同步到本地）
if (mMetaInfo == null) {
// 如果任务名称为空，打印警告日志并返回null
// 名称验证：空任务不予同步
if (name == null) {
Log.w(TAG, "the note seems to be an empty one");
return null;
}
// 创建本地便签的JSON数据包
// 构建新的本地便签JSON结构
JSONObject js = new JSONObject();
JSONObject note = new JSONObject(); // 便签基本信息
JSONArray dataArray = new JSONArray(); // 便签明细内容
JSONObject data = new JSONObject(); // 明细内容（正文）
data.put(DataColumns.CONTENT, name); // 把任务名称设为便签正文
dataArray.put(data); // 把正文加入明细数组
js.put(GTaskStringUtils.META_HEAD_DATA, dataArray); // 存入明细内容
note.put(NoteColumns.TYPE, Notes.TYPE_NOTE); // 标记为普通便签类型
js.put(GTaskStringUtils.META_HEAD_NOTE, note); // 存入便签基本信息
return js; // 返回打包好的本地便签JSON
}
// 情况2：有本地元信息（已同步过的任务，更新本地内容）
else {
// 提取已有的本地便签元信息
JSONObject note = new JSONObject();
JSONArray dataArray = new JSONArray();
JSONObject data = new JSONObject();
data.put(DataColumns.CONTENT, name);
dataArray.put(data);
js.put(GTaskStringUtils.META_HEAD_DATA, dataArray);
note.put(NoteColumns.TYPE, Notes.TYPE_NOTE);
js.put(GTaskStringUtils.META_HEAD_NOTE, note);
return js;
} else {
// Case 2: 有本地元信息（更新现有便签）
JSONObject note = mMetaInfo.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
JSONArray dataArray = mMetaInfo.getJSONArray(GTaskStringUtils.META_HEAD_DATA);
// 遍历明细内容，更新便签正文（用最新的任务名称）
// 更新便签内容
for (int i = 0; i < dataArray.length(); i++) {
JSONObject data = dataArray.getJSONObject(i);
// 找到普通便签的明细内容
if (TextUtils.equals(data.getString(DataColumns.MIME_TYPE), DataConstants.NOTE)) {
data.put(DataColumns.CONTENT, getName()); // 更新便签正文
break; // 找到后停止遍历
data.put(DataColumns.CONTENT, getName());
break;
}
}
note.put(NoteColumns.TYPE, Notes.TYPE_NOTE); // 确保是普通便签类型
return mMetaInfo; // 返回更新后的本地元信息
note.put(NoteColumns.TYPE, Notes.TYPE_NOTE);
return mMetaInfo;
}
} catch (JSONException e) {
// JSON打包出错，打印错误日志
Log.e(TAG, e.toString());
e.printStackTrace();
return null;
@ -304,18 +351,19 @@ public class Task extends Node {
}
/**
* 设置本地便签的元信息
* 通俗说：把MetaData里的本地便签信息，转换成JSON格式存到当前任务对象
* 设置本地便签元信息
* <p>
* 架构说明：从MetaData对象提取并解析本地便签的元信息，
* 用于建立云端任务与本地便签的关联关系。
*
* @param metaData 本地便签的元数据对象
*/
public void setMetaInfo(MetaData metaData) {
// 如果元数据不为空，且包含便签信息
if (metaData != null && metaData.getNotes() != null) {
try {
// 把元数据里的便签信息转换成JSON对象，存入mMetaInfo
// 将MetaData中的notes字段解析为JSON对象
mMetaInfo = new JSONObject(metaData.getNotes());
} catch (JSONException e) {
// 转换失败，打印警告日志，清空元信息
Log.w(TAG, e.toString());
mMetaInfo = null;
}
@ -323,64 +371,70 @@ public class Task extends Node {
}
/**
* 对比本地和云端数据，判断该执行哪种同步操作
* 通俗说：查本地数据库，对比便签和云端任务的状态，确定是上传、下载还是冲突
* @param c 本地数据库查询结果（存着本地便签的信息）
* @return 同步操作类型（对应Node类里的SYNC_ACTION_XXX常量）
* 获取同步动作类型
* <p>
* 架构说明：通过对比本地数据库记录与云端任务状态，
* 判断需要执行的同步动作类型，实现智能冲突检测。
* 业务逻辑：支持所有8种同步动作类型的判断，包括冲突检测。
*
* @param c 数据库游标，指向本地数据库中的对应记录
* @return 同步动作类型常量（SYNC_ACTION_XXX）
*/
@Override
public int getSyncAction(Cursor c) {
try {
JSONObject noteInfo = null;
// 提取本地便签的元信息（如果存在）
// 提取本地元信息中的便签信息
if (mMetaInfo != null && mMetaInfo.has(GTaskStringUtils.META_HEAD_NOTE)) {
noteInfo = mMetaInfo.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
}
// 1. 如果本地元信息为空，说明本地便签已删除，返回“更新云端”（让云端也删除）
// Case 1: 本地元信息为空（本地便签已删除）
if (noteInfo == null) {
Log.w(TAG, "it seems that note meta has been deleted");
return SYNC_ACTION_UPDATE_REMOTE;
}
// 2. 如果元信息里没有便签ID，说明本地便签无效，返回“更新本地”（用云端数据覆盖）
// Case 2: 元信息中无便签ID（云端任务关联的本地便签已删除）
if (!noteInfo.has(NoteColumns.ID)) {
Log.w(TAG, "remote note id seems to be deleted");
return SYNC_ACTION_UPDATE_LOCAL;
}
// 3. 验证便签ID是否匹配（本地便签ID和元信息里的ID不一致，返回“更新本地”）
// Case 3: 便签ID不匹配（数据不一致）
if (c.getLong(SqlNote.ID_COLUMN) != noteInfo.getLong(NoteColumns.ID)) {
Log.w(TAG, "note id doesn't match");
return SYNC_ACTION_UPDATE_LOCAL;
}
// 4. 判断本地是否有修改
// Case 4: 检查本地修改状态
if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
// 本地没有修改
// 本地无修改
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
// 本地和云端都没有修改，返回“无需操作”
// 两端数据一致，无需同步
return SYNC_ACTION_NONE;
} else {
// 云端有修改，返回“更新本地”（用云端数据覆盖本地）
// 云端有修改，需要更新本地
return SYNC_ACTION_UPDATE_LOCAL;
}
} else {
// 本地有修改
// 验证云端任务ID是否匹配（不匹配返回“同步异常”）
// 验证GTask ID匹配
if (!c.getString(SqlNote.GTASK_ID_COLUMN).equals(getGid())) {
Log.e(TAG, "gtask id doesn't match");
return SYNC_ACTION_ERROR;
}
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
// 只有本地修改，返回“更新云端”（把本地修改同步到云端）
// 只有本地修改，需要更新云端
return SYNC_ACTION_UPDATE_REMOTE;
} else {
// 本地和云端都有修改，返回“同步冲突”（需要用户手动选择）
// 两端都有修改，发生冲突
return SYNC_ACTION_UPDATE_CONFLICT;
}
}
} catch (Exception e) {
// 出现异常，打印错误日志，返回“同步异常”
Log.e(TAG, e.toString());
e.printStackTrace();
}
@ -389,78 +443,90 @@ public class Task extends Node {
}
/**
* 判断当前任务是否值得保存
* 通俗说：判断任务是否有有效内容，避免保存空任务
* @return true=值得保存（有元信息/名称/备注），false=不值得保存（空任务）
* 判断任务是否值得保存
* <p>
* 业务逻辑：检查任务是否包含有效内容，避免同步空数据。
* 设计说明：如果任务有元信息、名称或备注中任意一项有效，则认为值得保存。
*
* @return true表示任务包含有效内容，值得保存
*/
public boolean isWorthSaving() {
return mMetaInfo != null // 有本地元信息
|| (getName() != null && getName().trim().length() > 0) // 任务名称不为空
|| (getNotes() != null && getNotes().trim().length() > 0); // 任务备注不为空
return mMetaInfo != null
|| (getName() != null && getName().trim().length() > 0)
|| (getNotes() != null && getNotes().trim().length() > 0);
}
// ==================== 属性访问器 ====================
/**
* 设置任务的完成状态
* @param completed true=已完成，false=未完成
* 设置任务完成状态
*
* @param completed 完成状态，true表示已完成
*/
public void setCompleted(boolean completed) {
this.mCompleted = completed;
}
/**
* 设置任务的备注信息
* @param notes 任务备注
* 设置任务备注
*
* @param notes 任务备注字符串
*/
public void setNotes(String notes) {
this.mNotes = notes;
}
/**
* 设置任务的上一个兄弟任务（用来确定任务排序）
* @param priorSibling 上一个兄弟任务
* 设置前一个兄弟任务
*
* @param priorSibling 前一个兄弟任务对象
*/
public void setPriorSibling(Task priorSibling) {
this.mPriorSibling = priorSibling;
}
/**
* 设置任务的所属任务列表（对应本地文件夹）
* @param parent 所属任务列表
* 设置父任务列表
*
* @param parent 父任务列表对象
*/
public void setParent(TaskList parent) {
this.mParent = parent;
}
/**
* 获取任务的完成状态
* @return true=已完成，false=未完成
* 获取任务完成状态
*
* @return 完成状态，true表示已完成
*/
public boolean getCompleted() {
return this.mCompleted;
}
/**
* 获取任务的备注信息
* @return 任务备注
* 获取任务备注
*
* @return 任务备注字符串
*/
public String getNotes() {
return this.mNotes;
}
/**
* 获取任务的上一个兄弟任务
* @return 上一个兄弟任务（没有则返回null）
* 获取前一个兄弟任务
*
* @return 前一个兄弟任务对象，null表示没有
*/
public Task getPriorSibling() {
return this.mPriorSibling;
}
/**
* 获取任务的所属任务列表
* @return 所属任务列表（没有则返回null）
* 获取父任务列表
*
* @return 父任务列表对象，null表示没有
*/
public TaskList getParent() {
return this.mParent;
}
}

411
src/Notes-master/src/net/micode/notes/gtask/data/TaskList.java
Unescape View File

@ -29,131 +29,158 @@ import org.json.JSONObject;
import java.util.ArrayList;
/**
* GTask云端任务列表处理类（对应本地文件夹）
* 通俗说：这个类是用来处理和GTask云端交互的“任务列表”（对应本地的便签文件夹），
* 继承自同步基础模板Node，负责打包创建/更新云端列表的请求、解析云端/本地文件夹数据、
* 判断同步操作类型，还负责管理列表下的子任务（对应文件夹里的普通便签）
* Google Tasks任务列表实体类 (Data Layer - Google Tasks List Management)
* <p>
* 核心职责：实现Google Tasks任务列表的双向同步逻辑，将云端任务列表与本地便签文件夹进行映射转换，
* 管理任务列表的层级结构和任务顺序，支持列表的创建、更新、删除和任务排序操作。
* 架构说明：作为Node基类的具体实现，封装了Google Tasks API的标准列表模型，
* 负责云端列表数据与本地文件夹JSON格式的相互转换。
* 设计要点：支持任务列表层级管理、任务顺序维护和双向同步冲突解决。
*/
public class TaskList extends Node {
// 日志标签：打印这个类的日志时，用来标识日志来自这个类
/**
* 日志标识，使用类名作为TAG
*/
private static final String TAG = TaskList.class.getSimpleName();
// 列表排序索引：用来确定这个任务列表在云端的显示顺序
/**
* 列表排序索引
* <p>
* 业务逻辑：用于确定任务列表在Google Tasks中的显示顺序，
* 索引值越小，在列表中显示越靠前。
*/
private int mIndex;
// 子任务列表：存储当前列表下的所有任务（对应本地文件夹里的普通便签）
/**
* 子任务集合
* <p>
* 架构说明：存储当前任务列表下的所有任务对象，
* 用于维护任务与列表的层级关系，支持任务的增删改查操作。
*/
private ArrayList<Task> mChildren;
/**
* 构造方法：初始化任务列表的默认状态
* 通俗说：创建任务列表对象时，设置默认值，同时调用父类的初始化方法
* 默认构造函数
* <p>
* 设计说明：初始化列表索引和子任务集合，创建一个空的本地文件夹。
*/
public TaskList() {
super(); // 调用父类Node的构造方法，初始化同步相关的默认属性
mChildren = new ArrayList<Task>(); // 初始化子任务列表（空列表）
mIndex = 1; // 默认排序索引为1（控制列表在云端的显示顺序）
super();
mChildren = new ArrayList<Task>();
mIndex = 1;
}
/**
* 打包“创建云端任务列表”的请求参数
* 通俗说：把本地新文件夹的信息整理成云端能识别的JSON格式，传给云端用来创建新列表
* @param actionId 动作编号（云端用来识别这次操作的唯一标记）
* @return 整理好的创建列表请求参数（JSON格式）
* 生成创建云端任务列表的JSON动作参数
* <p>
* 架构说明：构建符合Google Tasks API规范的创建列表请求参数，
* 包含列表的基本信息和索引位置，用于在云端创建新的任务列表。
*
* @param actionId Google Tasks API要求的动作标识符
* @return 符合Google Tasks API规范的创建列表JSON对象
* @throws ActionFailureException 生成JSON失败时抛出业务异常
*/
public JSONObject getCreateAction(int actionId) {
JSONObject js = new JSONObject(); // 创建空的JSON数据包
JSONObject js = new JSONObject();
try {
// 1. 设置动作类型：告诉云端这次是“创建任务列表”
// 1. 设置动作类型：创建任务列表
js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);
// 2. 设置动作ID：给这次创建操作一个唯一编号，方便云端识别
// 2. 设置动作ID：确保请求幂等性
js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
// 3. 设置列表排序索引：告诉云端这个新列表在云端的显示顺序
// 3. 设置列表索引：在云端列表中的显示顺序
js.put(GTaskStringUtils.GTASK_JSON_INDEX, mIndex);
// 4. 设置列表核心信息：打包列表的名称、创建者等信息
// 4. 构建列表实体数据
JSONObject entity = new JSONObject();
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName()); // 列表名称（对应本地文件夹名称）
entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null"); // 创建者ID（这里默认传null）
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null");
entity.put(GTaskStringUtils.GTASK_JSON_ENTITY_TYPE,
GTaskStringUtils.GTASK_JSON_TYPE_GROUP); // 实体类型：告诉云端这是一个“任务列表”（文件夹）
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity); // 把列表核心信息存入总JSON
GTaskStringUtils.GTASK_JSON_TYPE_GROUP);
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
} catch (JSONException e) {
// JSON打包出错，打印错误日志并抛出异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("fail to generate tasklist-create jsonobject");
}
return js; // 返回打包好的创建请求参数
return js;
}
/**
* 打包“更新云端任务列表”的请求参数
* 通俗说：把本地修改后的文件夹信息整理成云端能识别的JSON格式，传给云端用来更新已有列表
* @param actionId 动作编号（云端用来识别这次操作的唯一标记）
* @return 整理好的更新列表请求参数（JSON格式）
* 生成更新云端任务列表的JSON动作参数
* <p>
* 架构说明：构建符合Google Tasks API规范的更新列表请求参数，
* 只包含需要更新的字段，支持部分更新以减少网络传输。
*
* @param actionId Google Tasks API要求的动作标识符
* @return 符合Google Tasks API规范的更新列表JSON对象
* @throws ActionFailureException 生成JSON失败时抛出业务异常
*/
public JSONObject getUpdateAction(int actionId) {
JSONObject js = new JSONObject(); // 创建空的JSON数据包
JSONObject js = new JSONObject();
try {
// 1. 设置动作类型：告诉云端这次是“更新任务列表”
// 1. 设置动作类型：更新任务列表
js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
// 2. 设置动作ID：给这次更新操作一个唯一编号，方便云端识别
// 2. 设置动作ID
js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
// 3. 设置列表ID：告诉云端要更新哪个列表（用云端给的唯一ID）
// 3. 设置列表ID：指定要更新的列表
js.put(GTaskStringUtils.GTASK_JSON_ID, getGid());
// 4. 设置要更新的列表信息：打包修改后的名称、删除状态
// 4. 构建更新实体数据
JSONObject entity = new JSONObject();
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName()); // 更新后的列表名称
entity.put(GTaskStringUtils.GTASK_JSON_DELETED, getDeleted()); // 列表是否被删除（标记云端是否要删除该列表）
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity); // 把更新信息存入总JSON
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
entity.put(GTaskStringUtils.GTASK_JSON_DELETED, getDeleted());
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
} catch (JSONException e) {
// JSON打包出错，打印错误日志并抛出异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("fail to generate tasklist-update jsonobject");
}
return js; // 返回打包好的更新请求参数
return js;
}
/**
* 解析云端返回的列表数据，赋值给当前列表对象
* 通俗说：从云端获取到列表信息后，把数据拆解开，存到当前对象的属性里（同步到本地）
* @param js 云端返回的列表数据包（JSON格式）
* 从云端JSON数据解析任务列表内容
* <p>
* 架构说明：将Google Tasks API返回的JSON数据解析为本地列表对象，
* 支持增量更新，只处理有变化的字段。
*
* @param js Google Tasks API返回的列表JSON数据
* @throws ActionFailureException JSON解析失败时抛出业务异常
*/
@Override
public void setContentByRemoteJSON(JSONObject js) {
if (js != null) { // 如果云端返回的数据不为空
if (js != null) {
try {
// 1. 提取列表ID（云端给的唯一编号），设置到当前对象
// 提取并设置所有可用字段
if (js.has(GTaskStringUtils.GTASK_JSON_ID)) {
setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
}
// 2. 提取列表最后修改时间，设置到当前对象
if (js.has(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED)) {
setLastModified(js.getLong(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED));
}
// 3. 提取列表名称，设置到当前对象
if (js.has(GTaskStringUtils.GTASK_JSON_NAME)) {
setName(js.getString(GTaskStringUtils.GTASK_JSON_NAME));
}
} catch (JSONException e) {
// JSON解析出错，打印错误日志并抛出异常
Log.e(TAG, e.toString());
e.printStackTrace();
throw new ActionFailureException("fail to get tasklist content from jsonobject");
@ -162,86 +189,85 @@ public class TaskList extends Node {
}
/**
* 解析本地文件夹的JSON数据，设置列表内容
* 通俗说：把本地文件夹的JSON数据拆解开，提取文件夹名称，设置为云端列表名称（加专属前缀）
* @param js 本地文件夹的JSON数据包
* 从本地JSON数据解析任务列表内容
* <p>
* 业务逻辑：将本地便签文件夹的JSON数据解析为任务列表对象，
* 为不同类型文件夹（普通文件夹、系统文件夹）设置相应的云端列表名称。
*
* @param js 本地便签文件夹的JSON数据对象
*/
@Override
public void setContentByLocalJSON(JSONObject js) {
// 如果JSON数据为空，或者缺少文件夹信息，打印警告日志
// 数据验证：确保JSON包含必要的结构
if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)) {
Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
Log.w(TAG, "setContentByLocalJSON: nothing is available");
}
try {
// 1. 提取本地文件夹的基本信息
JSONObject folder = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
// 2. 如果是普通文件夹（用户自己创建的文件夹）
// Case 1: 普通文件夹 - 添加MIUI前缀
if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {
// 提取文件夹名称，加上MIUI专属前缀（区分云端其他列表）
String name = folder.getString(NoteColumns.SNIPPET);
setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + name);
}
// 3. 如果是系统文件夹（自带的根目录/通话记录文件夹）
// Case 2: 系统文件夹 - 特殊处理根目录和通话记录文件夹
else if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM) {
// 根目录文件夹：设置默认名称（加前缀）
if (folder.getLong(NoteColumns.ID) == Notes.ID_ROOT_FOLDER)
if (folder.getLong(NoteColumns.ID) == Notes.ID_ROOT_FOLDER) {
setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_DEFAULT);
// 通话记录文件夹：设置通话便签文件夹名称（加前缀）
else if (folder.getLong(NoteColumns.ID) == Notes.ID_CALL_RECORD_FOLDER)
setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX
+ GTaskStringUtils.FOLDER_CALL_NOTE);
// 其他系统文件夹：打印错误日志
else
} else if (folder.getLong(NoteColumns.ID) == Notes.ID_CALL_RECORD_FOLDER) {
setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_CALL_NOTE);
} else {
Log.e(TAG, "invalid system folder");
}
}
// 4. 无效类型：打印错误日志
// Case 3: 无效类型
else {
Log.e(TAG, "error type");
}
} catch (JSONException e) {
// JSON解析出错，打印错误日志
Log.e(TAG, e.toString());
e.printStackTrace();
}
}
/**
* 把当前列表数据打包成本地文件夹的JSON格式
* 通俗说：把云端列表的信息整理成本地文件夹能识别的JSON格式，方便保存到本地数据库
* @return 本地文件夹格式的JSON数据包（打包失败返回null）
* 从任务列表内容生成本地JSON数据
* <p>
* 架构说明：将任务列表对象转换为本地便签文件夹的JSON格式，
* 处理MIUI前缀，正确设置文件夹类型（普通文件夹或系统文件夹）。
*
* @return 本地便签文件夹格式的JSON对象，失败返回null
*/
@Override
public JSONObject getLocalJSONFromContent() {
try {
// 创建本地文件夹的JSON数据包
JSONObject js = new JSONObject();
JSONObject folder = new JSONObject(); // 文件夹基本信息
JSONObject folder = new JSONObject();
// 1. 提取云端列表名称，去掉MIUI专属前缀（还原成本地文件夹名称）
// 去除MIUI前缀，恢复原始文件夹名称
String folderName = getName();
if (getName().startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX))
if (getName().startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX)) {
folderName = folderName.substring(GTaskStringUtils.MIUI_FOLDER_PREFFIX.length(),
folderName.length());
}
// 2. 设置文件夹名称（摘要）
// 设置文件夹名称（摘要）
folder.put(NoteColumns.SNIPPET, folderName);
// 3. 判断文件夹类型（系统文件夹/普通文件夹）
// 判断文件夹类型
if (folderName.equals(GTaskStringUtils.FOLDER_DEFAULT)
|| folderName.equals(GTaskStringUtils.FOLDER_CALL_NOTE)) {
// 根目录/通话记录文件夹：标记为系统文件夹
// 系统文件夹：根目录或通话记录文件夹
folder.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);
} else {
// 其他文件夹：标记为普通文件夹
// 普通文件夹：用户创建的文件夹
folder.put(NoteColumns.TYPE, Notes.TYPE_FOLDER);
}
// 4. 把文件夹信息存入总JSON
js.put(GTaskStringUtils.META_HEAD_NOTE, folder);
return js; // 返回打包好的本地文件夹JSON
return js;
} catch (JSONException e) {
// JSON打包出错，打印错误日志
Log.e(TAG, e.toString());
e.printStackTrace();
return null;
@ -249,40 +275,44 @@ public class TaskList extends Node {
}
/**
* 对比本地和云端列表数据，判断该执行哪种同步操作
* 通俗说：查本地数据库，对比文件夹和云端列表的状态，确定是上传、下载还是无需操作
* @param c 本地数据库查询结果（存着本地文件夹的信息）
* @return 同步操作类型（对应Node类里的SYNC_ACTION_XXX常量）
* 获取同步动作类型
* <p>
* 架构说明：通过对比本地数据库记录与云端任务列表状态，
* 判断需要执行的同步动作类型，实现智能冲突检测。
* 业务逻辑：文件夹冲突时优先采用本地修改，确保用户意图得以保留。
*
* @param c 数据库游标，指向本地数据库中的对应记录
* @return 同步动作类型常量（SYNC_ACTION_XXX）
*/
@Override
public int getSyncAction(Cursor c) {
try {
// 1. 判断本地文件夹是否有修改
// Case 1: 本地无修改
if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
// 本地没有修改
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
// 本地和云端都没有修改，返回“无需操作”
// 两端数据一致，无需同步
return SYNC_ACTION_NONE;
} else {
// 云端有修改，返回“更新本地”（用云端列表数据覆盖本地文件夹）
// 云端有修改，需要更新本地
return SYNC_ACTION_UPDATE_LOCAL;
}
} else {
// 本地有修改
// 2. 验证云端列表ID是否匹配（不匹配返回“同步异常”）
// Case 2: 本地有修改
// 验证GTask ID匹配
if (!c.getString(SqlNote.GTASK_ID_COLUMN).equals(getGid())) {
Log.e(TAG, "gtask id doesn't match");
return SYNC_ACTION_ERROR;
}
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
// 只有本地修改，返回“更新云端”（把本地文件夹修改同步到云端）
// 只有本地修改，需要更新云端
return SYNC_ACTION_UPDATE_REMOTE;
} else {
// 本地和云端都有修改，文件夹冲突时优先本地修改，返回“更新云端”
// 两端都有修改，文件夹冲突时优先采用本地修改
return SYNC_ACTION_UPDATE_REMOTE;
}
}
} catch (Exception e) {
// 出现异常，打印错误日志，返回“同步异常”
Log.e(TAG, e.toString());
e.printStackTrace();
}
@ -290,131 +320,160 @@ public class TaskList extends Node {
return SYNC_ACTION_ERROR;
}
// ==================== 子任务管理方法 ====================
/**
* 获取当前列表下的子任务数量
* 通俗说：统计这个文件夹里有多少个普通便签（子任务）
* @return 子任务数量
* 获取子任务数量
*
* @return 当前列表中的子任务数量
*/
public int getChildTaskCount() {
return mChildren.size();
}
/**
* 给当前列表添加子任务（直接添加到列表末尾）
* 通俗说：往文件夹里添加一个普通便签，自动设置便签的父文件夹和上一个兄弟便签
* @param task 要添加的子任务（普通便签）
* @return true=添加成功，false=添加失败（任务为空/已存在）
* 添加子任务（追加到末尾）
* <p>
* 业务逻辑：将任务添加到列表末尾，自动维护任务间的兄弟关系。
* 设计说明：通过前一个兄弟任务建立任务顺序链。
*
* @param task 要添加的子任务对象
* @return true表示添加成功，false表示添加失败
*/
public boolean addChildTask(Task task) {
boolean ret = false;
// 如果任务不为空，且列表中没有该任务
if (task != null && !mChildren.contains(task)) {
ret = mChildren.add(task); // 添加任务到列表末尾
ret = mChildren.add(task);
if (ret) {
// 设置任务的上一个兄弟任务（列表最后一个任务的前一个）
task.setPriorSibling(mChildren.isEmpty() ? null : mChildren
.get(mChildren.size() - 1));
task.setParent(this); // 设置任务的所属列表（当前文件夹）
// 设置前一个兄弟任务
task.setPriorSibling(mChildren.isEmpty() ? null :
mChildren.get(mChildren.size() - 1));
// 设置父列表
task.setParent(this);
}
}
return ret;
}
/**
* 给当前列表添加子任务（指定位置添加）
* 通俗说：往文件夹的指定位置插入一个普通便签，更新该任务和前后任务的兄弟关系
* @param task 要添加的子任务（普通便签）
* 添加子任务（指定位置）
* <p>
* 业务逻辑：将任务插入到指定位置，更新相关任务的兄弟关系。
* 设计说明：支持精细化的任务排序控制。
*
* @param task 要添加的子任务对象
* @param index 要插入的位置索引
* @return true=添加成功，false=添加失败（索引无效/任务已存在）
* @return true表示添加成功，false表示添加失败
*/
public boolean addChildTask(Task task, int index) {
// 索引无效（小于0或大于列表长度），打印错误日志并返回false
// 索引验证
if (index < 0 || index > mChildren.size()) {
Log.e(TAG, "add child task: invalid index");
return false;
}
// 查找任务在列表中的位置（-1表示不存在）
int pos = mChildren.indexOf(task);
// 如果任务不存在，插入到指定位置
if (task != null && pos == -1) {
mChildren.add(index, task); // 在指定位置插入任务
mChildren.add(index, task);
// 获取该任务的前一个和后一个任务
// 获取前一个任务和后一个任务
Task preTask = null;
Task afterTask = null;
if (index != 0)
preTask = mChildren.get(index - 1); // 前一个任务（上一个兄弟）
if (index != mChildren.size() - 1)
afterTask = mChildren.get(index + 1); // 后一个任务
task.setPriorSibling(preTask); // 设置当前任务的上一个兄弟
if (afterTask != null)
afterTask.setPriorSibling(task); // 更新后一个任务的上一个兄弟为当前任务
if (index != 0) {
preTask = mChildren.get(index - 1);
}
if (index != mChildren.size() - 1) {
afterTask = mChildren.get(index + 1);
}
// 设置当前任务的前一个兄弟
task.setPriorSibling(preTask);
// 更新后一个任务的前一个兄弟
if (afterTask != null) {
afterTask.setPriorSibling(task);
}
}
return true;
}
/**
* 从当前列表移除子任务
* 通俗说：从文件夹里删除一个普通便签，重置该便签的父文件夹和兄弟关系，更新后续便签的兄弟关系
* @param task 要移除的子任务（普通便签）
* @return true=移除成功，false=移除失败（任务不存在）
* 移除子任务
* <p>
* 业务逻辑：从列表中移除指定任务，更新相关任务的兄弟关系。
* 设计说明：确保移除后列表的顺序关系仍然正确。
*
* @param task 要移除的子任务对象
* @return true表示移除成功，false表示移除失败
*/
public boolean removeChildTask(Task task) {
boolean ret = false;
// 查找任务在列表中的位置
int index = mChildren.indexOf(task);
if (index != -1) {
ret = mChildren.remove(task); // 移除该任务
ret = mChildren.remove(task);
if (ret) {
task.setPriorSibling(null); // 重置该任务的上一个兄弟关系
task.setParent(null); // 重置该任务的所属列表
// 重置被移除任务的关联关系
task.setPriorSibling(null);
task.setParent(null);
// 如果移除的不是最后一个任务，更新后续任务的兄弟关系
// 更新后续任务的兄弟关系
if (index != mChildren.size()) {
mChildren.get(index).setPriorSibling(
index == 0 ? null : mChildren.get(index - 1));
}
}
}
return ret;
}
/**
* 移动子任务在列表中的位置
* 通俗说：调整文件夹里普通便签的显示顺序，先移除再添加到指定位置
* @param task 要移动的子任务（普通便签）
* @param index 要移动到的目标位置
* @return true=移动成功，false=移动失败（索引无效/任务不存在/位置未变）
* 移动子任务位置
* <p>
* 业务逻辑：将任务从一个位置移动到另一个位置，重新排序任务列表。
* 设计说明：通过先移除后添加的方式实现位置移动。
*
* @param task 要移动的子任务对象
* @param index 目标位置索引
* @return true表示移动成功，false表示移动失败
*/
public boolean moveChildTask(Task task, int index) {
// 索引无效（小于0或大于等于列表长度），打印错误日志并返回false
// 索引验证
if (index < 0 || index >= mChildren.size()) {
Log.e(TAG, "move child task: invalid index");
return false;
}
// 查找任务当前位置（-1表示不存在）
int pos = mChildren.indexOf(task);
if (pos == -1) {
Log.e(TAG, "move child task: the task should in the list");
return false;
}
// 如果当前位置和目标位置一致，无需移动，返回true
if (pos == index)
// 如果位置未变，无需移动
if (pos == index) {
return true;
// 先移除任务，再添加到目标位置，返回操作结果
}
// 先移除后添加，实现位置移动
return (removeChildTask(task) && addChildTask(task, index));
}
/**
* 通过云端ID查找列表下的子任务
* 通俗说：根据便签对应的云端唯一ID，在文件夹里找到对应的普通便签
* @param gid 云端唯一ID
* @return 找到的子任务（普通便签），找不到返回null
* 通过GID查找子任务
* <p>
* 业务逻辑：根据Google Tasks ID在列表中查找对应的子任务。
*
* @param gid Google Tasks任务ID
* @return 找到的任务对象，未找到返回null
*/
public Task findChildTaskByGid(String gid) {
for (int i = 0; i < mChildren.size(); i++) {
@ -427,23 +486,26 @@ public class TaskList extends Node {
}
/**
* 获取子任务在列表中的位置索引
* 通俗说：查找某个普通便签在文件夹里的排序位置
* @param task 要查找的子任务（普通便签）
* @return 任务的位置索引（不存在返回-1）
* 获取子任务索引
* <p>
* 业务逻辑：查找任务在列表中的位置索引。
*
* @param task 要查找的子任务对象
* @return 任务索引，未找到返回-1
*/
public int getChildTaskIndex(Task task) {
return mChildren.indexOf(task);
}
/**
* 通过位置索引获取子任务
* 通俗说：根据排序位置，获取文件夹里对应的普通便签
* @param index 位置索引
* @return 对应的子任务（普通便签），索引无效返回null
* 通过索引获取子任务
* <p>
* 业务逻辑：根据索引位置获取对应的子任务。
*
* @param index 任务索引
* @return 对应的子任务对象，索引无效返回null
*/
public Task getChildTaskByIndex(int index) {
// 索引无效，打印错误日志并返回null
if (index < 0 || index >= mChildren.size()) {
Log.e(TAG, "getTaskByIndex: invalid index");
return null;
@ -452,41 +514,46 @@ public class TaskList extends Node {
}
/**
* 通过云端ID查找列表下的子任务（和findChildTaskByGid功能一致）
* 通俗说：根据便签对应的云端唯一ID，在文件夹里找到对应的普通便签
* @param gid 云端唯一ID
* @return 找到的子任务（普通便签），找不到返回null
* 通过GID获取子任务（别名方法）
* <p>
* 设计说明：与findChildTaskByGid功能相同，提供方法别名以保持API一致性。
*
* @param gid Google Tasks任务ID
* @return 找到的任务对象，未找到返回null
*/
public Task getChilTaskByGid(String gid) {
for (Task task : mChildren) {
if (task.getGid().equals(gid))
if (task.getGid().equals(gid)) {
return task;
}
}
return null;
}
/**
* 获取当前列表的所有子任务
* 通俗说：获取文件夹里所有的普通便签，返回完整列表
* @return 子任务列表（所有普通便签）
* 获取所有子任务
*
* @return 子任务列表
*/
public ArrayList<Task> getChildTaskList() {
return this.mChildren;
}
// ==================== 属性访问器 ====================
/**
* 设置当前列表的排序索引
* 通俗说：设置这个文件夹在云端的显示顺序
* @param index 排序索引
* 设置列表索引
*
* @param index 列表索引值
*/
public void setIndex(int index) {
this.mIndex = index;
}
/**
* 获取当前列表的排序索引
* 通俗说：获取这个文件夹在云端的显示顺序
* @return 排序索引
* 获取列表索引
*
* @return 列表索引值
*/
public int getIndex() {
return this.mIndex;

61
src/Notes-master/src/net/micode/notes/gtask/exception/ActionFailureException.java
Unescape View File

@ -1,32 +1,63 @@
/*
* Description：支持小米便签运行过程中的运行异常处理。
* Description：Google Tasks同步操作异常处理类
* 说明：封装GTask同步过程中的操作失败异常，提供丰富的异常构造方式
*/
package net.micode.notes.gtask.exception;
/**
* Google Tasks同步操作失败异常类 (Exception Layer - Operation Failure)
* <p>
* 核心职责：封装GTask同步过程中所有操作失败的异常情况，
* 包括任务创建、更新、删除、数据解析等操作失败场景。
* 架构说明：继承自RuntimeException，属于非受检异常，
* 设计用于需要立即中断同步流程的严重错误场景。
* 设计要点：支持异常消息和原因的链式传递，便于问题追踪和调试。
*/
public class ActionFailureException extends RuntimeException {
private static final long serialVersionUID = 4425249765923293627L;
/*
* serialVersionUID相当于java类的身份证。主要用于版本控制。
* serialVersionUID作用是序列化时保持版本的兼容性，即在版本升级时反序列化仍保持对象的唯一性。
* Made By Cuican
/**
* 序列化版本UID
* <p>
* 架构说明：用于序列化/反序列化过程中的版本兼容性控制，
* 确保在不同版本的应用间传输异常对象时能正确识别和处理。
* 设计要点：固定值确保版本一致性，避免自动生成导致的版本冲突。
*/
private static final long serialVersionUID = 4425249765923293627L;
/**
* 默认构造函数
* <p>
* 设计说明：创建无详细信息的异常实例，
* 适用于简单异常场景，调用方可通过异常栈自行分析。
*/
public ActionFailureException() {
super();
super(); // 调用父类RuntimeException的无参构造方法
}
/*
* 在JAVA类中使用super来引用父类的成分，用this来引用当前对象.
* 如果一个类从另外一个类继承，我们new这个子类的实例对象的时候，这个子类对象里面会有一个父类对象。
* 怎么去引用里面的父类对象呢？使用super来引用
* 也就是说，此处super()以及super (paramString)可认为是Exception ()和Exception (paramString)
* Made By Cuican
/**
* 带详细消息的构造函数
* <p>
* 架构说明：创建包含详细错误描述的异常实例，
* 便于调用方直接获取异常原因，无需额外分析。
*
* @param paramString 详细的错误描述信息
*/
public ActionFailureException(String paramString) {
super(paramString);
super(paramString); // 调用父类RuntimeException的带消息构造方法
}
/**
* 带详细消息和根本原因的构造函数
* <p>
* 架构说明：创建包含详细错误描述和底层原因的异常实例，
* 支持异常链传递，便于追踪问题根源。
* 设计要点：将底层异常封装为当前异常的原因，保持异常链完整。
*
* @param paramString 详细的错误描述信息
* @param paramThrowable 引发当前异常的根本原因
*/
public ActionFailureException(String paramString, Throwable paramThrowable) {
super(paramString, paramThrowable);
super(paramString, paramThrowable); // 调用父类RuntimeException的带消息和原因的构造方法
}
}

61
src/Notes-master/src/net/micode/notes/gtask/exception/NetworkFailureException.java
Unescape View File

@ -1,33 +1,64 @@
/*
* Description：支持小米便签运行过程中的网络异常处理。
* Description：Google Tasks同步网络异常处理类
* 说明：封装GTask同步过程中的网络相关异常，提供丰富的异常构造方式
*/
package net.micode.notes.gtask.exception;
/**
* Google Tasks同步网络异常类 (Exception Layer - Network Failure)
* <p>
* 核心职责：封装GTask同步过程中所有网络相关的异常情况，
* 包括连接超时、服务器无响应、网络不可用、SSL证书错误等网络问题。
* 架构说明：继承自Exception，属于受检异常（Checked Exception），
* 设计用于需要调用方显式处理的网络错误场景，确保网络操作的健壮性。
* 设计要点：提供多种构造方式，支持异常消息和原因的链式传递，便于问题诊断和恢复。
*/
public class NetworkFailureException extends Exception {
private static final long serialVersionUID = 2107610287180234136L;
/*
* serialVersionUID相当于java类的身份证。主要用于版本控制。
* serialVersionUID作用是序列化时保持版本的兼容性，即在版本升级时反序列化仍保持对象的唯一性。
* Made By Cuican
/**
* 序列化版本UID
* <p>
* 架构说明：用于序列化/反序列化过程中的版本兼容性控制，
* 确保在不同版本的应用间传输异常对象时能正确识别和处理。
* 设计要点：固定值确保版本一致性，避免自动生成导致的版本冲突。
*/
private static final long serialVersionUID = 2107610287180234136L;
/**
* 默认构造函数
* <p>
* 设计说明：创建无详细信息的网络异常实例，
* 适用于简单网络错误场景，调用方可通过异常栈自行分析。
*/
public NetworkFailureException() {
super();
super(); // 调用父类Exception的无参构造方法
}
/*
* 在JAVA类中使用super来引用父类的成分，用this来引用当前对象.
* 如果一个类从另外一个类继承，我们new这个子类的实例对象的时候，这个子类对象里面会有一个父类对象。
* 怎么去引用里面的父类对象呢？使用super来引用
* 也就是说，此处super()以及super (paramString)可认为是Exception ()和Exception (paramString)
* Made By Cuican
/**
* 带详细消息的构造函数
* <p>
* 架构说明：创建包含详细网络错误描述的异常实例，
* 便于调用方直接获取异常原因，无需额外分析。
*
* @param paramString 详细的网络错误描述信息，如"连接超时"、"服务器不可达"等
*/
public NetworkFailureException(String paramString) {
super(paramString);
super(paramString); // 调用父类Exception的带消息构造方法
}
/**
* 带详细消息和根本原因的构造函数
* <p>
* 架构说明：创建包含详细网络错误描述和底层原因的异常实例，
* 支持异常链传递，便于追踪网络问题根源。
* 设计要点：将底层网络异常（如IOException、SocketException等）
* 封装为当前异常的原因，保持异常链完整。
*
* @param paramString 详细的网络错误描述信息
* @param paramThrowable 引发当前异常的根本原因（底层网络异常）
*/
public NetworkFailureException(String paramString, Throwable paramThrowable) {
super(paramString, paramThrowable);
super(paramString, paramThrowable); // 调用父类Exception的带消息和原因的构造方法
}
}

262
src/Notes-master/src/net/micode/notes/gtask/remote/GTaskASyncTask.java
Unescape View File

@ -22,117 +22,167 @@ import android.content.Context;
import android.content.Intent;
import android.os.AsyncTask;
import android.os.Build;
// 导入弱引用工具：防止因一直持有页面/服务导致的内存浪费（通俗说就是不占无用内存）
import java.lang.ref.WeakReference;
// 导入兼容版通知工具：让老安卓手机和新安卓手机都能正常显示通知
import androidx.core.app.NotificationCompat;
// 导入通知权限检查工具：用来判断用户有没有开启这个APP的通知权限
import androidx.core.app.NotificationManagerCompat;
// 导入APP资源：获取APP里的文字、图标等内容
import net.micode.notes.R;
// 导入便签列表页面：通知点击后跳转到这个页面
import net.micode.notes.ui.NotesListActivity;
// 导入便签设置页面：同步失败时，通知点击后跳转到这个页面
import net.micode.notes.ui.NotesPreferenceActivity;
/**
* 这个类是用来在后台同步GTask和本地便签的（不会卡住手机界面）
* 注意：类名里的"ASync"写错了，应该是"Async"，而且类名要和文件名一模一样
* Google Tasks异步同步任务类 (UI Layer - Background Synchronization)
* <p>
* 核心职责：封装Google Tasks与本地便签的异步同步操作，
* 在后台线程执行同步逻辑，通过通知栏实时展示同步进度和结果。
* 架构说明：继承自AsyncTask，采用生产者-消费者模式，
* 实现线程安全的同步任务管理，支持进度更新和任务取消。
* 设计要点：使用弱引用避免内存泄漏，支持Android 8.0+通知通道，
* 提供完整的同步生命周期管理。
*/
// 类名和文件名保持一致：GTaskASyncTask（建议改成GTaskAsyncTask更规范）
public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
// 同步通知的唯一编号：用来区分这个同步通知和其他通知，不会弄混
/**
* 同步通知ID常量
* <p>
* 设计说明：用于唯一标识GTask同步通知，避免与其他通知冲突。
* 数值设计：使用大素数作为ID，降低与其他通知ID重复的概率。
*/
private static final int GTASK_SYNC_NOTIFICATION_ID = 5234235;
// 通知分类ID（安卓8.0以上必须有）：给同步通知单独分个类
/**
* 通知通道ID（Android 8.0+）
* <p>
* 架构说明：用于Android 8.0及以上版本的通知通道管理，
* 允许用户单独控制GTask同步通知的显示和声音设置。
*/
private static final String GTASK_SYNC_CHANNEL_ID = "gtask_sync_channel";
// 通知分类名称（安卓8.0以上必须有）：在手机设置里能看到这个分类的名字
/**
* 通知通道名称（Android 8.0+）
*/
private static final String GTASK_SYNC_CHANNEL_NAME = "GTask同步通知";
/**
* 任务完成后的回调接口
* 通俗说：同步任务不管成功、失败还是取消，都会告诉外部“我做完了”
* 同步任务完成监听器接口
* <p>
* 设计说明：定义同步任务完成时的回调接口，
* 允许外部组件（如Activity或Service）在同步结束后执行清理操作。
*/
public interface OnCompleteListener {
/**
* 任务完成后会调用这个方法
* 同步任务完成回调方法
* <p>
* 业务逻辑：无论同步成功、失败或取消，都会调用此方法，
* 通知调用方同步过程已结束。
*/
void onComplete();
}
// 用弱引用存上下文（页面/服务信息）：页面关闭后，这个引用不会占着内存不放
/**
* 上下文弱引用
* <p>
* 架构说明：使用WeakReference持有Context，防止内存泄漏。
* 设计要点：当外部Activity或Service被销毁时，GC可以自动回收Context，
* 避免因异步任务持有导致的内存泄漏问题。
*/
private final WeakReference<Context> mContextRef;
// 用弱引用存回调监听器：外部页面关闭后，这个监听器不会浪费内存
/**
* 完成监听器弱引用
*/
private final WeakReference<OnCompleteListener> mListenerRef;
// 通知管理器：用来发送、关闭手机通知的工具
/**
* 通知管理器
*/
private NotificationManager mNotificationManager;
// GTask管理工具：专门处理GTask同步逻辑的单例（整个APP只有这一个实例）
/**
* GTask管理器实例
* <p>
* 架构说明：持有GTaskManager单例，用于执行实际的同步逻辑。
* 设计要点：使用单例模式确保同步操作的唯一性和一致性。
*/
private final GTaskManager mTaskManager;
/**
* 构造方法：初始化这个同步任务
* @param context 页面/服务的上下文（用来获取图标、跳转页面等）
* @param listener 任务完成后的回调（告诉外部任务做完了）
* 构造函数
* <p>
* 设计说明：初始化异步任务所需的所有组件，包括通知通道的创建。
*
* @param context 应用上下文，用于资源访问和通知管理
* @param listener 同步完成监听器，用于任务结束后的回调
*/
public GTaskASyncTask(Context context, OnCompleteListener listener) {
// 把上下文存成弱引用，防止内存浪费
mContextRef = new WeakReference<>(context);
// 把回调监听器存成弱引用，防止内存浪费
mListenerRef = new WeakReference<>(listener);
// 先获取上下文（弱引用要先取出来才能用，还要判断不为空）
// 初始化通知管理器
Context ctx = mContextRef.get();
if (ctx != null) {
// 获取手机的通知管理服务（用来发通知的）
mNotificationManager = (NotificationManager) ctx.getSystemService(Context.NOTIFICATION_SERVICE);
// 创建通知分类
// 创建通知通道（Android 8.0+）
createNotificationChannel();
}
// 获取GTask管理工具的实例
// 获取GTask管理器单例
mTaskManager = GTaskManager.getInstance();
}
/**
* 取消同步任务
* 通俗说：不想同步了，调用这个方法就能停止
* 取消同步操作
* <p>
* 业务逻辑：向GTask管理器发送取消信号，
* 中断正在进行的同步操作，释放相关资源。
*/
public void cancelSync() {
mTaskManager.cancelSync();
}
/**
* 发送同步进度信息
* 通俗说：把后台同步的进度（比如“正在登录账号”）告诉主线程，用来显示通知
* @param message 进度提示文字（比如“正在同步第2条便签”）
* 发布同步进度
* <p>
* 架构说明：将同步进度信息发布到主线程，
* 用于更新UI组件或显示进度通知。
*
* @param message 进度信息文本
*/
public void publishProgress(String message) {
// 调用系统方法，把进度信息传出去
// 调用AsyncTask的进度发布方法
publishProgress(new String[]{message});
}
/**
* 创建通知分类（安卓8.0以上必须有）
* 通俗说：给同步通知单独建个分类，用户可以在手机设置里单独开关这个分类的通知
* 创建通知通道（Android 8.0+）
* <p>
* 架构说明：为Android 8.0及以上版本创建通知通道，
* 这是Android O及以后版本显示通知的强制要求。
* 设计要点：设置通知通道的基本属性，如重要性、指示灯等。
*/
private void createNotificationChannel() {
// 先获取上下文
Context ctx = mContextRef.get();
// 上下文为空，或者手机系统低于安卓8.0，就不用创建分类
// 版本兼容性检查：Android 8.0以下无需创建通知通道
if (ctx == null || Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
return;
}
// 构建通知分类
// 创建通知通道
android.app.NotificationChannel channel = new android.app.NotificationChannel(
GTASK_SYNC_CHANNEL_ID, // 分类ID
GTASK_SYNC_CHANNEL_NAME, // 分类名称
NotificationManager.IMPORTANCE_DEFAULT // 通知重要性：默认级别（有提示音，不震动）
GTASK_SYNC_CHANNEL_ID,
GTASK_SYNC_CHANNEL_NAME,
NotificationManager.IMPORTANCE_DEFAULT // 默认重要性：显示通知，发出声音
);
// 开启通知指示灯（如果手机有指示灯的话）
// 启用指示灯
channel.enableLights(true);
// 不在手机桌面APP图标上显示角标
// 禁用应用图标角标
channel.setShowBadge(false);
// 把分类注册到手机系统里
// 注册通知通道
if (mNotificationManager != null) {
mNotificationManager.createNotificationChannel(channel);
}
@ -140,122 +190,144 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
/**
* 显示同步通知
* 通俗说：根据同步状态（正在同步/成功/失败），在手机通知栏显示对应的提示
* @param tickerId 通知顶部一闪而过的文字ID（比如“正在同步GTask”）
* @param content 通知正文文字（比如“同步成功：共3条便签”）
* <p>
* 架构说明：根据同步状态显示不同类型的通知，
* 支持点击通知跳转到相应的Activity。
* 设计要点：适配不同Android版本的通知权限和API差异。
*
* @param tickerId 通知Ticker文本资源ID
* @param content 通知内容文本
*/
private void showNotification(int tickerId, String content) {
// 先获取上下文
Context ctx = mContextRef.get();
// 上下文或通知管理器为空，就不显示通知
// 上下文或通知管理器检查
if (ctx == null || mNotificationManager == null) {
return;
}
// 安卓13以上要检查通知权限：用户没开权限，就不显示通知
// Android 13+通知权限检查
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
if (!NotificationManagerCompat.from(ctx).areNotificationsEnabled()) {
// 这里可以提示用户开权限，现在先直接返回
// 用户禁用了通知权限，跳过通知显示
return;
}
}
// 构建通知点击后的跳转意图
// 构建PendingIntent
PendingIntent pendingIntent;
Intent intent;
// 同步成功就跳转到便签列表，失败/取消就跳转到便签设置
// 根据同步结果选择目标Activity
if (tickerId != R.string.ticker_success) {
intent = new Intent(ctx, NotesPreferenceActivity.class); // 跳设置页面
// 同步失败或取消：跳转到设置页面
intent = new Intent(ctx, NotesPreferenceActivity.class);
} else {
intent = new Intent(ctx, NotesListActivity.class); // 跳便签列表
// 同步成功：跳转到便签列表
intent = new Intent(ctx, NotesListActivity.class);
}
// 配置跳转意图的标志：更新已有意图，防止重复创建
// 设置PendingIntent标志
int flags = PendingIntent.FLAG_UPDATE_CURRENT;
// 安卓6.0以上添加不可变标志，防止报错
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
flags |= PendingIntent.FLAG_IMMUTABLE;
flags |= PendingIntent.FLAG_IMMUTABLE; // Android 6.0+添加不可变标志
}
// 创建跳转意图
pendingIntent = PendingIntent.getActivity(ctx, 0, intent, flags);
// 构建通知内容
// 构建通知
NotificationCompat.Builder builder = new NotificationCompat.Builder(ctx, GTASK_SYNC_CHANNEL_ID)
.setSmallIcon(R.drawable.notification) // 通知小图标（必须设置，不然不显示）
.setContentTitle(ctx.getString(R.string.app_name)) // 通知标题（显示APP名字）
.setContentText(content) // 通知正文
.setTicker(ctx.getString(tickerId)) // 通知顶部一闪而过的文字（老手机有效）
.setWhen(System.currentTimeMillis()) // 通知创建时间
.setDefaults(NotificationCompat.DEFAULT_LIGHTS) // 开启默认指示灯
.setAutoCancel(true) // 点击通知后，通知自动消失
.setContentIntent(pendingIntent); // 通知点击后跳转到指定页面
.setSmallIcon(R.drawable.notification) // 小图标（必需）
.setContentTitle(ctx.getString(R.string.app_name)) // 应用名称作为标题
.setContentText(content) // 通知内容
.setTicker(ctx.getString(tickerId)) // Ticker文本（旧版本Android）
.setWhen(System.currentTimeMillis()) // 通知时间
.setDefaults(NotificationCompat.DEFAULT_LIGHTS) // 默认指示灯
.setAutoCancel(true) // 点击后自动取消
.setContentIntent(pendingIntent); // 点击跳转
// 显示通知
mNotificationManager.notify(GTASK_SYNC_NOTIFICATION_ID, builder.build());
}
/**
* 后台执行同步任务（运行在子线程，不会卡界面）
* @param unused 没有参数
* @return 同步结果（成功/网络错误/内部错误/取消）
* 后台执行同步任务
* <p>
* 架构说明：在后台线程中执行实际的同步操作，
* 定期发布进度信息，返回同步结果状态。
*
* @param unused 无用的Void参数（AsyncTask约定）
* @return 同步结果状态码
*/
@Override
protected Integer doInBackground(Void... unused) {
// 获取上下文
Context ctx = mContextRef.get();
// 发布登录进度
if (ctx != null) {
// 发送进度：提示正在登录同步账号
publishProgress(ctx.getString(R.string.sync_progress_login,
NotesPreferenceActivity.getSyncAccountName(ctx)));
}
// 执行同步逻辑，返回同步结果
// 执行同步逻辑
return mTaskManager.sync(ctx, this);
}
/**
* 进度更新回调（运行在主线程，可以更新界面/显示通知）
* @param progress 进度信息
* 进度更新回调
* <p>
* 架构说明：在主线程中处理进度更新，
* 显示同步通知并向相关组件广播进度信息。
*
* @param progress 进度信息数组
*/
@Override
protected void onProgressUpdate(String... progress) {
// 显示“正在同步”的通知
// 显示同步中通知
showNotification(R.string.ticker_syncing, progress[0]);
// 获取上下文
Context ctx = mContextRef.get();
// 如果上下文是GTask同步服务，就发送广播告诉服务当前进度
// 如果是GTaskSyncService，发送进度广播
if (ctx instanceof GTaskSyncService) {
((GTaskSyncService) ctx).sendBroadcast(progress[0]);
}
}
/**
* 任务完成回调（运行在主线程，同步结束后会调用）
* @param result 同步结果（成功/失败/取消等）
* 同步任务完成后回调
* <p>
* 架构说明：在主线程中处理同步结果，
* 根据结果状态显示相应通知，更新最后同步时间，
* 调用完成监听器进行后续处理。
*
* @param result 同步结果状态码
*/
@Override
protected void onPostExecute(Integer result) {
// 获取上下文
Context ctx = mContextRef.get();
if (ctx != null) {
// 根据同步结果显示对应通知
// 根据同步结果显示相应通知
if (result == GTaskManager.STATE_SUCCESS) {
// 同步成功：显示成功通知，记录最后同步时间
// 同步成功
showNotification(R.string.ticker_success, ctx.getString(
R.string.success_sync_account, mTaskManager.getSyncAccount()));
// 更新最后同步时间
NotesPreferenceActivity.setLastSyncTime(ctx, System.currentTimeMillis());
} else if (result == GTaskManager.STATE_NETWORK_ERROR) {
// 网络错误：显示网络异常通知
// 网络错误
showNotification(R.string.ticker_fail, ctx.getString(R.string.error_sync_network));
} else if (result == GTaskManager.STATE_INTERNAL_ERROR) {
// 内部错误：显示内部异常通知
// 内部错误
showNotification(R.string.ticker_fail, ctx.getString(R.string.error_sync_internal));
} else if (result == GTaskManager.STATE_SYNC_CANCELLED) {
// 同步取消：显示取消通知
// 同步取消
showNotification(R.string.ticker_cancel, ctx.getString(R.string.error_sync_cancelled));
}
}
// 获取回调监听器，告诉外部任务完成了
// 调用完成监听器
OnCompleteListener listener = mListenerRef.get();
if (listener != null) {
listener.onComplete();
@ -263,14 +335,18 @@ public class GTaskASyncTask extends AsyncTask<Void, String, Integer> {
}
/**
* 任务被取消时的回调
* 通俗说：调用cancel()方法取消任务后，会执行这个方法
* @param result 同步结果
* 任务取消回调
* <p>
* 架构说明：当任务被取消时调用此方法，
* 确保即使任务取消也能正确调用完成监听器。
*
* @param result 同步结果（可能为null）
*/
@Override
protected void onCancelled(Integer result) {
super.onCancelled(result);
// 告诉外部任务完成了
// 调用完成监听器
OnCompleteListener listener = mListenerRef.get();
if (listener != null) {
listener.onComplete();

664
src/Notes-master/src/net/micode/notes/gtask/remote/GTaskClient.java
View File

File diff suppressed because it is too large Load Diff

662
src/Notes-master/src/net/micode/notes/gtask/remote/GTaskManager.java
View File

File diff suppressed because it is too large Load Diff

187
src/Notes-master/src/net/micode/notes/gtask/remote/GTaskSyncService.java
Unescape View File

@ -16,204 +16,219 @@
package net.micode.notes.gtask.remote;
import android.app.Activity; // 页面类：外部启动同步时需要关联的页面
import android.app.Service; // 后台服务类：在后台执行耗时操作（同步），不占用前台页面资源
import android.content.Context; // 上下文：保存页面/服务信息，用来启动服务
import android.content.Intent; // 意图：用来传递指令（启动/取消同步）、发送广播
import android.os.Bundle; // 数据容器：用来存储意图中的额外参数（比如同步操作类型）
import android.os.IBinder; // 绑定接口：服务绑定相关（这里用不到）
import android.app.Activity;
import android.app.Service;
import android.content.Context;
import android.content.Intent;
import android.os.Bundle;
import android.os.IBinder;
/**
* GTask同步后台服务类
* 通俗说：这个类是后台运行的服务，专门负责管理GTask同步（启动同步、取消同步），
* 还会发送广播，把同步状态（是否在同步）和进度（比如“正在登录”）通知给前台界面
* 特点：在后台运行，即使前台页面关闭，同步也能继续执行
* GTask 同步后台服务 (Sync Service Layer)
* <p>
* 作为 GTask 同步体系的前端服务层，负责在后台执行耗时同步任务，并通过广播机制与 UI 层进行状态通信。
* 采用 Android Service 组件实现，确保同步任务在后台持续运行，即使 UI 界面被销毁也不中断。
* <p>
* 架构职责：
* 1. 命令接收器：接收来自 UI 层的 START/CANCEL 命令，控制同步任务的生命周期。
* 2. 任务调度器：管理 {@link GTaskASyncTask} 的单一实例，防止并发同步导致数据混乱。
* 3. 状态广播器：通过 {@link Intent} 广播实时同步状态（进度、是否进行中）到所有注册的组件。
* <p>
* 设计模式：前端服务 (Foreground Service 未启用) + 观察者模式 (广播)。
*/
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;
// 同步状态广播的名称：前台界面通过这个名称接收同步状态通知
/** 同步状态广播的 Action 名称，UI 层需监听此 Action 以接收状态更新 */
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";
// 静态变量：当前正在执行的同步异步任务（整个APP共享，确保只有一个同步任务在运行）
/** 当前正在执行的同步异步任务实例（静态，确保整个应用只有一个活跃实例） */
private static GTaskASyncTask mSyncTask = null;
// 静态变量：当前同步进度提示文字（比如“正在初始化列表”“正在同步”）
/** 当前同步进度文本（静态，供 UI 查询） */
private static String mSyncProgress = "";
/**
* 启动同步任务
* 通俗说：创建并执行同步异步任务，确保同一时间只有一个同步任务在运行
* 启动 GTask 同步任务。
* <p>
* 采用懒加载单例模式创建 {@link GTaskASyncTask}。如果当前已有同步任务正在运行，则不再创建新任务，避免并发冲突。
* 任务完成后会通过 {@link OnCompleteListener} 自动清理引用并停止服务。
*/
private void startSync() {
// 如果当前没有正在执行的同步任务，才创建新任务（避免重复同步）
// 单例检查：防止重复启动同步任务
if (mSyncTask == null) {
// 创建GTask同步异步任务，传入服务上下文和任务完成监听器
mSyncTask = new GTaskASyncTask(this, new GTaskASyncTask.OnCompleteListener() {
/**
* 同步任务完成后的回调方法
* 通俗说：同步不管成功、失败还是被取消，都会执行这个方法
* 异步任务完成回调（无论成功、失败或被取消）。
* <p>
* 清理静态引用，发送最终状态广播，并停止服务以释放系统资源。
*/
@Override
public void onComplete() {
mSyncTask = null; // 同步完成，清空当前任务引用
sendBroadcast(""); // 发送空进度广播，通知界面同步已结束
stopSelf(); // 停止当前服务（同步完成，不需要后台服务了）
mSyncTask = null; // 清理引用，允许下次启动
sendBroadcast(""); // 发送空进度广播，通知 UI 同步结束
stopSelf(); // 同步完成，服务使命结束
}
});
sendBroadcast(""); // 发送广播，通知界面同步已开始
mSyncTask.execute(); // 执行同步异步任务（在后台开始同步）
// 同步开始，立即发送广播通知 UI 更新状态
sendBroadcast("");
// 启动异步任务（实际同步逻辑在 GTaskASyncTask 中执行）
mSyncTask.execute();
}
}
/**
* 取消同步任务
* 通俗说：如果有正在执行的同步任务，就停止它
* 取消正在进行的同步任务。
* <p>
* 通过调用 {@link GTaskASyncTask#cancelSync()} 设置取消标志，同步任务会在下一个检查点优雅终止。
* 注意：这是一个异步取消，并非立即中断线程。
*/
private void cancelSync() {
// 如果当前有正在执行的同步任务
if (mSyncTask != null) {
// 调用异步任务的取消方法，终止同步
mSyncTask.cancelSync();
}
}
/**
* 服务创建时的初始化方法
* 通俗说：这个服务第一次被创建时，会执行这里的代码，初始化同步任务为null
* 服务创建生命周期回调。
* <p>
* 初始化静态任务引用为 null，确保服务重启后状态一致。
*/
@Override
public void onCreate() {
mSyncTask = null; // 初始化当前同步任务为null（还没有同步任务执行）
mSyncTask = null;
}
/**
* 服务启动时的处理逻辑
* 通俗说：外部通过意图启动服务时，会执行这里的代码，根据意图中的指令执行“启动”或“取消”同步
* @param intent 外部传递的意图（包含同步操作类型）
* @param flags 服务启动标记（系统使用）
* @param startId 服务启动ID（系统使用）
* @return 服务启动模式（START_STICKY=服务被意外杀死后，系统会尝试重启）
* 服务启动命令处理。
* <p>
* 解析 Intent 中的操作类型，执行对应的同步控制逻辑。
* 采用 {@link START_STICKY} 启动模式，确保系统在内存不足杀死服务后，条件允许时会自动重启服务。
*
* @param intent 启动服务的 Intent，应包含 {@link #ACTION_STRING_NAME} Extra。
* @param flags 启动标志，由系统传入。
* @param startId 本次启动的唯一 ID。
* @return 服务启动模式，此处返回 {@link START_STICKY}。
*/
@Override
public int onStartCommand(Intent intent, int flags, int startId) {
// 获取意图中的额外参数（存储了同步操作类型）
Bundle bundle = intent.getExtras();
// 如果参数不为空，且包含“同步操作类型”的键
if (bundle != null && bundle.containsKey(ACTION_STRING_NAME)) {
// 根据同步操作类型执行对应逻辑
switch (bundle.getInt(ACTION_STRING_NAME, ACTION_INVALID)) {
case ACTION_START_SYNC:
// 收到“启动同步”指令，执行启动同步方法
startSync();
break;
case ACTION_CANCEL_SYNC:
// 收到“取消同步”指令，执行取消同步方法
cancelSync();
break;
default:
// 收到无效指令，不做处理
// 无效操作类型，忽略
break;
}
// 返回START_STICKY：服务被意外杀死（比如内存不足），系统会尝试重启服务
// 使用 STICKY 模式，服务被意外杀死后系统会尝试重启
return START_STICKY;
}
// 如果没有有效参数，执行父类默认逻辑
return super.onStartCommand(intent, flags, startId);
}
/**
* 手机内存不足时的处理方法
* 通俗说：当手机内存不够用的时候，系统会调用这个方法，这里选择取消同步来释放内存
* 系统低内存回调。
* <p>
* 当系统内存严重不足时调用，主动取消同步任务以释放资源，避免应用被强制终止。
*/
@Override
public void onLowMemory() {
// 如果有正在执行的同步任务，就取消它，释放内存
// 主动取消同步，释放内存
if (mSyncTask != null) {
mSyncTask.cancelSync();
}
}
/**
* 绑定服务的方法
* 通俗说：这个服务不需要被前台界面绑定，所以直接返回null
* @param intent 绑定服务的意图
* @return null（表示不支持绑定）
* 服务绑定回调（未实现绑定功能）。
* <p>
* 本服务仅通过 startService() 启动，不支持绑定模式。
*
* @param intent 绑定请求的 Intent。
* @return 始终返回 null，表示不提供 IBinder 接口。
*/
@Override
public IBinder onBind(Intent intent) {
return null;
}
/**
* 发送同步状态广播
* 通俗说：把当前的同步状态（是否在同步）和进度提示，通过广播发送给前台界面，让界面更新显示
* @param msg 同步进度提示文字（比如“正在登录”“正在同步”）
* 发送同步状态广播。
* <p>
* 将当前同步状态（是否进行中）和进度文本打包到 Intent 中，通过全局广播发送。
* UI 组件（如 {@link net.micode.notes.ui.NotesListActivity}）应注册监听此广播以更新界面。
*
* @param msg 当前同步进度描述文本（例如："正在登录"、"正在同步便签"），空字符串表示同步开始或结束。
*/
public void sendBroadcast(String msg) {
mSyncProgress = msg; // 更新当前同步进度文字
// 创建广播意图，指定广播名称（前台界面通过这个名称接收）
mSyncProgress = msg;
Intent intent = new Intent(GTASK_SERVICE_BROADCAST_NAME);
// 存入“是否正在同步”的状态（有同步任务就是正在同步）
intent.putExtra(GTASK_SERVICE_BROADCAST_IS_SYNCING, mSyncTask != null);
// 存入同步进度提示文字
intent.putExtra(GTASK_SERVICE_BROADCAST_PROGRESS_MSG, msg);
// 发送广播，通知所有监听该广播的界面
// 发送无序广播，所有注册的接收者都会收到
sendBroadcast(intent);
}
/**
* 静态方法：外部启动GTask同步的快捷方法
* 通俗说：前台界面可以直接调用这个方法，快速启动GTask同步服务
* @param activity 关联的页面（用来获取谷歌账号登录凭证）
* 静态便捷方法：从 UI 层启动 GTask 同步。
* <p>
* 为调用方封装了设置 {@link GTaskManager} 上下文和启动服务的细节。
* 注意：调用此方法前应确保用户已登录 Google 账户（由 GTaskClient 内部处理）。
*
* @param activity 当前 Activity，用于提供 Google 账户认证的上下文。
*/
public static void startSync(Activity activity) {
// 给GTask管理器设置关联页面（用于登录）
// 设置 Activity 上下文，供 GTaskClient 登录使用
GTaskManager.getInstance().setActivityContext(activity);
// 创建启动服务的意图，指定服务类
Intent intent = new Intent(activity, GTaskSyncService.class);
// 存入“启动同步”的操作类型
intent.putExtra(GTaskSyncService.ACTION_STRING_NAME, GTaskSyncService.ACTION_START_SYNC);
// 启动后台服务（开始同步）
activity.startService(intent);
}
/**
* 静态方法：外部取消GTask同步的快捷方法
* 通俗说：前台界面可以直接调用这个方法，快速取消正在执行的同步
* @param context 上下文（用来启动服务）
* 静态便捷方法：从 UI 层取消 GTask 同步。
* <p>
* 通过启动服务并发送取消命令，触发 {@link #cancelSync()} 方法。
*
* @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);
}
/**
* 静态方法：判断当前是否正在同步
* 通俗说：前台界面可以调用这个方法，获取同步状态（用来更新界面按钮，比如同步中就禁用启动按钮）
* @return true=正在同步，false=未同步
* 静态便捷方法：查询当前同步状态。
*
* @return true 表示同步正在进行中，false 表示空闲。
*/
public static boolean isSyncing() {
return mSyncTask != null; // 有同步任务就是正在同步
return mSyncTask != null;
}
/**
* 静态方法：获取当前同步进度提示文字
* 通俗说：前台界面可以调用这个方法，获取同步进度（用来显示在界面上，比如“正在初始化列表”）
* @return 同步进度提示文字
* 静态便捷方法：获取当前同步进度文本。
* <p>
* UI 层可在适当时机（如界面刷新）调用此方法获取最新进度描述。
*
* @return 当前同步进度描述文本。
*/
public static String getProgressString() {
return mSyncProgress;

385
src/Notes-master/src/net/micode/notes/model/Note.java
Unescape View File

@ -16,69 +16,82 @@
package net.micode.notes.model;
import android.content.ContentProviderOperation; // 数据库批量操作指令：用来批量执行数据库更新操作
import android.content.ContentProviderResult; // 数据库批量操作结果：存储批量操作的执行结果
import android.content.ContentUris; // URI拼接工具：用来拼接便签/数据的数据库访问地址
import android.content.ContentValues; // 数据键值对容器：用来存储要写入数据库的字段和对应值
import android.content.Context; // 上下文：用来获取本地数据库操作工具
import android.content.OperationApplicationException; // 批量操作异常：批量执行数据库操作失败时抛出
import android.net.Uri; // 数据库访问地址：标识数据库中的某类数据（比如便签表、便签数据表）
import android.os.RemoteException; // 远程操作异常：跨进程访问数据库失败时抛出
import android.util.Log; // 日志工具：打印错误信息，方便排查问题
import net.micode.notes.data.Notes; // 便签常量类：存储便签类型、数据库地址等固定值
import net.micode.notes.data.Notes.CallNote; // 通话便签常量：存储通话便签的MIME类型等
import net.micode.notes.data.Notes.DataColumns; // 便签数据列：便签数据表的字段名（比如所属便签ID、内容）
import net.micode.notes.data.Notes.NoteColumns; // 便签主列：便签主表的字段名（比如创建时间、修改时间）
import net.micode.notes.data.Notes.TextNote; // 文本便签常量：存储文本便签的MIME类型等
import java.util.ArrayList; // 数组列表：用来存储批量操作指令
import android.content.ContentProviderOperation;
import android.content.ContentProviderResult;
import android.content.ContentUris;
import android.content.ContentValues;
import android.content.Context;
import android.content.OperationApplicationException;
import android.net.Uri;
import android.os.RemoteException;
import android.util.Log;
import net.micode.notes.data.Notes;
import net.micode.notes.data.Notes.CallNote;
import net.micode.notes.data.Notes.DataColumns;
import net.micode.notes.data.Notes.NoteColumns;
import net.micode.notes.data.Notes.TextNote;
import java.util.ArrayList;
/**
* 本地便签数据模型类
* 通俗说：这个类是本地便签的“数据管家”，负责创建新便签ID、存储便签的主信息（创建时间、所属文件夹等）
* 和具体数据（文本内容、通话记录内容），还能把便签的修改同步到本地数据库
* 便签数据模型类 (Model Layer - Data Buffer)
* <p>
* 核心职责：作为 MVC 架构中 Model 层的数据缓冲区，管理单个便签在内存中的状态变更，并负责将这些变更同步到本地数据库。
* 采用"脏数据缓冲区"设计模式：所有修改先在内存中累积，通过 {@link #syncNote} 方法原子性地刷新到数据库。
* <p>
* 数据层次结构：
* 1. 便签元数据 (mNoteDiffValues): 存储 {@link NoteColumns} 表的字段变更，如标题、文件夹、修改时间等。
* 2. 便签内容数据 (mNoteData): 存储 {@link DataColumns} 表的字段变更，如文本内容、通话记录等。
* <p>
* 注意：本类不直接执行网络同步，仅处理本地数据库的原子操作。GTask 同步由 {@link net.micode.notes.gtask.remote.GTaskManager} 处理。
* <p>
* 【架构变迁 (2025)】：
* - 在旧版本中，同步操作在主线程直接执行，可能导致 ANR。
* - 在 2025 年重构中，调用本类 {@link #syncNote} 的代码已被封装为 Runnable，通过 {@link net.micode.notes.model.ThreadExecutor} 异步执行。
*/
public class Note {
// 便签主信息修改容器：存储便签主表的修改字段（比如修改时间、本地修改标记）
/** 存储便签元数据字段的变更 (NoteColumns) */
private ContentValues mNoteDiffValues;
// 便签具体数据管理对象：负责存储和管理便签的文本/通话记录数据
/** 管理便签内容数据 (文本/通话) 的变更 */
private NoteData mNoteData;
// 日志标签：打印日志时标识是这个类的日志，方便查找问题
/** 日志标签 */
private static final String TAG = "Note";
/**
* 生成新便签ID（用于给数据库添加新便签）
* 通俗说：创建新便签时，先在数据库里生成一个唯一的便签ID，后续用这个ID操作该便签
* @param context 上下文（获取数据库操作工具用）
* @param folderId 便签所属文件夹ID（比如根文件夹、自定义文件夹）
* @return 新便签的唯一ID（返回0表示生成失败）
* 生成新便签的数据库 ID。
* <p>
* 在创建新便签时调用，向数据库的 notes 表插入一条基础记录，并返回其主键 ID。
* 此方法同步，确保在多线程环境下不会生成重复 ID。
*
* @param context 应用上下文，用于获取 ContentResolver。
* @param folderId 新便签所属的文件夹 ID。
* @return 新生成的便签 ID，若为 0 或 -1 则表示创建失败。
* @throws IllegalStateException 如果数据库返回的 ID 为 -1（表示插入失败）。
*/
public static synchronized long getNewNoteId(Context context, long folderId) {
// 1. 准备新便签的默认数据（存储到便签主表）
// 准备新便签的默认元数据
ContentValues values = new ContentValues();
long createdTime = System.currentTimeMillis(); // 获取当前时间作为创建时间
values.put(NoteColumns.CREATED_DATE, createdTime); // 存入创建时间
values.put(NoteColumns.MODIFIED_DATE, createdTime); // 存入修改时间（初始和创建时间一致）
values.put(NoteColumns.TYPE, Notes.TYPE_NOTE); // 存入便签类型（普通文本便签）
values.put(NoteColumns.LOCAL_MODIFIED, 1); // 存入本地修改标记（1=已修改，需要同步）
values.put(NoteColumns.PARENT_ID, folderId); // 存入所属文件夹ID
// 2. 插入新便签到数据库，获取数据库返回的访问地址（包含新便签ID）
long createdTime = System.currentTimeMillis();
values.put(NoteColumns.CREATED_DATE, createdTime);
values.put(NoteColumns.MODIFIED_DATE, createdTime);
values.put(NoteColumns.TYPE, Notes.TYPE_NOTE);
values.put(NoteColumns.LOCAL_MODIFIED, 1); // 初始标记为需要本地同步
values.put(NoteColumns.PARENT_ID, folderId);
// DB操作：插入新便签记录
Uri uri = context.getContentResolver().insert(Notes.CONTENT_NOTE_URI, values);
// 3. 从访问地址中解析出新便签ID
long noteId = 0;
try {
// 数据库返回的Uri格式是：content://xxx/notes/[noteId]，取第2个分段就是便签ID
// 从返回的 Uri 中解析出 ID (格式: content://authority/notes/[id])
noteId = Long.valueOf(uri.getPathSegments().get(1));
} catch (NumberFormatException e) {
// 解析ID失败，打印错误日志
Log.e(TAG, "Get note id error :" + e.toString());
noteId = 0;
}
// 4. 校验便签ID是否有效（-1表示插入失败）
// 验证 ID 有效性，-1 表示数据库插入失败
if (noteId == -1) {
throw new IllegalStateException("Wrong note id:" + noteId);
}
@ -86,179 +99,204 @@ public class Note {
}
/**
* 构造方法：初始化便签对象
* 通俗说：创建Note对象时，自动初始化便签主信息容器和具体数据管理对象
* 构造函数：初始化一个空的便签数据缓冲区。
*/
public Note() {
mNoteDiffValues = new ContentValues(); // 初始化便签主信息修改容器
mNoteData = new NoteData(); // 初始化便签具体数据管理对象
mNoteDiffValues = new ContentValues();
mNoteData = new NoteData();
}
/**
* 设置便签主信息字段
* 通俗说：修改便签的主信息（比如标题、所属文件夹），同时标记为“已修改”并更新修改时间
* @param key 便签主表的字段名（比如NoteColumns.TITLE）
* @param value 字段对应的值（比如便签标题文字）
* 设置便签元数据字段的值。
* <p>
* 此方法会同时设置 {@link NoteColumns#LOCAL_MODIFIED} 和 {@link NoteColumns#MODIFIED_DATE}，
* 标记此便签已被修改，需要在下次同步时更新。
*
* @param key 元数据字段名，必须是 {@link NoteColumns} 中定义的常量。
* @param value 字段的新值。
*/
public void setNoteValue(String key, String value) {
mNoteDiffValues.put(key, value); // 存入要修改的字段和值
mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1); // 标记为本地已修改（需要同步到GTask）
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis()); // 更新修改时间为当前时间
mNoteDiffValues.put(key, value);
mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
/**
* 设置便签文本数据字段
* 通俗说：修改便签的文本内容相关字段（比如正文文字）
* @param key 便签数据表的文本字段名（比如TextNote.CONTENT）
* @param value 文本字段对应的值（比如便签正文）
* 设置文本便签内容字段的值。
* <p>
* 委托给内部 {@link NoteData} 对象处理，同时标记元数据为已修改。
*
* @param key 文本字段名，必须是 {@link TextNote} 中定义的常量。
* @param value 字段的新值。
*/
public void setTextData(String key, String value) {
mNoteData.setTextData(key, value); // 委托给NoteData对象处理
mNoteData.setTextData(key, value);
}
/**
* 设置文本数据的ID
* 通俗说：给便签的文本数据设置唯一ID（对应数据库里的文本数据记录ID）
* @param id 文本数据ID
* 设置文本内容数据的数据库 ID。
* <p>
* 用于关联已经存在于数据库中的文本数据记录。
*
* @param id 文本内容数据在 data 表中的主键 ID。
* @throws IllegalArgumentException 如果 id ≤ 0。
*/
public void setTextDataId(long id) {
mNoteData.setTextDataId(id); // 委托给NoteData对象处理
mNoteData.setTextDataId(id);
}
/**
* 获取文本数据的ID
* 通俗说：获取便签文本数据对应的数据库记录ID
* @return 文本数据ID
* 获取文本内容数据的数据库 ID。
*
* @return 文本数据 ID，若为 0 则表示尚未关联数据库记录。
*/
public long getTextDataId() {
return mNoteData.mTextDataId; // 从NoteData对象中获取
return mNoteData.mTextDataId;
}
/**
* 设置通话数据的ID
* 通俗说：给便签的通话记录数据设置唯一ID（对应数据库里的通话数据记录ID）
* @param id 通话数据ID
* 设置通话记录内容数据的数据库 ID。
* <p>
* 用于关联已经存在于数据库中的通话数据记录。
*
* @param id 通话内容数据在 data 表中的主键 ID。
* @throws IllegalArgumentException 如果 id ≤ 0。
*/
public void setCallDataId(long id) {
mNoteData.setCallDataId(id); // 委托给NoteData对象处理
mNoteData.setCallDataId(id);
}
/**
* 设置便签通话数据字段
* 通俗说：修改便签的通话记录相关字段（比如通话号码、通话时间）
* @param key 便签数据表的通话字段名（比如CallNote.NUMBER）
* @param value 通话字段对应的值（比如10086）
* 设置通话记录便签内容字段的值。
* <p>
* 委托给内部 {@link NoteData} 对象处理，同时标记元数据为已修改。
*
* @param key 通话字段名，必须是 {@link CallNote} 中定义的常量。
* @param value 字段的新值。
*/
public void setCallData(String key, String value) {
mNoteData.setCallData(key, value); // 委托给NoteData对象处理
mNoteData.setCallData(key, value);
}
/**
* 判断便签是否有本地修改
* 通俗说：检查便签的主信息或具体数据是否有修改，用来判断是否需要同步到数据库/GTask
* @return true=有修改，false=无修改
* 检查便签数据是否有未同步的本地修改。
* <p>
* 通过检查 {@link #mNoteDiffValues} 和 {@link #mNoteData} 是否有变更来确定。
* 此状态用于决定是否需要调用 {@link #syncNote} 方法。
*
* @return true 表示有未同步的修改，false 表示数据与数据库一致。
*/
public boolean isLocalModified() {
// 主信息容器有数据 或 具体数据有修改，就表示便签有本地修改
return mNoteDiffValues.size() > 0 || mNoteData.isLocalModified();
}
/**
* 同步便签修改到本地数据库
* 通俗说：把便签的主信息修改和具体数据修改，写入本地数据库，完成本地同步
* @param context 上下文（获取数据库操作工具用）
* @param noteId 要同步的便签ID
* @return true=同步成功，false=同步失败
* 核心方法：将内存中的便签变更原子性地同步到本地数据库。
* <p>
* 执行步骤：
* 1. 验证便签 ID 有效性。
* 2. 如果无本地修改，则直接返回成功。
* 3. 更新便签元数据到 notes 表。
* 4. 通过 {@link NoteData#pushIntoContentResolver} 同步内容数据到 data 表。
* <p>
* 注意：此方法在旧版本中可能被主线程调用，现已通过 {@link ThreadExecutor} 异步执行。
*
* @param context 应用上下文，用于获取 ContentResolver。
* @param noteId 要同步的便签 ID。
* @return true 表示同步成功，false 表示同步失败。
* @throws IllegalArgumentException 如果 noteId ≤ 0。
*/
public boolean syncNote(Context context, long noteId) {
// 1. 校验便签ID是否有效（必须大于0）
if (noteId <= 0) {
throw new IllegalArgumentException("Wrong note id:" + noteId);
}
// 2. 如果没有本地修改，直接返回成功（无需同步）
// 快速检查：如果没有任何修改，则无需执行数据库操作
if (!isLocalModified()) {
return true;
}
/**
* 理论上：只要便签数据有修改，就必须更新“本地修改标记”和“修改时间”
* 为了数据安全：即使便签主信息更新失败，也要尝试更新便签具体数据
*/
// 3. 更新便签主信息到数据库
// 先更新便签元数据（notes 表）
// DB操作：更新便签元数据
if (context.getContentResolver().update(
ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId), // 拼接该便签的数据库访问地址
mNoteDiffValues, // 要更新的主信息数据
ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId),
mNoteDiffValues,
null, null) == 0) {
// 更新返回0表示失败，打印错误日志（理论上不该发生）
// 更新行数为 0 可能是正常情况（如无实际变更），但记录日志以供调试
Log.e(TAG, "Update note error, should not happen");
// 不返回，继续尝试更新具体数据
// 继续执行内容数据同步，不立即返回失败
}
mNoteDiffValues.clear(); // 主信息更新完成（无论成败），清空容器
mNoteDiffValues.clear(); // 清空缓冲区
// 4. 更新便签具体数据到数据库
// 同步便签内容数据（data 表）
if (mNoteData.isLocalModified()
&& (mNoteData.pushIntoContentResolver(context, noteId) == null)) {
// 具体数据有修改 且 更新失败，返回同步失败
// 内容数据同步失败
return false;
}
// 5. 所有修改同步完成，返回成功
return true;
}
/**
* 内部类：便签具体数据管理类
* 通俗说：专门负责管理便签的文本数据和通话记录数据，处理这两类数据的存储和数据库同步
* 内部类：管理便签内容数据的变更和同步。
* <p>
* 负责处理两种类型的便签内容数据：
* 1. 文本便签 ({@link TextNote#CONTENT_ITEM_TYPE})
* 2. 通话记录便签 ({@link CallNote#CONTENT_ITEM_TYPE})
* <p>
* 设计：每个 Note 实例包含一个 NoteData 实例，用于管理该便签的所有内容数据变更。
* 采用"新增或更新"策略：根据数据 ID 是否为零判断是插入新记录还是更新现有记录。
*/
private class NoteData {
// 文本数据ID：对应数据库里文本便签数据的唯一ID
/** 文本内容数据的数据库 ID，0 表示未关联数据库记录 */
private long mTextDataId;
// 文本数据修改容器：存储文本数据的修改字段和值
/** 存储文本内容字段的变更 */
private ContentValues mTextDataValues;
// 通话数据ID：对应数据库里通话便签数据的唯一ID
/** 通话内容数据的数据库 ID，0 表示未关联数据库记录 */
private long mCallDataId;
// 通话数据修改容器：存储通话数据的修改字段和值
/** 存储通话内容字段的变更 */
private ContentValues mCallDataValues;
// 日志标签：打印该内部类的错误日志
/** 日志标签 */
private static final String TAG = "NoteData";
/**
* 构造方法：初始化便签具体数据管理对象
* 构造函数：初始化内容数据缓冲区。
*/
public NoteData() {
mTextDataValues = new ContentValues(); // 初始化文本数据容器
mCallDataValues = new ContentValues(); // 初始化通话数据容器
mTextDataId = 0; // 初始文本数据ID为0（未关联数据库记录）
mCallDataId = 0; // 初始通话数据ID为0（未关联数据库记录）
mTextDataValues = new ContentValues();
mCallDataValues = new ContentValues();
mTextDataId = 0;
mCallDataId = 0;
}
/**
* 判断具体数据是否有本地修改
* 通俗说：检查文本数据或通话数据是否有修改
* @return true=有修改，false=无修改
* 检查内容数据是否有未同步的修改。
*
* @return true 表示有未同步的修改。
*/
boolean isLocalModified() {
// 文本数据容器有数据 或 通话数据容器有数据，就表示有修改
return mTextDataValues.size() > 0 || mCallDataValues.size() > 0;
}
/**
* 设置文本数据ID
* 通俗说：给文本数据绑定数据库记录ID，ID必须大于0
* @param id 文本数据ID
* 设置文本内容数据的数据库 ID。
*
* @param id 文本数据 ID，必须大于 0。
* @throws IllegalArgumentException 如果 id ≤ 0。
*/
void setTextDataId(long id) {
if(id <= 0) {
if (id <= 0) {
throw new IllegalArgumentException("Text data id should larger than 0");
}
mTextDataId = id;
}
/**
* 设置通话数据ID
* 通俗说：给通话数据绑定数据库记录ID，ID必须大于0
* @param id 通话数据ID
* 设置通话内容数据的数据库 ID。
*
* @param id 通话数据 ID，必须大于 0。
* @throws IllegalArgumentException 如果 id ≤ 0。
*/
void setCallDataId(long id) {
if (id <= 0) {
@ -268,120 +306,125 @@ public class Note {
}
/**
* 设置通话数据字段
* 通俗说：存储通话数据的修改字段和值，同时标记便签主信息为“已修改”
* @param key 通话数据字段名（比如CallNote.DATE）
* @param value 通话数据字段值（比如通话时间戳）
* 设置通话内容字段的值。
* <p>
* 此方法会同时标记父便签为已修改（更新 {@link NoteColumns#LOCAL_MODIFIED} 和 {@link NoteColumns#MODIFIED_DATE}）。
*
* @param key 通话字段名，如 {@link CallNote#NUMBER}。
* @param value 字段的新值。
*/
void setCallData(String key, String value) {
mCallDataValues.put(key, value); // 存入通话数据修改
// 同步更新便签主信息的“本地修改标记”和“修改时间”
mCallDataValues.put(key, value);
// 内容变更意味着便签整体被修改
mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
/**
* 设置文本数据字段
* 通俗说：存储文本数据的修改字段和值，同时标记便签主信息为“已修改”
* @param key 文本数据字段名（比如TextNote.CONTENT）
* @param value 文本数据字段值（比如便签正文）
* 设置文本内容字段的值。
* <p>
* 此方法会同时标记父便签为已修改（更新 {@link NoteColumns#LOCAL_MODIFIED} 和 {@link NoteColumns#MODIFIED_DATE}）。
*
* @param key 文本字段名，如 {@link TextNote#CONTENT}。
* @param value 字段的新值。
*/
void setTextData(String key, String value) {
mTextDataValues.put(key, value); // 存入文本数据修改
// 同步更新便签主信息的“本地修改标记”和“修改时间”
mTextDataValues.put(key, value);
// 内容变更意味着便签整体被修改
mNoteDiffValues.put(NoteColumns.LOCAL_MODIFIED, 1);
mNoteDiffValues.put(NoteColumns.MODIFIED_DATE, System.currentTimeMillis());
}
/**
* 将具体数据同步到本地数据库
* 通俗说：把文本数据和通话数据的修改，写入本地数据库（新增或更新数据记录）
* @param context 上下文（获取数据库操作工具用）
* @param noteId 所属便签ID
* @return 同步后的便签URI（null表示同步失败）
* 将内容数据变更同步到数据库的 data 表。
* <p>
* 执行逻辑：
* 1. 如果文本数据有变更且 mTextDataId 为 0，则插入新记录并获取 ID。
* 2. 如果文本数据有变更且 mTextDataId 不为 0，则更新现有记录。
* 3. 对通话数据执行相同的逻辑。
* 4. 使用 {@link ContentProviderOperation} 批量执行更新操作以提高效率。
*
* @param context 应用上下文。
* @param noteId 所属便签的 ID，用于关联数据记录。
* @return 同步成功后返回便签的 URI，失败返回 null。
* @throws IllegalArgumentException 如果 noteId ≤ 0。
*/
Uri pushIntoContentResolver(Context context, long noteId) {
// 1. 校验便签ID是否有效
if (noteId <= 0) {
throw new IllegalArgumentException("Wrong note id:" + noteId);
}
// 2. 准备数据库批量操作指令列表（批量执行更新，效率更高）
ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
ContentProviderOperation.Builder builder = null; // 批量操作指令构建器
ContentProviderOperation.Builder builder = null;
// 3. 处理文本数据同步
if(mTextDataValues.size() > 0) {
mTextDataValues.put(DataColumns.NOTE_ID, noteId); // 绑定所属便签ID
// 1. 处理文本数据
if (mTextDataValues.size() > 0) {
mTextDataValues.put(DataColumns.NOTE_ID, noteId); // 关联所属便签
if (mTextDataId == 0) {
// 文本数据ID为0：表示是新增文本数据，插入到数据库
mTextDataValues.put(DataColumns.MIME_TYPE, TextNote.CONTENT_ITEM_TYPE); // 标记为文本数据类型
// 插入新文本数据记录
mTextDataValues.put(DataColumns.MIME_TYPE, TextNote.CONTENT_ITEM_TYPE);
// DB操作：插入文本数据
Uri uri = context.getContentResolver().insert(Notes.CONTENT_DATA_URI, mTextDataValues);
try {
// 解析插入后返回的ID，绑定到文本数据
// 从返回的 URI 中解析出数据 ID
setTextDataId(Long.valueOf(uri.getPathSegments().get(1)));
} catch (NumberFormatException e) {
// 插入失败，打印日志并清空数据容器
Log.e(TAG, "Insert new text data fail with noteId" + noteId);
mTextDataValues.clear();
return null;
}
} else {
// 文本数据ID不为0：表示是更新已有文本数据，添加批量更新指令
// 更新现有文本数据记录
builder = ContentProviderOperation.newUpdate(ContentUris.withAppendedId(
Notes.CONTENT_DATA_URI, mTextDataId)); // 拼接文本数据的数据库地址
builder.withValues(mTextDataValues); // 设置要更新的数据
operationList.add(builder.build()); // 添加到批量操作列表
Notes.CONTENT_DATA_URI, mTextDataId));
builder.withValues(mTextDataValues);
operationList.add(builder.build());
}
mTextDataValues.clear(); // 文本数据处理完成，清空容器
mTextDataValues.clear(); // 清空缓冲区
}
// 4. 处理通话数据同步（逻辑和文本数据一致）
if(mCallDataValues.size() > 0) {
mCallDataValues.put(DataColumns.NOTE_ID, noteId); // 绑定所属便签ID
// 2. 处理通话数据（逻辑与文本数据类似）
if (mCallDataValues.size() > 0) {
mCallDataValues.put(DataColumns.NOTE_ID, noteId);
if (mCallDataId == 0) {
// 通话数据ID为0：新增通话数据，插入到数据库
mCallDataValues.put(DataColumns.MIME_TYPE, CallNote.CONTENT_ITEM_TYPE); // 标记为通话数据类型
// 插入新通话数据记录
mCallDataValues.put(DataColumns.MIME_TYPE, CallNote.CONTENT_ITEM_TYPE);
// DB操作：插入通话数据
Uri uri = context.getContentResolver().insert(Notes.CONTENT_DATA_URI, mCallDataValues);
try {
// 解析插入后返回的ID，绑定到通话数据
setCallDataId(Long.valueOf(uri.getPathSegments().get(1)));
} catch (NumberFormatException e) {
// 插入失败，打印日志并清空数据容器
Log.e(TAG, "Insert new call data fail with noteId" + noteId);
mCallDataValues.clear();
return null;
}
} else {
// 通话数据ID不为0：更新已有通话数据，添加批量更新指令
// 更新现有通话数据记录
builder = ContentProviderOperation.newUpdate(ContentUris.withAppendedId(
Notes.CONTENT_DATA_URI, mCallDataId)); // 拼接通话数据的数据库地址
builder.withValues(mCallDataValues); // 设置要更新的数据
operationList.add(builder.build()); // 添加到批量操作列表
Notes.CONTENT_DATA_URI, mCallDataId));
builder.withValues(mCallDataValues);
operationList.add(builder.build());
}
mCallDataValues.clear(); // 通话数据处理完成，清空容器
mCallDataValues.clear(); // 清空缓冲区
}
// 5. 执行批量更新操作（如果有更新指令）
// 3. 批量执行更新操作（如果有）
if (operationList.size() > 0) {
try {
// 批量执行数据库操作
// DB操作：批量执行更新
ContentProviderResult[] results = context.getContentResolver().applyBatch(
Notes.AUTHORITY, operationList);
// 判断操作结果是否有效，返回便签的数据库地址
// 验证操作结果
return (results == null || results.length == 0 || results[0] == null) ? null
: ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId);
} catch (RemoteException e) {
// 跨进程访问失败，打印日志并返回null
Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
return null;
} catch (OperationApplicationException e) {
// 批量操作执行失败，打印日志并返回null
Log.e(TAG, String.format("%s: %s", e.toString(), e.getMessage()));
return null;
}
}
// 没有批量更新指令，返回null（表示无需更新或更新完成）
return null;
}
}

556
src/Notes-master/src/net/micode/notes/model/WorkingNote.java
Unescape View File

@ -16,131 +16,173 @@
package net.micode.notes.model;
import android.appwidget.AppWidgetManager; // 桌面小组件管理类：用于判断小组件ID是否有效
import android.content.ContentUris; // URI拼接工具：拼接便签的数据库访问地址
import android.content.Context; // 上下文：获取数据库操作工具和资源
import android.database.Cursor; // 数据库查询结果游标：存储数据库查询返回的结果集
import android.text.TextUtils; // 文本工具类：判断字符串是否为空/空白
import android.util.Log; // 日志工具：打印错误/调试信息
import net.micode.notes.data.Notes; // 便签常量类：存储便签类型、文件夹ID等固定值
import net.micode.notes.data.Notes.CallNote; // 通话便签常量：存储通话便签的字段名
import net.micode.notes.data.Notes.DataColumns; // 便签数据表字段：数据表的列名
import net.micode.notes.data.Notes.DataConstants; // 便签数据类型常量：区分文本/通话便签
import net.micode.notes.data.Notes.NoteColumns; // 便签主表字段：主表的列名
import net.micode.notes.data.Notes.TextNote; // 文本便签常量：存储文本便签的字段名
import net.micode.notes.tool.ResourceParser.NoteBgResources; // 便签背景资源工具：根据颜色ID获取背景资源
import android.appwidget.AppWidgetManager;
import android.content.ContentUris;
import android.content.Context;
import android.database.Cursor;
import android.text.TextUtils;
import android.util.Log;
import net.micode.notes.data.Notes;
import net.micode.notes.data.Notes.CallNote;
import net.micode.notes.data.Notes.DataColumns;
import net.micode.notes.data.Notes.DataConstants;
import net.micode.notes.data.Notes.NoteColumns;
import net.micode.notes.data.Notes.TextNote;
import net.micode.notes.tool.ResourceParser.NoteBgResources;
/**
* 工作便签封装类
* 通俗说：这个类是便签的“前台操作管家”，封装了便签的所有属性（内容、提醒时间、背景色等）
* 还负责加载已有便签、创建新便签、保存便签修改，以及通知界面便签设置的变化（比如背景色改变）
* 工作便签类 - MVC 架构中的混合控制器与视图模型 (Hybrid Controller & ViewModel)
* <p>
* 核心职责：作为便签编辑与展示的核心业务逻辑承载者，协调 UI 层 ({@link net.micode.notes.ui.NoteEditActivity})
* 与数据层 ({@link Note}) 的交互。管理单个便签的完整生命周期和运行时状态。
* <p>
* 架构角色解析：
* 1. **ViewModel**: 持有便签的所有展示相关状态（内容、背景色、提醒时间、模式等），提供 UI 数据绑定。
* 2. **Controller**: 接收 UI 层操作指令（如保存、删除、设置提醒），执行业务逻辑，并同步数据变更到底层 Model。
* <p>
* 关键设计：
* - **状态封装**: 将便签的 UI 状态（如背景色、模式）与持久化状态（数据库 ID）统一管理。
* - **监听器模式**: 通过 {@link NoteSettingChangedListener} 通知 UI 层状态变更，实现双向数据流。
* - **懒加载**: 通过 {@link #loadNote()} 和 {@link #loadNoteData()} 分离加载主数据与内容数据。
* <p>
* 【2025 重构相关性】：
* - 本类是 {@link ThreadExecutor} 异步保存机制的核心调用者之一。
* - 可能间接集成 AI 能力，如通过便签背景色 ({@link NoteColumns#BG_COLOR_ID}) 体现 AI 分类结果。
*/
public class WorkingNote {
// 关联的Note数据对象：负责和本地数据库交互（存储/同步便签数据）
/** 底层数据模型对象，负责与数据库的直接交互 */
private Note mNote;
// 便签唯一ID：对应数据库里的便签ID（0表示新便签，未存入数据库）
/** 便签在数据库中的唯一标识，0 表示新便签（未持久化） */
private long mNoteId;
// 便签内容：文本便签的正文文字
/** 便签的文本内容（正文） */
private String mContent;
// 便签模式：区分普通文本模式和清单模式（比如0=普通模式，1=清单模式）
/** 便签模式：0-普通文本模式，1-清单（Checklist）模式 */
private int mMode;
// 提醒时间戳：便签的提醒日期（0表示无提醒）
/** 提醒时间戳（毫秒），0 表示未设置提醒 */
private long mAlertDate;
// 修改时间戳：便签最后一次修改的时间
/** 最后修改时间戳（毫秒） */
private long mModifiedDate;
// 背景颜色ID：便签的背景色标识（对应不同的背景样式）
/** 便签背景颜色标识符，对应 {@link NoteBgResources} 中的定义 */
private int mBgColorId;
// 桌面小组件ID：关联的桌面便签小组件ID（无效时为INVALID_APPWIDGET_ID）
/** 关联的桌面小部件 ID，{@link AppWidgetManager#INVALID_APPWIDGET_ID} 表示无关联 */
private int mWidgetId;
// 桌面小组件类型：关联的桌面小组件类型（无效时为TYPE_WIDGET_INVALIDE）
/** 关联的桌面小部件类型，{@link Notes#TYPE_WIDGET_INVALIDE} 表示无效类型 */
private int mWidgetType;
// 所属文件夹ID：便签所在的文件夹ID（比如通话记录文件夹、自定义文件夹）
/** 所属文件夹的数据库 ID */
private long mFolderId;
// 上下文：用于获取数据库工具、资源等
/** 应用上下文，用于资源访问和 ContentResolver */
private Context mContext;
// 日志标签：打印该类的日志，方便排查问题
/** 日志标签 */
private static final String TAG = "WorkingNote";
// 删除标记：是否标记为已删除（true=已删除，无需保存）
/** 软删除标记，为 true 时表示便签已标记为删除（但可能尚未从数据库物理删除） */
private boolean mIsDeleted;
// 便签设置变化监听器：用于通知界面便签设置的改变（比如背景色、提醒时间变化）
/** 便签设置变更监听器，用于通知 UI 层更新 */
private NoteSettingChangedListener mNoteSettingStatusListener;
// 便签数据表查询投影：查询便签数据时，要获取的字段列表（相当于查询结果的列清单）
/**
* 便签内容数据表（data表）查询投影（列定义）
* <p>
* 用于从 {@link Notes#CONTENT_DATA_URI} 查询便签的具体内容数据。
*/
public static final String[] DATA_PROJECTION = new String[] {
DataColumns.ID, // 0: 数据记录ID
DataColumns.CONTENT, // 1: 数据内容（文本便签的正文）
DataColumns.MIME_TYPE, // 2: 数据类型（文本/通话便签）
DataColumns.ID, // 0: 数据记录主键 ID
DataColumns.CONTENT, // 1: 数据内容（文本正文）
DataColumns.MIME_TYPE, // 2: MIME 类型，区分文本便签或通话便签
DataColumns.DATA1, // 3: 扩展字段1（存储便签模式）
DataColumns.DATA2, // 4: 扩展字段2
DataColumns.DATA3, // 5: 扩展字段3
DataColumns.DATA4, // 6: 扩展字段4
};
// 便签主表查询投影：查询便签主信息时，要获取的字段列表
/**
* 便签主表（notes表）查询投影（列定义）
* <p>
* 用于从 {@link Notes#CONTENT_NOTE_URI} 查询便签的元数据。
*/
public static final String[] NOTE_PROJECTION = new String[] {
NoteColumns.PARENT_ID, // 0: 所属文件夹ID
NoteColumns.ALERTED_DATE,// 1: 提醒时间
NoteColumns.BG_COLOR_ID, // 2: 背景颜色ID
NoteColumns.WIDGET_ID, // 3: 桌面小组件ID
NoteColumns.WIDGET_TYPE, // 4: 桌面小组件类型
NoteColumns.MODIFIED_DATE// 5: 修改时间
NoteColumns.PARENT_ID, // 0: 父文件夹 ID
NoteColumns.ALERTED_DATE,// 1: 提醒时间戳
NoteColumns.BG_COLOR_ID, // 2: 背景颜色 ID
NoteColumns.WIDGET_ID, // 3: 关联小部件 ID
NoteColumns.WIDGET_TYPE, // 4: 关联小部件类型
NoteColumns.MODIFIED_DATE// 5: 最后修改时间戳
};
// 数据表查询结果的列索引：对应DATA_PROJECTION的字段位置，方便快速取值
private static final int DATA_ID_COLUMN = 0; // 数据记录ID的索引
private static final int DATA_CONTENT_COLUMN = 1; // 数据内容的索引
private static final int DATA_MIME_TYPE_COLUMN = 2; // 数据类型的索引
private static final int DATA_MODE_COLUMN = 3; // 便签模式的索引
// 主表查询结果的列索引：对应NOTE_PROJECTION的字段位置，方便快速取值
private static final int NOTE_PARENT_ID_COLUMN = 0; // 所属文件夹ID的索引
private static final int NOTE_ALERTED_DATE_COLUMN = 1; // 提醒时间的索引
private static final int NOTE_BG_COLOR_ID_COLUMN = 2; // 背景颜色ID的索引
private static final int NOTE_WIDGET_ID_COLUMN = 3; // 桌面小组件ID的索引
private static final int NOTE_WIDGET_TYPE_COLUMN = 4; // 桌面小组件类型的索引
private static final int NOTE_MODIFIED_DATE_COLUMN = 5; // 修改时间的索引
// 私有构造方法：创建新便签（未存入数据库）
// 通俗说：初始化一个空白便签，设置默认属性
/** DATA_PROJECTION 中数据记录 ID 的列索引 */
private static final int DATA_ID_COLUMN = 0;
/** DATA_PROJECTION 中数据内容的列索引 */
private static final int DATA_CONTENT_COLUMN = 1;
/** DATA_PROJECTION 中 MIME 类型的列索引 */
private static final int DATA_MIME_TYPE_COLUMN = 2;
/** DATA_PROJECTION 中便签模式（存储在 DATA1）的列索引 */
private static final int DATA_MODE_COLUMN = 3;
/** NOTE_PROJECTION 中父文件夹 ID 的列索引 */
private static final int NOTE_PARENT_ID_COLUMN = 0;
/** NOTE_PROJECTION 中提醒时间的列索引 */
private static final int NOTE_ALERTED_DATE_COLUMN = 1;
/** NOTE_PROJECTION 中背景颜色 ID 的列索引 */
private static final int NOTE_BG_COLOR_ID_COLUMN = 2;
/** NOTE_PROJECTION 中关联小部件 ID 的列索引 */
private static final int NOTE_WIDGET_ID_COLUMN = 3;
/** NOTE_PROJECTION 中关联小部件类型的列索引 */
private static final int NOTE_WIDGET_TYPE_COLUMN = 4;
/** NOTE_PROJECTION 中最后修改时间的列索引 */
private static final int NOTE_MODIFIED_DATE_COLUMN = 5;
/**
* 私有构造函数：创建新的空白便签（尚未持久化）。
*
* @param context 应用上下文。
* @param folderId 新便签所属的文件夹 ID。
*/
private WorkingNote(Context context, long folderId) {
mContext = context;
mAlertDate = 0; // 默认无提醒
mModifiedDate = System.currentTimeMillis(); // 默认修改时间为当前时间
mFolderId = folderId; // 设置所属文件夹ID
mNote = new Note(); // 创建关联的Note数据对象
mNoteId = 0; // 新便签ID为0（未存入数据库）
mIsDeleted = false; // 默认未删除
mModifiedDate = System.currentTimeMillis();
mFolderId = folderId;
mNote = new Note(); // 初始化底层数据模型
mNoteId = 0; // 标记为新便签
mIsDeleted = false;
mMode = 0; // 默认普通文本模式
mWidgetType = Notes.TYPE_WIDGET_INVALIDE; // 默认无有效桌面小组件
mWidgetType = Notes.TYPE_WIDGET_INVALIDE; // 默认无有效小部件
}
// 私有构造方法：加载已有便签（从数据库读取）
// 通俗说：根据便签ID，从数据库加载已有便签的所有信息
/**
* 私有构造函数：从数据库加载已存在的便签。
*
* @param context 应用上下文。
* @param noteId 要加载的便签 ID。
* @param folderId （冗余参数）所属文件夹 ID，实际会从数据库重新加载。
*/
private WorkingNote(Context context, long noteId, long folderId) {
mContext = context;
mNoteId = noteId; // 设置已有便签的ID
mFolderId = folderId; // 设置所属文件夹ID
mIsDeleted = false; // 默认未删除
mNote = new Note(); // 创建关联的Note数据对象
loadNote(); // 加载便签主信息
mNoteId = noteId;
mFolderId = folderId;
mIsDeleted = false;
mNote = new Note(); // 初始化底层数据模型
loadNote(); // 从数据库加载便签数据
}
/**
* 加载便签主信息（从数据库主表读取）
* 通俗说：根据便签ID，从数据库便签主表中读取文件夹ID、背景色、提醒时间等主信息
* 从数据库加载便签的元数据（notes 表）。
* <p>
* 加载便签的文件夹、背景色、小部件信息、提醒时间等核心属性。
* 此方法在构造函数中调用，用于初始化一个已存在便签的运行时状态。
*
* @throws IllegalArgumentException 如果数据库中找不到指定 ID 的便签。
*/
private void loadNote() {
// 拼接该便签的数据库访问地址，查询主表信息
// DB操作：查询指定便签的元数据
Cursor cursor = mContext.getContentResolver().query(
ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, mNoteId),
NOTE_PROJECTION, // 要查询的字段列表
NOTE_PROJECTION,
null, null, null);
if (cursor != null) {
// 如果查询到结果，移动到第一条记录
if (cursor.moveToFirst()) {
// 从查询结果中读取各字段值，赋值给成员变量
// 从 Cursor 中读取各字段值，更新成员变量
mFolderId = cursor.getLong(NOTE_PARENT_ID_COLUMN);
mBgColorId = cursor.getInt(NOTE_BG_COLOR_ID_COLUMN);
mWidgetId = cursor.getInt(NOTE_WIDGET_ID_COLUMN);
@ -148,134 +190,148 @@ public class WorkingNote {
mAlertDate = cursor.getLong(NOTE_ALERTED_DATE_COLUMN);
mModifiedDate = cursor.getLong(NOTE_MODIFIED_DATE_COLUMN);
}
cursor.close(); // 关闭游标，释放资源
cursor.close();
} else {
// 未查询到便签，打印错误日志并抛出异常
Log.e(TAG, "No note with id:" + mNoteId);
throw new IllegalArgumentException("Unable to find note with id " + mNoteId);
}
loadNoteData(); // 主信息加载完成后，加载便签具体数据
loadNoteData(); // 继续加载便签的具体内容数据
}
/**
* 加载便签具体数据（从数据库数据表读取）
* 通俗说：根据便签ID，从数据库便签数据表中读取文本内容、便签模式等具体数据
* 从数据库加载便签的具体内容数据（data 表）。
* <p>
* 一个便签可能关联多条数据记录（如文本内容和通话记录）。此方法遍历所有关联的数据记录，
* 根据 MIME 类型区分处理，并初始化对应的 {@link Note} 数据模型。
*
* @throws IllegalArgumentException 如果找不到便签对应的任何数据记录。
*/
private void loadNoteData() {
// 查询该便签对应的所有数据记录（条件：NOTE_ID等于当前便签ID）
// DB操作：查询便签关联的所有数据记录
Cursor cursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI,
DATA_PROJECTION,
DataColumns.NOTE_ID + "=?", // 查询条件
new String[] { String.valueOf(mNoteId) }, // 条件参数
DataColumns.NOTE_ID + "=?",
new String[] { String.valueOf(mNoteId) },
null);
if (cursor != null) {
// 如果查询到结果，移动到第一条记录
if (cursor.moveToFirst()) {
// 循环遍历所有数据记录（一个便签可能对应多条数据，比如文本+通话记录）
do {
String type = cursor.getString(DATA_MIME_TYPE_COLUMN); // 获取数据类型
String type = cursor.getString(DATA_MIME_TYPE_COLUMN);
if (DataConstants.NOTE.equals(type)) {
// 文本便签：读取内容、模式，并绑定数据ID
// 文本便签数据：加载内容和模式
mContent = cursor.getString(DATA_CONTENT_COLUMN);
mMode = cursor.getInt(DATA_MODE_COLUMN);
mNote.setTextDataId(cursor.getLong(DATA_ID_COLUMN));
} else if (DataConstants.CALL_NOTE.equals(type)) {
// 通话便签：绑定通话数据ID
// 通话便签数据：记录数据 ID
mNote.setCallDataId(cursor.getLong(DATA_ID_COLUMN));
} else {
// 未知数据类型，打印调试日志
Log.d(TAG, "Wrong note type with type:" + type);
}
} while (cursor.moveToNext()); // 移动到下一条记录，继续遍历
} while (cursor.moveToNext());
}
cursor.close(); // 关闭游标，释放资源
cursor.close();
} else {
// 未查询到便签数据，打印错误日志并抛出异常
Log.e(TAG, "No data with id:" + mNoteId);
throw new IllegalArgumentException("Unable to find note's data with id " + mNoteId);
}
}
/**
* 静态方法：创建空白便签（带默认配置）
* 通俗说：外部调用该方法，创建一个指定文件夹、小组件配置和默认背景色的空白便签
* @param context 上下文
* @param folderId 所属文件夹ID
* @param widgetId 桌面小组件ID
* @param widgetType 桌面小组件类型
* @param defaultBgColorId 默认背景颜色ID
* @return 初始化完成的空白WorkingNote对象
* 创建并返回一个新的空白便签实例，附带初始配置。
* <p>
* 工厂方法，用于 UI 层创建新便签。注意：此时便签尚未保存到数据库。
*
* @param context 应用上下文。
* @param folderId 便签所属文件夹 ID。
* @param widgetId 关联的桌面小部件 ID（可能来自小部件创建意图）。
* @param widgetType 关联的桌面小部件类型。
* @param defaultBgColorId 默认背景颜色 ID。
* @return 一个配置好的空白便签实例。
*/
public static WorkingNote createEmptyNote(Context context, long folderId, int widgetId,
int widgetType, int defaultBgColorId) {
WorkingNote note = new WorkingNote(context, folderId); // 创建空白便签
note.setBgColorId(defaultBgColorId); // 设置默认背景色
note.setWidgetId(widgetId); // 设置桌面小组件ID
note.setWidgetType(widgetType); // 设置桌面小组件类型
WorkingNote note = new WorkingNote(context, folderId);
note.setBgColorId(defaultBgColorId);
note.setWidgetId(widgetId);
note.setWidgetType(widgetType);
return note;
}
/**
* 静态方法：加载已有便签
* 通俗说：外部调用该方法，根据便签ID加载数据库中的已有便签
* @param context 上下文
* @param id 便签ID
* @return 加载完成的WorkingNote对象
* 加载指定 ID 的已存在便签。
* <p>
* 工厂方法，用于 UI 层编辑已保存的便签。
*
* @param context 应用上下文。
* @param id 要加载的便签 ID。
* @return 加载完成的便签实例。
*/
public static WorkingNote load(Context context, long id) {
return new WorkingNote(context, id, 0);
}
/**
* 保存便签到数据库
* 通俗说：判断便签是否值得保存，若值得则新建/更新数据库记录，并通知小组件更新
* @return true=保存成功，false=保存失败/无需保存
* 核心业务方法：保存便签到数据库。
* <p>
* 执行流程：
* 1. 检查便签是否"值得保存"（{@link #isWorthSaving()}）。
* 2. 如果是新便签（未持久化），先在数据库创建记录并获取 ID。
* 3. 调用底层 {@link Note#syncNote(Context, long)} 将内存变更同步到数据库。
* 4. 如果关联了有效小部件，通知监听器更新小部件。
* <p>
* 【2025 异步重构上下文】：
* 在旧版本中，此方法可能直接在 UI 线程调用 {@link Note#syncNote} 执行数据库 IO。
* 重构后，调用此方法的代码（如 {@link net.micode.notes.ui.NoteEditActivity#onPause}）
* 应已将整个保存逻辑封装为 Runnable 并通过 {@link ThreadExecutor} 异步执行。
*
* @return true 表示保存任务成功提交/执行；false 表示保存失败或无需保存。
*/
public synchronized boolean saveNote() {
// 先判断是否值得保存（已删除、空白新便签、无修改的旧便签都无需保存）
if (isWorthSaving()) {
// 如果是新便签（未存入数据库），先生成新便签ID
if (!existInDatabase()) {
// 新便签：先在数据库创建记录以获取有效 ID
mNoteId = Note.getNewNoteId(mContext, mFolderId);
if (mNoteId == 0) {
// 生成新ID失败，打印错误日志并返回失败
Log.e(TAG, "Create new note fail with id:" + mNoteId);
return false;
}
}
// 调用Note对象的同步方法，将修改写入数据库
// DB操作：将内存中的变更同步到数据库（通过 Note 对象）
mNote.syncNote(mContext, mNoteId);
/**
* 如果该便签关联了有效桌面小组件，且设置了监听器，通知小组件更新内容
*/
// 如果关联了有效小部件，通知 UI 层更新小部件显示
if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
&& mWidgetType != Notes.TYPE_WIDGET_INVALIDE
&& mNoteSettingStatusListener != null) {
mNoteSettingStatusListener.onWidgetChanged();
}
return true; // 保存成功
return true;
} else {
return false; // 无需保存
return false;
}
}
/**
* 判断便签是否已存入数据库
* 通俗说：通过便签ID是否大于0，判断是否是已存在的便签
* @return true=已存入数据库，false=新便签（未存入）
* 检查便签是否已在数据库中存在（已持久化）。
*
* @return true 表示已存在数据库（mNoteId > 0）。
*/
public boolean existInDatabase() {
return mNoteId > 0;
}
/**
* 判断便签是否值得保存
* 通俗说：满足以下条件之一则无需保存：
* 1. 已标记为删除；2. 新便签且内容为空；3. 旧便签且无任何本地修改
* @return true=值得保存，false=无需保存
* 判断当前便签状态是否"值得保存"。
* <p>
* 以下情况不需要保存：
* 1. 便签已被标记为删除（软删除）。
* 2. 是新便签（未持久化）且内容为空。
* 3. 是已存在便签但没有任何本地修改（底层 {@link Note#isLocalModified()} 返回 false）。
*
* @return true 表示需要保存，false 表示无需保存。
*/
private boolean isWorthSaving() {
if (mIsDeleted || (!existInDatabase() && TextUtils.isEmpty(mContent))
@ -287,40 +343,49 @@ public class WorkingNote {
}
/**
* 设置便签设置变化监听器
* 通俗说：给当前便签绑定监听器，以便便签设置变化时通知界面更新
* @param l 监听器对象
* 设置便签设置变更监听器。
* <p>
* UI 层（如 {@link net.micode.notes.ui.NoteEditActivity}）通过此方法注册监听，
* 以便在便签属性（背景色、提醒、模式等）变更时更新界面。
*
* @param l 监听器实例。
*/
public void setOnSettingStatusChangedListener(NoteSettingChangedListener l) {
mNoteSettingStatusListener = l;
}
/**
* 设置便签提醒时间
* 通俗说：修改便签的提醒时间，并通知监听器提醒时间已变化
* @param date 新的提醒时间戳
* @param set 是否设置提醒（true=设置，false=取消）
* 设置或取消便签的提醒时间。
* <p>
* 此方法会更新内存状态，并将变更记录到底层 {@link Note} 模型中。
* 同时，通过监听器通知 UI 层提醒状态变化。
*
* @param date 新的提醒时间戳（毫秒），设为 0 表示取消提醒。
* @param set 操作类型：true 表示设置提醒，false 表示取消提醒（用于 UI 反馈）。
*/
public void setAlertDate(long date, boolean set) {
if (date != mAlertDate) {
mAlertDate = date; // 更新提醒时间
// 将提醒时间存入Note对象，准备同步到数据库
mAlertDate = date;
// 记录变更到底层数据模型
mNote.setNoteValue(NoteColumns.ALERTED_DATE, String.valueOf(mAlertDate));
}
// 如果设置了监听器，通知提醒时间变化
// 通知 UI 层提醒状态变化
if (mNoteSettingStatusListener != null) {
mNoteSettingStatusListener.onClockAlertChanged(date, set);
}
}
/**
* 标记便签为已删除/未删除
* 通俗说：设置便签的删除标记，若关联了桌面小组件，通知小组件更新
* @param mark true=标记为已删除，false=取消删除标记
* 标记或取消标记便签为删除状态。
* <p>
* 此方法仅设置软删除标记，实际的数据库删除操作可能在同步流程或其他地方处理。
* 如果便签关联了小部件，会通知小部件更新。
*
* @param mark true 表示标记为删除，false 表示取消删除标记。
*/
public void markDeleted(boolean mark) {
mIsDeleted = mark; // 更新删除标记
// 如果关联了有效桌面小组件且设置了监听器，通知小组件变化
mIsDeleted = mark;
// 如果关联了小部件，通知 UI 层更新小部件（如隐藏或显示删除状态）
if (mWidgetId != AppWidgetManager.INVALID_APPWIDGET_ID
&& mWidgetType != Notes.TYPE_WIDGET_INVALIDE && mNoteSettingStatusListener != null) {
mNoteSettingStatusListener.onWidgetChanged();
@ -328,142 +393,223 @@ public class WorkingNote {
}
/**
* 设置便签背景颜色ID
* 通俗说：修改便签的背景色，通知监听器背景色已变化，并准备同步到数据库
* @param id 新的背景颜色ID
* 设置便签的背景颜色 ID。
* <p>
* 此方法会更新内存状态，通过监听器通知 UI 层，并记录变更到底层模型。
* <p>
* 【AI 智能分类相关性】：
* 背景颜色 ID 可能与 AI 分类结果关联（如通过 {@link net.micode.notes.ai.AIService}）。
* 设置背景色时，UI 层可能会根据新的颜色 ID 更新便签的视觉主题。
*
* @param id 新的背景颜色 ID（参见 {@link NoteBgResources}）。
*/
public void setBgColorId(int id) {
if (id != mBgColorId) {
mBgColorId = id; // 更新背景颜色ID
// 如果设置了监听器，通知背景色变化
mBgColorId = id;
// 通知 UI 层背景色变化
if (mNoteSettingStatusListener != null) {
mNoteSettingStatusListener.onBackgroundColorChanged();
}
// 将背景颜色ID存入Note对象，准备同步到数据库
// 记录变更到底层数据模型
mNote.setNoteValue(NoteColumns.BG_COLOR_ID, String.valueOf(id));
}
}
/**
* 设置便签模式（普通/清单）
* 通俗说：切换便签的显示模式，通知监听器模式变化，并准备同步到数据库
* @param mode 新的便签模式（0=普通，1=清单等）
* 切换便签的显示模式（普通文本模式 ↔ 清单模式）。
* <p>
* 清单模式通常用于待办事项，具有不同的 UI 渲染逻辑（如复选框）。
* 此方法会通过监听器通知 UI 层模式变化，以便动态调整编辑界面。
*
* @param mode 新的模式：0-普通文本模式，1-清单模式。
*/
public void setCheckListMode(int mode) {
if (mMode != mode) {
// 如果设置了监听器，通知模式变化（传入旧模式和新模式）
// 通知 UI 层模式变化（传递新旧模式以便过渡处理）
if (mNoteSettingStatusListener != null) {
mNoteSettingStatusListener.onCheckListModeChanged(mMode, mode);
}
mMode = mode; // 更新便签模式
// 将便签模式存入Note对象，准备同步到数据库
mMode = mode;
// 记录变更到底层数据模型（存储到文本数据的扩展字段 DATA1）
mNote.setTextData(TextNote.MODE, String.valueOf(mMode));
}
}
/**
* 设置桌面小组件类型
* 通俗说：修改便签关联的桌面小组件类型，并准备同步到数据库
* @param type 新的小组件类型
* 设置便签关联的桌面小部件类型。
* <p>
* 此信息用于标识便签是通过哪种类型的小部件创建或关联的。
*
* @param type 小部件类型，参见 {@link Notes} 中的 TYPE_WIDGET_* 常量。
*/
public void setWidgetType(int type) {
if (type != mWidgetType) {
mWidgetType = type; // 更新小组件类型
// 将小组件类型存入Note对象，准备同步到数据库
mWidgetType = type;
mNote.setNoteValue(NoteColumns.WIDGET_TYPE, String.valueOf(mWidgetType));
}
}
/**
* 设置桌面小组件ID
* 通俗说：修改便签关联的桌面小组件ID，并准备同步到数据库
* @param id 新的小组件ID
* 设置便签关联的桌面小部件 ID。
* <p>
* 当便签从小部件创建或与小部件绑定时设置此 ID，用于后续更新对应小部件的内容。
*
* @param id 小部件 ID，来自 {@link AppWidgetManager}。
*/
public void setWidgetId(int id) {
if (id != mWidgetId) {
mWidgetId = id; // 更新小组件ID
// 将小组件ID存入Note对象，准备同步到数据库
mWidgetId = id;
mNote.setNoteValue(NoteColumns.WIDGET_ID, String.valueOf(mWidgetId));
}
}
/**
* 设置便签文本内容
* 通俗说：修改便签的正文内容，只有内容变化时才更新，并准备同步到数据库
* @param text 新的便签内容
* 设置便签的文本内容。
* <p>
* 此方法是便签编辑的核心，负责更新内存中的内容，并记录变更到底层模型。
* 内容比较使用 {@link TextUtils#equals} 以避免不必要的更新。
* <p>
* 【AI 能力集成点】：
* 在文本内容设置后，可触发 AI 相关处理（如自动分类、润色建议），
* 但本方法目前仅负责数据记录，AI 集成可能在调用链的更高层。
*
* @param text 新的便签文本内容。
*/
public void setWorkingText(String text) {
if (!TextUtils.equals(mContent, text)) {
mContent = text; // 更新便签内容
// 将新内容存入Note对象，准备同步到数据库
mContent = text;
// 记录变更到底层数据模型
mNote.setTextData(DataColumns.CONTENT, mContent);
}
}
/**
* 转换为通话便签
* 通俗说：将当前便签设置为通话便签，存入通话号码和通话时间，并指定到通话记录文件夹
* @param phoneNumber 通话号码
* @param callDate 通话时间戳
* 将当前便签转换为通话记录便签。
* <p>
* 此方法用于处理来自系统通话记录的应用场景，将普通便签转换为特殊的通话便签类型。
* 转换包括设置通话相关数据（号码、时间）并将便签移动到专用的通话记录文件夹。
*
* @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));
}
/**
* 判断是否设置了提醒
* 通俗说：通过提醒时间戳是否大于0，判断便签是否有有效提醒
* @return true=有提醒，false=无提醒
* 检查便签是否设置了提醒。
*
* @return true 表示提醒时间已设置（>0），false 表示未设置。
*/
public boolean hasClockAlert() {
return (mAlertDate > 0 ? true : false);
}
// 以下都是属性获取方法：返回对应的便签属性值，供外部界面使用
public String getContent() { return mContent; }
public long getAlertDate() { return mAlertDate; }
public long getModifiedDate() { return mModifiedDate; }
public int getBgColorResId() { return NoteBgResources.getNoteBgResource(mBgColorId); }
public int getBgColorId() { return mBgColorId; }
public int getTitleBgResId() { return NoteBgResources.getNoteTitleBgResource(mBgColorId); }
public int getCheckListMode() { return mMode; }
public long getNoteId() { return mNoteId; }
public long getFolderId() { return mFolderId; }
public int getWidgetId() { return mWidgetId; }
public int getWidgetType() { return mWidgetType; }
/** 获取便签的文本内容 */
public String getContent() {
return mContent;
}
/** 获取便签的提醒时间戳 */
public long getAlertDate() {
return mAlertDate;
}
/** 获取便签的最后修改时间戳 */
public long getModifiedDate() {
return mModifiedDate;
}
/**
* 获取便签背景颜色对应的可绘制资源 ID。
* <p>
* 用于 UI 层直接设置背景。
*
* @return 背景颜色资源 ID。
*/
public int getBgColorResId() {
return NoteBgResources.getNoteBgResource(mBgColorId);
}
/** 获取便签背景颜色 ID（逻辑标识符） */
public int getBgColorId() {
return mBgColorId;
}
/**
* 获取便签标题栏背景颜色对应的可绘制资源 ID。
* <p>
* 标题栏背景可能与便签主体背景不同，用于视觉分层。
*
* @return 标题栏背景颜色资源 ID。
*/
public int getTitleBgResId() {
return NoteBgResources.getNoteTitleBgResource(mBgColorId);
}
/** 获取便签当前模式（0=普通文本，1=清单模式） */
public int getCheckListMode() {
return mMode;
}
/** 获取便签的数据库 ID（为 0 表示新便签） */
public long getNoteId() {
return mNoteId;
}
/** 获取便签所属文件夹的数据库 ID */
public long getFolderId() {
return mFolderId;
}
/** 获取关联的桌面小部件 ID */
public int getWidgetId() {
return mWidgetId;
}
/** 获取关联的桌面小部件类型 */
public int getWidgetType() {
return mWidgetType;
}
/**
* 便签设置变化监听器接口
* 通俗说：定义了便签设置变化时的回调方法，让界面能感知到变化并更新UI
* 便签设置变更监听器接口。
* <p>
* 定义了一系列回调方法，允许 UI 层监听便签关键属性的变化并实时响应。
* 这是实现 UI 与业务逻辑解耦的关键机制。
*/
public interface NoteSettingChangedListener {
/**
* 便签背景色变化时的回调
* 通俗说：当便签背景色修改后，会调用该方法，界面可在此更新背景样式
* 当便签背景颜色发生变化时调用。
* <p>
* UI 层应在此回调中更新便签的背景视觉。
*/
void onBackgroundColorChanged();
/**
* 便签提醒时间变化时的回调
* 通俗说：当设置/取消便签提醒后，会调用该方法，界面可在此更新提醒相关UI
* 当便签的提醒时间被设置或取消时调用。
*
* @param date 新的提醒时间戳，0 表示取消提醒。
* @param set 操作类型：true 表示设置提醒，false 表示取消提醒。
*/
void onClockAlertChanged(long date, boolean set);
/**
* 桌面小组件相关变化时的回调
* 通俗说：当便签关联的小组件变化（比如创建/删除小组件便签），会调用该方法更新小组件
* 当便签关联的桌面小部件需要更新时调用。
* <p>
* 通常由于便签内容、标题或背景色变更，需要同步到小部件显示。
*/
void onWidgetChanged();
/**
* 便签模式切换时的回调
* 通俗说：当在普通模式和清单模式之间切换时，会调用该方法，界面可在此更新显示样式
* @param oldMode 切换前的旧模式
* @param newMode 切换后的新模式
* 当便签在普通文本模式与清单模式之间切换时调用。
*
* @param oldMode 切换前的模式。
* @param newMode 切换后的模式。
*/
void onCheckListModeChanged(int oldMode, int newMode);
}

348
src/Notes-master/src/net/micode/notes/tool/BackupUtils.java
Unescape View File

@ -5,7 +5,7 @@
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
@ -14,31 +14,21 @@
* limitations under the License.
*/
// 包声明：归属小米便签的工具模块，提供笔记备份（导出为文本文件）核心功能
package net.micode.notes.tool;
// 导入安卓上下文类：访问资源、ContentResolver
import android.content.Context;
// 导入安卓数据库游标类：查询便签/便签数据的核心载体
import android.database.Cursor;
// 导入安卓外部存储类：判断SD卡挂载状态、获取SD卡根目录
import android.os.Environment;
// 导入安卓文本工具类：判空、字符串处理
import android.text.TextUtils;
// 导入安卓日期格式化类：格式化便签修改时间、导出文件名
import android.text.format.DateFormat;
// 导入安卓日志类：输出备份过程中的日志（调试/错误）
import android.util.Log;
// 导入小米便签资源类：引用字符串（文件路径、格式模板、文件夹名称）
import net.micode.notes.R;
// 导入便签数据常量类：定义ContentURI、字段、便签类型、特殊文件夹ID等
import net.micode.notes.data.Notes;
import net.micode.notes.data.Notes.DataColumns;
import net.micode.notes.data.Notes.DataConstants;
import net.micode.notes.data.Notes.NoteColumns;
// 导入文件操作相关类：创建文件/目录、文件输出流、打印流
import java.io.File;
import java.io.FileNotFoundException;
import java.io.FileOutputStream;
@ -46,29 +36,36 @@ import java.io.IOException;
import java.io.PrintStream;
/**
* 便签备份工具类
* 核心特性：
* 1. 单例模式：全局唯一实例，避免重复初始化资源；
* 2. 核心功能：将便签数据库中的所有有效便签（排除回收站）导出为SD卡上的文本文件；
* 3. 导出范围：
* - 所有文件夹（排除回收站）及文件夹下的便签；
* - 通话记录文件夹及其中的通话记录便签；
* - 根目录下的普通便签；
* 4. 导出格式：按文件夹分组，包含便签修改时间、内容（普通文本/通话记录详情）；
* 5. 状态码机制：返回备份操作的结果（SD卡未挂载、文件创建失败、成功等）。
* 便签数据备份与导出工具类 (Utility Layer - Data Export)
* <p>
* 核心职责：提供将本地便签数据导出为可读文本文件（TXT格式）的功能，便于用户备份或迁移数据。
* 遵循单例模式，确保备份操作的状态统一管理。
* <p>
* 导出流程：
* 1. 检查外部存储（SD卡）是否可用。
* 2. 创建按日期命名的文本文件。
* 3. 遍历所有文件夹及便签，按照预设格式（包含文件夹名、便签日期、内容）逐级写入文件。
* 4. 支持文本便签和通话记录便签两种类型的格式化输出。
* <p>
* 设计特点：
* - **用户友好**：导出的文本文件采用清晰的分层格式，便于用户直接阅读。
* - **增量兼容**：仅导出用户数据（排除回收站、系统文件夹），避免冗余。
* - **外部存储**：备份文件存储在SD卡固定目录，便于用户管理。
* <p>
* 注意：当前版本仅支持导出到文本文件，不支持从文本文件恢复（导入）功能。
*/
public class BackupUtils {
// 日志标签：用于备份过程的日志输出
/** 日志标签 */
private static final String TAG = "BackupUtils";
// 单例实例：全局唯一的BackupUtils对象
/** 单例实例，延迟初始化 */
private static BackupUtils sInstance;
/**
* 获取单例实例（线程安全）
* 采用同步方法确保多线程环境下实例唯一，避免重复创建
* @param context 应用上下文：用于初始化内部导出器、访问资源
* @return BackupUtils全局唯一实例
* 获取 BackupUtils 单例实例。
*
* @param context 应用上下文，用于资源访问和 ContentResolver。
* @return BackupUtils 单例。
*/
public static synchronized BackupUtils getInstance(Context context) {
if (sInstance == null) {
@ -78,75 +75,75 @@ public class BackupUtils {
}
/**
* 备份操作状态码：标识导出过程的结果，供外部判断操作是否成功
* 备份/导出操作状态码。
*/
// SD卡未挂载（无法创建/写入导出文件）
public static final int STATE_SD_CARD_UNMOUONTED = 0;
// 备份文件不存在（仅恢复操作使用，当前导出逻辑未用到）
public static final int STATE_BACKUP_FILE_NOT_EXIST = 1;
// 数据格式错误（导出时未用到，预留恢复操作的状态码）
public static final int STATE_DATA_DESTROIED = 2;
// 系统错误（如文件创建失败、IO异常等运行时错误）
public static final int STATE_SYSTEM_ERROR = 3;
// 导出操作成功完成
public static final int STATE_SUCCESS = 4;
// 文本导出器实例：封装实际的文本导出逻辑，与工具类解耦
// SD卡未挂载（无法访问外部存储）
public static final int STATE_SD_CARD_UNMOUNTED = 0;
// 备份文件不存在（此状态可能不直接用于导出操作）
public static final int STATE_BACKUP_FILE_NOT_EXIST = 1;
// 数据格式被破坏（如数据库被外部工具篡改）
public static final int STATE_DATA_DESTROIED = 2;
// 系统运行时异常（如 IO 错误）
public static final int STATE_SYSTEM_ERROR = 3;
// 操作成功
public static final int STATE_SUCCESS = 4;
/** 文本导出器的具体实现 */
private TextExport mTextExport;
/**
* 私有构造方法：单例模式的核心，禁止外部直接实例化
* @param context 应用上下文：传递给TextExport初始化资源
* 私有构造函数。
*
* @param context 应用上下文。
*/
private BackupUtils(Context context) {
mTextExport = new TextExport(context);
}
/**
* 检查外部存储（SD卡）是否可用
* 仅当SD卡处于“已挂载”状态时，才允许执行导出操作
* @return true=SD卡已挂载且可读写，false=不可用
* 检查外部存储（SD卡）是否可用并可写。
*
* @return true 表示外部存储可用，false 表示不可用。
*/
private static boolean externalStorageAvailable() {
return Environment.MEDIA_MOUNTED.equals(Environment.getExternalStorageState());
}
/**
* 对外暴露的导出方法：触发便签导出为文本文件的核心逻辑
* @return 操作状态码：参考BackupUtils的STATE_XXX常量
* 执行便签数据导出到文本文件的操作。
*
* @return 操作状态码，取值为本类定义的 STATE_* 常量。
*/
public int exportToText() {
return mTextExport.exportToText();
}
/**
* 获取本次导出的文件名（导出成功后有效）
* @return 导出文件的名称（如notes_20251223.txt）
* 获取上次导出操作生成的文本文件名。
*
* @return 文本文件名（不含路径），如果尚未导出过则返回空字符串。
*/
public String getExportedTextFileName() {
return mTextExport.mFileName;
}
/**
* 获取本次导出的文件目录（导出成功后有效）
* @return 导出文件所在的目录路径（如/sdcard/MiNotes/）
* 获取上次导出操作生成的文本文件所在的目录路径。
*
* @return 目录路径（相对于 SD 卡根目录），如果尚未导出过则返回空字符串。
*/
public String getExportedTextFileDir() {
return mTextExport.mFileDirectory;
}
/**
* 内部文本导出器类：封装所有导出相关的核心逻辑
* 与外部BackupUtils解耦，专注处理“查询便签数据→格式化→写入文本文件”的完整流程
* 文本导出器的具体实现类，负责执行实际的数据库遍历和文件写入。
* <p>
* 采用内部类封装，避免暴露复杂的导出逻辑细节。
*/
private static class TextExport {
/**
* 便签查询投影数组：仅查询导出所需的核心字段，减少IO开销
* 字段说明：
* - NoteColumns.ID：便签/文件夹唯一ID；
* - NoteColumns.MODIFIED_DATE：便签最后修改时间（用于导出展示）；
* - NoteColumns.SNIPPET：便签摘要/文件夹名称；
* - NoteColumns.TYPE：便签类型（文件夹/普通便签/系统项）。
* 便签主表（notes表）查询投影。
*/
private static final String[] NOTE_PROJECTION = {
NoteColumns.ID,
@ -155,19 +152,15 @@ public class BackupUtils {
NoteColumns.TYPE
};
// 便签投影数组列索引常量：简化Cursor取值，避免硬编码
/** 便签 ID 列在查询结果中的索引 */
private static final int NOTE_COLUMN_ID = 0;
/** 便签修改日期列在查询结果中的索引 */
private static final int NOTE_COLUMN_MODIFIED_DATE = 1;
/** 便签摘要（标题）列在查询结果中的索引 */
private static final int NOTE_COLUMN_SNIPPET = 2;
/**
* 便签数据查询投影数组：查询便签的具体内容（普通文本/通话记录）
* 字段说明：
* - DataColumns.CONTENT：普通便签内容/通话记录附件位置；
* - DataColumns.MIME_TYPE：数据类型（普通便签/通话记录）；
* - DataColumns.DATA1：通话记录时间；
* - DataColumns.DATA4：通话记录手机号；
* 其他DATA字段为预留，暂未使用。
* 便签数据表（data表）查询投影。
*/
private static final String[] DATA_PROJECTION = {
DataColumns.CONTENT,
@ -178,194 +171,191 @@ public class BackupUtils {
DataColumns.DATA4,
};
// 便签数据投影数组列索引常量
/** 数据内容列在查询结果中的索引 */
private static final int DATA_COLUMN_CONTENT = 0;
/** MIME 类型列在查询结果中的索引 */
private static final int DATA_COLUMN_MIME_TYPE = 1;
/** 通话日期列在查询结果中的索引（存储在 DATA1 字段） */
private static final int DATA_COLUMN_CALL_DATE = 2;
/** 电话号码列在查询结果中的索引（存储在 DATA4 字段） */
private static final int DATA_COLUMN_PHONE_NUMBER = 4;
/**
* 导出文本格式模板数组：从资源文件读取，适配多语言，避免硬编码文本格式
* 数组索引对应：
* - FORMAT_FOLDER_NAME：文件夹名称展示格式（如“【文件夹：XXX】”）；
* - FORMAT_NOTE_DATE：便签修改时间展示格式（如“修改时间：2025-12-23 15:30”）；
* - FORMAT_NOTE_CONTENT：便签内容展示格式（如“内容：XXX”）。
* 导出文本格式模板数组，从资源文件（R.array.format_for_exported_note）加载。
* 包含文件夹名、便签日期和便签内容三种格式模板。
*/
private final String [] TEXT_FORMAT;
// 格式模板索引常量
private static final int FORMAT_FOLDER_NAME = 0;
private static final int FORMAT_NOTE_DATE = 1;
private static final int FORMAT_NOTE_CONTENT = 2;
// 上下文：用于访问ContentResolver、资源文件
private final String[] TEXT_FORMAT;
/** 文本格式模板数组中文件夹名格式的索引 */
private static final int FORMAT_FOLDER_NAME = 0;
/** 文本格式模板数组中便签日期格式的索引 */
private static final int FORMAT_NOTE_DATE = 1;
/** 文本格式模板数组中便签内容格式的索引 */
private static final int FORMAT_NOTE_CONTENT = 2;
/** 应用上下文，用于资源访问和 ContentResolver */
private Context mContext;
private String mFileName; // 导出文件的名称（如notes_20251223.txt）
private String mFileDirectory; // 导出文件的目录路径（如/sdcard/MiNotes/）
/** 上次导出的文件名 */
private String mFileName;
/** 上次导出的文件所在目录 */
private String mFileDirectory;
/**
* 文本导出器构造方法
* @param context 应用上下文：读取格式模板、资源字符串
* 构造函数，初始化导出格式模板和上下文。
*
* @param context 应用上下文。
*/
public TextExport(Context context) {
// 从资源文件加载导出文本的格式模板
TEXT_FORMAT = context.getResources().getStringArray(R.array.format_for_exported_note);
mContext = context;
// 初始化文件名/目录为空，导出成功后赋值
mFileName = "";
mFileDirectory = "";
}
/**
* 获取指定索引的文本格式模板
* @param id 格式模板索引（FORMAT_FOLDER_NAME/FORMAT_NOTE_DATE/FORMAT_NOTE_CONTENT）
* @return 格式模板字符串
* 根据 ID 获取导出格式模板字符串。
*
* @param id 格式模板 ID（FORMAT_FOLDER_NAME、FORMAT_NOTE_DATE 或 FORMAT_NOTE_CONTENT）。
* @return 格式模板字符串。
*/
private String getFormat(int id) {
return TEXT_FORMAT[id];
}
/**
* 导出指定文件夹下的所有便签到打印流
* @param folderId 文件夹ID：要导出的文件夹唯一标识
* @param ps 打印流：指向SD卡的导出文件，用于写入文本内容
* 将指定文件夹及其下的所有便签导出到打印流。
* <p>
* 遍历文件夹下的所有便签，为每个便签写入修改日期，然后调用 {@link #exportNoteToText} 导出便签内容。
*
* @param folderId 要导出的文件夹 ID。
* @param ps 目标打印流。
*/
private void exportFolderToText(String folderId, PrintStream ps) {
// 查询该文件夹下的所有普通便签
// DB操作：查询该文件夹下的所有便签
Cursor notesCursor = mContext.getContentResolver().query(Notes.CONTENT_NOTE_URI,
NOTE_PROJECTION,
NoteColumns.PARENT_ID + "=?", // 查询条件：父文件夹ID匹配
new String[] { folderId },
null);
NOTE_PROJECTION, NoteColumns.PARENT_ID + "=?", new String[] {
folderId
}, null);
if (notesCursor != null) {
// 遍历文件夹下的所有便签
if (notesCursor.moveToFirst()) {
do {
// 1. 打印便签最后修改时间（按格式模板）
// 写入便签的修改日期（格式化）
ps.println(String.format(getFormat(FORMAT_NOTE_DATE), DateFormat.format(
mContext.getString(R.string.format_datetime_mdhm), // 时间格式：月日时分
mContext.getString(R.string.format_datetime_mdhm),
notesCursor.getLong(NOTE_COLUMN_MODIFIED_DATE))));
// 2. 导出单条便签的详细内容
// 导出该便签的具体内容
String noteId = notesCursor.getString(NOTE_COLUMN_ID);
exportNoteToText(noteId, ps);
} while (notesCursor.moveToNext());
}
// 关闭游标，释放数据库资源
notesCursor.close();
}
}
/**
* 导出单条便签的详细内容到打印流
* 区分处理普通文本便签和通话记录便签，按不同格式写入内容
* @param noteId 便签ID：要导出的便签唯一标识
* @param ps 打印流：指向SD卡的导出文件
* 将指定便签的内容导出到打印流。
* <p>
* 遍历便签关联的所有数据记录，根据 MIME 类型分别处理：
* - 文本便签：直接写入内容。
* - 通话记录便签：写入电话号码、通话日期和可能的附件位置信息。
*
* @param noteId 要导出的便签 ID。
* @param ps 目标打印流。
*/
private void exportNoteToText(String noteId, PrintStream ps) {
// 查询该便签的具体数据（内容/通话记录详情）
// DB操作：查询该便签关联的所有数据记录
Cursor dataCursor = mContext.getContentResolver().query(Notes.CONTENT_DATA_URI,
DATA_PROJECTION,
DataColumns.NOTE_ID + "=?", // 查询条件：便签ID匹配
new String[] { noteId },
null);
DATA_PROJECTION, DataColumns.NOTE_ID + "=?", new String[] {
noteId
}, null);
if (dataCursor != null) {
// 遍历便签的所有数据项（单条便签可能包含多个数据项，如通话记录+附件）
if (dataCursor.moveToFirst()) {
do {
String mimeType = dataCursor.getString(DATA_COLUMN_MIME_TYPE);
// 1. 处理通话记录类型便签
if (DataConstants.CALL_NOTE.equals(mimeType)) {
// 获取通话记录核心信息
// 处理通话记录便签
String phoneNumber = dataCursor.getString(DATA_COLUMN_PHONE_NUMBER);
long callDate = dataCursor.getLong(DATA_COLUMN_CALL_DATE);
String location = dataCursor.getString(DATA_COLUMN_CONTENT);
// 打印手机号（非空时）
if (!TextUtils.isEmpty(phoneNumber)) {
ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), phoneNumber));
ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
phoneNumber));
}
// 打印通话时间
// 写入通话日期
ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), DateFormat
.format(mContext.getString(R.string.format_datetime_mdhm), callDate)));
// 打印通话记录附件位置（非空时）
.format(mContext.getString(R.string.format_datetime_mdhm),
callDate)));
// 写入通话附件位置（如果存在）
if (!TextUtils.isEmpty(location)) {
ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), location));
ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
location));
}
}
// 2. 处理普通文本便签
else if (DataConstants.NOTE.equals(mimeType)) {
} else if (DataConstants.NOTE.equals(mimeType)) {
// 处理文本便签
String content = dataCursor.getString(DATA_COLUMN_CONTENT);
// 打印便签内容（非空时）
if (!TextUtils.isEmpty(content)) {
ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT), content));
ps.println(String.format(getFormat(FORMAT_NOTE_CONTENT),
content));
}
}
} while (dataCursor.moveToNext());
}
// 关闭游标，释放资源
dataCursor.close();
}
// 便签内容结束后，添加分隔符（换行+分隔符），区分不同便签
// 在两个便签之间写入行分隔符，提高可读性
try {
ps.write(new byte[] {
Character.LINE_SEPARATOR, Character.LETTER_NUMBER
});
} catch (IOException e) {
// 写入分隔符失败时输出错误日志，不中断整体导出流程
Log.e(TAG, e.toString());
}
}
/**
* 执行核心导出逻辑：将所有有效便签导出为SD卡上的文本文件
* 导出流程：
* 1. 检查SD卡是否可用；
* 2. 创建导出文件的打印流；
* 3. 导出所有有效文件夹（排除回收站）+ 通话记录文件夹；
* 4. 导出根目录下的普通便签；
* 5. 关闭打印流，返回操作状态码。
* @return 操作状态码：参考BackupUtils的STATE_XXX常量
* 导出所有便签到文本文件的主方法。
* <p>
* 执行步骤：
* 1. 检查外部存储可用性。
* 2. 获取输出流（文件）。
* 3. 遍历所有非回收站的文件夹，导出文件夹及其便签。
* 4. 导出根目录下的便签（无文件夹归属的便签）。
* 5. 关闭流并返回状态。
*
* @return 操作状态码，取值为 BackupUtils.STATE_* 常量。
*/
public int exportToText() {
// 步骤1：检查SD卡是否挂载，未挂载直接返回对应状态码
if (!externalStorageAvailable()) {
Log.d(TAG, "Media was not mounted");
return STATE_SD_CARD_UNMOUONTED;
return STATE_SD_CARD_UNMOUNTED;
}
// 步骤2：创建导出文件的打印流，失败则返回系统错误
PrintStream ps = getExportToTextPrintStream();
if (ps == null) {
Log.e(TAG, "get print stream error");
return STATE_SYSTEM_ERROR;
}
// 步骤3：导出所有有效文件夹（排除回收站）+ 通话记录文件夹
// 第一部分：导出所有自定义文件夹及通话记录文件夹（排除回收站）
Cursor folderCursor = mContext.getContentResolver().query(
Notes.CONTENT_NOTE_URI,
NOTE_PROJECTION,
// 查询条件：
// - 类型为文件夹 + 父文件夹不是回收站；
// - 或ID为通话记录文件夹（特殊系统文件夹）
"(" + NoteColumns.TYPE + "=" + Notes.TYPE_FOLDER + " AND "
+ NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER + ") OR "
+ NoteColumns.ID + "=" + Notes.ID_CALL_RECORD_FOLDER,
null,
null);
+ NoteColumns.ID + "=" + Notes.ID_CALL_RECORD_FOLDER, null, null);
if (folderCursor != null) {
if (folderCursor.moveToFirst()) {
do {
// 处理文件夹名称：通话记录文件夹使用固定名称，其他文件夹用摘要
// 写入文件夹名称
String folderName = "";
if(folderCursor.getLong(NOTE_COLUMN_ID) == Notes.ID_CALL_RECORD_FOLDER) {
if (folderCursor.getLong(NOTE_COLUMN_ID) == Notes.ID_CALL_RECORD_FOLDER) {
folderName = mContext.getString(R.string.call_record_folder_name);
} else {
folderName = folderCursor.getString(NOTE_COLUMN_SNIPPET);
}
// 打印文件夹名称（非空时）
if (!TextUtils.isEmpty(folderName)) {
ps.println(String.format(getFormat(FORMAT_FOLDER_NAME), folderName));
}
@ -377,24 +367,20 @@ public class BackupUtils {
folderCursor.close();
}
// 步骤4：导出根目录下的普通便签（父文件夹ID为0）
// 第二部分：导出根目录下的便签（parent_id=0）
Cursor noteCursor = mContext.getContentResolver().query(
Notes.CONTENT_NOTE_URI,
NOTE_PROJECTION,
// 查询条件：类型为普通便签 + 父文件夹为根目录
NoteColumns.TYPE + "=" + Notes.TYPE_NOTE + " AND " + NoteColumns.PARENT_ID
+ "=0",
null,
null);
NoteColumns.TYPE + "=" + +Notes.TYPE_NOTE + " AND " + NoteColumns.PARENT_ID
+ "=0", null, null);
if (noteCursor != null) {
if (noteCursor.moveToFirst()) {
do {
// 打印便签修改时间
ps.println(String.format(getFormat(FORMAT_NOTE_DATE), DateFormat.format(
mContext.getString(R.string.format_datetime_mdhm),
noteCursor.getLong(NOTE_COLUMN_MODIFIED_DATE))));
// 导出单条便签内容
// 导出该便签的具体内容
String noteId = noteCursor.getString(NOTE_COLUMN_ID);
exportNoteToText(noteId, ps);
} while (noteCursor.moveToNext());
@ -402,41 +388,35 @@ public class BackupUtils {
noteCursor.close();
}
// 步骤5：关闭打印流，释放文件资源
ps.close();
// 导出成功，返回成功状态码
return STATE_SUCCESS;
}
/**
* 创建指向SD卡导出文件的PrintStream
* 核心逻辑：调用generateFileMountedOnSDcard创建文件，再包装为PrintStream
* @return PrintStream对象（成功）/null（失败）
* 创建并返回指向导出文本文件的打印流。
* <p>
* 文件路径和名称由 {@link #generateFileMountedOnSDcard} 方法生成，
* 通常位于 SD 卡上的固定目录，文件名包含当前日期。
*
* @return 指向新创建文本文件的 PrintStream，若创建失败则返回 null。
*/
private PrintStream getExportToTextPrintStream() {
// 生成SD卡上的导出文件（带日期的文本文件）
File file = generateFileMountedOnSDcard(mContext, R.string.file_path,
R.string.file_name_txt_format);
if (file == null) {
Log.e(TAG, "create file to exported failed");
return null;
}
// 记录导出文件的名称和目录（供外部获取）
mFileName = file.getName();
mFileDirectory = mContext.getString(R.string.file_path);
PrintStream ps = null;
try {
// 创建文件输出流，包装为打印流（方便文本写入）
FileOutputStream fos = new FileOutputStream(file);
ps = new PrintStream(fos);
} catch (FileNotFoundException e) {
// 文件未找到异常：打印堆栈，返回null
e.printStackTrace();
return null;
} catch (NullPointerException e) {
// 空指针异常：打印堆栈，返回null
e.printStackTrace();
return null;
}
@ -445,48 +425,42 @@ public class BackupUtils {
}
/**
* 在SD卡上生成导出用的文本文件
* 文件名规则：带当前日期（如notes_20251223.txt），目录为预设的便签备份目录
* @param context 应用上下文：读取目录路径、文件名格式资源
* @param filePathResId 目录路径资源ID：如R.string.file_path（/MiNotes/）
* @param fileNameFormatResId 文件名格式资源ID：如R.string.file_name_txt_format（notes_%s.txt）
* @return 生成的File对象（成功）/null（失败）
* 在 SD 卡上创建用于存储导出数据的文本文件。
* <p>
* 文件路径为：SD卡根目录 + 资源文件中定义的相对路径。
* 文件名为：资源文件中定义的格式（通常包含当前日期）。
*
* @param context 应用上下文，用于获取字符串资源。
* @param filePathResId 文件路径的资源 ID。
* @param fileNameFormatResId 文件名格式的资源 ID（可包含日期格式化参数）。
* @return 创建成功的 File 对象，若创建失败则返回 null。
*/
private static File generateFileMountedOnSDcard(Context context, int filePathResId, int fileNameFormatResId) {
StringBuilder sb = new StringBuilder();
// 1. 拼接SD卡根目录 + 预设目录路径（如/sdcard/MiNotes/）
sb.append(Environment.getExternalStorageDirectory());
sb.append(context.getString(filePathResId));
File filedir = new File(sb.toString());
// 2. 拼接完整文件路径：目录 + 带日期的文件名（如/sdcard/MiNotes/notes_20251223.txt）
// 文件名格式化为包含当前日期，例如：notes_20231231.txt
sb.append(context.getString(
fileNameFormatResId,
// 格式化文件名中的日期部分（年-月-日）
DateFormat.format(context.getString(R.string.format_date_ymd),
System.currentTimeMillis())));
File file = new File(sb.toString());
try {
// 3. 创建目录（不存在时）
if (!filedir.exists()) {
filedir.mkdir();
}
// 4. 创建文件（不存在时）
if (!file.exists()) {
file.createNewFile();
}
// 5. 返回创建成功的文件对象
return file;
} catch (SecurityException e) {
// 权限异常（如无SD卡写入权限）：打印堆栈，返回null
e.printStackTrace();
} catch (IOException e) {
// IO异常（如创建文件失败）：打印堆栈，返回null
e.printStackTrace();
}
// 创建失败，返回null
return null;
}
}

285
src/Notes-master/src/net/micode/notes/tool/DataUtils.java
Unescape View File

@ -5,7 +5,7 @@
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
@ -35,19 +35,38 @@ import java.util.ArrayList;
import java.util.HashSet;
/**
* 数据库操作工具类
* 提供笔记的增删改查、批量操作、数据校验等功能
* 数据库操作工具类 (Utility Layer - Data Operations)
* <p>
* 核心职责：提供便签数据库的批量操作和查询工具方法，封装复杂的数据库交互逻辑。
* 作为数据访问层（Data Access Layer）的辅助工具，简化上层业务逻辑对数据库的直接操作。
* <p>
* 功能范畴：
* 1. 批量操作：批量删除、批量移动便签到文件夹。
* 2. 数据验证：检查便签/数据是否存在，检查文件夹名称是否重复。
* 3. 查询工具：获取文件夹统计信息、查询小部件属性、获取便签摘要等。
* 4. 特殊查询：针对通话记录便签的专项查询。
* <p>
* 设计特点：
* - **批量处理优化**：使用 {@link ContentProviderOperation} 批量执行数据库操作，提高效率。
* - **防御性编程**：对输入参数进行空值检查，避免无效操作。
* - **异常处理**：捕获并记录数据库操作异常，但不向上抛出，保证调用方稳定性。
*/
public class DataUtils {
/** 日志标签 */
public static final String TAG = "DataUtils";
/**
* 批量删除笔记
* @param resolver ContentResolver用于数据库操作
* @param ids 待删除的笔记ID集合
* @return true删除成功，false删除失败
* 批量删除便签（及文件夹）。
* <p>
* 使用 {@link ContentProviderOperation} 批量构建删除操作，通过 {@link ContentResolver#applyBatch} 执行。
* 注意：该方法会跳过系统根文件夹（{@link Notes#ID_ROOT_FOLDER}）的删除请求。
*
* @param resolver ContentResolver，用于执行数据库操作。
* @param ids 要删除的便签/文件夹ID集合。
* @return true 表示批量删除成功，false 表示失败或部分失败。
*/
public static boolean batchDeleteNotes(ContentResolver resolver, HashSet<Long> ids) {
// 1. 参数校验
if (ids == null) {
Log.d(TAG, "the ids is null");
return true;
@ -57,23 +76,25 @@ public class DataUtils {
return true;
}
// 批量操作列表，用于执行事务性删除
// 2. 构建批量删除操作
ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
for (long id : ids) {
// 保护系统根文件夹不被删除
if(id == Notes.ID_ROOT_FOLDER) {
// 保护性检查：防止误删系统根文件夹
if (id == Notes.ID_ROOT_FOLDER) {
Log.e(TAG, "Don't delete system folder root");
continue;
}
// 构建删除操作，根据URI删除指定ID的笔记
// 创建删除操作
ContentProviderOperation.Builder builder = ContentProviderOperation
.newDelete(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id));
operationList.add(builder.build());
}
// 3. 执行批量操作
try {
// 批量执行删除操作
// DB操作：批量执行删除
ContentProviderResult[] results = resolver.applyBatch(Notes.AUTHORITY, operationList);
// 检查结果是否有效
// 验证操作结果
if (results == null || results.length == 0 || results[0] == null) {
Log.d(TAG, "delete notes failed, ids:" + ids.toString());
return false;
@ -88,47 +109,58 @@ public class DataUtils {
}
/**
* 移动单条笔记到目标文件夹
* @param resolver ContentResolver用于数据库操作
* @param id 笔记ID
* @param srcFolderId 源文件夹ID（记录原始位置）
* @param desFolderId 目标文件夹ID
* 将单个便签移动到目标文件夹，并记录原始父文件夹信息。
* <p>
* 主要用于支持撤销移动操作（通过 ORIGIN_PARENT_ID 记录来源）。
*
* @param resolver ContentResolver。
* @param id 要移动的便签 ID。
* @param srcFolderId 原始文件夹 ID（移动前的父文件夹）。
* @param desFolderId 目标文件夹 ID（移动后的父文件夹）。
*/
public static void moveNoteToFoler(ContentResolver resolver, long id, long srcFolderId, long desFolderId) {
// 准备更新数据：新父文件夹、原始父文件夹、标记为已修改
ContentValues values = new ContentValues();
values.put(NoteColumns.PARENT_ID, desFolderId); // 设置新的父文件夹
values.put(NoteColumns.ORIGIN_PARENT_ID, srcFolderId); // 记录原始父文件夹
values.put(NoteColumns.LOCAL_MODIFIED, 1); // 标记为本地已修改
values.put(NoteColumns.PARENT_ID, desFolderId);
values.put(NoteColumns.ORIGIN_PARENT_ID, srcFolderId);
values.put(NoteColumns.LOCAL_MODIFIED, 1); // 标记为需要同步
// DB操作：更新便签的父文件夹
resolver.update(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id), values, null, null);
}
/**
* 批量移动笔记到指定文件夹
* @param resolver ContentResolver用于数据库操作
* @param ids 待移动的笔记ID集合
* @param folderId 目标文件夹ID
* @return true成功，false失败
* 批量将便签移动到指定文件夹。
* <p>
* 与 {@link #moveNoteToFoler} 不同，此方法不记录原始父文件夹，主要用于批量整理操作。
* 使用批量操作提高效率。
*
* @param resolver ContentResolver。
* @param ids 要移动的便签ID集合。
* @param folderId 目标文件夹 ID。
* @return true 表示批量移动成功，false 表示失败或部分失败。
*/
public static boolean batchMoveToFolder(ContentResolver resolver, HashSet<Long> ids,
long folderId) {
long folderId) {
// 参数校验
if (ids == null) {
Log.d(TAG, "the ids is null");
return true;
}
// 批量操作列表，用于执行事务性更新
// 构建批量更新操作
ArrayList<ContentProviderOperation> operationList = new ArrayList<ContentProviderOperation>();
for (long id : ids) {
// 构建更新操作，修改笔记的父文件夹
ContentProviderOperation.Builder builder = ContentProviderOperation
.newUpdate(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, id));
builder.withValue(NoteColumns.PARENT_ID, folderId); // 设置新的父文件夹
builder.withValue(NoteColumns.LOCAL_MODIFIED, 1); // 标记为本地已修改
builder.withValue(NoteColumns.PARENT_ID, folderId);
builder.withValue(NoteColumns.LOCAL_MODIFIED, 1); // 标记为需要同步
operationList.add(builder.build());
}
// 执行批量操作
try {
// 批量执行移动操作
// DB操作：批量执行更新
ContentProviderResult[] results = resolver.applyBatch(Notes.AUTHORITY, operationList);
if (results == null || results.length == 0 || results[0] == null) {
Log.d(TAG, "delete notes failed, ids:" + ids.toString());
@ -144,27 +176,30 @@ public class DataUtils {
}
/**
* 获取用户创建的文件夹数量（排除系统文件夹和回收站）
* @param resolver ContentResolver用于数据库操作
* @return 文件夹数量
* 获取用户创建的自定义文件夹数量（排除系统文件夹和回收站）。
* <p>
* 查询条件：TYPE = TYPE_FOLDER 且 PARENT_ID ≠ ID_TRASH_FOLER。
*
* @param resolver ContentResolver。
* @return 用户文件夹的数量。
*/
public static int getUserFolderCount(ContentResolver resolver) {
// 查询类型为文件夹且父ID不是回收站的记录数
Cursor cursor =resolver.query(Notes.CONTENT_NOTE_URI,
// DB操作：查询符合条件的文件夹数量
Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI,
new String[] { "COUNT(*)" },
NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>?",
new String[] { String.valueOf(Notes.TYPE_FOLDER), String.valueOf(Notes.ID_TRASH_FOLER)},
null);
int count = 0;
if(cursor != null) {
if(cursor.moveToFirst()) {
if (cursor != null) {
if (cursor.moveToFirst()) {
try {
count = cursor.getInt(0); // 获取第一列的计数结果
count = cursor.getInt(0);
} catch (IndexOutOfBoundsException e) {
Log.e(TAG, "get folder count failed:" + e.toString());
} finally {
cursor.close(); // 确保游标被关闭
cursor.close();
}
}
}
@ -172,23 +207,26 @@ public class DataUtils {
}
/**
* 检查笔记是否在可见数据库中（不在回收站）
* @param resolver ContentResolver用于数据库操作
* @param noteId 笔记ID
* @param type 笔记类型
* @return true存在且可见，false不存在或已被删除到回收站
* 检查指定类型和ID的便签是否在数据库中“可见”。
* <p>
* “可见”定义为：存在于数据库，且未被放入回收站（PARENT_ID ≠ ID_TRASH_FOLER）。
*
* @param resolver ContentResolver。
* @param noteId 要检查的便签 ID。
* @param type 便签类型（{@link Notes#TYPE_NOTE} 或 {@link Notes#TYPE_FOLDER}）。
* @return true 表示便签存在且不在回收站中，false 表示不存在或在回收站中。
*/
public static boolean visibleInNoteDatabase(ContentResolver resolver, long noteId, int type) {
// 查询指定ID和类型的笔记，且父ID不是回收站
// DB操作：查询指定ID和类型，且不在回收站的便签
Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId),
null,
NoteColumns.TYPE + "=? AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER,
new String [] {String.valueOf(type)},
new String[] {String.valueOf(type)},
null);
boolean exist = false;
if (cursor != null) {
if (cursor.getCount() > 0) { // 检查是否有匹配的记录
if (cursor.getCount() > 0) {
exist = true;
}
cursor.close();
@ -197,19 +235,20 @@ public class DataUtils {
}
/**
* 检查笔记是否存在（包括回收站中的）
* @param resolver ContentResolver用于数据库操作
* @param noteId 笔记ID
* @return true存在，false不存在
* 检查指定ID的便签是否存在于数据库中（不考虑回收站状态）。
*
* @param resolver ContentResolver。
* @param noteId 要检查的便签 ID。
* @return true 表示便签存在于数据库（可能在回收站），false 表示不存在。
*/
public static boolean existInNoteDatabase(ContentResolver resolver, long noteId) {
// 查询指定ID的笔记，不做其他条件限制
// DB操作：查询指定ID的便签是否存在
Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_NOTE_URI, noteId),
null, null, null, null);
boolean exist = false;
if (cursor != null) {
if (cursor.getCount() > 0) { // 检查是否有匹配的记录
if (cursor.getCount() > 0) {
exist = true;
}
cursor.close();
@ -218,19 +257,22 @@ public class DataUtils {
}
/**
* 检查数据记录是否存在
* @param resolver ContentResolver用于数据库操作
* @param dataId 数据ID
* @return true存在，false不存在
* 检查指定ID的数据记录是否存在于data表中。
* <p>
* 用于验证便签内容数据（文本或通话记录）的数据库记录是否存在。
*
* @param resolver ContentResolver。
* @param dataId 要检查的数据记录 ID。
* @return true 表示数据记录存在，false 表示不存在。
*/
public static boolean existInDataDatabase(ContentResolver resolver, long dataId) {
// 查询指定ID的数据记录
// DB操作：查询指定ID的数据记录是否存在
Cursor cursor = resolver.query(ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, dataId),
null, null, null, null);
boolean exist = false;
if (cursor != null) {
if (cursor.getCount() > 0) { // 检查是否有匹配的记录
if (cursor.getCount() > 0) {
exist = true;
}
cursor.close();
@ -239,21 +281,25 @@ public class DataUtils {
}
/**
* 检查可见文件夹名称是否已存在（用于重命名或新建时的冲突检测）
* @param resolver ContentResolver用于数据库操作
* @param name 文件夹名称
* @return true已存在，false不存在
* 检查指定的文件夹名称是否在“可见”文件夹中已存在（重复性检查）。
* <p>
* 查询条件：TYPE = TYPE_FOLDER，不在回收站，且 SNIPPET（文件夹名称）等于指定名称。
* 用于创建或重命名文件夹时的重复校验。
*
* @param resolver ContentResolver。
* @param name 要检查的文件夹名称。
* @return true 表示已存在同名的可见文件夹，false 表示不存在。
*/
public static boolean checkVisibleFolderName(ContentResolver resolver, String name) {
// 查询类型为文件夹、不在回收站中且名称匹配的记录
// DB操作：查询是否存在同名且不在回收站的文件夹
Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI, null,
NoteColumns.TYPE + "=" + Notes.TYPE_FOLDER +
" AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER +
" AND " + NoteColumns.SNIPPET + "=?",
" AND " + NoteColumns.PARENT_ID + "<>" + Notes.ID_TRASH_FOLER +
" AND " + NoteColumns.SNIPPET + "=?",
new String[] { name }, null);
boolean exist = false;
if(cursor != null) {
if(cursor.getCount() > 0) { // 检查是否有同名文件夹
if (cursor != null) {
if (cursor.getCount() > 0) {
exist = true;
}
cursor.close();
@ -262,13 +308,17 @@ public class DataUtils {
}
/**
* 获取文件夹中所有笔记的桌面小部件信息
* @param resolver ContentResolver用于数据库操作
* @param folderId 文件夹ID
* @return 小部件属性集合
* 获取指定文件夹下所有关联的桌面小部件属性集合。
* <p>
* 用于文件夹被删除或修改时，更新或删除关联的小部件。
*
* @param resolver ContentResolver。
* @param folderId 文件夹 ID。
* @return 包含 {@link AppWidgetAttribute} 对象的集合，每个对象包含 widgetId 和 widgetType。
* 如果没有关联的小部件，则返回 null。
*/
public static HashSet<AppWidgetAttribute> getFolderNoteWidget(ContentResolver resolver, long folderId) {
// 查询文件夹下所有笔记的小部件ID和类型
// DB操作：查询指定文件夹下所有便签的小部件信息
Cursor c = resolver.query(Notes.CONTENT_NOTE_URI,
new String[] { NoteColumns.WIDGET_ID, NoteColumns.WIDGET_TYPE },
NoteColumns.PARENT_ID + "=?",
@ -281,10 +331,10 @@ public class DataUtils {
set = new HashSet<AppWidgetAttribute>();
do {
try {
// 封装小部件属性对象
// 提取小部件属性并封装到对象中
AppWidgetAttribute widget = new AppWidgetAttribute();
widget.widgetId = c.getInt(0); // 小部件ID
widget.widgetType = c.getInt(1); // 小部件类型
widget.widgetId = c.getInt(0);
widget.widgetType = c.getInt(1);
set.add(widget);
} catch (IndexOutOfBoundsException e) {
Log.e(TAG, e.toString());
@ -297,51 +347,58 @@ public class DataUtils {
}
/**
* 通过笔记ID获取通话号码（针对通话记录类型笔记）
* @param resolver ContentResolver用于数据库操作
* @param noteId 笔记ID
* @return 通话号码，失败返回空字符串
* 根据便签ID获取关联的通话记录电话号码。
* <p>
* 专用于通话记录便签，通过查询data表中MIME类型为 {@link CallNote#CONTENT_ITEM_TYPE} 的记录。
*
* @param resolver ContentResolver。
* @param noteId 便签 ID。
* @return 电话号码字符串，如果未找到则返回空字符串。
*/
public static String getCallNumberByNoteId(ContentResolver resolver, long noteId) {
// 查询指定笔记的通话号码，限定MIME类型为通话记录
// DB操作：查询指定便签的通话记录数据，提取电话号码
Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI,
new String [] { CallNote.PHONE_NUMBER },
new String[] { CallNote.PHONE_NUMBER },
CallNote.NOTE_ID + "=? AND " + CallNote.MIME_TYPE + "=?",
new String [] { String.valueOf(noteId), CallNote.CONTENT_ITEM_TYPE },
new String[] { String.valueOf(noteId), CallNote.CONTENT_ITEM_TYPE },
null);
if (cursor != null && cursor.moveToFirst()) {
try {
return cursor.getString(0); // 获取通话号码
return cursor.getString(0);
} catch (IndexOutOfBoundsException e) {
Log.e(TAG, "Get call number fails " + e.toString());
} finally {
cursor.close(); // 确保游标被关闭
cursor.close();
}
}
return "";
}
/**
* 通过通话号码和日期查找对应的笔记ID
* @param resolver ContentResolver用于数据库操作
* @param phoneNumber 通话号码
* @param callDate 通话日期时间戳
* @return 笔记ID，未找到返回0
* 根据电话号码和通话日期查找对应的通话记录便签ID。
* <p>
* 使用自定义的 SQL 函数 PHONE_NUMBERS_EQUAL 进行电话号码匹配（可能支持模糊匹配或格式化处理）。
* 用于防止创建重复的通话记录便签。
*
* @param resolver ContentResolver。
* @param phoneNumber 电话号码。
* @param callDate 通话日期时间戳。
* @return 匹配的便签ID，如果未找到则返回 0。
*/
public static long getNoteIdByPhoneNumberAndCallDate(ContentResolver resolver, String phoneNumber, long callDate) {
// 使用自定义的PHONE_NUMBERS_EQUAL函数比较号码，确保同一联系人的不同格式号码能匹配
// DB操作：使用电话号码和通话日期联合查询通话记录便签
Cursor cursor = resolver.query(Notes.CONTENT_DATA_URI,
new String [] { CallNote.NOTE_ID },
new String[] { CallNote.NOTE_ID },
CallNote.CALL_DATE + "=? AND " + CallNote.MIME_TYPE + "=? AND PHONE_NUMBERS_EQUAL("
+ CallNote.PHONE_NUMBER + ",?)",
new String [] { String.valueOf(callDate), CallNote.CONTENT_ITEM_TYPE, phoneNumber },
+ CallNote.PHONE_NUMBER + ",?)",
new String[] { String.valueOf(callDate), CallNote.CONTENT_ITEM_TYPE, phoneNumber },
null);
if (cursor != null) {
if (cursor.moveToFirst()) {
try {
return cursor.getLong(0); // 获取笔记ID
return cursor.getLong(0);
} catch (IndexOutOfBoundsException e) {
Log.e(TAG, "Get call note id fails " + e.toString());
}
@ -352,24 +409,27 @@ public class DataUtils {
}
/**
* 通过笔记ID获取摘要内容
* @param resolver ContentResolver用于数据库操作
* @param noteId 笔记ID
* @return 摘要内容
* @throws IllegalArgumentException 笔记不存在时抛出异常
* 根据便签ID获取便签的摘要（标题/首行内容）。
* <p>
* 便签摘要通常存储在 notes 表的 SNIPPET 列，是便签内容的简短表示。
*
* @param resolver ContentResolver。
* @param noteId 便签 ID。
* @return 便签摘要字符串，如果未找到则返回空字符串。
* @throws IllegalArgumentException 如果便签不存在。
*/
public static String getSnippetById(ContentResolver resolver, long noteId) {
// 查询指定ID笔记的摘要字段
// DB操作：查询便签的摘要
Cursor cursor = resolver.query(Notes.CONTENT_NOTE_URI,
new String [] { NoteColumns.SNIPPET },
new String[] { NoteColumns.SNIPPET },
NoteColumns.ID + "=?",
new String [] { String.valueOf(noteId)},
new String[] { String.valueOf(noteId)},
null);
if (cursor != null) {
String snippet = "";
if (cursor.moveToFirst()) {
snippet = cursor.getString(0); // 获取摘要内容
snippet = cursor.getString(0);
}
cursor.close();
return snippet;
@ -378,16 +438,19 @@ public class DataUtils {
}
/**
* 格式化笔记摘要（取第一行非空内容并去除首尾空格）
* @param snippet 原始摘要
* @return 格式化后的摘要
* 格式化便签摘要：去除首尾空白，并截取到第一个换行符之前的内容。
* <p>
* 用于在列表等空间有限的地方显示简洁的便签标题。
*
* @param snippet 原始摘要字符串。
* @return 格式化后的摘要字符串。
*/
public static String getFormattedSnippet(String snippet) {
if (snippet != null) {
snippet = snippet.trim(); // 去除首尾空格
snippet = snippet.trim();
int index = snippet.indexOf('\n');
if (index != -1) {
snippet = snippet.substring(0, index); // 只保留第一行
snippet = snippet.substring(0, index);
}
}
return snippet;

152
src/Notes-master/src/net/micode/notes/tool/GTaskStringUtils.java
Unescape View File

@ -14,159 +14,195 @@
* limitations under the License.
*/
// 包声明：归属小米便签的工具模块，定义Google Tasks（GTask）同步相关的核心字符串常量
package net.micode.notes.tool;
/**
* Google Tasks（GTask）同步字符串常量类
* 核心职责：
* 1. 统一定义便签与GTask同步过程中JSON交互的所有字段名，避免硬编码；
* 2. 定义GTask侧的文件夹命名规则（区分MIUI便签专属文件夹、系统默认文件夹）；
* 3. 定义同步元数据的标识字段（用于存储GTask与便签的映射关系）；
* 设计目的：提升代码可维护性，便于统一修改GTask同步的字段/命名规则。
* GTask API 字符串常量工具类 (Utility Layer - API Constants)
* <p>
* 核心职责：集中定义与 Google Tasks API 交互时使用的 JSON 键名、操作类型、特殊标识符等字符串常量。
* 通过常量池设计，确保在整个 GTask 同步模块中引用的 API 字段名称一致，避免硬编码错误。
* <p>
* 架构作用：
* 1. **API 抽象层**：封装 Google Tasks API 的具体字段名，降低代码对特定 API 版本的耦合度。
* 2. **代码可读性**：使用有意义的常量名替代魔术字符串，提高代码自解释性。
* 3. **错误预防**：编译时检查常量引用，避免因拼写错误导致的运行时问题。
* <p>
* 常量分类：
* 1. **JSON 键常量 (GTASK_JSON_*)**：用于解析和构建与 Google Tasks 服务器通信的 JSON 数据结构。
* 2. **操作类型常量 (GTASK_JSON_ACTION_TYPE_*)**：标识客户端发起的同步操作类型（创建、移动、更新等）。
* 3. **类型标识常量 (GTASK_JSON_TYPE_*)**：标识 Google Tasks 实体类型（任务组 GROUP、单个任务 TASK）。
* 4. **应用特定前缀/标识符**：用于标识 MIUI 便签特有的任务列表和元数据。
*/
public class GTaskStringUtils {
// ======================== GTask同步JSON交互 - 动作相关字段 ========================
/** JSON字段：动作ID（标识单次同步操作的唯一ID） */
// ==================== Google Tasks JSON 字段键名 ====================
/** JSON 键：操作 ID，标识一次客户端请求的唯一性 */
public final static String GTASK_JSON_ACTION_ID = "action_id";
/** JSON字段：动作列表（批量同步时存储多个动作的数组） */
/** JSON 键：操作列表，包含多个待执行的同步操作 */
public final static String GTASK_JSON_ACTION_LIST = "action_list";
/** JSON字段：动作类型（标识当前同步动作的类型，如创建/查询/移动/更新） */
/** JSON 键：操作类型，定义客户端请求的操作类型（create/get_all/move/update） */
public final static String GTASK_JSON_ACTION_TYPE = "action_type";
/** JSON字段：动作类型-创建（同步时向GTask创建新任务/文件夹） */
/** 操作类型值：创建新实体（任务或任务列表） */
public final static String GTASK_JSON_ACTION_TYPE_CREATE = "create";
/** JSON字段：动作类型-全量查询（从GTask拉取所有任务/文件夹数据） */
/** 操作类型值：获取所有实体（全量同步） */
public final static String GTASK_JSON_ACTION_TYPE_GETALL = "get_all";
/** JSON字段：动作类型-移动（将GTask任务/文件夹移动到指定目录） */
/** 操作类型值：移动实体（如将任务移动到另一个列表） */
public final static String GTASK_JSON_ACTION_TYPE_MOVE = "move";
/** JSON字段：动作类型-更新（更新GTask中已存在的任务/文件夹信息） */
/** 操作类型值：更新现有实体 */
public final static String GTASK_JSON_ACTION_TYPE_UPDATE = "update";
// ======================== GTask同步JSON交互 - 实体/用户相关字段 ========================
/** JSON字段：创建者ID（标识GTask实体的创建者账号ID） */
/** JSON 键：创建者 ID，标识创建任务的用户 */
public final static String GTASK_JSON_CREATOR_ID = "creator_id";
/** JSON字段：子实体（存储GTask文件夹下的子任务/子文件夹） */
/** JSON 键：子实体列表，通常用于表示任务列表中的任务集合 */
public final static String GTASK_JSON_CHILD_ENTITY = "child_entity";
/** JSON字段：客户端版本（标识便签客户端的版本号，用于GTask服务端兼容） */
/** JSON 键：客户端版本，用于 API 版本兼容性 */
public final static String GTASK_JSON_CLIENT_VERSION = "client_version";
/** JSON字段：完成状态（标识GTask任务是否已完成，布尔值） */
/** JSON 键：完成状态，表示任务是否已完成 */
public final static String GTASK_JSON_COMPLETED = "completed";
/** JSON字段：当前列表ID（标识任务/文件夹所属的GTask列表ID） */
/** JSON 键：当前列表 ID，标识用户正在操作的任务列表 */
public final static String GTASK_JSON_CURRENT_LIST_ID = "current_list_id";
/** JSON字段：默认列表ID（GTask默认任务列表的ID） */
/** JSON 键：默认列表 ID，用户的默认任务列表 */
public final static String GTASK_JSON_DEFAULT_LIST_ID = "default_list_id";
/** JSON字段：删除标记（标识GTask实体是否已被删除，布尔值） */
/** JSON 键：删除标记，表示实体是否已被软删除 */
public final static String GTASK_JSON_DELETED = "deleted";
/** JSON字段：目标列表（移动操作时的目标列表ID） */
/** JSON 键：目标列表 ID（移动操作专用） */
public final static String GTASK_JSON_DEST_LIST = "dest_list";
/** JSON字段：目标父节点（移动操作时的目标父实体ID） */
/** JSON 键：目标父实体 ID（移动操作专用） */
public final static String GTASK_JSON_DEST_PARENT = "dest_parent";
/** JSON字段：目标父节点类型（移动操作时目标父实体的类型：GROUP/TASK） */
/** JSON 键：目标父实体类型（移动操作专用） */
public final static String GTASK_JSON_DEST_PARENT_TYPE = "dest_parent_type";
/** JSON字段：实体增量（同步时仅传输实体的变更部分，减少数据传输） */
/** JSON 键：实体增量变更，包含需要更新的字段 */
public final static String GTASK_JSON_ENTITY_DELTA = "entity_delta";
/** JSON字段：实体类型（标识GTask实体的类型：任务/文件夹） */
/** JSON 键：实体类型，区分任务列表（GROUP）和任务（TASK） */
public final static String GTASK_JSON_ENTITY_TYPE = "entity_type";
/** JSON字段：获取已删除项（同步时是否拉取GTask中已删除的实体） */
/** JSON 键：是否获取已删除的实体（用于增量同步） */
public final static String GTASK_JSON_GET_DELETED = "get_deleted";
/** JSON字段：实体ID（GTask任务/文件夹的唯一标识ID） */
/** JSON 键：实体的全局唯一标识符（GTask ID） */
public final static String GTASK_JSON_ID = "id";
/** JSON字段：索引（GTask实体在父节点中的排序索引） */
/** JSON 键：索引位置，用于排序任务在列表中的顺序 */
public final static String GTASK_JSON_INDEX = "index";
/** JSON字段：最后修改时间（GTask实体的最后修改时间戳） */
/** JSON 键：最后修改时间戳，用于冲突检测和增量同步 */
public final static String GTASK_JSON_LAST_MODIFIED = "last_modified";
/** JSON字段：最新同步点（标识上次同步的位置，用于增量同步） */
/** JSON 键：最新同步点，用于增量同步 */
public final static String GTASK_JSON_LATEST_SYNC_POINT = "latest_sync_point";
/** JSON字段：列表ID（GTask列表的唯一标识ID） */
/** JSON 键：列表 ID，标识任务所属的任务列表 */
public final static String GTASK_JSON_LIST_ID = "list_id";
/** JSON字段：列表数组（存储GTask所有列表的数组） */
/** JSON 键：任务列表集合，服务器返回的多个任务列表 */
public final static String GTASK_JSON_LISTS = "lists";
/** JSON字段：名称（GTask任务/文件夹的名称） */
/** JSON 键：实体名称（任务或任务列表的标题） */
public final static String GTASK_JSON_NAME = "name";
/** JSON字段：新ID（创建/移动操作后生成的新实体ID） */
/** JSON 键：新 ID（客户端创建实体时生成的临时 ID，服务器返回后替换为正式 ID） */
public final static String GTASK_JSON_NEW_ID = "new_id";
/** JSON字段：备注（GTask任务的备注内容，对应便签的正文） */
/** JSON 键：备注内容（任务的详细描述） */
public final static String GTASK_JSON_NOTES = "notes";
/** JSON字段：父节点ID（GTask实体的父文件夹/父任务ID） */
/** JSON 键：父实体 ID（如任务所属的列表 ID） */
public final static String GTASK_JSON_PARENT_ID = "parent_id";
/** JSON字段：前序兄弟ID（标识实体在父节点中的前一个兄弟实体ID，用于排序） */
/** JSON 键：前一个兄弟节点的 ID（用于排序） */
public final static String GTASK_JSON_PRIOR_SIBLING_ID = "prior_sibling_id";
/** JSON字段：同步结果（GTask服务端返回的同步操作结果） */
/** JSON 键：操作结果集合，服务器返回的批量操作结果 */
public final static String GTASK_JSON_RESULTS = "results";
/** JSON字段：源列表（移动操作时的源列表ID） */
/** JSON 键：源列表 ID（移动操作专用） */
public final static String GTASK_JSON_SOURCE_LIST = "source_list";
/** JSON字段：任务数组（存储GTask所有任务的数组） */
/** JSON 键：任务集合，服务器返回的多个任务 */
public final static String GTASK_JSON_TASKS = "tasks";
/** JSON字段：类型（兼容字段，同entity_type） */
/** JSON 键：类型，与 {@link #GTASK_JSON_ENTITY_TYPE} 类似，可能为冗余字段 */
public final static String GTASK_JSON_TYPE = "type";
/** JSON字段：类型-分组（GTask文件夹的类型标识） */
// ==================== Google Tasks 实体类型常量 ====================
/** 实体类型值：任务列表（组） */
public final static String GTASK_JSON_TYPE_GROUP = "GROUP";
/** JSON字段：类型-任务（GTask普通任务的类型标识） */
/** 实体类型值：单个任务 */
public final static String GTASK_JSON_TYPE_TASK = "TASK";
/** JSON字段：用户（标识GTask所属的用户账号信息） */
/** JSON 键：用户信息 */
public final static String GTASK_JSON_USER = "user";
// ======================== GTask侧文件夹命名规则 ========================
/** MIUI便签专属文件夹前缀（区分GTask中其他文件夹，避免命名冲突） */
// ==================== MIUI 便签特定标识符 ====================
/**
* MIUI 便签专用前缀，用于标记由本应用创建的任务列表和任务。
* 在 Google Tasks 中通过此前缀区分 MIUI 便签数据与其他任务。
*/
public final static String MIUI_FOLDER_PREFFIX = "[MIUI_Notes]";
/** GTask侧默认文件夹名称（对应便签的根目录） */
/**
* 默认文件夹（根文件夹）在 GTask 中的名称后缀。
* 完整名称示例：[MIUI_Notes]Default
*/
public final static String FOLDER_DEFAULT = "Default";
/** GTask侧通话记录文件夹名称（对应便签的通话记录文件夹） */
/**
* 通话记录文件夹在 GTask 中的名称后缀。
* 完整名称示例：[MIUI_Notes]Call_Note
*/
public final static String FOLDER_CALL_NOTE = "Call_Note";
/** GTask侧元数据文件夹名称（存储便签与GTask的同步映射元数据） */
/**
* 元数据文件夹名称后缀。
* 元数据文件夹用于存储便签的额外信息（如本地数据库ID映射），不直接显示给用户。
* 完整名称示例：[MIUI_Notes]METADATA
*/
public final static String FOLDER_META = "METADATA";
// ======================== 同步元数据标识字段 ========================
/** 元数据头-GTask ID（存储便签对应的GTask实体ID） */
// ==================== 元数据（MetaData）相关键名 ====================
/**
* 元数据 JSON 键：关联的 GTask 任务 ID。
* 存储在元数据任务中，指向其关联的 MIUI 便签主任务。
*/
public final static String META_HEAD_GTASK_ID = "meta_gid";
/** 元数据头-便签（存储便签核心信息的元数据标识） */
/**
* 元数据 JSON 键：便签主信息（Note 表数据）。
* 包含便签的核心元数据，如标题、修改时间、文件夹ID等。
*/
public final static String META_HEAD_NOTE = "meta_note";
/** 元数据头-数据（存储便签扩展数据的元数据标识） */
/**
* 元数据 JSON 键：便签内容数据（Data 表数据）。
* 包含便签的具体内容，如文本正文、通话记录信息等。
*/
public final static String META_HEAD_DATA = "meta_data";
/** 元数据便签名称（GTask中元数据便签的固定名称，禁止修改/删除） */
/**
* 元数据任务的名称。
* 用于提示用户（或开发者）不要直接修改或删除这些任务，以免破坏同步数据。
*/
public final static String META_NOTE_NAME = "[META INFO] DON'T UPDATE AND DELETE";
}

308
src/Notes-master/src/net/micode/notes/tool/ResourceParser.java
Unescape View File

@ -5,7 +5,7 @@
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
@ -23,67 +23,93 @@ import net.micode.notes.R;
import net.micode.notes.ui.NotesPreferenceActivity;
/**
* 资源解析工具类
* 负责管理笔记背景、字体大小、桌面小部件等资源的ID映射
* 提供常量定义和静态方法获取各类资源
* 资源解析与配置工具类 (Utility Layer - Resource & Configuration)
* <p>
* 核心职责：集中管理便签应用中的所有视觉资源（背景、字体、颜色）的映射和配置逻辑。
* 通过颜色/字体大小ID与Android资源ID之间的双向映射，实现业务逻辑与UI表现的解耦。
* <p>
* 架构设计模式：
* 1. **常量映射**：使用整型常量作为逻辑标识符，通过数组映射到具体的资源ID。
* 2. **静态内部类**：按功能模块（便签背景、列表项背景、小部件背景、文字外观）组织资源映射。
* 3. **配置感知**：根据用户偏好设置（如随机背景色开关）动态确定默认值。
* <p>
* 关键特性：
* - **可配置性**：支持通过设置调整默认背景颜色和字体大小。
* - **一致性**：确保编辑界面、列表界面和小部件界面使用统一的颜色主题。
* - **可维护性**：集中管理所有颜色/字体相关资源，便于主题更换和扩展。
*/
public class ResourceParser {
// 背景颜色常量定义
public static final int YELLOW = 0;
public static final int BLUE = 1;
public static final int WHITE = 2;
public static final int GREEN = 3;
public static final int RED = 4;
// ==================== 颜色常量（逻辑标识符） ====================
// 默认背景颜色
/** 颜色标识：黄色主题 */
public static final int YELLOW = 0;
/** 颜色标识：蓝色主题 */
public static final int BLUE = 1;
/** 颜色标识：白色主题 */
public static final int WHITE = 2;
/** 颜色标识：绿色主题 */
public static final int GREEN = 3;
/** 颜色标识：红色主题 */
public static final int RED = 4;
/** 默认背景颜色标识符 */
public static final int BG_DEFAULT_COLOR = YELLOW;
// 字体大小常量定义
public static final int TEXT_SMALL = 0;
public static final int TEXT_MEDIUM = 1;
public static final int TEXT_LARGE = 2;
public static final int TEXT_SUPER = 3;
// ==================== 字体大小常量（逻辑标识符） ====================
/** 字体大小：小 */
public static final int TEXT_SMALL = 0;
/** 字体大小：中 */
public static final int TEXT_MEDIUM = 1;
/** 字体大小：大 */
public static final int TEXT_LARGE = 2;
/** 字体大小：超大 */
public static final int TEXT_SUPER = 3;
// 默认字体大小
/** 默认字体大小标识符 */
public static final int BG_DEFAULT_FONT_SIZE = TEXT_MEDIUM;
/**
* 笔记编辑界面背景资源类
* 管理编辑页面不同颜色主题的背景图片
* 便签编辑界面背景资源映射工具类。
* <p>
* 包含便签内容区域和标题区域的背景图片资源映射。
* 每个颜色标识符对应一组（内容+标题）背景资源。
*/
public static class NoteBgResources {
// 编辑界面背景资源数组，索引对应颜色常量
private final static int [] BG_EDIT_RESOURCES = new int [] {
R.drawable.edit_yellow,
R.drawable.edit_blue,
R.drawable.edit_white,
R.drawable.edit_green,
R.drawable.edit_red
/** 便签内容区域背景资源数组，按颜色标识符索引 */
private final static int[] BG_EDIT_RESOURCES = new int[] {
R.drawable.edit_yellow, // YELLOW -> edit_yellow.png
R.drawable.edit_blue, // BLUE -> edit_blue.png
R.drawable.edit_white, // WHITE -> edit_white.png
R.drawable.edit_green, // GREEN -> edit_green.png
R.drawable.edit_red // RED -> edit_red.png
};
// 编辑界面标题栏背景资源数组
private final static int [] BG_EDIT_TITLE_RESOURCES = new int [] {
R.drawable.edit_title_yellow,
R.drawable.edit_title_blue,
R.drawable.edit_title_white,
R.drawable.edit_title_green,
R.drawable.edit_title_red
/** 便签标题区域背景资源数组，按颜色标识符索引 */
private final static int[] BG_EDIT_TITLE_RESOURCES = new int[] {
R.drawable.edit_title_yellow,
R.drawable.edit_title_blue,
R.drawable.edit_title_white,
R.drawable.edit_title_green,
R.drawable.edit_title_red
};
/**
* 获取笔记编辑界面背景资源ID
* @param id 颜色常量索引
* @return 背景资源ID
* 根据颜色标识符获取便签内容区域的背景资源ID。
*
* @param id 颜色标识符（YELLOW, BLUE, WHITE, GREEN, RED）。
* @return 对应的可绘制资源ID。
*/
public static int getNoteBgResource(int id) {
return BG_EDIT_RESOURCES[id];
}
/**
* 获取笔记标题栏背景资源ID
* @param id 颜色常量索引
* @return 标题栏背景资源ID
* 根据颜色标识符获取便签标题区域的背景资源ID。
*
* @param id 颜色标识符（YELLOW, BLUE, WHITE, GREEN, RED）。
* @return 对应的可绘制资源ID。
*/
public static int getNoteTitleBgResource(int id) {
return BG_EDIT_TITLE_RESOURCES[id];
@ -91,103 +117,115 @@ public class ResourceParser {
}
/**
* 获取默认背景颜色ID
* 根据用户设置决定是随机颜色还是固定黄色
* @param context 应用上下文
* @return 背景颜色常量索引
* 根据用户设置获取默认背景颜色标识符。
* <p>
* 读取用户偏好设置，如果启用了"随机背景颜色"功能，则随机返回一个颜色标识；
* 否则返回默认的黄色背景。
*
* @param context 应用上下文，用于访问SharedPreferences。
* @return 背景颜色标识符。
*/
public static int getDefaultBgId(Context context) {
// 检查用户是否启用了随机背景色设置
// 检查用户是否启用了"随机背景颜色"功能
if (PreferenceManager.getDefaultSharedPreferences(context).getBoolean(
NotesPreferenceActivity.PREFERENCE_SET_BG_COLOR_KEY, false)) {
// 生成随机颜色索引
// 随机选择一个颜色
return (int) (Math.random() * NoteBgResources.BG_EDIT_RESOURCES.length);
} else {
// 返回默认黄色
// 使用默认颜色（黄色）
return BG_DEFAULT_COLOR;
}
}
/**
* 笔记列表项背景资源类
* 管理列表中不同位置（首项、中间项、末项、单项）的背景图片
* 便签列表项背景资源映射工具类。
* <p>
* 为列表中的不同位置（第一项、中间项、最后一项、单项）提供不同的背景资源，
* 以实现视觉上的连续性和区分度。
*/
public static class NoteItemBgResources {
// 列表首项背景资源数组
private final static int [] BG_FIRST_RESOURCES = new int [] {
R.drawable.list_yellow_up,
R.drawable.list_blue_up,
R.drawable.list_white_up,
R.drawable.list_green_up,
R.drawable.list_red_up
/** 列表第一项背景资源数组 */
private final static int[] BG_FIRST_RESOURCES = new int[] {
R.drawable.list_yellow_up,
R.drawable.list_blue_up,
R.drawable.list_white_up,
R.drawable.list_green_up,
R.drawable.list_red_up
};
// 列表中间项背景资源数组
private final static int [] BG_NORMAL_RESOURCES = new int [] {
R.drawable.list_yellow_middle,
R.drawable.list_blue_middle,
R.drawable.list_white_middle,
R.drawable.list_green_middle,
R.drawable.list_red_middle
/** 列表中间项背景资源数组 */
private final static int[] BG_NORMAL_RESOURCES = new int[] {
R.drawable.list_yellow_middle,
R.drawable.list_blue_middle,
R.drawable.list_white_middle,
R.drawable.list_green_middle,
R.drawable.list_red_middle
};
// 列表末项背景资源数组
private final static int [] BG_LAST_RESOURCES = new int [] {
R.drawable.list_yellow_down,
R.drawable.list_blue_down,
R.drawable.list_white_down,
R.drawable.list_green_down,
R.drawable.list_red_down,
/** 列表最后一项背景资源数组 */
private final static int[] BG_LAST_RESOURCES = new int[] {
R.drawable.list_yellow_down,
R.drawable.list_blue_down,
R.drawable.list_white_down,
R.drawable.list_green_down,
R.drawable.list_red_down,
};
// 列表单一项背景资源数组（只有一项时使用）
private final static int [] BG_SINGLE_RESOURCES = new int [] {
R.drawable.list_yellow_single,
R.drawable.list_blue_single,
R.drawable.list_white_single,
R.drawable.list_green_single,
R.drawable.list_red_single
/** 列表只有一项时的背景资源数组 */
private final static int[] BG_SINGLE_RESOURCES = new int[] {
R.drawable.list_yellow_single,
R.drawable.list_blue_single,
R.drawable.list_white_single,
R.drawable.list_green_single,
R.drawable.list_red_single
};
/**
* 获取列表首项背景资源ID
* @param id 颜色常量索引
* @return 背景资源ID
* 获取列表第一项的背景资源ID。
*
* @param id 颜色标识符。
* @return 对应的可绘制资源ID。
*/
public static int getNoteBgFirstRes(int id) {
return BG_FIRST_RESOURCES[id];
}
/**
* 获取列表末项背景资源ID
* @param id 颜色常量索引
* @return 背景资源ID
* 获取列表最后一项的背景资源ID。
*
* @param id 颜色标识符。
* @return 对应的可绘制资源ID。
*/
public static int getNoteBgLastRes(int id) {
return BG_LAST_RESOURCES[id];
}
/**
* 获取列表单一项背景资源ID
* @param id 颜色常量索引
* @return 背景资源ID
* 获取列表只有一项时的背景资源ID。
*
* @param id 颜色标识符。
* @return 对应的可绘制资源ID。
*/
public static int getNoteBgSingleRes(int id) {
return BG_SINGLE_RESOURCES[id];
}
/**
* 获取列表中间项背景资源ID
* @param id 颜色常量索引
* @return 背景资源ID
* 获取列表中间项的背景资源ID。
*
* @param id 颜色标识符。
* @return 对应的可绘制资源ID。
*/
public static int getNoteBgNormalRes(int id) {
return BG_NORMAL_RESOURCES[id];
}
/**
* 获取文件夹背景资源ID（固定资源）
* @return 文件夹背景资源ID
* 获取文件夹列表项的特殊背景资源ID。
* <p>
* 文件夹在列表中采用统一的外观，不区分颜色。
*
* @return 文件夹列表项背景资源ID。
*/
public static int getFolderBgRes() {
return R.drawable.list_folder;
@ -195,41 +233,45 @@ public class ResourceParser {
}
/**
* 桌面小部件背景资源类
* 管理2x2和4x4尺寸小部件的背景图片
* 桌面小部件背景资源映射工具类。
* <p>
* 为不同尺寸的小部件提供背景资源映射。
* 目前支持2x1和4x1两种尺寸的小部件。
*/
public static class WidgetBgResources {
// 2x2小部件背景资源数组
private final static int [] BG_2X_RESOURCES = new int [] {
R.drawable.widget_2x_yellow,
R.drawable.widget_2x_blue,
R.drawable.widget_2x_white,
R.drawable.widget_2x_green,
R.drawable.widget_2x_red,
/** 2x1小部件背景资源数组 */
private final static int[] BG_2X_RESOURCES = new int[] {
R.drawable.widget_2x_yellow,
R.drawable.widget_2x_blue,
R.drawable.widget_2x_white,
R.drawable.widget_2x_green,
R.drawable.widget_2x_red,
};
/**
* 获取2x2小部件背景资源ID
* @param id 颜色常量索引
* @return 背景资源ID
* 获取2x1小部件的背景资源ID。
*
* @param id 颜色标识符。
* @return 对应的可绘制资源ID。
*/
public static int getWidget2xBgResource(int id) {
return BG_2X_RESOURCES[id];
}
// 4x4小部件背景资源数组
private final static int [] BG_4X_RESOURCES = new int [] {
R.drawable.widget_4x_yellow,
R.drawable.widget_4x_blue,
R.drawable.widget_4x_white,
R.drawable.widget_4x_green,
R.drawable.widget_4x_red
/** 4x1小部件背景资源数组 */
private final static int[] BG_4X_RESOURCES = new int[] {
R.drawable.widget_4x_yellow,
R.drawable.widget_4x_blue,
R.drawable.widget_4x_white,
R.drawable.widget_4x_green,
R.drawable.widget_4x_red
};
/**
* 获取4x4小部件背景资源ID
* @param id 颜色常量索引
* @return 背景资源ID
* 获取4x1小部件的背景资源ID。
*
* @param id 颜色标识符。
* @return 对应的可绘制资源ID。
*/
public static int getWidget4xBgResource(int id) {
return BG_4X_RESOURCES[id];
@ -237,37 +279,43 @@ public class ResourceParser {
}
/**
* 文本外观资源类
* 管理不同字体大小的样式资源
* 文字外观样式资源映射工具类。
* <p>
* 将字体大小标识符映射到Android样式资源ID，用于统一应用文字外观。
*/
public static class TextAppearanceResources {
// 字体大小样式资源数组，索引对应字体大小常量
private final static int [] TEXTAPPEARANCE_RESOURCES = new int [] {
R.style.TextAppearanceNormal,
R.style.TextAppearanceMedium,
R.style.TextAppearanceLarge,
R.style.TextAppearanceSuper
/** 文字样式资源数组，按字体大小标识符索引 */
private final static int[] TEXTAPPEARANCE_RESOURCES = new int[] {
R.style.TextAppearanceNormal, // TEXT_SMALL
R.style.TextAppearanceMedium, // TEXT_MEDIUM
R.style.TextAppearanceLarge, // TEXT_LARGE
R.style.TextAppearanceSuper // TEXT_SUPER
};
/**
* 获取文本外观资源ID
* @param id 字体大小常量索引
* @return 样式资源ID
* 根据字体大小标识符获取对应的文字样式资源ID。
* <p>
* 包含防御性检查：如果标识符超出资源数组范围，则返回默认字体大小标识符。
* 这种情况可能发生在升级或数据损坏时，旧版本的字体大小标识符与新版本不匹配。
*
* @param id 字体大小标识符。
* @return 对应的样式资源ID，如果id无效则返回{@link #BG_DEFAULT_FONT_SIZE}。
*/
public static int getTexAppearanceResource(int id) {
/**
* HACKME: 修复将资源ID存储在SharedPreference中的bug
* 存储的ID可能大于资源数组长度，此时返回默认字体大小
*/
// 防御性检查：防止数组越界
if (id >= TEXTAPPEARANCE_RESOURCES.length) {
return BG_DEFAULT_FONT_SIZE; // 越界时返回默认值
// 如果标识符超出范围，返回默认字体大小标识符
return BG_DEFAULT_FONT_SIZE;
}
return TEXTAPPEARANCE_RESOURCES[id];
}
/**
* 获取可用资源数量
* @return 字体大小选项总数
* 获取可用的文字样式资源数量。
* <p>
* 用于验证字体大小标识符的有效范围。
*
* @return 文字样式资源的数量。
*/
public static int getResourcesSize() {
return TEXTAPPEARANCE_RESOURCES.length;

Write Preview
Loading…
Cancel
Save