添加注释

src/Notes-master/app/src/main/java/net/micode/notes/gtask/data/SqlData.java

@@ -34,61 +34,70 @@ import net.micode.notes.gtask.exception.ActionFailureException;
 import org.json.JSONException;
 import org.json.JSONObject;
 
-
+/**
+ * SqlData 类用于封装便签数据（data表）的数据库操作，
+ * 提供对便签内容（如文本、通话记录等）的创建、更新和提交功能，支持与 Google Tasks 同步的数据处理。
+ */
 public class SqlData {
     private static final String TAG = SqlData.class.getSimpleName();
+    private static final int INVALID_ID = -99999; // 无效ID标识
 
-    private static final int INVALID_ID = -99999;
+    // 数据库查询投影列（对应data表字段）
-
     public static final String[] PROJECTION_DATA = new String[] {
-            DataColumns.ID, DataColumns.MIME_TYPE, DataColumns.CONTENT, DataColumns.DATA1,
+            DataColumns.ID,         // 数据项ID
-            DataColumns.DATA3
+            DataColumns.MIME_TYPE,  // MIME类型
+            DataColumns.CONTENT,    // 内容
+            DataColumns.DATA1,      // 通用数据1（整数）
+            DataColumns.DATA3       // 通用数据3（文本）
     };
 
+    // 投影列索引
     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;
 
-    private ContentResolver mContentResolver;
+    private ContentResolver mContentResolver; // 内容解析器，用于操作内容提供者
-
+    private boolean mIsCreate;                 // 是否为新建数据（true=新建，false=已存在）
-    private boolean mIsCreate;
+    private long mDataId;                      // 数据项ID
-
+    private String mDataMimeType;              // MIME类型（默认文本便签）
-    private long mDataId;
+    private String mDataContent;               // 数据内容
-
+    private long mDataContentData1;            // 通用整数型数据
-    private String mDataMimeType;
+    private String mDataContentData3;          // 通用文本型数据
-
+    private ContentValues mDiffDataValues;     // 变更数据缓存（用于批量提交）
-    private String mDataContent;
+
-
+    /**
-    private long mDataContentData1;
+     * 构造函数（新建数据场景）
-
+     * @param context 应用上下文
-    private String mDataContentData3;
+     */
-
-    private ContentValues mDiffDataValues;
-
     public SqlData(Context context) {
         mContentResolver = context.getContentResolver();
         mIsCreate = true;
         mDataId = INVALID_ID;
-        mDataMimeType = DataConstants.NOTE;
+        mDataMimeType = DataConstants.NOTE; // 默认MIME类型为文本便签
         mDataContent = "";
         mDataContentData1 = 0;
         mDataContentData3 = "";
         mDiffDataValues = new ContentValues();
     }
 
+    /**
+     * 构造函数（从数据库查询结果初始化）
+     * @param context 应用上下文
+     * @param c 数据库游标（指向data表记录）
+     */
     public SqlData(Context context, Cursor c) {
         mContentResolver = context.getContentResolver();
         mIsCreate = false;
-        loadFromCursor(c);
+        loadFromCursor(c); // 从游标加载数据
         mDiffDataValues = new ContentValues();
     }
 
+    /**
+     * 从游标加载数据到对象属性
+     * @param c 数据库游标
+     */
     private void loadFromCursor(Cursor c) {
         mDataId = c.getLong(DATA_ID_COLUMN);
         mDataMimeType = c.getString(DATA_MIME_TYPE_COLUMN);
@@ -97,43 +106,58 @@ public class SqlData {
         mDataContentData3 = c.getString(DATA_CONTENT_DATA_3_COLUMN);
     }
 
+    /**
+     * 根据JSON数据设置内容（支持新建和更新场景）
+     * @param js 包含数据的JSON对象
+     * @throws JSONException JSON解析异常
+     */
     public void setContent(JSONObject js) throws JSONException {
+        // 解析ID
         long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID;
         if (mIsCreate || mDataId != dataId) {
-            mDiffDataValues.put(DataColumns.ID, dataId);
+            mDiffDataValues.put(DataColumns.ID, dataId); // 记录ID变更
         }
         mDataId = dataId;
 
+        // 解析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);
+            mDiffDataValues.put(DataColumns.MIME_TYPE, dataMimeType); // 记录MIME类型变更
         }
         mDataMimeType = dataMimeType;
 
+        // 解析内容
         String dataContent = js.has(DataColumns.CONTENT) ? js.getString(DataColumns.CONTENT) : "";
         if (mIsCreate || !mDataContent.equals(dataContent)) {
-            mDiffDataValues.put(DataColumns.CONTENT, dataContent);
+            mDiffDataValues.put(DataColumns.CONTENT, dataContent); // 记录内容变更
         }
         mDataContent = dataContent;
 
+        // 解析整数型数据（DATA1）
         long dataContentData1 = js.has(DataColumns.DATA1) ? js.getLong(DataColumns.DATA1) : 0;
         if (mIsCreate || mDataContentData1 != dataContentData1) {
-            mDiffDataValues.put(DataColumns.DATA1, dataContentData1);
+            mDiffDataValues.put(DataColumns.DATA1, dataContentData1); // 记录DATA1变更
         }
         mDataContentData1 = dataContentData1;
 
+        // 解析文本型数据（DATA3）
         String dataContentData3 = js.has(DataColumns.DATA3) ? js.getString(DataColumns.DATA3) : "";
         if (mIsCreate || !mDataContentData3.equals(dataContentData3)) {
-            mDiffDataValues.put(DataColumns.DATA3, dataContentData3);
+            mDiffDataValues.put(DataColumns.DATA3, dataContentData3); // 记录DATA3变更
         }
         mDataContentData3 = dataContentData3;
     }
 
+    /**
+     * 获取当前数据的JSON表示
+     * @return JSON对象（包含data表字段）
+     * @throws JSONException JSON构建异常
+     */
     public JSONObject getContent() throws JSONException {
         if (mIsCreate) {
             Log.e(TAG, "it seems that we haven't created this in database yet");
-            return null;
+            return null; // 新建未提交时返回null
         }
         JSONObject js = new JSONObject();
         js.put(DataColumns.ID, mDataId);
@@ -144,46 +168,59 @@ public class SqlData {
         return js;
     }
 
+    /**
+     * 提交数据变更到数据库（新建或更新）
+     * @param noteId 所属便签ID（关联note表）
+     * @param validateVersion 是否验证版本（用于同步时避免冲突）
+     * @param version 预期的便签版本号（仅在validateVersion为true时有效）
+     */
     public void commit(long noteId, boolean validateVersion, long version) {
-
         if (mIsCreate) {
+            // 新建场景：处理无效ID
             if (mDataId == INVALID_ID && mDiffDataValues.containsKey(DataColumns.ID)) {
-                mDiffDataValues.remove(DataColumns.ID);
+                mDiffDataValues.remove(DataColumns.ID); // 移除无效ID
             }
-
+            // 添加所属便签ID
             mDiffDataValues.put(DataColumns.NOTE_ID, noteId);
+            // 插入数据到data表
             Uri uri = mContentResolver.insert(Notes.CONTENT_DATA_URI, mDiffDataValues);
             try {
+                // 解析返回的URI获取数据项ID
                 mDataId = Long.valueOf(uri.getPathSegments().get(1));
             } catch (NumberFormatException e) {
                 Log.e(TAG, "Get note id error :" + e.toString());
-                throw new ActionFailureException("create note failed");
+                throw new ActionFailureException("create note failed"); // 抛出创建失败异常
             }
         } else {
+            // 更新场景：处理变更数据
             if (mDiffDataValues.size() > 0) {
                 int result = 0;
+                Uri dataUri = ContentUris.withAppendedId(Notes.CONTENT_DATA_URI, mDataId);
                 if (!validateVersion) {
-                    result = mContentResolver.update(ContentUris.withAppendedId(
+                    // 不验证版本，直接更新
-                            Notes.CONTENT_DATA_URI, mDataId), mDiffDataValues, null, null);
+                    result = mContentResolver.update(dataUri, mDiffDataValues, null, null);
                 } else {
-                    result = mContentResolver.update(ContentUris.withAppendedId(
+                    // 验证版本，防止并发冲突
-                            Notes.CONTENT_DATA_URI, mDataId), mDiffDataValues,
+                    result = mContentResolver.update(dataUri, mDiffDataValues,
-                            " ? in (SELECT " + NoteColumns.ID + " FROM " + TABLE.NOTE
+                            " ? IN (SELECT " + NoteColumns.ID + " FROM " + TABLE.NOTE
-                                    + " WHERE " + NoteColumns.VERSION + "=?)", new String[] {
+                                    + " WHERE " + NoteColumns.VERSION + "=?)",
-                                    String.valueOf(noteId), String.valueOf(version)
+                            new String[] { String.valueOf(noteId), String.valueOf(version) });
-                            });
                 }
                 if (result == 0) {
                     Log.w(TAG, "there is no update. maybe user updates note when syncing");
                 }
             }
         }
-
+        // 重置状态
         mDiffDataValues.clear();
         mIsCreate = false;
     }
 
+    /**
+     * 获取数据项ID
+     * @return 数据项ID，新建未提交时返回INVALID_ID
+     */
     public long getId() {
         return mDataId;
     }
-}
+}