git/java/net/micode/notes/gtask/data/Node.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;

import android.database.Cursor;

import org.json.JSONObject;

/**
 * GTask同步的核心抽象节点类
 * 该类是所有GTask同步数据（如笔记、文件夹）的基类，定义了同步所需的通用属性（GID、名称、修改时间、删除标记）、
 * 同步动作常量以及需要子类实现的抽象方法（JSON序列化/反序列化、同步动作判断等）。
 * 作为抽象类，它封装了GTask同步的通用逻辑，子类需根据具体数据类型（笔记/文件夹）实现抽象方法，完成具体的同步逻辑。
 *
 * @author MiCode Open Source Community
 * @date 2010-2011
 */
public abstract class Node {
    // ====================== 同步动作常量 ======================
    /**
     * 同步动作：无操作（数据一致，无需同步）
     */
    public static final int SYNC_ACTION_NONE = 0;

    /**
     * 同步动作：向远程GTask添加数据（本地新增数据，需要同步到远程）
     */
    public static final int SYNC_ACTION_ADD_REMOTE = 1;

    /**
     * 同步动作：向本地添加数据（远程GTask新增数据，需要同步到本地）
     */
    public static final int SYNC_ACTION_ADD_LOCAL = 2;

    /**
     * 同步动作：删除远程GTask数据（本地删除数据，需要同步删除远程数据）
     */
    public static final int SYNC_ACTION_DEL_REMOTE = 3;

    /**
     * 同步动作：删除本地数据（远程GTask删除数据，需要同步删除本地数据）
     */
    public static final int SYNC_ACTION_DEL_LOCAL = 4;

    /**
     * 同步动作：更新远程GTask数据（本地数据修改，需要同步更新远程数据）
     */
    public static final int SYNC_ACTION_UPDATE_REMOTE = 5;

    /**
     * 同步动作：更新本地数据（远程GTask数据修改，需要同步更新本地数据）
     */
    public static final int SYNC_ACTION_UPDATE_LOCAL = 6;

    /**
     * 同步动作：数据冲突（本地和远程数据都被修改，需要处理冲突）
     */
    public static final int SYNC_ACTION_UPDATE_CONFLICT = 7;

    /**
     * 同步动作：同步错误（同步过程中出现异常，标记为错误状态）
     */
    public static final int SYNC_ACTION_ERROR = 8;

    // ====================== 成员变量 ======================
    /**
     * GTask的唯一标识ID（Gid），用于关联本地数据和远程GTask数据
     */
    private String mGid;

    /**
     * 节点名称（如笔记标题、文件夹名称）
     */
    private String mName;

    /**
     * 最后修改时间戳（毫秒），用于判断数据是否需要同步（本地与远程时间对比）
     */
    private long mLastModified;

    /**
     * 删除标记：true表示数据已被删除（本地或远程），需要同步删除操作
     */
    private boolean mDeleted;

    /**
     * 构造方法：初始化节点的默认属性
     * Gid为null，名称为空字符串，最后修改时间为0，删除标记为false
     */
    public Node() {
        mGid = null;
        mName = "";
        mLastModified = 0;
        mDeleted = false;
    }

    // ====================== 抽象方法（子类需实现） ======================
    /**
     * 获取创建动作的JSON对象（用于向远程GTask发送创建请求）
     * @param actionId 动作ID（标识本次创建动作的唯一ID）
     * @return 包含创建动作信息的JSONObject
     */
    public abstract JSONObject getCreateAction(int actionId);

    /**
     * 获取更新动作的JSON对象（用于向远程GTask发送更新请求）
     * @param actionId 动作ID（标识本次更新动作的唯一ID）
     * @return 包含更新动作信息的JSONObject
     */
    public abstract JSONObject getUpdateAction(int actionId);

    /**
     * 根据远程GTask的JSON数据设置节点内容（将远程数据同步到本地）
     * @param js 远程GTask返回的JSON数据对象
     */
    public abstract void setContentByRemoteJSON(JSONObject js);

    /**
     * 根据本地的JSON数据设置节点内容（本地数据序列化后的恢复）
     * @param js 本地存储的JSON数据对象
     */
    public abstract void setContentByLocalJSON(JSONObject js);

    /**
     * 从节点内容中获取本地JSON数据（将本地数据序列化为JSON，用于存储或同步）
     * @return 包含本地节点内容的JSONObject
     */
    public abstract JSONObject getLocalJSONFromContent();

    /**
     * 根据本地数据库的Cursor数据判断当前节点的同步动作类型
     * 核心逻辑：对比本地数据和远程GTask数据的状态（新增、修改、删除），返回对应的同步动作常量
     * @param c 本地数据库的Cursor对象（包含本地数据的状态信息）
     * @return 同步动作类型（对应SYNC_ACTION_*常量）
     */
    public abstract int getSyncAction(Cursor c);

    // ====================== 成员变量的setter/getter方法 ======================
    /**
     * 设置GTask的唯一标识ID（Gid）
     * @param gid 远程GTask的Gid字符串
     */
    public void setGid(String gid) {
        this.mGid = gid;
    }

    /**
     * 设置节点名称
     * @param name 节点名称字符串（笔记标题/文件夹名称）
     */
    public void setName(String name) {
        this.mName = name;
    }

    /**
     * 设置最后修改时间戳
     * @param lastModified 最后修改时间（毫秒）
     */
    public void setLastModified(long lastModified) {
        this.mLastModified = lastModified;
    }

    /**
     * 设置删除标记
     * @param deleted true表示数据已被删除，false表示数据正常
     */
    public void setDeleted(boolean deleted) {
        this.mDeleted = deleted;
    }

    /**
     * 获取GTask的唯一标识ID（Gid）
     * @return Gid字符串，若未关联远程数据则返回null
     */
    public String getGid() {
        return this.mGid;
    }

    /**
     * 获取节点名称
     * @return 节点名称字符串
     */
    public String getName() {
        return this.mName;
    }

    /**
     * 获取最后修改时间戳
     * @return 最后修改时间（毫秒）
     */
    public long getLastModified() {
        return this.mLastModified;
    }

    /**
     * 获取删除标记
     * @return true表示数据已被删除，false表示数据正常
     */
    public boolean getDeleted() {
        return this.mDeleted;
    }

}