/*
 * 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 中组织类的方式，有助于代码的组织和管理。
package net.micode.notes.gtask.data;
//导入 Android 的 Cursor 类，Cursor 是用于访问和操作数据库查询结果的工具。
import android.database.Cursor;
//导入 Android 的 Log 类，用于在代码中输出日志信息。
import android.util.Log;

//导入一个自定义的工具类 GTaskStringUtils，它包含与 Google Tasks 相关的常量和方法。
import net.micode.notes.tool.GTaskStringUtils;

//导入 JSON 处理类。JSONObject 用于创建和解析 JSON 数据，JSONException 用于捕获解析 JSON 时的错误。
import org.json.JSONException;
import org.json.JSONObject;



//定义一个公共类 MetaData，该类继承自 Task 类，表示与 Google 任务相关的元数据（例如任务的 gid）。
public class MetaData extends Task {
    
    //定义一个 TAG 字符串常量，存储当前类的简短类名 "MetaData"，用于在日志中输出调试信息。
    private final static String TAG = MetaData.class.getSimpleName();

    
    //声明一个私有成员变量 mRelatedGid，用于保存与任务相关的 Google 任务 ID（gid）。初始值为 null。
    private String mRelatedGid = null;


//    定义一个公共方法 setMeta，用于设置任务的元数据。接收两个参数：
//    gid：一个字符串，表示任务的 Google ID。
//    metaInfo：一个 JSONObject，包含其他元数据（如任务的附加信息）。
    public void setMeta(String gid, JSONObject metaInfo) {

//        尝试将传入的 gid 插入到 metaInfo 中。GTaskStringUtils.META_HEAD_GTASK_ID 是用于存储任务 ID 的常量。
//        如果插入失败，捕获 JSONException 异常并打印错误日志。
        try {
            metaInfo.put(GTaskStringUtils.META_HEAD_GTASK_ID, gid);
        } catch (JSONException e) {
            Log.e(TAG, "failed to put related gid");
        }
        //将 metaInfo 转换为字符串并调用 setNotes() 方法保存。这将任务的元数据作为字符串保存在任务的 notes 字段中。
        setNotes(metaInfo.toString());
        //调用 setName() 设置任务的名称为 GTaskStringUtils.META_NOTE_NAME。这个名称可能是一个预定义的常量，表示任务的默认名称。
        setName(GTaskStringUtils.META_NOTE_NAME);
    }


    //定义一个公共方法 getRelatedGid，用于获取与任务相关的 Google 任务 ID。
    // return mRelatedGid;：返回之前保存的 mRelatedGid。
    public String getRelatedGid() {
        return mRelatedGid;
    }

    
    
    //@Override：表示该方法是重写父类 Task 中的方法。
    //public boolean isWorthSaving()：定义一个方法 isWorthSaving，用于判断当前任务是否值得保存。通常，它会根据某些条件来判断任务是否需要被同步或保存到数据库中。
    //return getNotes() != null;：判断任务的 notes 字段是否为 null。如果 notes 字段不为空，说明任务有有效内容，返回 true；否则返回 false。
    @Override
    public boolean isWorthSaving() {
        return getNotes() != null;
    }
    @Override
    //定义方法 setContentByRemoteJSON，用于从远程获取 JSON 数据并设置任务内容。
    public void setContentByRemoteJSON(JSONObject js) {
        //调用父类的同名方法来处理远程 JSON 数据的基本设置。
        super.setContentByRemoteJSON(js);
        //检查任务的 notes 字段是否不为空。
        if (getNotes() != null) {
            //如果 notes 不为空，尝试将其转换为 JSONObject。
            //然后，从中提取出 gid 并保存到 mRelatedGid 中。
            // 如果解析过程中出现错误（例如格式问题),会捕获 JSONException 并输出警告日志，同时将 mRelatedGid 设为 null。
            try {
                JSONObject metaInfo = new JSONObject(getNotes().trim());
                mRelatedGid = metaInfo.getString(GTaskStringUtils.META_HEAD_GTASK_ID);
            } catch (JSONException e) {
                Log.w(TAG, "failed to get related gid");
                mRelatedGid = null;
            }
        }
    }

    
    //@Override：
    //public void setContentByLocalJSON(JSONObject js)：
    //throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");：
    @Override
    //该方法定义了从本地 JSON 数据设置任务内容的行为。
    public void setContentByLocalJSON(JSONObject js) {
        // this function should not be called
        //该方法被设计为不可调用，如果被调用，抛出 IllegalAccessError 异常。
        // 该类不允许使用本地 JSON 数据设置任务内容，因此抛出异常来提醒开发者
        throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");
    }



    //表示重写父类的方法。
    @Override
    //该方法定义了获取本地 JSON 数据的行为。
    public JSONObject getLocalJSONFromContent() {
        //与 setContentByLocalJSON 类似，该方法不应该被调用，如果被调用，抛出 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");
    }

}