Module com.darkcollective.relix.connectors.std
Package com.darkcollective.relix.connectors.std.internal

Interface ConnectionProvider

All Known Implementing Classes:
DataSourceRegistry
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface ConnectionProvider
Turns a declared connection into a live JDBC Connection.

Exactly two places need one, and until this seam existed both reached the same static opener: catalog introspection during analysis (JdbcCatalogProvider) and query execution (ConnectionPool.borrow(com.darkcollective.relix.lang.ast.ConnectionDeclaration)). Both began at ConnectionDeclaration.config(), which requires a url — so a connection whose coordinates are not a URL could not be served at all, and failed during analysis rather than at the point of use.

The declaration is the argument rather than the projected DatabaseConnectionConfig for exactly that reason: an implementation that resolves a connection by name needs the name, and the projection discards it.

Pooling

managesPooling(com.darkcollective.relix.lang.ast.ConnectionDeclaration) tells ConnectionPool whether a connection from this provider is already pooled somewhere else. It is asked per declaration, not per provider, because one session may mix the two — a provider may serve some connections from its own registry and delegate the rest here. When it answers true the engine's pool retains nothing: it opens on demand and closes on release, which is what hands the connection back to whatever pool actually owns it.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final ConnectionProvider
    FROM_URL
    The default provider: opens a fresh connection from the declaration's url through DriverManager, which is the behaviour every caller had before this seam existed.

  • Method Summary

    Modifier and Type
    Method
    Description
    Connection
    connectionFor(ConnectionDeclaration connection)
    Opens a connection for the given declaration.
    default boolean
    managesPooling(ConnectionDeclaration connection)
    Whether connections this provider returns for connection are pooled by something other than ConnectionPool, so the engine must not retain them.

  • Field Details

    • FROM_URL

      static final ConnectionProvider FROM_URL
      The default provider: opens a fresh connection from the declaration's url through DriverManager, which is the behaviour every caller had before this seam existed.

      A declaration with no url yields a SQLException rather than the IllegalStateException ConnectionDeclaration.config() raises. That distinction is the point: "this is not a JDBC connection" is a condition a JDBC caller must be able to handle, and every caller here already degrades on SQLException — introspection to "schema unavailable", execution to an evaluation error naming the connection.

  • Method Details

    • connectionFor

      Connection connectionFor(ConnectionDeclaration connection) throws SQLException
      Opens a connection for the given declaration.
      Parameters:
      connection - the declared connection; must not be null
      Returns:
      an open connection the caller owns
      Throws:
      SQLException - if no connection can be opened for this declaration

    • managesPooling

      default boolean managesPooling(ConnectionDeclaration connection)
      Whether connections this provider returns for connection are pooled by something other than ConnectionPool, so the engine must not retain them.
      Parameters:
      connection - the declared connection
      Returns:
      true to bypass engine-side pooling; false by default