Update TaskList.java

src/gtask/data/TaskList.java

@@ -13,186 +13,250 @@ public class TaskList extends Node {
         mIndex = 1;
     }
  
-    /* (non-Javadoc)
+    /**
-     * @see net.micode.notes.gtask.data.Node#getCreateAction(int)
+     * 获取创建任务列表操作的 JSON 对象
-     * 生成并返回一个包含了一定数据的JSONObject实体
+     *
+     * @param actionId 操作的唯一标识符
+     * @return 包含创建任务列表操作信息的 JSON 对象
+     * @throws ActionFailureException 如果生成 JSON 对象过程中发生异常
      */
-    public JSONObject getCreateAction(int actionId) {
+    public JSONObject getCreateAction(int actionId) throws ActionFailureException {
+        // 创建空的 JSON 对象
         JSONObject js = new JSONObject();
- 
+
         try {
-            // action_type
+            // 设置操作类型为创建任务列表
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                     GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);
- 
+
-            // action_id
+            // 设置操作的唯一标识符
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
- 
+
-            // index
+            // 设置任务列表的索引
             js.put(GTaskStringUtils.GTASK_JSON_INDEX, mIndex);
- 
+
-            // entity_delta
+            // 创建实体信息的 JSON 对象
-            JSONObject entity = new JSONObject();//entity实体
+            JSONObject entity = new JSONObject();
             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);
- 
+
         } catch (JSONException e) {
+            // 如果生成 JSON 对象过程中发生异常，记录错误日志并抛出 ActionFailureException 异常
             Log.e(TAG, e.toString());
             e.printStackTrace();
-            throw new ActionFailureException("fail to generate tasklist-create jsonobject");
+            throw new ActionFailureException("生成任务列表创建操作的 JSON 对象失败");
         }
- 
+
         return js;
     }
+
  
-    /* (non-Javadoc)
+    /**
-     * @see net.micode.notes.gtask.data.Node#getUpdateAction(int)
+     * 获取更新任务列表操作的 JSON 对象
-     * 生成并返回一个包含了一定数据的JSONObject实体
+     *
+     * @param actionId 操作的唯一标识符
+     * @return 包含更新任务列表操作信息的 JSON 对象
+     * @throws ActionFailureException 如果生成 JSON 对象过程中发生异常
      */
-    public JSONObject getUpdateAction(int actionId) {
+    public JSONObject getUpdateAction(int actionId) throws ActionFailureException {
+        // 创建空的 JSON 对象
         JSONObject js = new JSONObject();
- 
+
         try {
-            // action_type
+            // 设置操作类型为更新任务列表
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                     GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
- 
+
-            // action_id
+            // 设置操作的唯一标识符
             js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
- 
+
-            // id
+            // 设置任务列表的唯一标识符
             js.put(GTaskStringUtils.GTASK_JSON_ID, getGid());
- 
+
-            // entity_delta
+            // 创建实体信息的 JSON 对象
             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);
- 
+
         } catch (JSONException e) {
+            // 如果生成 JSON 对象过程中发生异常，记录错误日志并抛出 ActionFailureException 异常
             Log.e(TAG, e.toString());
             e.printStackTrace();
-            throw new ActionFailureException("fail to generate tasklist-update jsonobject");
+            throw new ActionFailureException("生成任务列表更新操作的 JSON 对象失败");
         }
- 
+
         return js;
     }
+
  
-    public void setContentByRemoteJSON(JSONObject js) {
+    /**
+     * 通过远程 JSON 对象设置任务列表内容
+     *
+     * @param js 包含任务列表信息的 JSON 对象
+     * @throws ActionFailureException 如果在设置任务列表内容过程中发生异常
+     */
+    public void setContentByRemoteJSON(JSONObject js) throws ActionFailureException {
         if (js != null) {
             try {
-                // id
+                // 设置任务列表的唯一标识符
                 if (js.has(GTaskStringUtils.GTASK_JSON_ID)) {
                     setGid(js.getString(GTaskStringUtils.GTASK_JSON_ID));
                 }
- 
+
-                // last_modified
+                // 设置任务列表的最后修改时间
                 if (js.has(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED)) {
                     setLastModified(js.getLong(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED));
                 }
- 
+
-                // name
+                // 设置任务列表的名称
                 if (js.has(GTaskStringUtils.GTASK_JSON_NAME)) {
                     setName(js.getString(GTaskStringUtils.GTASK_JSON_NAME));
                 }
- 
+
             } catch (JSONException e) {
+                // 如果在设置任务列表内容过程中发生异常，记录错误日志并抛出 ActionFailureException 异常
                 Log.e(TAG, e.toString());
                 e.printStackTrace();
-                throw new ActionFailureException("fail to get tasklist content from jsonobject");
+                throw new ActionFailureException("从 JSON 对象获取任务列表内容失败");
             }
         }
     }
+
  
+    /**
+     * 通过本地 JSON 对象设置任务列表内容
+     *
+     * @param js 包含任务列表信息的本地 JSON 对象
+     */
     public void setContentByLocalJSON(JSONObject js) {
         if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)) {
-            Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
+            // 如果 JSON 对象为空或不包含任务列表信息，记录警告日志
+            Log.w(TAG, "setContentByLocalJSON: 没有可用的信息");
         }
- 
+
         try {
+            // 获取任务列表的元数据信息
             JSONObject folder = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
- 
+
             if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {
+                // 如果是文件夹类型的任务列表
                 String name = folder.getString(NoteColumns.SNIPPET);
+                // 设置任务列表名称为 MIUI 文件夹前缀加上文件夹的片段信息
                 setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + name);
             } else if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM) {
+                // 如果是系统文件夹类型的任务列表
                 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);
+                    setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + GTaskStringUtils.FOLDER_CALL_NOTE);
                 else
-                    Log.e(TAG, "invalid system folder");
+                    // 无效的系统文件夹
+                    Log.e(TAG, "无效的系统文件夹");
             } else {
-                Log.e(TAG, "error type");
+                // 错误的类型
+                Log.e(TAG, "错误的类型");
             }
         } catch (JSONException e) {
+            // 如果在设置任务列表内容的过程中发生异常，记录错误日志
             Log.e(TAG, e.toString());
             e.printStackTrace();
         }
     }
+
  
+    /**
+     * 根据任务列表内容生成本地 JSON 对象
+     *
+     * @return 包含任务列表信息的本地 JSON 对象
+     */
     public JSONObject getLocalJSONFromContent() {
         try {
+            // 创建 JSON 对象用于存储任务列表信息
             JSONObject js = new JSONObject();
+            // 创建 JSON 对象用于存储任务列表元数据
             JSONObject folder = new JSONObject();
- 
+
+            // 获取任务列表名称
             String folderName = getName();
+            // 如果名称以 MIUI 文件夹前缀开头，去掉前缀部分
             if (getName().startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX))
                 folderName = folderName.substring(GTaskStringUtils.MIUI_FOLDER_PREFFIX.length(),
                         folderName.length());
+
+            // 设置任务列表元数据的片段信息和类型
             folder.put(NoteColumns.SNIPPET, folderName);
             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);
- 
+
+            // 将任务列表元数据放入 JSON 对象
             js.put(GTaskStringUtils.META_HEAD_NOTE, folder);
- 
+
             return js;
         } catch (JSONException e) {
+            // 如果在生成本地 JSON 对象的过程中发生异常，记录错误日志
             Log.e(TAG, e.toString());
             e.printStackTrace();
             return null;
         }
     }
+
  
+    /**
+     * 获取同步操作类型
+     *
+     * @param c 游标对象，包含本地数据库中的任务信息
+     * @return 同步操作类型，可能的取值有 SYNC_ACTION_NONE、SYNC_ACTION_UPDATE_LOCAL、
+     * SYNC_ACTION_UPDATE_REMOTE 和 SYNC_ACTION_ERROR
+     */
     public int getSyncAction(Cursor c) {
         try {
             if (c.getInt(SqlNote.LOCAL_MODIFIED_COLUMN) == 0) {
-                // there is no local update
+                // 本地无更新
                 if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
-                    // no update both side
+                    // 本地和远程都无更新
                     return SYNC_ACTION_NONE;
                 } else {
-                    // apply remote to local
+                    // 将远程更新应用到本地
                     return SYNC_ACTION_UPDATE_LOCAL;
                 }
             } else {
-                // validate gtask 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()) {
-                    // local modification only
+                    // 仅有本地修改
                     return SYNC_ACTION_UPDATE_REMOTE;
                 } else {
-                    // for folder conflicts, just apply local modification
+                    // 对于文件夹冲突，仅应用本地修改
                     return SYNC_ACTION_UPDATE_REMOTE;
                 }
             }
         } catch (Exception e) {
+            // 如果在获取同步操作类型的过程中发生异常，记录错误日志
             Log.e(TAG, e.toString());
             e.printStackTrace();
         }
- 
+
         return SYNC_ACTION_ERROR;
     }
+
  
     /**
      * @return