Module org.firebirdsql.jaybird
Package org.firebirdsql.jaybird.props

Interface DatabaseConnectionProperties

All Superinterfaces:
AttachmentProperties, BaseProperties
All Known Subinterfaces:
FirebirdConnectionProperties, IConnectionProperties
All Known Implementing Classes:
AbstractConnectionPropertiesDataSource, FBAbstractCommonDataSource, FBConnectionPoolDataSource, FbConnectionProperties, FBConnectionProperties, FbImmutableConnectionProperties, FBManagedConnectionFactory, FBSimpleDataSource, FBXADataSource
public interface DatabaseConnectionProperties extends AttachmentProperties
Properties for database connections.
Since:
5
Author:
Mark Rotteveel

  • Method Details

    • getDatabaseName

      default String getDatabaseName()
      Gets the database of the connection.
      Returns:
      database name
      See Also:

    • setDatabaseName

      default void setDatabaseName(String databaseName)
      Sets the database of the connection

      When serverName is null, the value is taken as the URL of the database, and exact interpretation depends on the protocol implementation (type). Basically, the URL would be the JDBC URL, but without the jdbc:firebird[sql]:[subprotocol:] prefix and without connection properties. Examples:

      • //localhost/employee — PURE_JAVA, NATIVE (for NATIVE, this format is parsed and transformed to the next example)
      • localhost:employee — NATIVE, PURE_JAVA
      • //localhost:3051/employee — PURE_JAVA, NATIVE (for NATIVE, this format is parsed and transformed to the next example)
      • localhost/3051:employee — NATIVE, PURE_JAVA
      • /path/to/your.fdb — NATIVE, EMBEDDED, PURE_JAVA (PURE_JAVA will use localhost as serverName, depending on the Firebird version and platform, NATIVE may use Firebird Embedded)
      • C:\path\to\your.fdb — NATIVE, EMBEDDED (protocols like PURE_JAVA may attempt to connect to a server called C, depending on the Firebird version and platform, NATIVE may use Firebird Embedded)
      • C:/path/to/your.fdb — NATIVE, EMBEDDED (protocols like PURE_JAVA may attempt to connect to a server called C, depending on the Firebird version and platform, NATIVE may use Firebird Embedded)
      • xnet://employee — NATIVE (EMBEDDED will behave as NATIVE, protocols like PURE_JAVA may attempt to connect to a server called xnet)
      • other Firebird fbclient connection URLs — NATIVE (EMBEDDED will behave as NATIVE, protocols like PURE_JAVA may interpret the protocol name as a host name
      • Custom type implementations may support other URL formats

      Some protocols, for example PURE_JAVA, when serverName is not set, but databaseName doesn't seem to contain a host name, may default to attempting to connect to localhost with databaseName as the database path or alias.

      When serverName is set, the value is taken as the database path or alias. Examples:

      • employee
      • /path/to/your.fdb
      • C:\path\to\your.fdb
      • C:/path/to/your.fdb
      • relative/path/to/your.fdb — not recommended
      Parameters:
      databaseName - database name

    • getSqlDialect

      default int getSqlDialect()
      Returns:
      SQL dialect of the client connection

    • setSqlDialect

      default void setSqlDialect(int sqlDialect)
      Parameters:
      sqlDialect - SQL dialect of the client connection.

    • getPageCacheSize

      default int getPageCacheSize()
      Get the page cache size.

      A value of 0 indicates that the value is not set, and that the server default is used.

      This option is only relevant for Firebird implementations with per connection cache (eg Classic)

      NOTE: Implementer should take care to return 0 if the value hasn't been set yet.

      Returns:
      size of cache in pages for this connection, can be specified for Classic and SuperClassic instances, ignored for SuperServer as the cache is shared; 0 when not set

    • setPageCacheSize

      default void setPageCacheSize(int pageCacheSize)
      Set the page cache size.

      A value of 0 indicates that the value is not set, and that the server default is used.

      This option is only relevant for Firebird implementations with per connection cache (eg Classic).

      Parameters:
      pageCacheSize - size of cache in pages for this connection, can be specified for Classic and SuperClassic instances ignored for SuperServer as the cache is shared.

    • getDataTypeBind

      default String getDataTypeBind()
      Get the dataTypeBind configuration.
      Returns:
      configuration value for dataTypeBind, or null for driver default
      Since:
      4.0

    • setDataTypeBind

      default void setDataTypeBind(String dataTypeBind)
      Sets the dataTypeBind configuration.

      If the value is explicitly set to a non-null value and the connected server is Firebird 4 or higher, this will configure the data type binding with the specified values using isc_dpb_set_bind, which is equivalent to executing SET BIND statements with the values.

      See also Firebird documentation for SET BIND.

      Parameters:
      dataTypeBind - Firebird 4+ data type bind configuration, a semicolon-separated list of <from-type> TO <to-type>
      Since:
      4.0

    • getSessionTimeZone

      default String getSessionTimeZone()
      Get the sessionTimeZone.
      Returns:
      value for sessionTimeZone, or null for driver default (JVM default time zone)
      Since:
      4.0

    • setSessionTimeZone

      default void setSessionTimeZone(String sessionTimeZone)
      Sets the sessionTimeZone.
      Parameters:
      sessionTimeZone - Firebird 4+ session time zone name (we strongly suggest to use Java compatible names only), use "server" to use server default time zone (note: conversion will use JVM default time zone). For offset-based names, the value will be normalized to the Firebird name (e.g. GMT+05:00 is stored as +05:00).
      Since:
      4.0

    • getBlobBufferSize

      default int getBlobBufferSize()
      Returns:
      BLOB buffer size in bytes; if the configured value is less than an implementation-specific minimum, that minimum is returned

    • setBlobBufferSize

      default void setBlobBufferSize(int blobBufferSize)
      Parameters:
      blobBufferSize - size of the BLOB buffer in bytes

    • isUseStreamBlobs

      default boolean isUseStreamBlobs()
      Returns:
      true if stream blobs should be created, otherwise false.

    • setUseStreamBlobs

      default void setUseStreamBlobs(boolean useStreamBlobs)
      Parameters:
      useStreamBlobs - true if stream blobs should be created, otherwise false.

    • isDefaultResultSetHoldable

      default boolean isDefaultResultSetHoldable()
      Get whether ResultSets are holdable by default.
      Returns:
      true ResultSets by default are ResultSet.HOLD_CURSORS_OVER_COMMIT, false (default), ResultSets are ResultSet.CLOSE_CURSORS_AT_COMMIT

    • setDefaultResultSetHoldable

      default void setDefaultResultSetHoldable(boolean defaultResultSetHoldable)
      Set if ResultSet should be ResultSet.HOLD_CURSORS_OVER_COMMIT by default.
      Parameters:
      defaultResultSetHoldable - true ResultSets are holdable, false (default) ResultSets are ResultSet.CLOSE_CURSORS_AT_COMMIT

    • isUseFirebirdAutocommit

      default boolean isUseFirebirdAutocommit()
      Get whether to use Firebird autocommit (experimental).
      Returns:
      true use Firebird autocommit
      Since:
      2.2.9

    • setUseFirebirdAutocommit

      default void setUseFirebirdAutocommit(boolean useFirebirdAutocommit)
      Set whether to use Firebird autocommit (experimental).
      Parameters:
      useFirebirdAutocommit - true Use Firebird autocommit
      Since:
      2.2.9

    • isColumnLabelForName

      default boolean isColumnLabelForName()
      Gets the current setting of columnLabelForName
      Returns:
      false JDBC compliant behavior (columnName is returned), true compatibility option (columnLabel is returned)
      Since:
      2.2.1
      See Also:

    • setColumnLabelForName

      default void setColumnLabelForName(boolean columnLabelForName)
      Set if ResultSetMetaData.getColumnName(int) returns the columnLabel instead of the columnName.

      The default behaviour (with columnLabelForName=false is JDBC-compliant. The behavior for value true is to provide compatibility with tools with a wrong expectation.

      Parameters:
      columnLabelForName - false JDBC compliant behavior (columnName is returned), true compatibility option (columnLabel is returned)
      Since:
      2.2.1

    • getGeneratedKeysEnabled

      default String getGeneratedKeysEnabled()
      Get the generatedKeysEnabled configuration.
      Returns:
      configuration value for generatedKeysEnabled, or null for driver default
      Since:
      4.0

    • setGeneratedKeysEnabled

      default void setGeneratedKeysEnabled(String generatedKeysEnabled)
      Sets the generatedKeysEnabled configuration.
      Parameters:
      generatedKeysEnabled - Generated keys support configuration: default (or null/empty), disabled, ignored, or a list of statement types to enable (possible values: insert, update, delete, update_or_insert, merge)
      Since:
      4.0

    • isIgnoreProcedureType

      default boolean isIgnoreProcedureType()
      Get the value for ignoreProcedureType.
      Returns:
      value for ignoreProcedureType
      Since:
      3.0.6

    • setIgnoreProcedureType

      default void setIgnoreProcedureType(boolean ignoreProcedureType)
      Sets the value ignoreProcedureType.

      When set to true, the CallableStatement implementation in Jaybird will ignore metadata information about the stored procedure type and default to using EXECUTE PROCEDURE, unless the type is explicitly set using FirebirdCallableStatement.setSelectableProcedure(boolean). This can be useful in situations where a stored procedure is selectable, but tooling or code expects an executable stored procedure.

      Parameters:
      ignoreProcedureType - true Ignore procedure type
      Since:
      3.0.6

    • getDecfloatRound

      default String getDecfloatRound()
      Returns:
      the server-side DECFLOAT rounding mode, null applies the Firebird server default

    • setDecfloatRound

      default void setDecfloatRound(String decfloatRound)
      Sets the DECFLOAT rounding mode
      Parameters:
      decfloatRound - Firebird 4+ server-side DECFLOAT rounding mode (ceiling, up, half_up, half_even, half_down, down, floor, reround); null to apply the Firebird server default (half_up in Firebird 4)

    • getDecfloatTraps

      default String getDecfloatTraps()
      Returns:
      the server-side DECFLOAT error traps, null applies the Firebird server default

    • setDecfloatTraps

      default void setDecfloatTraps(String decfloatTraps)
      Sets the DECFLOAT error traps.
      Parameters:
      decfloatTraps - Firebird 4+ server-side DECFLOAT error traps; comma-separated list with options Division_by_zero, Inexact, Invalid_operation, Overflow, Underflow; null to apply Firebird server default (Division_by_zero,Invalid_operation,Overflow in Firebird 4)

    • getTpbMapping

      default String getTpbMapping()
      Get the used TPB mapping.
      Returns:
      resource bundle name of the TPB mapping
      See Also:

    • setTpbMapping

      default void setTpbMapping(String tpbMapping)
      Sets a resource bundle name with the TPB mapping.

      For compatibility reasons, the prefix "res:" is allowed, but this works exactly the same as without a prefix. We strongly recommend not to use the "res:" prefix, future versions of Jaybird (Jaybird 7 or later) may stop supporting this.

      The resource bundle should contain a mapping between the transaction isolation level (name of the constant in the Connection interface and a comma-separated list of TPB parameters).

      Parameters:
      tpbMapping - name of the resource bundle
      Throws:
      IllegalStateException - May be thrown when the mapping has already been initialized (not all implementations do this)

    • getDefaultTransactionIsolation

      default int getDefaultTransactionIsolation()
      Get the default transaction isolation level. This is the transaction isolation level for the newly created connections.
      Returns:
      default transaction isolation level.

    • setDefaultTransactionIsolation

      default void setDefaultTransactionIsolation(int defaultIsolationLevel)
      Set the default transaction isolation level.
      Parameters:
      defaultIsolationLevel - default transaction isolation level.

    • getDefaultIsolation

      default String getDefaultIsolation()
      Get the default transaction isolation level as string. This method is complementary to getDefaultTransactionIsolation(), however it returns a string name instead of a numeric constant.
      Returns:
      default transaction isolation as string.
      See Also:

    • setDefaultIsolation

      default void setDefaultIsolation(String isolation)
      Set the default transaction isolation level as string. This method is complementary to setDefaultTransactionIsolation(int), however it takes a string as parameter instead of a numeric constant.

      Following strings are allowed:

      • "TRANSACTION_READ_COMMITTED" for a READ COMMITTED isolation level.
      • "TRANSACTION_REPEATABLE_READ" for a REPEATABLE READ isolation level.
      • "TRANSACTION_SERIALIZABLE" for a SERIALIZABLE isolation level.
      • Integer string values matching the isolation levels

      Parameters:
      isolation - string constant representing a default isolation level.

    • getScrollableCursor

      default String getScrollableCursor()
      Returns:
      Configuration of scrollable cursors, either EMULATED (default) or SERVER (case-insensitive)
      See Also:

    • setScrollableCursor

      default void setScrollableCursor(String scrollableCursor)
      Sets the type of scrollable cursor.

      Possible values are (case-insensitive):

      • EMULATED (default) - emulate scrollable cursors in memory by fetching all rows
      • SERVER - user server-side scrollable cursor (requires Firebird 5.0 and pure-java connection). Falls back to EMULATED behaviour when server-side support is not available, or when holdable cursors are requested
      Parameters:
      scrollableCursor - Scrollable cursor type, one of EMULATED or SERVER (case-insensitive)

    • isUseServerBatch

      default boolean isUseServerBatch()
      Returns:
      true (default) use server-side batch if supported by server, false always use emulated batch
      See Also:

    • setUseServerBatch

      default void setUseServerBatch(boolean useServerBatch)
      Sets whether to use server-side batch support, if available.

      Currently, server-side batch is only supported with Firebird 4.0 or higher, with a pure Java connection, using a PreparedStatement, but not a CallableStatement, and only when not requesting generated keys.

      The implementation will fall back to emulated batches if either the server version doesn't support batches, or if the statement cannot be executed using the server-side batch mechanism for other reasons (e.g. requesting generated keys).

      Parameters:
      useServerBatch - true, use server-side batch support if possible, false always use emulated batch

    • getServerBatchBufferSize

      default int getServerBatchBufferSize()
      Returns:
      batch buffer size in bytes, < 0 to use server-side default (16MB as of Firebird 4.0), 0 (default) to use server-side maximum (256MB as of Firebird 4.0), values exceeding server-side maximum will set server-side maximum
      See Also:

    • setServerBatchBufferSize

      default void setServerBatchBufferSize(int serverBatchBufferSize)
      Sets the server batch buffer size (if server batch is supported and enabled).
      Parameters:
      serverBatchBufferSize - server batch buffer size in bytes, use < 0 to set server-side default (16MB as of Firebird 4.0), use 0 to use server-side maximum (256MB as of Firebird 4.0), values exceeding server-side maximum will set server-side maximum

    • isUseCatalogAsPackage

      default boolean isUseCatalogAsPackage()
      Returns:
      true database metadata uses catalogs to report packages, false (default) no catalogs, and packages and their procedures and functions are not accessible
      See Also:

    • setUseCatalogAsPackage

      default void setUseCatalogAsPackage(boolean useCatalogAsPackage)
      Sets whether to use catalogs to report packages in database metadata.

      When set to true, database metadata will return the names of packages from DatabaseMetaData.getCatalogs(), and DatabaseMetaData.getFunctions(String, String, String), DatabaseMetaData.getFunctionColumns(String, String, String, String), DatabaseMetaData.getProcedures(String, String, String), and DatabaseMetaData.getProcedureColumns(String, String, String, String) will include information on packaged procedures and functions.

      The behaviour of the input parameter catalog of these methods is modified compared to the default behaviour:

      • null: both packaged and top-level procedures/functions are searched
      • "" (empty string): only top-level procedures/functions are searched
      • non-empty string: only procedures/functions in the named package are searched (NOTE: exact match, case-sensitive)

      The returned result set is modified compared to the default behaviour:

      • PROCEDURE_CAT/FUNCTION_CAT: for top-level procedures/functions, its value is "" (empty string) — not null — to account for behaviour of parameter package when searching metadata
      • SPECIFIC_NAME: for packaged procedures/functions will report <quoted-package-name>.<quoted-routine-name>

      Return values of other metadata methods are changed to match: DatabaseMetaData.getCatalogSeparator(), DatabaseMetaData.getCatalogTerm(), DatabaseMetaData.isCatalogAtStart(), DatabaseMetaData.getMaxCatalogNameLength(), DatabaseMetaData.supportsCatalogsInDataManipulation(), DatabaseMetaData.supportsCatalogsInProcedureCalls()

      Parameters:
      useCatalogAsPackage - true database metadata uses catalogs to report packages, false (default) no catalogs, and packages and their procedures and functions are not accessible

    • isAllowTxStmts

      default boolean isAllowTxStmts()
      Returns:
      true if execution of COMMIT [WORK], ROLLBACK [WORK] or SET TRANSACTION [..] is allowed, false (default) to throw an exception when attempting to execute or prepare such statements
      Since:
      6
      See Also:

    • setAllowTxStmts

      default void setAllowTxStmts(boolean allowTxStmts)
      Sets whether transaction management statements with (hard) transaction boundaries are allowed to be prepared or executed.

      Setting to true will enable Jaybird to execute equivalent operations through the JDBC API (specifically, Statement.execute(String), Statement.executeUpdate(String), Statement.executeLargeUpdate(String) and siblings, and statements prepared with Connection.prepareStatement(String) and siblings. Using callable statements (e.g. using Connection.prepareCall(String)), Statement.executeQuery(String), or batch execution is never supported.

      The implementation is free to execute the provided statement text or use an equivalent operation that has the same effect.

      Setting this configuration to true only affects the JDBC API, and has no effect on direct use of the GDS-ng API.

      Parameters:
      allowTxStmts - true to allow execution of COMMIT [WORK], ROLLBACK [WORK] or SET TRANSACTION [..], false (default) to throw an exception when attempting to execute or prepare such statements
      Since:
      6

    • isExtendedMetadata

      default boolean isExtendedMetadata()
      Returns:
      true (default) if metadata (e.g. ResultSetMetaData) will perform additional queries for more detailed information, false if only the available bind information will be used
      Since:
      5.0.5
      See Also:

    • setExtendedMetadata

      default void setExtendedMetadata(boolean extendedMetadata)
      Sets if certain metadata classes will perform additional queries to enrich the information for certain types.

      Currently this is used only by ResultSetMetaData for its getPrecision and isAutoIncrement methods. If disabled, these methods will return an estimated precision, or false for auto-increment instead of actual precision and identity column state information.

      Disabling this setting may improve performance of querying metadata information, in exchange for less precise information.

      Parameters:
      extendedMetadata - true (default) - metadata (e.g. ResultSetMetaData) will perform additional queries for more detailed information, false - only the available bind information will be used
      Since:
      5.0.5

    • isCreateDatabaseIfNotExist

      default boolean isCreateDatabaseIfNotExist()
      Returns:
      false (default) if failure to connect does nothing, true if some classes of connection failures will result in an attempt to create the database
      Since:
      6
      See Also:

    • setCreateDatabaseIfNotExist

      default void setCreateDatabaseIfNotExist(boolean createDatabaseIfNotExist)
      Sets if an attempt should be made to create a database if it does not exist.

      If the connection fails because the database cannot be opened, Jaybird will attempt to create the database. Additional or overridden properties can be set using BaseProperties.setProperty(String, String) by suffixing the property name with @create.

      As Firebird does not clearly report that a database does not exist (e.g. it may exist, but not be accessible to the server, etc.), and the errors may be OS-specific, the attempt to create may fail. Jaybird may try to use some heuristics to avoid creation for some errors, but this is an implementation details which may change in point releases.

      Parameters:
      createDatabaseIfNotExist - false (default) if failure to connect does nothing, true if some classes of connection failures will result in an attempt to create the database
      Since:
      6

    • getReportSQLWarnings

      default String getReportSQLWarnings()
      Returns:
      ALL (default) if SQLWarning should be reported by Connection, Statement and ResultSet, NONE if SQLWarning should not be reported
      Since:
      6
      See Also:

    • setReportSQLWarnings

      default void setReportSQLWarnings(String reportSQLWarnings)
      Sets if SQLWarning should be reported by Connection.getWarnings(), Statement.getWarnings(), and ResultSet.getWarnings().

      Allowed values (case-insensitive):

      • ALL — (default) report all SQLWarning
      • NONE — report no SQLWarning; this behaviour is not JDBC-compliant

      The default value can be overridden by setting system property org.firebirdsql.jdbc.defaultReportSQLWarnings.

      Parameters:
      reportSQLWarnings - ALL (default) if SQLWarning should be reported by Connection, Statement and ResultSet, NONE if SQLWarning should not be reported; setting null will use ALL
      Since:
      6

    • isAsyncFetch

      default boolean isAsyncFetch()
      Gets if async fetching is enabled or disabled (pure Java only).

      This property may get removed in Jaybird 7 or later, once this async fetching has proven itself.

      Returns:
      true (default) async fetching is enabled, false async fetching is disabled
      Since:
      6
      See Also:

    • setAsyncFetch

      default void setAsyncFetch(boolean asyncFetch)
      Sets if async fetching is enabled or disabled (pure Java only).

      The default value can be overridden by setting system property org.firebirdsql.jdbc.defaultAsyncFetch.

      This property may get removed in Jaybird 7 or later, once this async fetching has proven itself.

      Parameters:
      asyncFetch - true (default) async fetching is enabled, false async fetching is disabled
      Since:
      6