001package gudusoft.gsqlparser.sqlenv.catalog;
002
003import gudusoft.gsqlparser.sqlenv.ESQLDataObjectType;
004import gudusoft.gsqlparser.sqlenv.TSQLCatalog;
005import gudusoft.gsqlparser.sqlenv.TSQLSchemaObject;
006
007import java.util.List;
008
009/**
010 * Catalog 提供者接口（解耦 TSQLEnv 与具体实现）
011 *
012 * <p>此接口将 Catalog 存储与检索抽象化，支持多种实现：
013 * <ul>
014 *   <li>LegacyCatalogProvider: 兼容旧实现（catalogList）
015 *   <li>CatalogStoreProvider: 新实现（CatalogStore）
016 *   <li>DatabaseCatalogProvider: 外部数据库持久化
017 *   <li>CachedCatalogProvider: Redis/Memcached 缓存
018 * </ul>
019 *
020 * @since 3.2.0 (Phase 0)
021 */
022public interface ICatalogProvider {
023
024    /**
025     * 获取 catalog（不存在返回 null）
026     *
027     * @param catalogName catalog 名称
028     * @return catalog 实例，未找到返回 null
029     */
030    TSQLCatalog getCatalog(String catalogName);
031
032    /**
033     * 创建 catalog（已存在则返回现有）
034     *
035     * @param catalogName catalog 名称
036     * @return catalog 实例
037     */
038    TSQLCatalog createCatalog(String catalogName);
039
040    /**
041     * 获取所有 catalog
042     *
043     * @return catalog 列表
044     */
045    List<TSQLCatalog> getAllCatalogs();
046
047    /**
048     * 获取默认 catalog 名称
049     *
050     * @return 默认 catalog 名称
051     */
052    String getDefaultCatalogName();
053
054    /**
055     * 设置默认 catalog 名称
056     *
057     * @param name 默认 catalog 名称
058     */
059    void setDefaultCatalogName(String name);
060
061    /**
062     * 查找 schema 对象（全限定名查找）
063     *
064     * @param catalog catalog 名称
065     * @param schema schema 名称
066     * @param objectName 对象名称
067     * @param type 对象类型
068     * @return schema 对象，未找到返回 null
069     */
070    TSQLSchemaObject findObject(String catalog, String schema,
071                                 String objectName, ESQLDataObjectType type);
072
073    /**
074     * 添加 schema 对象
075     *
076     * @param object schema 对象
077     */
078    void addObject(TSQLSchemaObject object);
079
080    /**
081     * 移除 schema 对象
082     *
083     * @param object schema 对象
084     * @return true 如果移除成功
085     */
086    boolean removeObject(TSQLSchemaObject object);
087
088    /**
089     * 清空所有对象
090     */
091    void clear();
092
093    /**
094     * 获取对象总数
095     *
096     * @return 对象总数
097     */
098    int size();
099}