Module org.firebirdsql.jaybird
Package org.firebirdsql.gds.impl

# Interface GDSFactoryPlugin

All Known Implementing Classes:
  `BaseGDSFactoryPlugin`, `WireGDSFactoryPlugin`

public interface GDSFactoryPlugin
SPI interface to define JDBC protocol implementations for Jaybird.

Please be aware that although this is formally an API of Jaybird, it is considered an internal API. This means that it should be considered unstable, though we strive to not make changes in point releases.

Additional protocols can be registered by creating a service definition in `META-INF/services/org.firebirdsql.gds.impl.GDSFactoryPlugin`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Class<?>`
  `getConnectionClass()`
  Class used for connection.
  `FbDatabaseFactory`
  `getDatabaseFactory()`
  `String`
  `getDatabasePath(String jdbcUrl)`
  `String`
  `getDatabasePath(String server, Integer port, String path)`
  `default String`
  `getDatabasePath(DbAttachInfo dbAttachInfo)`
  `String`
  `getDefaultProtocol()`
  The default protocol prefix for this type (for example, for PURE_JAVA, it's `"jdbc:firebirdsql:"`.
  `String`
  `getPluginName()`
  `default List<String>`
  `getSupportedProtocolList()`
  List of JDBC supported protocol prefixes, including `defaultProtocol`.
  `String[]`
  `getSupportedProtocols()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `getSupportedProtocolList()`, may be removed in Jaybird 7 or later
  `String[]`
  `getTypeAliases()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  Use `getTypeAliasList()`, may be removed in Jaybird 7 or later
  `default List<String>`
  `getTypeAliasList()`
  List of type aliases (in addition to `getTypeName()`), for example the PURE_JAVA type has alias TYPE4.
  `String`
  `getTypeName()`

- ## Method Details

  - ### getPluginName

    String getPluginName()
    Returns:
      descriptive name of the plugin

  - ### getTypeName

    String getTypeName()
    Returns:
      primary type name of the plugin
    See Also:
      - `getTypeAliasList()`

  - ### getTypeAliases

    @Deprecated(since="6", forRemoval=true) String[] getTypeAliases()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `getTypeAliasList()`, may be removed in Jaybird 7 or later
    List of type aliases.

    Implementations with aliases are encouraged to explicitly implement `getTypeAliasList()` to return an immutable list and override this method to use `return getTypeAliasList().toArray(new String[0])` or similar.

    Returns:
      array with type aliases (empty array if there are no aliases)
    See Also:
      - `getTypeAliasList()`

  - ### getTypeAliasList

    default List<String> getTypeAliasList()
    List of type aliases (in addition to `getTypeName()`), for example the PURE_JAVA type has alias TYPE4.

    In general, we recommend not to define aliases for types, but instead only have a `typeName`.

    The default implementation wraps `getTypeAliases()`, but implementations are encouraged to implement this with an immutable list. This default implementation will be removed when `getTypeAliases()` is removed.

    Returns:
      list of type aliases (empty list if there are no aliases)
    Since:
      6

  - ### getConnectionClass

    Class<?> getConnectionClass()
    Class used for connection.

    The class must define a one-arg constructor accepting `FBManagedConnection`. Currently, the Jaybird implementation also requires that the class is `FBConnection` or a subclass. This may change in the future.

    Returns:
      class for connection

  - ### getDefaultProtocol

    String getDefaultProtocol()
    The default protocol prefix for this type (for example, for PURE_JAVA, it's `"jdbc:firebirdsql:"`.

    The protocol prefix must be distinct from other plugins.

    Returns:
      default protocol name

  - ### getSupportedProtocols

    @Deprecated(since="6", forRemoval=true) String[] getSupportedProtocols()
    Deprecated, for removal: This API element is subject to removal in a future version.
    Use `getSupportedProtocolList()`, may be removed in Jaybird 7 or later
    List of JDBC supported protocol prefixes.

    Implementations with aliases are encouraged to explicitly implement `getSupportedProtocolList()` to return an immutable list and override this method to use `return getSupportedProtocolList().toArray(new String[0])` or similar.

    Returns:
      array with supported protocol prefixes (must include the value of `getDefaultProtocol()`).
    See Also:
      - `getSupportedProtocolList()`

  - ### getSupportedProtocolList

    default List<String> getSupportedProtocolList()
    List of JDBC supported protocol prefixes, including `defaultProtocol`. For example the PURE_JAVA type has supported protocols `["jdbc:firebirdsql:java:", "jdbc:firebird:java:", "jdbc:firebird:", "jdbc:firebirdsql:"]`.

    In general, one protocol should suffice. An exception can be made if the default is `"jdbc:firebirdsql:subtype:"` to also define `"jdbc:firebird:subtype"`.

    The default implementation wraps `getSupportedProtocols()`, but implementations are encouraged to implement this with an immutable list. This default implementation will be removed when `getSupportedProtocols()` is removed.

    Returns:
      list of type aliases (must include the value of `getDefaultProtocol()`)
    Since:
      6

  - ### getDatabaseFactory

    FbDatabaseFactory getDatabaseFactory()
    Returns:
      instance of `FbDatabaseFactory` for this implementation

  - ### getDatabasePath

    String getDatabasePath(String server, Integer port, String path) throws SQLException
    Throws:
      `SQLException`

  - ### getDatabasePath

    @InternalApi default String getDatabasePath(DbAttachInfo dbAttachInfo) throws SQLException
    Throws:
      `SQLException`

  - ### getDatabasePath

    String getDatabasePath(String jdbcUrl) throws SQLException
    Throws:
      `SQLException`