001package gudusoft.gsqlparser.resolver2.result;
002
003import gudusoft.gsqlparser.TCustomSqlStatement;
004import gudusoft.gsqlparser.nodes.TTable;
005import gudusoft.gsqlparser.nodes.TObjectName;
006import gudusoft.gsqlparser.nodes.TCTE;
007import gudusoft.gsqlparser.resolver2.scope.IScope;
008
009import gudusoft.gsqlparser.resolver2.model.ResolutionStatistics;
010
011import java.util.List;
012import java.util.Set;
013
014/**
015 * TSQLResolver2 解析结果的访问接口
016 *
017 * <p>设计原则：</p>
018 * <ul>
019 *   <li>语句为中心 - 按语句查询表和列</li>
020 *   <li>复用现有类型 - 直接返回 TTable、TObjectName、TCTE</li>
021 *   <li>按需查询 - 不预构建所有数据</li>
022 * </ul>
023 *
024 * <p>使用示例:</p>
025 * <pre>
026 * TSQLResolver2 resolver = new TSQLResolver2(context, statements);
027 * resolver.resolve();
028 *
029 * IResolutionResult result = resolver.getResult();
030 *
031 * // 按语句遍历
032 * for (TCustomSqlStatement stmt : resolver.getStatements()) {
033 *     // 获取语句中的表
034 *     for (TTable table : result.getTables(stmt)) {
035 *         System.out.println("Table: " + table.getFullName());
036 *
037 *         // 获取关联到此表的列
038 *         for (TObjectName col : result.getColumnsForTable(stmt, table)) {
039 *             System.out.println("  Column: " + col.getColumnNameOnly());
040 *             System.out.println("  Resolved: " + (col.getSourceTable() != null));
041 *         }
042 *     }
043 *
044 *     // 获取孤儿列（未解析的列）
045 *     for (TObjectName orphan : result.getOrphanColumns(stmt)) {
046 *         System.out.println("  Orphan: " + orphan.getColumnNameOnly());
047 *     }
048 *
049 *     // 递归处理子语句
050 *     for (TCustomSqlStatement subStmt : stmt.getStatements()) {
051 *         // 使用相同的 result 对象处理子语句
052 *     }
053 * }
054 *
055 * // 全局访问（批量处理时有用）
056 * Set&lt;String&gt; allTables = result.getAllTableNames();
057 * Set&lt;String&gt; allFields = result.getAllFieldNames();
058 * </pre>
059 */
060public interface IResolutionResult {
061
062    // ==================== 语句级查询方法 ====================
063
064    /**
065     * 获取指定语句的 Scope
066     * 仅供高级用户使用，一般不需要直接访问 Scope
067     *
068     * @param stmt SQL语句
069     * @return 该语句对应的 Scope，如果不存在返回 null
070     */
071    IScope getScope(TCustomSqlStatement stmt);
072
073    /**
074     * 获取指定语句中涉及的所有表
075     * 默认过滤：排除 JOIN 容器，包含物理表
076     *
077     * @param stmt SQL语句
078     * @return 表列表
079     */
080    List<TTable> getTables(TCustomSqlStatement stmt);
081
082    /**
083     * 获取指定语句中涉及的所有表（带过滤选项）
084     *
085     * @param stmt SQL语句
086     * @param options 过滤选项
087     * @return 表列表
088     */
089    List<TTable> getTables(TCustomSqlStatement stmt, TableFilterOptions options);
090
091    /**
092     * 获取指定语句中涉及的所有列引用
093     *
094     * @param stmt SQL语句
095     * @return 列列表
096     */
097    List<TObjectName> getColumns(TCustomSqlStatement stmt);
098
099    /**
100     * 获取关联到指定表的列
101     *
102     * @param stmt SQL语句
103     * @param table 目标表
104     * @return 关联到此表的列列表
105     */
106    List<TObjectName> getColumnsForTable(TCustomSqlStatement stmt, TTable table);
107
108    /**
109     * 获取指定语句中未解析的列（孤儿列）
110     * 即 sourceTable 为 null 的列
111     *
112     * @param stmt SQL语句
113     * @return 孤儿列列表
114     */
115    List<TObjectName> getOrphanColumns(TCustomSqlStatement stmt);
116
117    /**
118     * 获取指定语句中的 CTE 定义
119     *
120     * @param stmt SQL语句（通常是包含 WITH 子句的 SELECT）
121     * @return CTE 列表
122     */
123    List<TCTE> getCTEs(TCustomSqlStatement stmt);
124
125    // ==================== 全局访问方法 ====================
126
127    /**
128     * 获取所有表名（全局去重）
129     * 适用于批量处理场景
130     *
131     * @return 所有表名集合
132     */
133    Set<String> getAllTableNames();
134
135    /**
136     * 获取所有字段名（table.column 格式，全局去重）
137     *
138     * @return 所有字段名集合
139     */
140    Set<String> getAllFieldNames();
141
142    /**
143     * 获取所有 CTE 名称
144     *
145     * @return CTE 名称集合
146     */
147    Set<String> getAllCTENames();
148
149    /**
150     * 获取所有已解析的列（sourceTable != null）
151     *
152     * @return 已解析列列表
153     */
154    List<TObjectName> getAllResolvedColumns();
155
156    /**
157     * 获取所有未解析的列（sourceTable == null）
158     *
159     * @return 未解析列列表
160     */
161    List<TObjectName> getAllUnresolvedColumns();
162
163    // ==================== 统计信息 ====================
164
165    /**
166     * 获取解析统计信息
167     *
168     * @return 统计信息 (使用 gudusoft.gsqlparser.resolver2.model.ResolutionStatistics)
169     */
170    ResolutionStatistics getStatistics();
171}