|
|
/*
|
|
|
* Copyright (c) 2010-2011, The MiCode Open Source Community (www.micode.net)
|
|
|
*
|
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
|
* you may not use this file except in compliance with the License.
|
|
|
* You may obtain a copy of the License at
|
|
|
*
|
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
|
*
|
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
* See the License for the specific language governing permissions and
|
|
|
* limitations under the License.
|
|
|
*/
|
|
|
|
|
|
package net.micode.notes.gtask.data;
|
|
|
|
|
|
import android.database.Cursor;
|
|
|
import android.util.Log;
|
|
|
|
|
|
import net.micode.notes.data.Notes;
|
|
|
import net.micode.notes.data.Notes.NoteColumns;
|
|
|
import net.micode.notes.gtask.exception.ActionFailureException;
|
|
|
import net.micode.notes.tool.GTaskStringUtils;
|
|
|
|
|
|
import org.json.JSONException;
|
|
|
import org.json.JSONObject;
|
|
|
|
|
|
import java.util.ArrayList;
|
|
|
|
|
|
|
|
|
public class TaskList extends Node
|
|
|
//TaskList 类继承了 Node 类
|
|
|
// 表示它是可以存储在树形结构中的一个节点
|
|
|
// TaskList 类有三个属性：mIndex、mChildren 和 TAG
|
|
|
{
|
|
|
private static final String TAG = TaskList.class.getSimpleName();
|
|
|
//用于记录 TaskList 类的类名，方便在调试过程中进行日志记录和错误跟踪
|
|
|
|
|
|
private int mIndex;
|
|
|
//表示 TaskList 对象在树形结构中的序号。默认情况下，它被初始化为 1
|
|
|
|
|
|
private ArrayList<Task> mChildren;
|
|
|
// ArrayList<Task> 类型的属性，表示 TaskList 对象的子节点列表
|
|
|
|
|
|
public TaskList() {
|
|
|
super();
|
|
|
mChildren = new ArrayList<Task>();
|
|
|
mIndex = 1;
|
|
|
}
|
|
|
|
|
|
public JSONObject getCreateAction(int actionId)
|
|
|
//据当前文件夹对象的属性值，构造一个包含创建操作信息的 JSON 对象，并返回给调用者
|
|
|
{
|
|
|
JSONObject js = new JSONObject();
|
|
|
//创建一个空的 JSONObject 对象 js
|
|
|
try {
|
|
|
// action_type
|
|
|
js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
|
|
|
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);
|
|
|
//添加 GTASK_JSON_ACTION_TYPE字段及对应的值
|
|
|
// action_id
|
|
|
js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
|
|
|
// 添加GTASK_JSON_ACTION_ID字段及对应的值
|
|
|
// index
|
|
|
js.put(GTaskStringUtils.GTASK_JSON_INDEX, mIndex);
|
|
|
|
|
|
// entity_delta
|
|
|
// 添加GTASK_JSON_INDEX 和 GTASK_JSON_ENTITY_DELTA 等字段及对应的值。
|
|
|
JSONObject entity = new JSONObject();
|
|
|
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
|
|
|
//创建一个包含实体信息的 JSONObject 对象 entity，并向其中添加文件夹名称 GTASK_JSON_NAME
|
|
|
entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null");
|
|
|
entity.put(GTaskStringUtils.GTASK_JSON_ENTITY_TYPE,
|
|
|
GTaskStringUtils.GTASK_JSON_TYPE_GROUP);
|
|
|
//创建人 ID GTASK_JSON_CREATOR_ID 和实体类型 GTASK_JSON_ENTITY_TYPE 等字段及对应的值
|
|
|
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
|
|
|
//将 entity 对象作为值添加到父级 JSONObject 对象 js 中的 GTASK_JSON_ENTITY_DELTA 字段中
|
|
|
} catch (JSONException e) {
|
|
|
Log.e(TAG, e.toString());
|
|
|
e.printStackTrace();
|
|
|
throw new ActionFailureException("fail to generate tasklist-create jsonobject");
|
|
|
}//如果生成 JSON 对象时出现异常，则记录错误日志并抛出 ActionFailureException 异常
|
|
|
|
|
|
return js;
|
|
|
}
|
|
|
|
|
|
public JSONObject getUpdateAction(int actionId)
|
|
|
//根据当前文件夹对象的属性值，构造一个包含更新操作信息的 JSON 对象，并返回给调用者
|
|
|
{
|
|
|
JSONObject js = new JSONObject();//创建一个空的 JSONObject 对象 js
|
|
|
|
|
|
try {
|
|
|
// action_type
|
|
|
js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
|
|
|
GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);
|
|
|
//添加 GTASK_JSON_ACTION_TYPE字段及对应的值
|
|
|
// action_id
|
|
|
js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);
|
|
|
//添加GTASK_JSON_ACTION_ID字段及对应的值
|
|
|
// id
|
|
|
js.put(GTaskStringUtils.GTASK_JSON_ID, getGid());
|
|
|
//添加GTASK_JSON_ID字段及对应的值
|
|
|
// entity_delta
|
|
|
JSONObject entity = new JSONObject();
|
|
|
entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());
|
|
|
entity.put(GTaskStringUtils.GTASK_JSON_DELETED, getDeleted());
|
|
|
//添加GTASK_JSON_DELETED字段及对应的值
|
|
|
js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);
|
|
|
////然后将 entity 对象作为值添加到父级 JSONObject 对象 js 中的 GTASK_JSON_ENTITY_DELTA 字段
|
|
|
} catch (JSONException e) {
|
|
|
Log.e(TAG, e.toString());
|
|
|
e.printStackTrace();
|
|
|
throw new ActionFailureException("fail to generate tasklist-update jsonobject");
|
|
|
}
|
|
|
//如果生成 JSON 对象时出现异常，则记录错误日志并抛出 ActionFailureException 异常
|
|
|
|
|
|
return js;
|
|
|
}
|
|
|
|
|
|
public void setContentByRemoteJSON(JSONObject js)
|
|
|
//从给定的 JSONObject 对象 js 中读取云端 Google Tasks 的文件夹信息，并将其应用到当前的文件夹对象中
|
|
|
{
|
|
|
if (js != null)
|
|
|
//对输入进行判空
|
|
|
{
|
|
|
try {
|
|
|
// id
|
|
|
if (js.has(GTaskStringUtils.GTASK_JSON_ID))
|
|
|
//检查是否含有字段 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));
|
|
|
}//检查是否含有字段 GTASK_JSON_LAST_MODIFIED
|
|
|
|
|
|
// name
|
|
|
if (js.has(GTaskStringUtils.GTASK_JSON_NAME)) {
|
|
|
setName(js.getString(GTaskStringUtils.GTASK_JSON_NAME));
|
|
|
}//检查是否含有字段GTASK_JSON_NAME
|
|
|
|
|
|
} catch (JSONException e) {
|
|
|
Log.e(TAG, e.toString());
|
|
|
e.printStackTrace();
|
|
|
throw new ActionFailureException("fail to get tasklist content from jsonobject");
|
|
|
}
|
|
|
//如果解析 JSON 对象时出现异常
|
|
|
// 则记录错误日志并抛出 ActionFailureException 异常
|
|
|
}
|
|
|
}
|
|
|
|
|
|
public void setContentByLocalJSON(JSONObject js)
|
|
|
//从给定的 JSONObject 对象 js 中读取文件夹信息，并将其应用到当前的文件夹对象中
|
|
|
{
|
|
|
if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)) {
|
|
|
Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");
|
|
|
}
|
|
|
//如果输入的 JSON 对象为 null 或不含有 GTaskStringUtils.META_HEAD_NOTE 字段
|
|
|
// 则会记录警告日志并跳过后续处理
|
|
|
|
|
|
try {
|
|
|
JSONObject folder = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);
|
|
|
//从 GTaskStringUtils.META_HEAD_NOTE 字段中获取 folder 子对象，并根据 NoteColumns.TYPE 属性判断文件夹类型
|
|
|
if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER)
|
|
|
// 如果文件夹类型是 Notes.TYPE_FOLDER
|
|
|
{
|
|
|
String name = folder.getString(NoteColumns.SNIPPET);//则从 NoteColumns.SNIPPET 属性中获取文件夹名称
|
|
|
setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + name);//为当前文件夹对象设置名称，以 GTaskStringUtils.MIUI_FOLDER_PREFFIX 作为前缀
|
|
|
} else if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_SYSTEM)
|
|
|
//如果文件夹类型是 Notes.TYPE_SYSTEM，
|
|
|
{
|
|
|
if (folder.getLong(NoteColumns.ID) == Notes.ID_ROOT_FOLDER)
|
|
|
//根据 NoteColumns.ID 属性的值判断系统文件夹类型，并为当前文件夹对象设置相应的名称
|
|
|
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);
|
|
|
else
|
|
|
Log.e(TAG, "invalid system folder");
|
|
|
} else {
|
|
|
Log.e(TAG, "error type");
|
|
|
}//如果出现错误，则记录错误日志并跳过后续处理。如果文件夹类型不合法，则同样记录错误日志并跳过后续处理。
|
|
|
} catch (JSONException e) {
|
|
|
Log.e(TAG, e.toString());
|
|
|
e.printStackTrace();
|
|
|
}
|
|
|
}
|
|
|
|
|
|
public JSONObject getLocalJSONFromContent()
|
|
|
//将应用中的文件夹信息转换为 JSON 格式的方法
|
|
|
//返回一个包含文件夹信息的 JSONObject 对象
|
|
|
{
|
|
|
try {
|
|
|
JSONObject js = new JSONObject();
|
|
|
JSONObject folder = new JSONObject();
|
|
|
//创建一个新的 JSONObject 对象
|
|
|
// 并创建一个名为 folder 的子对象，用于存储文件夹的属性信息
|
|
|
String folderName = getName();
|
|
|
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);
|
|
|
// //如果是系统文件夹，则设置 NoteColumns.TYPE 属性为 Notes.TYPE_SYSTEM
|
|
|
else
|
|
|
folder.put(NoteColumns.TYPE, Notes.TYPE_FOLDER);//否则设置为 Notes.TYPE_FOLDER
|
|
|
|
|
|
js.put(GTaskStringUtils.META_HEAD_NOTE, folder);
|
|
|
//将文件夹的名称和类型信息添加到 folder 子对象中，并将 folder 作为 GTaskStringUtils.META_HEAD_NOTE 的值添加到主 JSONObject 中
|
|
|
// 用于指定待更新笔记的文件夹信息。
|
|
|
return js;
|
|
|
} catch (JSONException e) {
|
|
|
Log.e(TAG, e.toString());
|
|
|
e.printStackTrace();
|
|
|
return null;
|
|
|
}//如果转换过程中出现异常，则记录错误日志并返回 null
|
|
|
}
|
|
|
|
|
|
public int getSyncAction(Cursor c)
|
|
|
//从给定的 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
|
|
|
//如果本地笔记没有被修改
|
|
|
// 则进一步判断云端笔记的最后修改时间和本地笔记最后同步时间是否相等
|
|
|
// 如果相等，则不需要更新，返回 SYNC_ACTION_NON
|
|
|
return SYNC_ACTION_NONE;
|
|
|
} else {
|
|
|
// apply remote to local
|
|
|
//如果不相等，则需要将云端笔记的内容同步到本地，返回 SYNC_ACTION_UPDATE_LOCAL
|
|
|
return SYNC_ACTION_UPDATE_LOCAL;
|
|
|
}
|
|
|
} else
|
|
|
//被修改过
|
|
|
{
|
|
|
// validate gtask id
|
|
|
if (!c.getString(SqlNote.GTASK_ID_COLUMN).equals(getGid()))
|
|
|
//验证云端笔记的 ID 和本地笔记的 ID 是否匹配
|
|
|
{
|
|
|
Log.e(TAG, "gtask id doesn't match");
|
|
|
return SYNC_ACTION_ERROR;
|
|
|
}//如果不匹配，则说明出现了错误
|
|
|
// 返回 SYNC_ACTION_ERROR 表示同步失败
|
|
|
if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {
|
|
|
// local modification only
|
|
|
return SYNC_ACTION_UPDATE_REMOTE;
|
|
|
//如果 ID 匹配，则需要进一步判断本地笔记和云端笔记的最后修改时间。
|
|
|
// 如果相等，则只需要将本地笔记同步到云端
|
|
|
//返回 SYNC_ACTION_UPDATE_REMOTE
|
|
|
} else {
|
|
|
// for folder conflicts, just apply local modification
|
|
|
return SYNC_ACTION_UPDATE_REMOTE;
|
|
|
}//存在冲突，优先选择本地笔记的修改内容
|
|
|
// 返回 SYNC_ACTION_UPDATE_REMOTE
|
|
|
}
|
|
|
} catch (Exception e) {
|
|
|
Log.e(TAG, e.toString());
|
|
|
e.printStackTrace();
|
|
|
}
|
|
|
|
|
|
return SYNC_ACTION_ERROR;
|
|
|
}
|
|
|
|
|
|
public int getChildTaskCount() {
|
|
|
return mChildren.size();
|
|
|
}
|
|
|
|
|
|
public boolean addChildTask(Task task)
|
|
|
//向任务列表中添加指定的子任务
|
|
|
{
|
|
|
boolean ret = false;
|
|
|
if (task != null && !mChildren.contains(task))
|
|
|
//判断待添加的任务是否为空，并且是否已经存在于列表中
|
|
|
//如果待添加任务为空，或者已经在列表中，则直接返回添加失败
|
|
|
{
|
|
|
ret = mChildren.add(task);
|
|
|
if (ret) {
|
|
|
// need to set prior sibling and parent
|
|
|
task.setPriorSibling(mChildren.isEmpty() ? null : mChildren
|
|
|
.get(mChildren.size() - 1));
|
|
|
task.setParent(this);//将待添加任务的前驱节点设置为列表中的最后一个任务（如果列表不为空,将其父节点设置为该任务列表的实例对象。
|
|
|
}//该方法返回操作结果，如果添加成功则返回 true，否则返回 false。
|
|
|
|
|
|
}
|
|
|
return ret;
|
|
|
}
|
|
|
|
|
|
public boolean addChildTask(Task task, int index)
|
|
|
//用于向任务列表中添加指定的子任务
|
|
|
{
|
|
|
if (index < 0 || index > mChildren.size())
|
|
|
//判断待添加任务的索引是否越界
|
|
|
{
|
|
|
Log.e(TAG, "add child task: invalid index");
|
|
|
return false;
|
|
|
}//越界则记录一条错误日志，并返回 false 表示添加失败
|
|
|
|
|
|
int pos = mChildren.indexOf(task);
|
|
|
if (task != null && pos == -1) {
|
|
|
mChildren.add(index, task);
|
|
|
|
|
|
// update the task list
|
|
|
Task preTask = null;
|
|
|
Task afterTask = null;
|
|
|
if (index != 0)//如果待添加任务不在列表中，则将其插入到指定位置上，并更新列表中其他任务的“父兄弟”关系
|
|
|
preTask = mChildren.get(index - 1);
|
|
|
//将待添加任务的前驱节点设置为索引 index - 1
|
|
|
if (index != mChildren.size() - 1)
|
|
|
afterTask = mChildren.get(index + 1);
|
|
|
//后继节点设置为索引 index + 1 的任务
|
|
|
|
|
|
task.setPriorSibling(preTask);
|
|
|
if (afterTask != null)
|
|
|
afterTask.setPriorSibling(task);
|
|
|
}
|
|
|
|
|
|
return true;
|
|
|
}//待添加任务已经在列表中，则不执行操作并直接返回 true 表示添加成功
|
|
|
|
|
|
public boolean removeChildTask(Task task)
|
|
|
//从任务列表中删除指定的子任务
|
|
|
{
|
|
|
boolean ret = false;
|
|
|
int index = mChildren.indexOf(task);
|
|
|
if (index != -1) {
|
|
|
ret = mChildren.remove(task);
|
|
|
//通过 indexOf() 方法查找待删除任务在列表中的索引
|
|
|
|
|
|
if (ret) {
|
|
|
// reset prior sibling and parent
|
|
|
task.setPriorSibling(null);
|
|
|
task.setParent(null);
|
|
|
//执行删除操作,重置为 null
|
|
|
|
|
|
// update the task list
|
|
|
if (index != mChildren.size()) {
|
|
|
mChildren.get(index).setPriorSibling(
|
|
|
index == 0 ? null : mChildren.get(index - 1));
|
|
|
}
|
|
|
//更新列表中其他任务的关系：如果待删除任务的前一个任务存在，则将其设置为待删除任务的前驱节点；
|
|
|
// 否则，设置为 null。
|
|
|
}
|
|
|
}
|
|
|
return ret;
|
|
|
}
|
|
|
|
|
|
public boolean moveChildTask(Task task, int index)
|
|
|
//将指定的子任务移动到新的位置
|
|
|
{
|
|
|
if (index < 0 || index >= mChildren.size())//判断待移动任务的索引是否越界
|
|
|
{
|
|
|
Log.e(TAG, "move child task: invalid index");
|
|
|
return false;
|
|
|
}
|
|
|
//若存在越界,返回 false 表示操作失败
|
|
|
|
|
|
int pos = mChildren.indexOf(task);
|
|
|
if (pos == -1) {
|
|
|
Log.e(TAG, "move child task: the task should in the list");
|
|
|
return false;
|
|
|
}//如果待移动任务不在列表中，则会记录一条错误日志，并返回 false 表示操作失败
|
|
|
|
|
|
if (pos == index)////如果待移动任务已经在列表中，并且新的索引与当前位置相同
|
|
|
return true;
|
|
|
return (removeChildTask(task) && addChildTask(task, index));
|
|
|
}//直接返回 true 表示操作成功
|
|
|
|
|
|
public Task findChildTaskByGid(String gid)
|
|
|
//根据子任务的GID（全局唯一标识符）查找指定的子任务
|
|
|
{
|
|
|
for (int i = 0; i < mChildren.size(); i++)
|
|
|
//当前任务列表节点下所有的子任务中依次查找，判断每个子任务的GID是否等于输入的参数gid
|
|
|
{
|
|
|
Task t = mChildren.get(i);
|
|
|
if (t.getGid().equals(gid)) {
|
|
|
return t;
|
|
|
}//若找到对应的子任务，则返回该子任务；
|
|
|
}
|
|
|
return null;
|
|
|
}//否则，返回null表示找不到指定的子任务
|
|
|
|
|
|
public int getChildTaskIndex(Task task) {
|
|
|
return mChildren.indexOf(task);
|
|
|
}
|
|
|
|
|
|
public Task getChildTaskByIndex(int index)
|
|
|
//根据子任务在任务列表中的位置获取指定的子任务
|
|
|
{
|
|
|
if (index < 0 || index >= mChildren.size())
|
|
|
{
|
|
|
Log.e(TAG, "getTaskByIndex: invalid index");
|
|
|
return null;
|
|
|
}//判断输入的参数index是否越界，如果小于0或大于等于当前子任务的个数，则会记录一条错误日志，并返回null
|
|
|
return mChildren.get(index);//返回该位置上对应的子任务
|
|
|
}
|
|
|
|
|
|
public Task getChilTaskByGid(String gid)
|
|
|
//根据子任务的GID（全局唯一标识符）查找指定的子任务
|
|
|
{
|
|
|
for (Task task : mChildren)
|
|
|
//遍历当前任务列表节点下所有的子任务，并依次判断每个子任务的GID是否等于输入的参数gid
|
|
|
{
|
|
|
if (task.getGid().equals(gid))
|
|
|
return task;
|
|
|
}
|
|
|
return null;
|
|
|
}
|
|
|
//若找到对应的子任务，则返回该子任务；否则，返回null表示找不到指定的子任务
|
|
|
|
|
|
public ArrayList<Task> getChildTaskList() {
|
|
|
return this.mChildren;
|
|
|
}
|
|
|
|
|
|
public void setIndex(int index) {
|
|
|
this.mIndex = index;
|
|
|
}
|
|
|
|
|
|
public int getIndex() {
|
|
|
return this.mIndex;
|
|
|
}
|
|
|
}
|
