Module com.darkcollective.relix.processor
Package com.darkcollective.relix.processor.connector

Interface RelixConnector

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
CsvConnector, GedcomConnector, LogConnector
public interface RelixConnector extends AutoCloseable
The plug-in boundary for an external data source — the open seam that replaces the closed CSV/JSON/JDBC dispatch.

A connector handles one or more type tokens (the word after from in a connection declaration — "jdbc", "csv", "http", "mongodb"); the ConnectorRegistry dispatches to it by that token. All backend-specific configuration arrives per call as a type-agnostic ConnectorConfig, so a connector is stateless with respect to any one query and need not see the semantic model.

Capabilities are expressed by which optional methods a connector overrides, not by boolean flags: schema introspection (tableSchema(com.darkcollective.relix.processor.connector.ConnectorConfig, java.lang.String)) and statistics (tableStatistics(com.darkcollective.relix.processor.connector.ConnectorConfig, java.lang.String)) default to "unavailable", and pushdown (openQuery(com.darkcollective.relix.processor.connector.ConnectorConfig, java.lang.String, com.darkcollective.relix.symbol.Schema)) defaults to "unsupported". A SQL backend overrides openQuery; a document store overrides open only.

Built-in connectors are discovered via ServiceLoader from the module path; external connectors are loaded by ConnectorPluginLoader from the connector directory (~/.relix/connectors/). Implementations must therefore have a public no-argument constructor.

  • Method Details

    • handles

      Set<String> handles()
      The type tokens this connector handles, lower-cased — e.g. {"jdbc"}, {"csv"}, {"mongodb"}. The registry uses these for dispatch.
      Returns:
      a non-empty set of handled type tokens

    • open

      Stream<Row> open(ConnectorConfig config, String table, Schema schema)
      Opens a stream of rows for a named table/collection/endpoint. The caller closes the returned stream.
      Parameters:
      config - the connector configuration for this relation
      table - the table/collection/endpoint name within the source
      schema - the expected output schema (column order and types)
      Returns:
      a stream of rows; the caller is responsible for closing it

    • tableSchema

      default Optional<Schema> tableSchema(ConnectorConfig config, String table)
      Introspects the schema of a table, when the backend supports it. The default returns empty — "not available", in which case the declared schema is used as-is.
      Parameters:
      config - the connector configuration
      table - the table/collection name
      Returns:
      the introspected schema, or empty when unavailable

    • tableStatistics

      default Optional<RelationStatistics> tableStatistics(ConnectorConfig config, String table)
      Returns cardinality/column statistics for a table, when available, to feed the cost model. The default returns empty.
      Parameters:
      config - the connector configuration
      table - the table/collection name
      Returns:
      statistics, or empty when unavailable

    • openQuery

      default Stream<Row> openQuery(ConnectorConfig config, String query, Schema schema)
      Runs a pushed-down native query and streams the result — SQL text for a JDBC backend, an aggregation pipeline for a document store. The default rejects pushdown, so a connector that does not support it never needs to implement this (and the planner simply never produces a pushed query for it).
      Parameters:
      config - the connector configuration
      query - the backend-native query (e.g. SQL)
      schema - the expected output schema; columns read in this order
      Returns:
      a stream of rows; the caller is responsible for closing it
      Throws:
      UnsupportedOperationException - if this connector has no pushdown

    • close

      default void close()
      Releases any resources the connector holds (connection pools, clients). The default does nothing.
      Specified by:
      close in interface AutoCloseable