git_Project/src/gtask/data/TaskList.java

/*
 * 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;//声名gtask下的data包

import android.database.Cursor;//引用andriod和JSON中的一些操作，以及引用自己的包里的一些类
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;//导入json异常处理类
import org.json.JSONObject;//对象类

import java.util.ArrayList;


public class TaskList extends Node {//TaskList类继承于Node类
    private static final String TAG = TaskList.class.getSimpleName();//调用 getSimpleName ()函数来得到类的简写名称并存入字符串TAG中

    private int mIndex;//当前TaskList的指针

    private ArrayList<Task> mChildren;//声明了一个ArrayList的动态数组，这类数组可以加入不同类型的数据

    public TaskList() {//TaskList的构造函数
        super();//调用父类构造方法，也就是Node类
        mChildren = new ArrayList<Task>();//声明arraylist数组
        mIndex = 1;//初始化
    }

    public JSONObject getCreateAction(int actionId) {//定义在Node中定义的一个抽象函数
        JSONObject js = new JSONObject();//创建一个新的JSONObject对象

        try {
            // action_type
            js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                    GTaskStringUtils.GTASK_JSON_ACTION_TYPE_CREATE);//指明了操作类型是“create”

            // action_id
            js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);//调用put放入编号

            // index
            js.put(GTaskStringUtils.GTASK_JSON_INDEX, mIndex);

            // entity_delta
            JSONObject entity = new JSONObject();//新建一个新的JSONObject对象
            entity.put(GTaskStringUtils.GTASK_JSON_NAME, getName());//getName是父类的一个函数
            entity.put(GTaskStringUtils.GTASK_JSON_CREATOR_ID, "null");//将创建者的ID设置为空
            entity.put(GTaskStringUtils.GTASK_JSON_ENTITY_TYPE,
                    GTaskStringUtils.GTASK_JSON_TYPE_GROUP);//将实体类型设置为“GROUP”
            js.put(GTaskStringUtils.GTASK_JSON_ENTITY_DELTA, entity);

        } catch (JSONException e) {//异常处理机制
            Log.e(TAG, e.toString());//获取异常类型和异常详细消息
            e.printStackTrace();//在命令行打印异常信息在程序中出错的位置及原因
            throw new ActionFailureException("fail to generate tasklist-create jsonobject");//抛出异常，生成更新任务列表的 JSONObject 失败
        }

        return js;//将已经存储数据的js对象返回
    }

    public JSONObject getUpdateAction(int actionId) {//获取更新的行为
        JSONObject js = new JSONObject();//创建一个JSONObject的实例化对象js

        try {
            // action_type
            js.put(GTaskStringUtils.GTASK_JSON_ACTION_TYPE,
                    GTaskStringUtils.GTASK_JSON_ACTION_TYPE_UPDATE);//初始化js中的类型

            // action_id
            js.put(GTaskStringUtils.GTASK_JSON_ACTION_ID, actionId);//初始化actionID

            // id
            js.put(GTaskStringUtils.GTASK_JSON_ID, getGid());//初始化ID

            // entity_delta
            JSONObject entity = new JSONObject();//创建一个 JSONObject 的实例化对象entity
            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) {//异常处理机制
            Log.e(TAG, e.toString());//获取异常类型和异常详细消息
            e.printStackTrace();//在命令行打印异常信息在程序中出错的位置及原因
            throw new ActionFailureException("fail to generate tasklist-update jsonobject");//抛出异常
        }

        return js;
    }

    public void setContentByRemoteJSON(JSONObject js) {//通过远端设置内容
        if (js != null) {//js对象不为空
            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)) {//若 js 中存在 GATSK_JSON_LAST_MODIFIED 信息
                    setLastModified(js.getLong(GTaskStringUtils.GTASK_JSON_LAST_MODIFIED));//获取 GTASK_JSON_NAME 字符串并设置为该 js 对象的名称
                }

                // name
                if (js.has(GTaskStringUtils.GTASK_JSON_NAME)) {
                    setName(js.getString(GTaskStringUtils.GTASK_JSON_NAME));//对任务的name进行设置
                }

            } catch (JSONException e) {//异常处理机制
                Log.e(TAG, e.toString());//获取异常类型和异常详细消息
                e.printStackTrace();//在命令行打印异常信息在程序中出错的位置及原因
                throw new ActionFailureException("fail to get tasklist content from jsonobject");//抛出异常
            }
        }
    }

    public void setContentByLocalJSON(JSONObject js) {//通过本地 JSON 数据设置对象 js 内容
        if (js == null || !js.has(GTaskStringUtils.META_HEAD_NOTE)) {//若 js 创建失败或 js 中不存在 META_HEAD_NOTE信息
            Log.w(TAG, "setContentByLocalJSON: nothing is avaiable");//警告，没有可用资源
        }

        try {
            JSONObject folder = js.getJSONObject(GTaskStringUtils.META_HEAD_NOTE);

            if (folder.getInt(NoteColumns.TYPE) == Notes.TYPE_FOLDER) {//若为一般类型的文件夹
                String name = folder.getString(NoteColumns.SNIPPET);//获取文件夹片段字符串作为文件夹名称
                setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX + name);//设置名称为MIUI系统文件夹前缀+文件夹名称
            } 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);//设置名称为MIUI系统文件夹前缀+默认文件夹名称
                else if (folder.getLong(NoteColumns.ID) == Notes.ID_CALL_RECORD_FOLDER)//若为通话记录文件夹
                    setName(GTaskStringUtils.MIUI_FOLDER_PREFFIX
                            + GTaskStringUtils.FOLDER_CALL_NOTE);//设置名称为MIUI系统文件夹前缀+默认文件夹名称
                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() {//通过 Content 机制获取本地 JSON 数据
        try {
            JSONObject js = new JSONObject();//创建一个 JSONObject 的实例化对象 js
            JSONObject folder = new JSONObject();//创建一个 JSONObject 的实例化对象 folder

            String folderName = getName();//获取完整的文件名字
            if (getName().startsWith(GTaskStringUtils.MIUI_FOLDER_PREFFIX))//如果这个文件名字是以"[MIUI_Notes]"开头
                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))//当获取的文件夹名称是以"Default"或"Call_Note开头
                folder.put(NoteColumns.TYPE, Notes.TYPE_SYSTEM);//则为系统文件夹
            else
                folder.put(NoteColumns.TYPE, Notes.TYPE_FOLDER);//否则为一般文件夹

            js.put(GTaskStringUtils.META_HEAD_NOTE, folder);

            return js;
        } catch (JSONException e) {//异常处理机制
            Log.e(TAG, e.toString());//获取异常类型和异常详细消息
            e.printStackTrace();//在命令行打印异常信息在程序中出错的位置及原因
            return null;
        }
    }

    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()) {//最近一次修改的 id 匹配成功
                    // no update both side
                    return SYNC_ACTION_NONE;//返回无的同步行为
                } else {//匹配失败
                    // apply remote to local
                    return SYNC_ACTION_UPDATE_LOCAL;//返回更新本地数据的同步行为
                }
            } else {
                // validate gtask id
                if (!c.getString(SqlNote.GTASK_ID_COLUMN).equals(getGid())) {//如果获取的ID不匹配
                    Log.e(TAG, "gtask id doesn't match");//错误，id不匹配
                    return SYNC_ACTION_ERROR;//返回同步动作失败
                }
                if (c.getLong(SqlNote.SYNC_ID_COLUMN) == getLastModified()) {//如果是最近一次修改的 id
                    // 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;//返回同步动作失败
    }

    public int getChildTaskCount() {//获取列表中子任务数量
        return mChildren.size();
    }

    public boolean addChildTask(Task task) {//在当前任务表中添加新的子任务
        boolean ret = false;//定义一个布尔型变量，初始化为false。
        if (task != null && !mChildren.contains(task)) {//任务非空且任务表中不存在该任务
            ret = mChildren.add(task);//在mChildren中 添加子任务，成功与否返回至ret中保存
            if (ret) {//添加子任务成功
                // need to set prior sibling and parent
                task.setPriorSibling(mChildren.isEmpty() ? null : mChildren
                        .get(mChildren.size() - 1));//设置兄弟任务优先级，若子任务为空，返回 NULL，否则返回子任务数量-1
                task.setParent(this);//设置该任务的父任务
            }
        }
        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;
        }

        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);
            if (index != mChildren.size() - 1)
                afterTask = mChildren.get(index + 1);

            task.setPriorSibling(preTask);//使得三个任务前后连在一块
            if (afterTask != null)//下一个任务设置兄弟任务优先级
                afterTask.setPriorSibling(task);
        }

        return true;
    }

    public boolean removeChildTask(Task task) {//删除任务表中的子任务
        boolean ret = false;//声明布尔类型ret为false
        int index = mChildren.indexOf(task);//获取该任务在任务表中的索引
        if (index != -1) {//index不等于-1，说明任务列表中存在该任务
            ret = mChildren.remove(task);//删除mChildren中的任务

            if (ret) {//如果删除成功
                // reset prior sibling and parent
                task.setPriorSibling(null);
                task.setParent(null);//就要将该任务的优先兄弟任务和父任务设置为空

                // update the task list
                if (index != mChildren.size()) {//删除成功后
                    mChildren.get(index).setPriorSibling(
                            index == 0 ? null : mChildren.get(index - 1));//对任务列表进行更新
                }
            }
        }
        return ret;//返回值是是否删除成功
    }

    public boolean moveChildTask(Task task, int index) {//将当前TaskList中含有的某个Task移到index位置

        if (index < 0 || index >= mChildren.size()) {//目标位置越界，无效
            Log.e(TAG, "move child task: invalid index");//错误，无效的索引导致移动子任务失败
            return false;
        }

        int pos = mChildren.indexOf(task);//若所要查找的子任务不存在
        if (pos == -1) {
            Log.e(TAG, "move child task: the task should in the list");//错误，任务不在列表中导致移动子任务失败
            return false;
        }

        if (pos == index)//当前位置与索引匹配成功
            return true;//返回真值
        return (removeChildTask(task) && addChildTask(task, index));//不相等则进行删除和添加即移动操作
    }

    public Task findChildTaskByGid(String gid) {//按gid寻找Task
        for (int i = 0; i < mChildren.size(); i++) {//遍历整个任务列表判断任务的gid与传入的gid是否相等
            Task t = mChildren.get(i);
            if (t.getGid().equals(gid)) {
                return t;
            }
        }
        return 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;
        }
        return mChildren.get(index);
    }

    public Task getChilTaskByGid(String gid) {//返回指定gid的任务task
        for (Task task : mChildren) {//ArrayList的遍历
            if (task.getGid().equals(gid))
                return task;
        }
        return null;
    }

    public ArrayList<Task> getChildTaskList() {//获取子任务列表
        return this.mChildren;
    }

    public void setIndex(int index) {//设置任务索引
        this.mIndex = index;
    }

    public int getIndex() {
        return this.mIndex;//获取任务索引
    }
}