[refactor](catalog) connector public interface cleanup: no common-module edit to add a connector, dead-surface deletion, 11 correctness fixes

fe/fe-connector/fe-connector-api/pom.xml

@@ -33,9 +33,15 @@ under the License.
     <packaging>jar</packaging>
     <name>Doris FE Connector API</name>
     <description>
-        Consumer-facing API for the Doris FE connector abstraction layer.
+        The interfaces a Doris FE connector plugin implements, and the engine consumes.
         Contains the core Connector interface, ConnectorMetadata sub-interfaces,
         opaque Handle types, ConnectorSession, value objects, and capability enums.
+        Design rules for the whole connector surface are documented in this module's
+        org.apache.doris.connector.api package-info.
+
+        Note that despite the module names, this is the module a connector implements;
+        fe-connector-spi holds the plugin entry point plus the engine services a
+        connector consumes.
 
         The fe-thrift dependency (provided scope) allows connectors to construct
         typed TTableDescriptor objects for the FE-BE protocol. At runtime the

fe/fe-connector/fe-connector-api/src/main/java/org/apache/doris/connector/api/Connector.java

@@ -19,15 +19,14 @@
 
 import org.apache.doris.connector.api.event.ConnectorEventSource;
 import org.apache.doris.connector.api.handle.ConnectorTableHandle;
-import org.apache.doris.connector.api.handle.WriteOperation;
 import org.apache.doris.connector.api.procedure.ConnectorProcedureOps;
+import org.apache.doris.connector.api.rest.ConnectorRestPassthrough;
 import org.apache.doris.connector.api.scan.ConnectorScanPlanProvider;
 import org.apache.doris.connector.api.write.ConnectorWritePlanProvider;
 
 import java.io.Closeable;
 import java.io.IOException;
 import java.util.Collections;
-import java.util.EnumSet;
 import java.util.List;
 import java.util.Map;
 import java.util.OptionalLong;
@@ -38,10 +37,28 @@
  *
  * <p>A {@code Connector} instance is created once per catalog and provides
  * access to metadata, scan planning, and optional write operations.</p>
+ *
+ * <p><b>This interface does not mirror any provider's switches, and must not start.</b> A subsystem trait
+ * (write operations, parallel write, partition-hash write, ...) is declared on the provider that owns it and
+ * read from there; a forwarding copy here would be a second overridable answer to one question, and a
+ * connector overriding the copy while leaving the provider at its default would produce two divergent
+ * answers with no compile error and no failing test. The engine reaches a trait by fetching the provider
+ * ({@link #getWritePlanProvider(ConnectorTableHandle)} for a per-table answer, {@link #getWritePlanProvider()}
+ * for a connector-wide one) and asking it, treating a {@code null} provider as "not supported".</p>
+ *
+ * <p>The getters that return {@code null} ({@code getScanPlanProvider}, {@code getWritePlanProvider},
+ * {@code getProcedureOps}, {@code getEventSource}, {@code getRestPassthrough}) are the opposite case: those
+ * ARE the declaration points for "this subsystem exists". See the {@code org.apache.doris.connector.api}
+ * package documentation for the full rule.</p>
  */
 public interface Connector extends Closeable {
 
-    /** Returns the metadata interface for the given session. */
+    /**
+     * Returns the metadata interface for the given session. The engine calls this exactly once per catalog per
+     * statement through its own single entry point and closes the result when the statement ends, so an
+     * implementation may return a fresh, statement-scoped object; see {@link ConnectorMetadata} for the
+     * lifecycle contract.
+     */
     ConnectorMetadata getMetadata(ConnectorSession session);
 
     /**
@@ -107,84 +124,6 @@ default ConnectorWritePlanProvider getWritePlanProvider(ConnectorTableHandle han
         return getWritePlanProvider();
     }
 
-    /**
-     * The write operations the engine may perform on this connector — the single admission source. Reads the
-     * write provider's {@link ConnectorWritePlanProvider#supportedOperations()}; no provider ⇒ empty set ⇒ all
-     * writes rejected. The engine consults this instead of {@code getWritePlanProvider() != null}.
-     */
-    default Set<WriteOperation> supportedWriteOperations() {
-        ConnectorWritePlanProvider p = getWritePlanProvider();
-        return p == null ? EnumSet.noneOf(WriteOperation.class) : p.supportedOperations();
-    }
-
-    /**
-     * Per-table view of {@link #supportedWriteOperations()}: derives from {@link #getWritePlanProvider(
-     * ConnectorTableHandle)} so a heterogeneous gateway admits the right operations for {@code handle} (e.g. an
-     * iceberg-on-HMS table admits DELETE/MERGE that the hive provider does not). The default routes through the
-     * per-handle provider, so every single-format connector is unaffected.
-     */
-    default Set<WriteOperation> supportedWriteOperations(ConnectorTableHandle handle) {
-        ConnectorWritePlanProvider p = getWritePlanProvider(handle);
-        return p == null ? EnumSet.noneOf(WriteOperation.class) : p.supportedOperations();
-    }
-
-    /** Null-safe view of {@link ConnectorWritePlanProvider#supportsWriteBranch()}. No provider ⇒ false. */
-    default boolean supportsWriteBranch() {
-        ConnectorWritePlanProvider p = getWritePlanProvider();
-        return p != null && p.supportsWriteBranch();
-    }
-
-    /** Per-table view of {@link #supportsWriteBranch()} (derives from the per-handle provider). */
-    default boolean supportsWriteBranch(ConnectorTableHandle handle) {
-        ConnectorWritePlanProvider p = getWritePlanProvider(handle);
-        return p != null && p.supportsWriteBranch();
-    }
-
-    /** Null-safe view of {@link ConnectorWritePlanProvider#requiresParallelWrite()}. No provider ⇒ false. */
-    default boolean requiresParallelWrite() {
-        ConnectorWritePlanProvider p = getWritePlanProvider();
-        return p != null && p.requiresParallelWrite();
-    }
-
-    /** Null-safe view of {@link ConnectorWritePlanProvider#requiresFullSchemaWriteOrder()}. No provider ⇒ false. */
-    default boolean requiresFullSchemaWriteOrder() {
-        ConnectorWritePlanProvider p = getWritePlanProvider();
-        return p != null && p.requiresFullSchemaWriteOrder();
-    }
-
-    /** Null-safe view of {@link ConnectorWritePlanProvider#requiresPartitionLocalSort()}. No provider ⇒ false. */
-    default boolean requiresPartitionLocalSort() {
-        ConnectorWritePlanProvider p = getWritePlanProvider();
-        return p != null && p.requiresPartitionLocalSort();
-    }
-
-    /** Null-safe view of {@link ConnectorWritePlanProvider#requiresPartitionHashWrite()}. No provider ⇒ false. */
-    default boolean requiresPartitionHashWrite() {
-        ConnectorWritePlanProvider p = getWritePlanProvider();
-        return p != null && p.requiresPartitionHashWrite();
-    }
-
-    /** Per-table view of {@link #requiresPartitionHashWrite()} (derives from the per-handle provider). */
-    default boolean requiresPartitionHashWrite(ConnectorTableHandle handle) {
-        ConnectorWritePlanProvider p = getWritePlanProvider(handle);
-        return p != null && p.requiresPartitionHashWrite();
-    }
-
-    /**
-     * Null-safe view of {@link ConnectorWritePlanProvider#requiresMaterializeStaticPartitionValues()}. No
-     * provider ⇒ false.
-     */
-    default boolean requiresMaterializeStaticPartitionValues() {
-        ConnectorWritePlanProvider p = getWritePlanProvider();
-        return p != null && p.requiresMaterializeStaticPartitionValues();
-    }
-
-    /** Per-table view of {@link #requiresMaterializeStaticPartitionValues()} (derives from the per-handle provider). */
-    default boolean requiresMaterializeStaticPartitionValues(ConnectorTableHandle handle) {
-        ConnectorWritePlanProvider p = getWritePlanProvider(handle);
-        return p != null && p.requiresMaterializeStaticPartitionValues();
-    }
-
     /**
      * Returns the procedure ops for {@code ALTER TABLE EXECUTE} dispatch, or {@code null} if this
      * connector exposes no table procedures. Procedure-side analogue of {@link #getWritePlanProvider()}.
@@ -214,10 +153,10 @@ default Set<ConnectorCapability> getCapabilities() {
 
     /**
      * Storage-configuration defaults this connector derives from its own catalog properties, which the raw
-     * catalog map does not already supply. Design S8: storage-property derivation is owned by the connector —
+     * catalog map does not already supply. Storage-property derivation is owned by the connector —
      * fe-core does not parse metastore properties. fe-core folds the returned map into the catalog's storage
      * properties as DEFAULTS (an explicit user key always wins via {@code putIfAbsent}), and does so BEFORE
-     * both the fe-filesystem bind ({@code ConnectorContext.getStorageProperties()}) and the BE storage map
+     * both the fe-filesystem bind ({@code ConnectorStorageContext.getStorageProperties()}) and the BE storage map
      * ({@code getBackendStorageProperties()}), so the FE bind and the BE scan see the same derived storage.
      *
      * <p>The default is empty (no derivation), so every connector that does not need it is unaffected. The
@@ -231,16 +170,6 @@ default Map<String, String> deriveStorageProperties(Map<String, String> rawCatal
         return Collections.emptyMap();
     }
 
-    /** Returns the table-level property descriptors. */
-    default List<ConnectorPropertyMetadata<?>> getTableProperties() {
-        return Collections.emptyList();
-    }
-
-    /** Returns the session-level property descriptors. */
-    default List<ConnectorPropertyMetadata<?>> getSessionProperties() {
-        return Collections.emptyList();
-    }
-
     /**
      * Returns whether connectivity testing should be enabled by default when
      * the user does not explicitly set the {@code test_connection} property.
@@ -289,21 +218,6 @@ default ConnectorTestResult testConnection(ConnectorSession session) {
     default void close() throws IOException {
     }
 
-    /**
-     * Execute a REST passthrough request against the underlying data source.
-     *
-     * <p>Connectors that expose HTTP endpoints (e.g., Elasticsearch) can
-     * override this to proxy REST requests from FE REST APIs.</p>
-     *
-     * @param path the relative URL path (e.g., "index_name/_search")
-     * @param body the request body (may be null for GET-style requests)
-     * @return the response body as a JSON string
-     * @throws UnsupportedOperationException if the connector doesn't support REST
-     */
-    default String executeRestRequest(String path, String body) {
-        throw new UnsupportedOperationException("REST passthrough not supported by this connector");
-    }
-
     /**
      * Invalidates any connector-side per-table cache (e.g. a latest-snapshot/version cache) so a subsequent
      * read reflects the latest external state. Called by the engine on {@code REFRESH TABLE}. The names are
@@ -348,6 +262,17 @@ default ConnectorEventSource getEventSource() {
         return null;
     }
 
+    /**
+     * Returns this connector's HTTP passthrough capability, or {@code null} if it has none. A capability-probe
+     * getter with the same shape as {@link #getEventSource()}: the caller probes for {@code null}, never via
+     * {@code instanceof}. Consumed by FE HTTP endpoints that speak one source's HTTP dialect (today
+     * {@code ESCatalogAction}), which narrow to that catalog type first and only then ask for the capability.
+     * The default returns {@code null}, so no connector inherits an entry point it cannot serve.
+     */
+    default ConnectorRestPassthrough getRestPassthrough() {
+        return null;
+    }
+
     /**
      * Optional per-connector override of the catalog's schema-cache TTL (in seconds), consulted generically by
      * the engine when sizing the schema meta-cache. Semantics match {@code schema.cache.ttl-second}: