package com.easyagents.skill.store;

import java.io.InputStream;

/**
 * Skill 二进制内容流式存储与引用生命周期接口。
 */
public interface SkillContentStore {

    /**
     * 保存内容并返回内容引用。
     *
     * @param bytes 内容字节
     * @return 内容引用
     */
    String put(byte[] bytes);

    /**
     * 暂存内容，供完成全包校验后统一提交。
     *
     * @param inputStream 内容流，不由本方法关闭
     * @param maxBytes 最大允许字节数
     * @return 暂存结果
     */
    SkillContentStage stage(InputStream inputStream, long maxBytes);

    /**
     * 提交暂存内容。
     *
     * @param stage 暂存结果
     * @return 最终内容引用
     */
    String commit(SkillContentStage stage);

    /**
     * 回滚尚未提交的内容。
     *
     * @param stage 暂存结果
     */
    void rollback(SkillContentStage stage);

    /**
     * 增加正式内容引用计数。
     *
     * @param contentRef 内容引用
     */
    void retain(String contentRef);

    /**
     * 释放正式内容引用；引用归零后实现可以删除物理内容。
     *
     * @param contentRef 内容引用
     */
    void release(String contentRef);

    /**
     * 打开内容流。
     *
     * @param contentRef 内容引用
     * @return 内容流
     */
    InputStream open(String contentRef);

    /**
     * 判断内容是否存在。
     *
     * @param contentRef 内容引用
     * @return 存在时为 true
     */
    boolean exists(String contentRef);
}
