//开源许可证声明
/*
 * 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.
 */
//声明了当前Java文件所属的包名。包名用于组织和管理Java类，避免命名冲突。
package net.micode.notes.gtask.data;

//导入Android系统提供的Cursor类，用于数据库查询操作。
import android.database.Cursor;
import android.util.Log;

import net.micode.notes.tool.GTaskStringUtils;

import org.json.JSONException;
import org.json.JSONObject;

//定义了一个名为MetaData的类，它继承自Task类。
//这个类主要用于处理与任务相关的元数据，包括设置元数据、获取相关任务ID、判断是否需要保存以及根据远程JSON和本地JSON设置内容等操作。
public class MetaData extends Task {
    // 定义一个常量，用于日志输出
    private final static String TAG = MetaData.class.getSimpleName();

    // 定义一个私有变量，用于存储相关任务ID
    private String mRelatedGid = null;

    // 设置元数据
    public void setMeta(String gid, JSONObject metaInfo) {
        try {
            // 将相关任务ID添加到元数据中（添加到JSON对象中，用于存储元数据）
            metaInfo.put(GTaskStringUtils.META_HEAD_GTASK_ID, gid);
        } catch (JSONException e) {
            // 日志输出错误信息
            Log.e(TAG, "failed to put related gid");
        }
        // 设置备注
        setNotes(metaInfo.toString());
        // 设置名称
        setName(GTaskStringUtils.META_NOTE_NAME);
    }

    // 获取相关任务的全局唯一标识符（GID）
    public String getRelatedGid() {
        // 返回存储的相关任务ID
        return mRelatedGid;
    }

    // 判断是否需要保存
    //重写父类方法，用于判断当前元数据是否值得保存。
    @Override
    public boolean isWorthSaving() {
        //如果备注信息不为 null，则认为该元数据有保存的价值，返回 true；
        // 反之，如果备注信息为 null，则返回 false
        return getNotes() != null;
    }

    // 根据远程JSONObject设置对象的内容
    //重写父类方法，用于根据远程JSON设置内容。
    //该方法首先调用父类的方法，然后尝试解析备注信息，提取相关任务ID。
    @Override//此注解表明该方法重写了父类 Task 中的 setContentByRemoteJSON 方法。
    //Java 编译器会检查父类是否存在同名同参数的方法，若不存在则会报错。
    //参数js：远程JSON对象，包含任务的元数据信息。
    public void setContentByRemoteJSON(JSONObject js) {
        super.setContentByRemoteJSON(js);
        // 调用父类 Task 的 setContentByRemoteJSON 方法，先让父类处理远程的 JSONObject，完成一些基础的内容设置操作。
        if (getNotes() != null) {
            //检查当前对象的备注信息是否不为 null。只有备注信息存在时，才会尝试从中提取相关任务的 GID。
            // 这是因为在 Google Task 中，元数据通常存储在备注信息中，而不是单独的字段。
            try {
                // 将备注转换为JSON对象
                JSONObject metaInfo = new JSONObject(getNotes().trim());
                //把备注信息去除首尾空格后转换为 JSONObject 对象。这样做是为了确保备注信息格式正确，能被 JSONObject 解析。
                //trim() 方法用于去除字符串两端的空白字符（包括空格、制表符、换行符等）。
                //getNotes() 方法返回当前对象的备注信息字符串。
                //new JSONObject(getNotes().trim()) 将备注信息转换为 JSON 对象。    
                
                // 获取相关任务ID
                mRelatedGid = metaInfo.getString(GTaskStringUtils.META_HEAD_GTASK_ID);
                //从 JSON 对象中获取相关任务的 GID。
                //metaInfo.getString(GTaskStringUtils.META_HEAD_GTASK_ID)：从 JSON 对象中获取名为 META_HEAD_GTASK_ID 的键值。
                //GTaskStringUtils.META_HEAD_GTASK_ID：一个常量字符串，表示 JSON 对象中存储相关任务 ID 的键名。
                //mRelatedGid：一个字符串变量，用于存储从 JSON 对象中获取到的相关任务 ID。
            } catch (JSONException e) {
                // 日志输出警告信息
                Log.w(TAG, "failed to get related gid");
                // 将相关任务ID设置为null
                mRelatedGid = null;
            }
        }
    }

    // 根据本地JSON设置内容
    @Override//注解，表明当前方法重写了父类中的同名方法
    public void setContentByLocalJSON(JSONObject js) {
        // this function should not be called
        // 抛出一个IllegalAccessError异常，提示该方法不应该被调用。
        throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");
    }

    // 从内容中获取本地JSON
    @Override
    public JSONObject getLocalJSONFromContent() {
        // 抛出一个IllegalAccessError异常，提示该方法不应该被调用。
        throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called");
    }

    // 获取同步操作
    @Override
    public int getSyncAction(Cursor c) {
        // 抛出一个IllegalAccessError异常，提示该方法不应该被调用。
        throw new IllegalAccessError("MetaData:getSyncAction should not be called");
    }

}
