/*
 * 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.tool.GTaskStringUtils;

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

/**
 * @Package: net.micode.notes.gtask.data
 * @ClassName:  MetaData
 * @Description:
 *  MetaData类继承自 Task 类。它用于处理任务的元数据信息，并封装了一些操作元数据的方法。
 *  这个类用于管理任务的元数据信息，包括相关的 GID，在设置和获取元数据的同时，还提供了判断任务是否值得保存的方法，以及根据远程 JSON 数据设置任务内容的方法。
 *  同时，限制了部分方法的访问，以确保其按照预期的方式被使用。
 *  @Author: Dong Jiaqi
 *  @CreateDate: 12/24/2023 9:53 AM
 */
public class MetaData extends Task {
    private final static String TAG = MetaData.class.getSimpleName();

    private String mRelatedGid = null;

    /**
     * 作用是将给定的 GID 和其他元数据信息添加到任务的注释信息中，并设置任务的名称为固定的值。
     * @param gid 表示任务的全局唯一标识符（Global Task ID），是一个字符串类型的参数。
     * @param metaInfo 表示元数据信息，是一个 JSONObject 对象，包含任务的其他相关信息。
     */
    public void setMeta(String gid, JSONObject metaInfo) {
        /**
         * 这个语句块作用是向 metaInfo 这个 JSONObject 对象中添加一个键值对，其中键是 GTaskStringUtils.META_HEAD_GTASK_ID，值是变量 gid。
         * 使用了 try-catch 块来捕获可能抛出的 JSONException 异常。
         * 为什么要这么写呢：
         * 因为在 Java 中，JSONObject 的 put 方法声明了可能抛出 JSONException 异常。这意味着在调用 put 方法时，需要进行异常处理，否则会导致编译错误。因此，为了保证程序的健壮性，开发者通常会在调用可能会引发异常的方法时使用 try-catch 块进行异常处理，以防止程序异常终止。
         */
        try {
            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() {
        return mRelatedGid;//返回值是一个字符串类型的变量 mRelatedGid，表示相关 GID（Global Task ID）。mRelatedGid 是一个成员变量，它保存了在任务的元数据信息中提取出来的相关 GID。
    }

    //作用是判断任务是否值得保存。它通过检查任务的注释信息是否为null来确定任务是否值得保存。
    @Override
    public boolean isWorthSaving() {
        return getNotes() != null;//如果注释信息不为null，则返回true，表示任务值得保存；反之，如果注释信息为null，则返回false，表示任务不值得保存。
    }

    /**
     * 功能是从远程 JSON 对象中获取任务的内容，包括基本的任务属性和元数据信息，并将其存储到当前的 Task 对象中。
     * @param js JSONObject 对象，表示从远程服务器获取的任务信息。
     */
    @Override
    public void setContentByRemoteJSON(JSONObject js) {
        super.setContentByRemoteJSON(js);
        if (getNotes() != null) {
            /**
             * 这个语句块作用是从任务的注释信息中提取相关 GID，并将其保存到变量 mRelatedGid 中。
             * 使用try-catch块是为了处理可能抛出的异常，确保程序稳定性
             */
            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) {
        // this function should not be called
        throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");//抛出一个IllegalAccessError异常，并且提供异常的详细描述信息
    }

    @Override
    public JSONObject getLocalJSONFromContent() {
        throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called");
    }

    @Override
    public int getSyncAction(Cursor c) {
        throw new IllegalAccessError("MetaData:getSyncAction should not be called");
    }

}
