diff --git a/src/gtask/data/Task.java b/src/gtask/data/Task.java index b9730ae..75922b7 100644 --- a/src/gtask/data/Task.java +++ b/src/gtask/data/Task.java @@ -24,170 +24,220 @@ public class Task extends Node { mMetaInfo = null; } + /** + * 生成创建任务操作的 JSON 对象 + * + * @param actionId 操作的唯一标识符 + * @return 包含创建任务操作信息的 JSON 对象 + * @throws ActionFailureException 如果生成 JSON 对象时发生异常，则抛出 ActionFailureException 异常 + */ public JSONObject getCreateAction(int actionId) { 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, mParent.getChildTaskIndex(this)); - - // entity_delta + + // 设置实体的变化信息 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_TASK); + + // 如果任务有附加注释，则设置注释信息 if (getNotes() != null) { entity.put(GTaskStringUtils.GTASK_JSON_NOTES, getNotes()); } js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity); - - // parent_id - if (mParent!= null) { - js.put(GTaskStringUtils.GTASK_JSON_PARENT_ID, mParent.getGid()); + + // 设置父任务的唯一标识符 + if (mParent != null) { + js.put(GTaskStringUtils.GTASK_JSON_PARENT_ID, mParent.getGid()); } - - // dest_parent_type + + // 设置目标父任务的类型为 GROUP js.put(GTaskStringUtils.GTASK_JSON_DEST_PARENT_TYPE, GTaskStringUtils.GTASK_JSON_TYPE_GROUP); - - // list_id - if (mParent!= null) { - js.put(GTaskStringUtils.GTASK_JSON_LIST_ID, mParent.getGid()); + + // 设置任务所属列表的唯一标识符 + if (mParent != null) { + js.put(GTaskStringUtils.GTASK_JSON_LIST_ID, mParent.getGid()); } - - // prior_sibling_id + + // 设置相邻任务的唯一标识符，用于确定任务在兄弟任务中的位置 if (mPriorSibling != null) { js.put(GTaskStringUtils.GTASK_JSON_PRIOR_SIBLING_ID, mPriorSibling.getGid()); } - + } catch (JSONException e) { + // 如果生成 JSON 对象时发生异常，则记录错误日志并抛出 ActionFailureException 异常 Log.e(TAG, e.toString()); e.printStackTrace(); - throw new ActionFailureException("fail to generate task-create jsonobject"); + throw new ActionFailureException("生成任务创建 JSON 对象失败"); } - + return js; } - + + /** + * 生成更新任务操作的 JSON 对象 + * + * @param actionId 操作的唯一标识符 + * @return 包含更新任务操作信息的 JSON 对象 + * @throws ActionFailureException 如果生成 JSON 对象时发生异常，则抛出 ActionFailureException 异常 + */ public JSONObject getUpdateAction(int actionId) { 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 + + // 设置实体的变化信息 JSONObject entity = new JSONObject(); 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); - + } catch (JSONException e) { + // 如果生成 JSON 对象时发生异常，则记录错误日志并抛出 ActionFailureException 异常 Log.e(TAG, e.toString()); e.printStackTrace(); - throw new ActionFailureException("fail to generate task-update jsonobject"); + throw new ActionFailureException("生成任务更新 JSON 对象失败"); } - + return js; } + + /** + * 根据远程 JSON 对象设置任务内容 + * + * @param js 包含任务内容信息的远程 JSON 对象 + * @throws ActionFailureException 如果解析 JSON 对象时发生异常，则抛出 ActionFailureException 异常 + */ public void setContentByRemoteJSON(JSONObject js) { 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)); } - - // notes + + // 设置任务的注释 if (js.has(GTaskStringUtils.GTASK_JSON_NOTES)) { setNotes(js.getString(GTaskStringUtils.GTASK_JSON_NOTES)); } - - // deleted + + // 设置任务是否被删除 if (js.has(GTaskStringUtils.GTASK_JSON_DELETED)) { setDeleted(js.getBoolean(GTaskStringUtils.GTASK_JSON_DELETED)); } - - // completed + + // 设置任务是否已完成 if (js.has(GTaskStringUtils.GTASK_JSON_COMPLETED)) { setCompleted(js.getBoolean(GTaskStringUtils.GTASK_JSON_COMPLETED)); } } catch (JSONException e) { + // 如果解析 JSON 对象时发生异常，则记录错误日志并抛出 ActionFailureException 异常 Log.e(TAG, e.toString()); e.printStackTrace(); - throw new ActionFailureException("fail to get task content from jsonobject"); + throw new ActionFailureException("从 JSON 对象获取任务内容失败"); } } } + - public void setContentByLocalJSON(JSONObject js) { // metadata ʵʩ + /** + * 根据本地 JSON 对象设置任务内容 + * + * @param js 包含任务内容信息的本地 JSON 对象 + */ + public void setContentByLocalJSON(JSONObject js) { + // 检查 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: 没有可用的信息"); } - + try { + // 获取任务的元数据 JSONObject note = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE); JSONArray dataArray = js.getJSONArray(GTaskStringUtils.META_HEAD_DATA); - + + // 检查任务类型是否为 Notes.TYPE_NOTE if (note.getInt(NoteColumns.TYPE) != Notes.TYPE_NOTE) { - Log.e(TAG, "invalid type"); + Log.e(TAG, "无效的类型"); return; } - + + // 遍历数据数组，查找包含 MIME_TYPE 为 DataConstants.NOTE 的数据项 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; } } - + } catch (JSONException e) { + // 如果解析 JSON 对象时发生异常，则记录错误日志 Log.e(TAG, e.toString()); e.printStackTrace(); } } + + /** + * 从任务内容生成本地 JSON 对象 + * + * @return 包含任务元数据的本地 JSON 对象 + */ public JSONObject getLocalJSONFromContent() { String name = getName(); try { + // 如果任务的元数据为空，表示是从 web 创建的新任务 if (mMetaInfo == null) { - // new task created from web + // 新任务为空，记录警告日志并返回 null if (name == null) { - Log.w(TAG, "the note seems to be an empty one"); + Log.w(TAG, "任务似乎是一个空任务"); return null; } - + + // 构建 JSON 对象包含任务元数据和数据数组 JSONObject js = new JSONObject(); JSONObject note = new JSONObject(); JSONArray dataArray = new JSONArray(); @@ -199,10 +249,10 @@ public class Task extends Node { js.put(GTaskStringUtils.META_HEAD_NOTE, note); return js; } else { - // synced task + // 如果是已同步的任务，更新数据数组中 MIME_TYPE 为 DataConstants.NOTE 的数据项的内容 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)) { @@ -210,80 +260,105 @@ public class Task extends Node { break; } } - + + // 更新任务类型为 Notes.TYPE_NOTE，并返回元数据 JSON 对象 note.put(NoteColumns.TYPE, Notes.TYPE_NOTE); return mMetaInfo; } } catch (JSONException e) { + // 如果生成 JSON 对象时发生异常，则记录错误日志并返回 null Log.e(TAG, e.toString()); e.printStackTrace(); return null; } } + + /** + * 根据 MetaData 对象设置元数据信息 + * + * @param metaData 包含元数据信息的 MetaData 对象 + */ public void setMetaInfo(MetaData metaData) { + // 检查 MetaData 对象是否有效，且是否包含注释信息 if (metaData != null && metaData.getNotes() != null) { try { + // 将注释信息转换为 JSON 对象并赋值给 mMetaInfo mMetaInfo = new JSONObject(metaData.getNotes()); } catch (JSONException e) { + // 如果转换为 JSON 对象时发生异常，则记录警告日志并将 mMetaInfo 置为 null Log.w(TAG, e.toString()); mMetaInfo = null; } } } + + /** + * 获取同步操作类型 + * + * @param c 包含本地数据库信息的 Cursor 对象 + * @return 同步操作类型，可能的值有 SYNC_ACTION_NONE、SYNC_ACTION_UPDATE_REMOTE、 + * SYNC_ACTION_UPDATE_LOCAL、SYNC_ACTION_UPDATE_CONFLICT 和 SYNC_ACTION_ERROR + */ 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); } - + + // 如果注释信息不存在，记录警告日志并返回 SYNC_ACTION_UPDATE_REMOTE if (noteInfo == null) { - Log.w(TAG, "it seems that note meta has been deleted"); + Log.w(TAG, "似乎已删除注释元数据"); return SYNC_ACTION_UPDATE_REMOTE; } - + + // 如果注释信息中不包含 NoteColumns.ID，记录警告日志并返回 SYNC_ACTION_UPDATE_LOCAL if (!noteInfo.has(NoteColumns.ID)) { - Log.w(TAG, "remote note id seems to be deleted"); + Log.w(TAG, "远程注释 ID 似乎已删除"); return SYNC_ACTION_UPDATE_LOCAL; } - - // validate the note id now + + // 验证注释 ID 是否与本地数据库中的 ID 匹配 if (c.getLong(SqlNote.ID_COLUMN) != noteInfo.getLong(NoteColumns.ID)) { - Log.w(TAG, "note id doesn't match"); + Log.w(TAG, "注释 ID 不匹配"); return SYNC_ACTION_UPDATE_LOCAL; } - + 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"); + Log.e(TAG, "gtask ID 不匹配"); return SYNC_ACTION_ERROR; } if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) { - // local modification only + // 仅本地修改 return SYNC_ACTION_UPDATE_REMOTE; } else { return SYNC_ACTION_UPDATE_CONFLICT; } } } catch (Exception e) { + // 如果发生异常，记录错误日志并返回 SYNC_ACTION_ERROR Log.e(TAG, e.toString()); e.printStackTrace(); } - + return SYNC_ACTION_ERROR; } + public boolean isWorthSaving() { return mMetaInfo != null || (getName() != null && getName().trim().length() > 0)