From 866d343773a495018e7318844cddd522720bc8e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E7=8E=89=E7=88=B1?= <3540412807@qq.com> Date: Fri, 13 Jun 2025 00:16:31 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B3=A8=E9=87=8Av2.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- java/net/micode/notes/data/Notes.java | 29 +-- .../notes/data/NotesDatabaseHelper.java | 180 +++++++++++++++- java/net/micode/notes/data/NotesProvider.java | 107 +++++++++- java/net/micode/notes/gtask/data/SqlData.java | 59 ++++++ java/net/micode/notes/gtask/data/SqlNote.java | 195 ++++++++++++++++++ 5 files changed, 532 insertions(+), 38 deletions(-) diff --git a/java/net/micode/notes/data/Notes.java b/java/net/micode/notes/data/Notes.java index f240604..fdd46a3 100644 --- a/java/net/micode/notes/data/Notes.java +++ b/java/net/micode/notes/data/Notes.java @@ -205,39 +205,18 @@ public class Notes { public static final String CONTENT = "content"; - /** - * Generic data column, the meaning is {@link #MIMETYPE} specific, used for - * integer data type - *
Type: INTEGER
- */ + public static final String DATA1 = "data1"; - /** - * Generic data column, the meaning is {@link #MIMETYPE} specific, used for - * integer data type - *Type: INTEGER
- */ public static final String DATA2 = "data2"; - /** - * Generic data column, the meaning is {@link #MIMETYPE} specific, used for - * TEXT data type - *Type: TEXT
- */ + public static final String DATA3 = "data3"; - /** - * Generic data column, the meaning is {@link #MIMETYPE} specific, used for - * TEXT data type - *Type: TEXT
- */ + public static final String DATA4 = "data4"; - /** - * Generic data column, the meaning is {@link #MIMETYPE} specific, used for - * TEXT data type - *Type: TEXT
- */ + public static final String DATA5 = "data5"; } diff --git a/java/net/micode/notes/data/NotesDatabaseHelper.java b/java/net/micode/notes/data/NotesDatabaseHelper.java index a0bad0b..4882055 100644 --- a/java/net/micode/notes/data/NotesDatabaseHelper.java +++ b/java/net/micode/notes/data/NotesDatabaseHelper.java @@ -52,8 +52,8 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * 1.作用:创建笔记主表结构 - * 2.方法名:CREATE_NOTE_TABLE_SQL - * 3.返回类型:String + * 2.变量名:CREATE_NOTE_TABLE_SQL + * 3.类型:String * 3.功能: * 存储笔记基本信息和元数据 * 支持文件夹嵌套结构 @@ -83,8 +83,8 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * 1.作用:创建笔记内容表结构 - * 2.方法名:CREATE_DATA_TABLE_SQL - * 3.返回类型:String + * 2.变量名:CREATE_DATA_TABLE_SQL + * 3.类型:String * 4.功能: * 存储不同类型的笔记内容 * 支持一对多关系(一个笔记可包含多个内容项) @@ -107,12 +107,12 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * 1.作用:优化笔记内容查询性能 - * 2.方法名:CREATE_DATA_NOTE_ID_INDEX_SQL - * 3.返回值:String + * 2.变量名:CREATE_DATA_NOTE_ID_INDEX_SQL + * 3.类型:String * 4.功能: - * 加速通过笔记 ID 查询相关内容的操作 - * 减少 JOIN 操作时的全表扫描 - * 提升批量数据查询效率 + * 加速通过笔记 ID 查询相关内容的操作 + * 减少 JOIN 操作时的全表扫描 + * 提升批量数据查询效率 */ private static final String CREATE_DATA_NOTE_ID_INDEX_SQL = "CREATE INDEX IF NOT EXISTS note_id_index ON " + @@ -121,6 +121,15 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Increase folder's note count when move note to the folder */ + + /** + * 1. 笔记文件夹计数触发器: + * 2.作用:更新笔记父文件夹时自动维护文件夹的笔记数量统计 + * 3.功能描述: + * - 当笔记的父文件夹(parent_id)发生变更时,自动增加新父文件夹的笔记计数 + * - 触发器在UPDATE操作后执行,确保计数更新与数据变更同步 + * - 通过维护冗余计数字段,避免频繁执行代价高昂的COUNT(*)查询 + */ 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 + @@ -133,6 +142,15 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Decrease folder's note count when move note from folder */ + /** + * 1.作用:维护笔记文件夹计数的完整性 + * 2.变量名:NOTE_DECREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER + * 3.类型:String + * 4.功能: + * 当笔记移动到新文件夹时,减少原文件夹的笔记计数 + * 确保文件夹中的笔记数量统计始终保持准确 + * 防止计数出现负值,通过条件检查确保计数≥0 + */ private static final String NOTE_DECREASE_FOLDER_COUNT_ON_UPDATE_TRIGGER = "CREATE TRIGGER decrease_folder_count_on_update " + " AFTER UPDATE OF " + NoteColumns.PARENT_ID + " ON " + TABLE.NOTE + @@ -146,6 +164,17 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Increase folder's note count when insert new note to the folder */ + + /** + * 1.作用:维护笔记文件夹计数的实时性和准确性 + * 2.变量名:NOTE_INCREASE_FOLDER_COUNT_ON_INSERT_TRIGGER + * 3.类型:String + * 4.功能: + * 当新笔记创建时,自动增加其父文件夹的笔记计数 + * 确保文件夹中的笔记数量统计始终保持准确 + * 避免手动维护计数可能导致的数据不一致问题 + */ + private static final String NOTE_INCREASE_FOLDER_COUNT_ON_INSERT_TRIGGER = "CREATE TRIGGER increase_folder_count_on_insert " + " AFTER INSERT ON " + TABLE.NOTE + @@ -158,6 +187,16 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Decrease folder's note count when delete note from the folder */ + + /** + * 1.作用:维护笔记文件夹计数的完整性 + * 2.变量名:NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER + * 3.类型:String + * 4.功能: + * 当笔记被删除时,自动减少其父文件夹的笔记计数 + * 确保文件夹中的笔记数量统计始终保持准确 + * 通过条件检查防止计数出现负值 + */ private static final String NOTE_DECREASE_FOLDER_COUNT_ON_DELETE_TRIGGER = "CREATE TRIGGER decrease_folder_count_on_delete " + " AFTER DELETE ON " + TABLE.NOTE + @@ -171,6 +210,17 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Update note's content when insert data with type {@link DataConstants#NOTE} */ + + /** + /** + * 1.作用:维护笔记内容与数据记录的同步性 + * 2.变量名:DATA_UPDATE_NOTE_CONTENT_ON_INSERT_TRIGGER + * 3.类型:String + * 4.功能: + * 当新的笔记数据记录插入时,自动更新关联笔记的摘要内容 + * 确保笔记列表中能快速显示最新的笔记内容片段 + * 仅对MIME类型为笔记的数据记录生效,避免处理其他类型数据 + */ private static final String DATA_UPDATE_NOTE_CONTENT_ON_INSERT_TRIGGER = "CREATE TRIGGER update_note_content_on_insert " + " AFTER INSERT ON " + TABLE.DATA + @@ -184,6 +234,16 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Update note's content when data with {@link DataConstants#NOTE} type has changed */ + + /** + * 1.作用:维护笔记摘要与内容数据的实时同步 + * 2.变量名:DATA_UPDATE_NOTE_CONTENT_ON_UPDATE_TRIGGER + * 3.类型:String + * 4.功能: + * 当笔记内容数据更新时,自动同步更新笔记的摘要字段 + * 确保笔记列表中显示的内容预览始终反映最新修改 + * 通过条件过滤仅处理MIME类型为笔记的数据记录 + */ private static final String DATA_UPDATE_NOTE_CONTENT_ON_UPDATE_TRIGGER = "CREATE TRIGGER update_note_content_on_update " + " AFTER UPDATE ON " + TABLE.DATA + @@ -197,6 +257,15 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Update note's content when data with {@link DataConstants#NOTE} type has deleted */ + /** + * 1.作用:维护笔记摘要与内容数据的一致性 + * 2.变量名:DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER + * 3.类型:String + * 4.功能: + * 当笔记内容数据被删除时,自动清空关联笔记的摘要字段 + * 确保笔记列表中不会显示已删除的内容预览 + * 通过条件过滤仅处理MIME类型为笔记的数据记录 + */ private static final String DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER = "CREATE TRIGGER update_note_content_on_delete " + " AFTER delete ON " + TABLE.DATA + @@ -210,6 +279,15 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Delete datas belong to note which has been deleted */ + /** + * 1.作用:维护数据完整性,实现级联删除 + * 2.变量名:NOTE_DELETE_DATA_ON_DELETE_TRIGGER + * 3.类型:String + * 4.功能: + * 当笔记主记录被删除时,自动删除该笔记关联的所有内容数据 + * 确保数据库中不会残留无主的数据记录 + * 实现逻辑上的级联删除,避免数据孤岛 + */ private static final String NOTE_DELETE_DATA_ON_DELETE_TRIGGER = "CREATE TRIGGER delete_data_on_delete " + " AFTER DELETE ON " + TABLE.NOTE + @@ -221,6 +299,15 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Delete notes belong to folder which has been deleted */ + /** + * 1.作用:维护文件夹层级结构的完整性,实现级联删除 + * 2.变量名:FOLDER_DELETE_NOTES_ON_DELETE_TRIGGER + * 3.类型:String + * 4.功能: + * 当文件夹被删除时,自动删除该文件夹下的所有子笔记 + * 确保数据库中不会残留无主的笔记记录 + * 实现树形结构中的级联删除,避免数据孤岛 + */ private static final String FOLDER_DELETE_NOTES_ON_DELETE_TRIGGER = "CREATE TRIGGER folder_delete_notes_on_delete " + " AFTER DELETE ON " + TABLE.NOTE + @@ -232,6 +319,15 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { /** * Move notes belong to folder which has been moved to trash folder */ + /** + * 1.作用:维护回收站功能的完整性,实现文件夹级联移动 + * 2.变量名:FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER + * 3.类型:String + * 4.功能: + * 当文件夹被移入回收站时,自动将该文件夹下的所有子笔记也移入回收站 + * 确保文件夹及其内容在回收站中保持层级关系 + * 实现树形结构中的级联移动,避免子笔记遗留在原位置 + */ private static final String FOLDER_MOVE_NOTES_ON_TRASH_TRIGGER = "CREATE TRIGGER folder_move_notes_on_trash " + " AFTER UPDATE ON " + TABLE.NOTE + @@ -342,7 +438,13 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { db.insert(TABLE.NOTE, null, values); } - + /** + * 1.作用:创建系统默认文件夹 + * 2.方法名:createSystemFolder + * 3.参数: + * SQLiteDatabase db:数据库实例 + * 4.返回类型:void + */ public void createDataTable(SQLiteDatabase db) { db.execSQL(CREATE_DATA_TABLE_SQL); reCreateDataTableTriggers(db); @@ -350,7 +452,15 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { Log.d(TAG, "data table has been created"); } - + /** + * 1.作用:重建数据表相关触发器 + * 2.方法名:reCreateDataTableTriggers + * 3.参数: + * SQLiteDatabase db:数据库实例 + * 4.返回类型:void + * 5.功能: + * 删除旧版触发器(插入/更新/删除) + */ private void reCreateDataTableTriggers(SQLiteDatabase db) { db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_insert"); db.execSQL("DROP TRIGGER IF EXISTS update_note_content_on_update"); @@ -361,6 +471,17 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { db.execSQL(DATA_UPDATE_NOTE_CONTENT_ON_DELETE_TRIGGER); } + /** + * 1.作用:获取NotesDatabaseHelper的单例实例 + * 2.方法名:getInstance + * 3.参数: + * Context context:应用上下文 + * 4.返回类型:NotesDatabaseHelper + * 5.功能: + * 确保全局只有一个数据库帮助类实例 + * 避免多实例导致的数据库连接冲突 + * 提供线程安全的实例访问方式 + */ static synchronized NotesDatabaseHelper getInstance(Context context) { if (mInstance == null) { mInstance = new NotesDatabaseHelper(context); @@ -374,6 +495,20 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { createDataTable(db); } + /** + * 1.作用:执行数据库版本升级 + * 2.方法名:onUpgrade + * 3.参数: + * SQLiteDatabase db:数据库实例 + * int oldVersion:当前数据库版本 + * int newVersion:目标数据库版本 + * 4.返回类型:void + * 5.功能: + * 处理跨版本升级路径 + * 执行特定版本的升级脚本 + * 在必要时重建触发器 + * 验证升级是否成功完成 + */ @Override public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { boolean reCreateTriggers = false; @@ -407,6 +542,17 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { } } + /** + * 1.作用:将数据库升级到版本2 + * 2.方法名:upgradeToV2 + * 3.参数: + * SQLiteDatabase db:数据库实例 + * 4.返回类型:void + * 5.功能: + * 删除旧版笔记表和数据表 + * 重新创建新版笔记表和数据表 + * 实现版本1到版本2的结构转换 + */ private void upgradeToV2(SQLiteDatabase db) { db.execSQL("DROP TABLE IF EXISTS " + TABLE.NOTE); db.execSQL("DROP TABLE IF EXISTS " + TABLE.DATA); @@ -414,6 +560,18 @@ public class NotesDatabaseHelper extends SQLiteOpenHelper { createDataTable(db); } + /** + * 1.作用:将数据库升级到版本3 + * 2.方法名:upgradeToV3 + * 3.参数: + * SQLiteDatabase db:数据库实例 + * 4.返回类型:void + * 5.功能: + * 删除不再使用的触发器 + * 添加Gtask ID字段用于Google任务同步 + * 创建回收站系统文件夹 + * 为版本3新增功能做准备 + */ private void upgradeToV3(SQLiteDatabase db) { // drop unused triggers db.execSQL("DROP TRIGGER IF EXISTS update_note_modified_date_on_insert"); diff --git a/java/net/micode/notes/data/NotesProvider.java b/java/net/micode/notes/data/NotesProvider.java index edb0a60..df08c42 100644 --- a/java/net/micode/notes/data/NotesProvider.java +++ b/java/net/micode/notes/data/NotesProvider.java @@ -36,6 +36,19 @@ import net.micode.notes.data.NotesDatabaseHelper.TABLE; public class NotesProvider extends ContentProvider { + /** + * 1.作用:笔记内容提供者常量定义 + * 2.常量类型: + * UriMatcher mMatcher:用于匹配内容URI的匹配器 + * NotesDatabaseHelper mHelper:数据库操作辅助类 + * String TAG:日志标签 + * int URI_*:URI匹配码 + * 3.功能: + * mMatcher:解析和匹配客户端请求的内容URI + * mHelper:提供对数据库的访问接口 + * TAG:用于日志记录,便于调试和问题追踪 + * URI_*:定义不同类型URI的匹配码,用于路由请求 + */ private static final UriMatcher mMatcher; private NotesDatabaseHelper mHelper; @@ -61,9 +74,16 @@ public class NotesProvider extends ContentProvider { mMatcher.addURI(Notes.AUTHORITY, SearchManager.SUGGEST_URI_PATH_QUERY + "/*", URI_SEARCH_SUGGEST); } + /** - * x'0A' represents the '\n' character in sqlite. For title and content in the search result, - * we will trim '\n' and white space in order to show more information. + * 1.作用:定义笔记搜索结果的SQL投影列 + * 2.变量:NOTES_SEARCH_PROJECTION + * 3.类型:String + * 4.功能: + * 配置搜索结果的列映射,使其符合Android搜索框架要求 + * 格式化笔记摘要内容,移除换行符并修剪空格 + * 为搜索建议提供图标、操作类型和数据类型信息 + * 支持点击搜索结果直接查看笔记详情 */ private static final String NOTES_SEARCH_PROJECTION = NoteColumns.ID + "," + NoteColumns.ID + " AS " + SearchManager.SUGGEST_COLUMN_INTENT_EXTRA_DATA + "," @@ -73,6 +93,17 @@ public class NotesProvider extends ContentProvider { + "'" + Intent.ACTION_VIEW + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_ACTION + "," + "'" + Notes.TextNote.CONTENT_TYPE + "' AS " + SearchManager.SUGGEST_COLUMN_INTENT_DATA; + + /** + * 1.作用:定义笔记摘要内容搜索的SQL查询语句 + * 2.变量名:NOTES_SNIPPET_SEARCH_QUERY + * 3.类型:String + * 4.功能: + * 在笔记摘要字段中执行模糊搜索 + * 排除回收站中的笔记 + * 仅搜索普通笔记类型(TYPE_NOTE) + * 返回符合搜索框架要求的格式化结果 + */ private static String NOTES_SNIPPET_SEARCH_QUERY = "SELECT " + NOTES_SEARCH_PROJECTION + " FROM " + TABLE.NOTE + " WHERE " + NoteColumns.SNIPPET + " LIKE ?" @@ -85,6 +116,22 @@ public class NotesProvider extends ContentProvider { return true; } + /** + * 1.作用:处理内容URI查询请求 + * 2.方法名:query + * 3.参数: + * Uri uri:请求的内容URI + * String[] projection:要返回的列,null表示返回所有列 + * String selection:WHERE子句,null表示返回所有行 + * String[] selectionArgs:WHERE子句参数 + * String sortOrder:排序方式 + * 4.返回类型:Cursor + * 5.功能: + * 根据URI匹配类型执行不同的查询逻辑 + * 支持查询笔记列表、单个笔记、数据列表、单个数据 + * 实现搜索和搜索建议功能 + * 设置结果通知URI,支持数据变化监听 + */ @Override public Cursor query(Uri uri, String[] projection, String selection, String[] selectionArgs, String sortOrder) { @@ -147,6 +194,20 @@ public class NotesProvider extends ContentProvider { return c; } + /** + * 1.作用:处理内容URI插入请求 + * 2.方法名:insert + * 3.参数: + * Uri uri:请求的内容URI + * ContentValues values:要插入的数据 + * 4.返回类型:Uri + * 5.功能: + * 根据URI匹配类型执行不同的插入逻辑 + * 支持插入笔记和笔记内容数据 + * 自动关联笔记ID和内容数据 + * 发送数据变化通知,触发监听更新 + * 返回包含新插入记录ID的URI + */ @Override public Uri insert(Uri uri, ContentValues values) { SQLiteDatabase db = mHelper.getWritableDatabase(); @@ -181,6 +242,20 @@ public class NotesProvider extends ContentProvider { return ContentUris.withAppendedId(uri, insertedId); } + /** + * 1.作用:处理内容URI删除请求 + * 2.方法名:delete + * 3.参数: + * Uri uri:请求的内容URI + * String selection:WHERE子句,null表示删除所有行 + * String[] selectionArgs:WHERE子句参数 + * 4.返回类型:int + * 5.功能: + * 根据URI匹配类型执行不同的删除逻辑 + * 支持删除笔记和笔记内容数据 + * 保护系统文件夹不被删除(ID≤0) + * 发送数据变化通知,触发监听更新 + */ @Override public int delete(Uri uri, String selection, String[] selectionArgs) { int count = 0; @@ -227,6 +302,21 @@ public class NotesProvider extends ContentProvider { return count; } + /** + * 1.作用:处理内容URI更新请求 + * 2.方法名:update + * 3.参数: + * Uri uri:请求的内容URI + * ContentValues values:要更新的数据 + * String selection:WHERE子句,null表示更新所有行 + * String[] selectionArgs:WHERE子句参数 + * 4.返回类型:int + * 5.功能: + * 根据URI匹配类型执行不同的更新逻辑 + * 支持更新笔记和笔记内容数据 + * 更新笔记时自动增加版本号 + * 发送数据变化通知,触发监听更新 + */ @Override public int update(Uri uri, ContentValues values, String selection, String[] selectionArgs) { int count = 0; @@ -271,6 +361,19 @@ public class NotesProvider extends ContentProvider { return (!TextUtils.isEmpty(selection) ? " AND (" + selection + ')' : ""); } + /** + * 1.作用:增加笔记版本号 + * 2.方法名:increaseNoteVersion + * 3.参数: + * long id:指定要更新的笔记ID,-1表示不指定ID + * String selection:额外的WHERE条件 + * String[] selectionArgs:WHERE条件参数 + * 4.返回类型:void + * 5.功能: + * 为指定笔记或符合条件的笔记增加版本号 + * 版本号用于数据同步和冲突检测 + * 支持单条记录或批量更新 + */ private void increaseNoteVersion(long id, String selection, String[] selectionArgs) { StringBuilder sql = new StringBuilder(120); sql.append("UPDATE "); diff --git a/java/net/micode/notes/gtask/data/SqlData.java b/java/net/micode/notes/gtask/data/SqlData.java index d3ec3be..30a4fef 100644 --- a/java/net/micode/notes/gtask/data/SqlData.java +++ b/java/net/micode/notes/gtask/data/SqlData.java @@ -36,10 +36,13 @@ import org.json.JSONObject; public class SqlData { + //TAG:用于日志记录,方便调试和问题追踪 private static final String TAG = SqlData.class.getSimpleName(); + //INVALID_ID:作为无效 ID 的标识,用于初始化和错误处理 private static final int INVALID_ID = -99999; + // public static final String[] PROJECTION_DATA = new String[] { DataColumns.ID, DataColumns.MIME_TYPE, DataColumns.CONTENT, DataColumns.DATA1, DataColumns.DATA3 @@ -71,6 +74,12 @@ public class SqlData { private ContentValues mDiffDataValues; + /** + * 1.作用:构造函数 + * 2.初始化 ContentResolver: + * 从传入的 Context 获取 ContentResolver 实例 + * 用于后续与 ContentProvider 交互 + */ public SqlData(Context context) { mContentResolver = context.getContentResolver(); mIsCreate = true; @@ -82,6 +91,12 @@ public class SqlData { mDiffDataValues = new ContentValues(); } + /** + * 1.作用:构造函数(两个参数) + * 2.初始化 ContentResolver: + * 从传入的 Context 获取 ContentResolver 实例 + * 用于后续与 ContentProvider 交互 + */ public SqlData(Context context, Cursor c) { mContentResolver = context.getContentResolver(); mIsCreate = false; @@ -89,6 +104,15 @@ public class SqlData { mDiffDataValues = new ContentValues(); } + /** + 1.作用:从Cursor中加载数据到当前对象 + * 2.方法名:loadFromCursor + * 3.参数: * Cursor c:包含数据的Cursor对象 + * 4.返回类型:void * 5.功能: + * 将Cursor中的数据映射到SqlData对象的成员变量 + * 使用预定义的列索引常量定位数据 + * 支持从数据库查询结果中初始化对象 + */ private void loadFromCursor(Cursor c) { mDataId = c.getLong(DATA_ID_COLUMN); mDataMimeType = c.getString(DATA_MIME_TYPE_COLUMN); @@ -97,6 +121,17 @@ public class SqlData { mDataContentData3 = c.getString(DATA_CONTENT_DATA_3_COLUMN); } + /** + * 1.作用:从JSONObject设置数据到当前对象 + * 2.方法名:setContent + * 3.参数: + * JSONObject js:包含数据的JSON对象 + * 4.返回类型:void + * 5.功能: + * 从JSON对象解析数据并设置到SqlData对象 + * 自动检测数据变化并记录差异 + * 支持默认值处理和类型转换 + */ public void setContent(JSONObject js) throws JSONException { long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID; if (mIsCreate || mDataId != dataId) { @@ -130,6 +165,16 @@ public class SqlData { mDataContentData3 = dataContentData3; } + /** + 1.作用:将当前对象数据导出为JSON对象 + * 2.方法名:getContent + * 3.参数:无 + * 4.返回类型:JSONObject + * 5.功能: + * 将SqlData对象的成员变量转换为JSON格式 + * 支持数据序列化和跨组件传递 + * 用于数据导出、网络传输和持久化存储 + */ public JSONObject getContent() throws JSONException { if (mIsCreate) { Log.e(TAG, "it seems that we haven't created this in database yet"); @@ -144,6 +189,20 @@ public class SqlData { return js; } + /** + * 1.作用:将数据变更提交到数据库 + * 2.方法名:commit + * 3.参数: + * long noteId:关联的笔记ID + * boolean validateVersion:是否验证版本号 + * long version:用于验证的版本号 + * 4.返回类型:void + * 5.功能: + * 根据对象状态执行插入或更新操作 + * 支持版本验证,防止并发修改冲突 + * 自动清除差异值跟踪容器 + * 更新对象状态为已创建 + */ public void commit(long noteId, boolean validateVersion, long version) { if (mIsCreate) { diff --git a/java/net/micode/notes/gtask/data/SqlNote.java b/java/net/micode/notes/gtask/data/SqlNote.java index 79a4095..bd2743c 100644 --- a/java/net/micode/notes/gtask/data/SqlNote.java +++ b/java/net/micode/notes/gtask/data/SqlNote.java @@ -43,6 +43,15 @@ public class SqlNote { private static final int INVALID_ID = -99999; + /** + * 1.作用:定义笔记查询的默认投影列 + * 2.常量名:PROJECTION_NOTE + * 3.类型:String[] + * 4.功能: + * 指定查询笔记表时默认返回的列 + * 优化查询性能,避免返回不必要的列 + * 统一数据访问接口,降低耦合度 + */ public static final String[] PROJECTION_NOTE = new String[] { NoteColumns.ID, NoteColumns.ALERTED_DATE, NoteColumns.BG_COLOR_ID, NoteColumns.CREATED_DATE, NoteColumns.HAS_ATTACHMENT, NoteColumns.MODIFIED_DATE, @@ -52,6 +61,14 @@ public class SqlNote { NoteColumns.VERSION }; + /** + * 1.作用:定义笔记投影列的索引位置 + * 2.常量类型:int + * 3.功能: + * 为PROJECTION_NOTE数组中的列定义固定索引 + * 在Cursor操作中快速定位特定列 + * 避免直接使用魔法数字,提高代码可读性 + */ public static final int ID_COLUMN = 0; public static final int ALERTED_DATE_COLUMN = 1; @@ -86,26 +103,114 @@ public class SqlNote { public static final int VERSION_COLUMN = 16; + /** + * 1.作用:应用上下文引用 + * 2.类型:Context + * 3.功能: + * 提供应用环境资源访问 + * 初始化ContentResolver + * 获取系统服务 + */ private Context mContext; + /** + * 1.作用:内容解析器 + * 2.类型:ContentResolver + * 3.功能: + * 执行数据库CRUD操作 + * 发送数据变化通知 + * 跨进程数据共享 + */ private ContentResolver mContentResolver; + /** + * 1.作用:对象创建状态标识 + * 2.类型:boolean + * 3.功能: + * 标记对象是否为新建状态 + * 决定保存操作类型(插入/更新) + * 控制差异值跟踪逻辑 + */ private boolean mIsCreate; + /** + * 1.作用:笔记ID + * 2.类型:long + * 3.功能: + * 笔记唯一标识 + * 数据库主键 + * 关联其他数据的外键 + */ private long mId; + /** + * 1.作用:提醒日期 + * 2.类型:long + * 3.功能: + * 存储笔记提醒时间戳 + * 用于日历提醒功能 + * 支持定时通知 + */ private long mAlertDate; + /** + * 1.作用:背景颜色ID + * 2.类型:int + * 3.功能: + * 存储笔记背景颜色标识 + * 用于UI展示差异化 + * 支持主题切换 + */ private int mBgColorId; + /** + * 1.作用:创建日期 + * 2.类型:long + * 3.功能: + * 记录笔记创建时间戳 + * 用于排序和过滤 + * 数据同步参考 + */ private long mCreatedDate; + /** + * 1.作用:附件状态 + * 2.类型:int + * 3.功能: + * 标记笔记是否包含附件 + * 0表示无附件 + * 1表示有附件 + */ private int mHasAttachment; + /** + * 1.作用:修改日期 + * 2.类型:long + * 3.功能: + * 记录笔记最后修改时间戳 + * 用于排序和同步 + * 版本控制参考 + */ private long mModifiedDate; + /** + * 1.作用:父文件夹ID + * 2.类型:long + * 3.功能: + * 定义笔记所属文件夹 + * 支持笔记分类管理 + * 构建笔记层级结构 + */ private long mParentId; + /** + * 1.作用:笔记摘要 + * 2.类型:String + * 3.功能: + * 存储笔记内容摘要 + * 用于列表快速预览 + * 搜索匹配字段 + */ private String mSnippet; private int mType; @@ -122,6 +227,16 @@ public class SqlNote { private ArrayList