添加注释

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

@@ -34,43 +34,42 @@ import net.micode.notes.gtask.exception.ActionFailureException;
 import org.json.JSONException;
 import org.json.JSONObject;
 
-
+/**
+ * 数据库数据操作类
+ * 用于处理笔记数据项的增删改查操作，支持JSON格式转换
+ */
 public class SqlData {
     private static final String TAG = SqlData.class.getSimpleName();
 
+    // 无效ID标识
     private static final int INVALID_ID = -99999;
 
+    // 查询数据项的投影字段
     public static final String[] PROJECTION_DATA = new String[] {
             DataColumns.ID, DataColumns.MIME_TYPE, DataColumns.CONTENT, DataColumns.DATA1,
             DataColumns.DATA3
     };
 
+    // 各字段在投影中的索引位置
     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 boolean mIsCreate;
-
-    private long mDataId;
-
-    private String mDataMimeType;
-
-    private String mDataContent;
-
-    private long mDataContentData1;
-
-    private String mDataContentData3;
-
-    private ContentValues mDiffDataValues;
-
+    private ContentResolver mContentResolver; // 内容解析器
+    private boolean mIsCreate; // 是否为新建数据
+    private long mDataId; // 数据ID
+    private String mDataMimeType; // MIME类型
+    private String mDataContent; // 内容
+    private long mDataContentData1; // 附加数据1
+    private String mDataContentData3; // 附加数据3
+    private ContentValues mDiffDataValues; // 差异值，用于更新操作
+
+    /**
+     * 构造函数（创建新数据项）
+     * @param context 上下文
+     */
     public SqlData(Context context) {
         mContentResolver = context.getContentResolver();
         mIsCreate = true;
@@ -82,6 +81,11 @@ public class SqlData {
         mDiffDataValues = new ContentValues();
     }
 
+    /**
+     * 构造函数（从游标加载现有数据项）
+     * @param context 上下文
+     * @param c 游标
+     */
     public SqlData(Context context, Cursor c) {
         mContentResolver = context.getContentResolver();
         mIsCreate = false;
@@ -89,6 +93,10 @@ public class SqlData {
         mDiffDataValues = new ContentValues();
     }
 
+    /**
+     * 从游标加载数据
+     * @param c 游标
+     */
     private void loadFromCursor(Cursor c) {
         mDataId = c.getLong(DATA_ID_COLUMN);
         mDataMimeType = c.getString(DATA_MIME_TYPE_COLUMN);
@@ -97,7 +105,13 @@ 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 {
+        // 从JSON中获取各字段值，并与当前值比较，记录差异
         long dataId = js.has(DataColumns.ID) ? js.getLong(DataColumns.ID) : INVALID_ID;
         if (mIsCreate || mDataId != dataId) {
             mDiffDataValues.put(DataColumns.ID, dataId);
@@ -130,9 +144,14 @@ public class SqlData {
         mDataContentData3 = dataContentData3;
     }
 
+    /**
+     * 获取内容的JSON表示
+     * @return JSON对象
+     * @throws JSONException JSON生成异常
+     */
     public JSONObject getContent() throws JSONException {
         if (mIsCreate) {
-            Log.e(TAG, "it seems that we haven't created this in database yet");
+            Log.e(TAG, "数据尚未在数据库中创建");
             return null;
         }
         JSONObject js = new JSONObject();
@@ -144,28 +163,38 @@ public class SqlData {
         return js;
     }
 
+    /**
+     * 提交数据到数据库
+     * @param noteId 所属笔记ID
+     * @param validateVersion 是否验证版本
+     * @param version 版本号
+     */
     public void commit(long noteId, boolean validateVersion, long version) {
-
         if (mIsCreate) {
+            // 新建数据项
             if (mDataId == INVALID_ID && mDiffDataValues.containsKey(DataColumns.ID)) {
-                mDiffDataValues.remove(DataColumns.ID);
+                mDiffDataValues.remove(DataColumns.ID); // 移除无效ID
             }
-
-            mDiffDataValues.put(DataColumns.NOTE_ID, noteId);
+            mDiffDataValues.put(DataColumns.NOTE_ID, noteId); // 设置所属笔记ID
+            
+            // 插入数据
             Uri uri = mContentResolver.insert(Notes.CONTENT_DATA_URI, mDiffDataValues);
             try {
-                mDataId = Long.valueOf(uri.getPathSegments().get(1));
+                mDataId = Long.valueOf(uri.getPathSegments().get(1)); // 获取插入后的ID
             } catch (NumberFormatException e) {
-                Log.e(TAG, "Get note id error :" + e.toString());
-                throw new ActionFailureException("create note failed");
+                Log.e(TAG, "获取数据ID失败: " + e.toString());
+                throw new ActionFailureException("创建笔记失败");
             }
         } else {
+            // 更新现有数据项
             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
@@ -174,15 +203,19 @@ public class SqlData {
                             });
                 }
                 if (result == 0) {
-                    Log.w(TAG, "there is no update. maybe user updates note when syncing");
+                    Log.w(TAG, "更新失败，可能在同步时有其他更新操作");
                 }
             }
         }
 
-        mDiffDataValues.clear();
-        mIsCreate = false;
+        mDiffDataValues.clear(); // 清空差异值
+        mIsCreate = false; // 标记为已创建
     }
 
+    /**
+     * 获取数据ID
+     * @return 数据ID
+     */
     public long getId() {
         return mDataId;
     }