/*
 * 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;


/**
 * <p>任务元数据管理类，用于存储Google任务的元数据信息。</p>
 * <p>核心职责：</p>
 * <ul>
 * <li>存储和管理任务的元数据信息</li>
 * <li>处理元数据的JSON序列化和反序列化</li>
 * <li>管理与其他任务的关联关系</li>
 * </ul>
 * <p>设计意图：</p>
 * <ul>
 * <li>继承自{@link Task}类，扩展其功能以支持元数据管理</li>
 * <li>使用JSON格式存储元数据，便于序列化和传输</li>
 * <li>提供元数据的设置和获取接口，简化元数据操作</li>
 * </ul>
 * <p>关键关联：</p>
 * <ul>
 * <li>继承自{@link Task}类，复用任务的基本功能</li>
 * <li>使用{@link GTaskStringUtils}提供的常量定义元数据格式</li>
 * <li>被{@link GTaskManager}和{@link GTaskSyncService}使用，管理任务同步元数据</li>
 * </ul>
 */
public class MetaData extends Task {
    /**
     * <p>日志标签。</p>
     * <p>业务含义：用于在日志中标识MetaData类的相关操作。</p>
     */
    private final static String TAG = MetaData.class.getSimpleName();

    /**
     * <p>关联的Google任务ID。</p>
     * <p>业务含义：存储与当前元数据相关联的Google任务的唯一标识符。</p>
     * <p>约束条件：仅通过{@link #setContentByRemoteJSON(JSONObject)}方法从远程JSON数据中获取。</p>
     */
    private String mRelatedGid = null;

    /**
     * <p>设置任务元数据信息。</p>
     * <p>业务逻辑：</p>
     * <ul>
     * <li>将Google任务ID添加到元数据JSON对象中</li>
     * <li>将元数据JSON对象转换为字符串，存储到任务的notes字段中</li>
     * <li>设置任务名称为元数据专用名称</li>
     * </ul>
     * <p>异常处理：</p>
     * <ul>
     * <li>处理JSONException异常，如果添加Google任务ID失败，记录错误日志</li>
     * </ul>
     * 
     * @param gid 关联的Google任务ID
     * @param metaInfo 元数据JSON对象
     */
    public void setMeta(String gid, JSONObject metaInfo) {
        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);
    }

    /**
     * <p>获取关联的Google任务ID。</p>
     * <p>业务含义：返回与当前元数据相关联的Google任务的唯一标识符。</p>
     * 
     * @return 关联的Google任务ID，如果不存在则返回null
     */
    public String getRelatedGid() {
        return mRelatedGid;
    }

    /**
     * <p>判断元数据是否值得保存。</p>
     * <p>业务逻辑：如果元数据的notes字段不为null，则认为值得保存。</p>
     * 
     * @return 如果元数据值得保存则返回true，否则返回false
     */
    @Override
    public boolean isWorthSaving() {
        return getNotes() != null;
    }

    /**
     * <p>根据远程JSON数据设置元数据内容。</p>
     * <p>业务逻辑：</p>
     * <ul>
     * <li>调用父类的setContentByRemoteJSON方法设置基本任务内容</li>
     * <li>如果notes字段不为null，则解析JSON字符串获取元数据信息</li>
     * <li>从元数据中提取关联的Google任务ID</li>
     * </ul>
     * <p>异常处理：</p>
     * <ul>
     * <li>处理JSONException异常，如果解析元数据失败，记录警告日志并将mRelatedGid设置为null</li>
     * </ul>
     * 
     * @param js 远程JSON数据对象
     */
    @Override
    public void setContentByRemoteJSON(JSONObject js) {
        super.setContentByRemoteJSON(js);
        if (getNotes() != 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;
            }
        }
    }

    /**
     * <p>根据本地JSON数据设置元数据内容。</p>
     * <p>业务逻辑：此方法不应被调用，直接抛出IllegalAccessError异常。</p>
     * <p>注意：MetaData类不支持从本地JSON数据设置内容。</p>
     * 
     * @param js 本地JSON数据对象
     * @throws IllegalAccessError 总是抛出此异常，因为该方法不应被调用
     */
    @Override
    public void setContentByLocalJSON(JSONObject js) {
        // this function should not be called
        throw new IllegalAccessError("MetaData:setContentByLocalJSON should not be called");
    }

    /**
     * <p>从元数据内容获取本地JSON对象。</p>
     * <p>业务逻辑：此方法不应被调用，直接抛出IllegalAccessError异常。</p>
     * <p>注意：MetaData类不支持获取本地JSON数据。</p>
     * 
     * @return 本地JSON数据对象
     * @throws IllegalAccessError 总是抛出此异常，因为该方法不应被调用
     */
    @Override
    public JSONObject getLocalJSONFromContent() {
        throw new IllegalAccessError("MetaData:getLocalJSONFromContent should not be called");
    }

    /**
     * <p>获取元数据的同步操作类型。</p>
     * <p>业务逻辑：此方法不应被调用，直接抛出IllegalAccessError异常。</p>
     * <p>注意：MetaData类不支持获取同步操作类型。</p>
     * 
     * @param c 数据库游标对象
     * @return 同步操作类型
     * @throws IllegalAccessError 总是抛出此异常，因为该方法不应被调用
     */
    @Override
    public int getSyncAction(Cursor c) {
        throw new IllegalAccessError("MetaData:getSyncAction should not be called");
    }

}