package com.easyagents.federation.sql.adapter;

import com.easyagents.federation.sql.federation.FederationStatisticsSnapshot;
import com.easyagents.federation.sql.federation.FederationTableStatistics;
import java.sql.SQLException;
import java.util.Map;

/**
 * 数据库 Adapter 提供的轻量目录统计采集 SPI。
 *
 * <p>实现应使用数据库系统目录或 JDBC 元数据批量采集，禁止执行逐表
 * {@code COUNT(*)}。采集异常由引擎统一降级，不应在实现中伪造成功结果。</p>
 */
@FunctionalInterface
public interface FederationStatisticsCollector {

    /**
     * 采集一个物理数据源当前 revision 的表统计。
     *
     * @param context 统计采集上下文
     * @return 按逻辑 Schema 和物理表索引的不可变统计；不支持时返回空映射
     * @throws SQLException 数据库目录或 JDBC 元数据读取失败
     */
    Map<FederationStatisticsSnapshot.TableKey, FederationTableStatistics> collect(
        FederationStatisticsCollectionContext context
    ) throws SQLException;
}
