package com.easyagents.federation.sql.execute;

import java.io.InputStream;
import java.io.Reader;
import java.util.List;

/**
 * 按行消费且必须关闭的流式结果游标。
 */
public interface FederationResultCursor extends AutoCloseable {

    /**
     * 返回查询标识。
     *
     * @return 查询标识
     */
    QueryId queryId();

    /**
     * 返回结果列元数据。
     *
     * @return 不可变列列表
     */
    List<FederationColumn> columns();

    /**
     * 返回查询当前或关闭后的消耗指标快照。
     *
     * @return 不可变指标快照
     */
    default FederationQueryMetricsSnapshot metrics() {
        return FederationQueryMetricsSnapshot.unavailable();
    }

    /**
     * 移动至下一行。
     *
     * @return 是否存在下一行
     */
    boolean next();

    /**
     * 按 JDBC 列序号读取当前行。
     *
     * @param columnIndex 从 1 开始的列序号
     * @return 列值
     */
    Object getObject(int columnIndex);

    /**
     * 以流方式读取二进制列，避免调用方为大字段一次性分配完整字节数组。
     *
     * @param columnIndex 从 1 开始的列序号
     * @return 二进制流；SQL NULL 返回 null
     * @throws UnsupportedOperationException Adapter 不支持流式列读取
     */
    default InputStream getBinaryStream(int columnIndex) {
        throw new UnsupportedOperationException("binary stream access is not supported by this adapter");
    }

    /**
     * 以流方式读取字符列，避免调用方为大字段一次性分配完整字符串。
     *
     * @param columnIndex 从 1 开始的列序号
     * @return 字符流；SQL NULL 返回 null
     * @throws UnsupportedOperationException Adapter 不支持流式列读取
     */
    default Reader getCharacterStream(int columnIndex) {
        throw new UnsupportedOperationException("character stream access is not supported by this adapter");
    }

    /**
     * 将当前行复制为不可变列表。
     *
     * @return 当前行列值
     */
    List<Object> row();

    /**
     * 关闭结果集、Statement、Connection、准入许可和 Runtime lease。
     */
    @Override
    void close();
}
