package com.easyagents.federation.sql.source;

import java.util.Collection;
import java.util.Optional;

/**
 * 数据源 Definition、revision 与节点本地 Runtime 的管理入口。
 */
public interface FederationSourceManager {

    /**
     * 使用 Resolver 临时探测数据源，并在结束后关闭临时句柄。
     *
     * @param definition 数据源定义
     * @return 探测结果
     */
    SourceProbeResult probe(FederationSourceDefinition definition);

    /**
     * 使用调用方提供的临时句柄探测数据源，并在结束后关闭句柄。
     *
     * @param definition 数据源定义
     * @param temporaryHandle 临时句柄
     * @return 探测结果
     */
    SourceProbeResult probe(FederationSourceDefinition definition, FederationDataSourceHandle temporaryHandle);

    /**
     * 以默认懒加载策略应用 Definition。
     *
     * @param definition 数据源定义
     * @return 应用结果
     */
    default SourceApplyResult apply(FederationSourceDefinition definition) {
        return apply(definition, SourceApplyOptions.lazy());
    }

    /**
     * 应用 Definition 并选择懒加载或预热。
     *
     * @param definition 数据源定义
     * @param options 应用策略
     * @return 应用结果
     */
    SourceApplyResult apply(FederationSourceDefinition definition, SourceApplyOptions options);

    /**
     * 预构建一个不进入共享 Source Slot 的节点本地 Runtime。
     *
     * @param definition 即将发布的数据源 Definition
     * @return 由调用方暂时持有的预构建 Runtime
     */
    PreparedSourceRuntime prepare(FederationSourceDefinition definition);

    /**
     * 原子发布预构建 Runtime，并切换对应 Source Slot 的 desired state。
     *
     * @param prepared 由当前 SourceManager 创建的预构建 Runtime
     * @return Definition 应用结果
     */
    SourceApplyResult commit(PreparedSourceRuntime prepared);

    /**
     * 应用共享状态快照。
     *
     * @param states 状态集合
     * @return 应用统计
     */
    SourceSnapshotResult applySnapshot(Collection<FederationSourceState> states);

    /**
     * 应用递增版本墓碑并禁止新查询。
     *
     * @param tombstone 删除墓碑
     * @return 删除结果
     */
    SourceRemoveResult remove(SourceTombstone tombstone);

    /**
     * 返回节点本地数据源视图。
     *
     * @param sourceId 数据源标识
     * @return 可选视图
     */
    Optional<FederationSourceView> view(SourceId sourceId);

    /**
     * 确保节点本地 Runtime 至少达到指定 revision。
     *
     * @param sourceId 数据源标识
     * @param minimumRevision 最低版本
     * @return 就绪视图
     */
    FederationSourceView ensureReady(SourceId sourceId, long minimumRevision);
}
