Interface DatabaseConnectionProperties
- All Superinterfaces:
AttachmentProperties,BaseProperties
- All Known Subinterfaces:
FirebirdConnectionProperties,IConnectionProperties
- All Known Implementing Classes:
AbstractConnectionPropertiesDataSource,FBAbstractCommonDataSource,FBConnectionPoolDataSource,FbConnectionProperties,FBConnectionProperties,FbImmutableConnectionProperties,FBManagedConnectionFactory,FBSimpleDataSource,FBXADataSource
- Since:
- 5
- Author:
- Mark Rotteveel
-
Method Summary
Modifier and TypeMethodDescriptiondefault intdefault StringGets the database of the connection.default StringGet thedataTypeBindconfiguration.default Stringdefault Stringdefault StringGet the default transaction isolation level as string.default intGet the default transaction isolation level.default StringGet thegeneratedKeysEnabledconfiguration.default intGet the page cache size.default Stringdefault Stringdefault intdefault StringGet thesessionTimeZone.default intdefault StringGet the used TPB mapping.default booleandefault booleanGets if async fetching is enabled or disabled (pure Java only).default booleanGets the current setting ofcolumnLabelForNamedefault booleandefault booleanGet whether ResultSets are holdable by default.default booleandefault booleanGet the value forignoreProcedureType.default booleandefault booleanGet whether to use Firebird autocommit (experimental).default booleandefault booleandefault voidsetAllowTxStmts(boolean allowTxStmts) Sets whether transaction management statements with (hard) transaction boundaries are allowed to be prepared or executed.default voidsetAsyncFetch(boolean asyncFetch) Sets if async fetching is enabled or disabled (pure Java only).default voidsetBlobBufferSize(int blobBufferSize) default voidsetColumnLabelForName(boolean columnLabelForName) default voidsetCreateDatabaseIfNotExist(boolean createDatabaseIfNotExist) Sets if an attempt should be made to create a database if it does not exist.default voidsetDatabaseName(String databaseName) Sets the database of the connectiondefault voidsetDataTypeBind(String dataTypeBind) Sets thedataTypeBindconfiguration.default voidsetDecfloatRound(String decfloatRound) Sets theDECFLOATrounding modedefault voidsetDecfloatTraps(String decfloatTraps) Sets theDECFLOATerror traps.default voidsetDefaultIsolation(String isolation) Set the default transaction isolation level as string.default voidsetDefaultResultSetHoldable(boolean defaultResultSetHoldable) Set ifResultSetshould beResultSet.HOLD_CURSORS_OVER_COMMITby default.default voidsetDefaultTransactionIsolation(int defaultIsolationLevel) Set the default transaction isolation level.default voidsetExtendedMetadata(boolean extendedMetadata) Sets if certain metadata classes will perform additional queries to enrich the information for certain types.default voidsetGeneratedKeysEnabled(String generatedKeysEnabled) Sets thegeneratedKeysEnabledconfiguration.default voidsetIgnoreProcedureType(boolean ignoreProcedureType) Sets the valueignoreProcedureType.default voidsetPageCacheSize(int pageCacheSize) Set the page cache size.default voidsetReportSQLWarnings(String reportSQLWarnings) Sets ifSQLWarningshould be reported byConnection.getWarnings(),Statement.getWarnings(), andResultSet.getWarnings().default voidsetScrollableCursor(String scrollableCursor) Sets the type of scrollable cursor.default voidsetServerBatchBufferSize(int serverBatchBufferSize) Sets the server batch buffer size (if server batch is supported and enabled).default voidsetSessionTimeZone(String sessionTimeZone) Sets thesessionTimeZone.default voidsetSqlDialect(int sqlDialect) default voidsetTpbMapping(String tpbMapping) Sets a resource bundle name with the TPB mapping.default voidsetUseCatalogAsPackage(boolean useCatalogAsPackage) Sets whether to use catalogs to report packages in database metadata.default voidsetUseFirebirdAutocommit(boolean useFirebirdAutocommit) Set whether to use Firebird autocommit (experimental).default voidsetUseServerBatch(boolean useServerBatch) Sets whether to use server-side batch support, if available.default voidsetUseStreamBlobs(boolean useStreamBlobs) Methods inherited from interface org.firebirdsql.jaybird.props.AttachmentProperties
getAuthPlugins, getCharSet, getConnectTimeout, getDbCryptConfig, getEnableProtocol, getEncoding, getParallelWorkers, getPassword, getPortNumber, getProcessId, getProcessName, getRoleName, getServerName, getSocketBufferSize, getSocketFactory, getSoTimeout, getType, getUser, getWireCrypt, isWireCompression, setAuthPlugins, setCharSet, setConnectTimeout, setDbCryptConfig, setEnableProtocol, setEncoding, setParallelWorkers, setPassword, setPortNumber, setProcessId, setProcessName, setRoleName, setServerName, setSocketBufferSize, setSocketFactory, setSoTimeout, setType, setUser, setWireCompression, setWireCryptMethods inherited from interface org.firebirdsql.jaybird.props.BaseProperties
connectionPropertyValues, getBooleanProperty, getBooleanProperty, getIntProperty, getIntProperty, getProperty, getProperty, setBooleanProperty, setIntProperty, setProperty
-
Method Details
-
getDatabaseName
Gets the database of the connection.- Returns:
- database name
- See Also:
-
setDatabaseName
Sets the database of the connectionWhen
serverNameisnull, 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 thejdbc: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
fbclientconnection URLs — NATIVE (EMBEDDED will behave as NATIVE, protocols like PURE_JAVA may interpret the protocol name as a host name - Custom
typeimplementations may support other URL formats
Some protocols, for example PURE_JAVA, when
serverNameis not set, butdatabaseNamedoesn't seem to contain a host name, may default to attempting to connect to localhost withdatabaseNameas the database path or alias.When
serverNameis 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
0indicates 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
0if 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
0indicates 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
Get thedataTypeBindconfiguration.- Returns:
- configuration value for
dataTypeBind, ornullfor driver default - Since:
- 4.0
-
setDataTypeBind
Sets thedataTypeBindconfiguration.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 executingSET BINDstatements 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
Get thesessionTimeZone.- Returns:
- value for
sessionTimeZone, ornullfor driver default (JVM default time zone) - Since:
- 4.0
-
setSessionTimeZone
Sets thesessionTimeZone.- 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:
trueif stream blobs should be created, otherwisefalse.
-
setUseStreamBlobs
default void setUseStreamBlobs(boolean useStreamBlobs) - Parameters:
useStreamBlobs-trueif stream blobs should be created, otherwisefalse.
-
isDefaultResultSetHoldable
default boolean isDefaultResultSetHoldable()Get whether ResultSets are holdable by default.- Returns:
trueResultSets by default areResultSet.HOLD_CURSORS_OVER_COMMIT,false(default), ResultSets areResultSet.CLOSE_CURSORS_AT_COMMIT
-
setDefaultResultSetHoldable
default void setDefaultResultSetHoldable(boolean defaultResultSetHoldable) Set ifResultSetshould beResultSet.HOLD_CURSORS_OVER_COMMITby default.- Parameters:
defaultResultSetHoldable-trueResultSets are holdable,false(default) ResultSets areResultSet.CLOSE_CURSORS_AT_COMMIT
-
isUseFirebirdAutocommit
default boolean isUseFirebirdAutocommit()Get whether to use Firebird autocommit (experimental).- Returns:
trueuse Firebird autocommit- Since:
- 2.2.9
-
setUseFirebirdAutocommit
default void setUseFirebirdAutocommit(boolean useFirebirdAutocommit) Set whether to use Firebird autocommit (experimental).- Parameters:
useFirebirdAutocommit-trueUse Firebird autocommit- Since:
- 2.2.9
-
isColumnLabelForName
default boolean isColumnLabelForName()Gets the current setting ofcolumnLabelForName- Returns:
falseJDBC compliant behavior (columnNameis returned),truecompatibility option (columnLabelis returned)- Since:
- 2.2.1
- See Also:
-
setColumnLabelForName
default void setColumnLabelForName(boolean columnLabelForName) Set ifResultSetMetaData.getColumnName(int)returns thecolumnLabelinstead of thecolumnName.The default behaviour (with
columnLabelForName=falseis JDBC-compliant. The behavior for valuetrueis to provide compatibility with tools with a wrong expectation.- Parameters:
columnLabelForName-falseJDBC compliant behavior (columnNameis returned),truecompatibility option (columnLabelis returned)- Since:
- 2.2.1
-
getGeneratedKeysEnabled
Get thegeneratedKeysEnabledconfiguration.- Returns:
- configuration value for
generatedKeysEnabled, ornullfor driver default - Since:
- 4.0
-
setGeneratedKeysEnabled
Sets thegeneratedKeysEnabledconfiguration.- 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 forignoreProcedureType.- Returns:
- value for
ignoreProcedureType - Since:
- 3.0.6
-
setIgnoreProcedureType
default void setIgnoreProcedureType(boolean ignoreProcedureType) Sets the valueignoreProcedureType.When set to true, the
CallableStatementimplementation in Jaybird will ignore metadata information about the stored procedure type and default to usingEXECUTE PROCEDURE, unless the type is explicitly set usingFirebirdCallableStatement.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-trueIgnore procedure type- Since:
- 3.0.6
-
getDecfloatRound
- Returns:
- the server-side
DECFLOATrounding mode,nullapplies the Firebird server default
-
setDecfloatRound
Sets theDECFLOATrounding mode- Parameters:
decfloatRound- Firebird 4+ server-sideDECFLOATrounding mode (ceiling, up, half_up, half_even, half_down, down, floor, reround);nullto apply the Firebird server default (half_upin Firebird 4)
-
getDecfloatTraps
- Returns:
- the server-side
DECFLOATerror traps,nullapplies the Firebird server default
-
setDecfloatTraps
Sets theDECFLOATerror traps.- Parameters:
decfloatTraps- Firebird 4+ server-sideDECFLOATerror traps; comma-separated list with optionsDivision_by_zero, Inexact, Invalid_operation, Overflow, Underflow;nullto apply Firebird server default (Division_by_zero,Invalid_operation,Overflowin Firebird 4)
-
getTpbMapping
Get the used TPB mapping.- Returns:
- resource bundle name of the TPB mapping
- See Also:
-
setTpbMapping
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
Connectioninterface 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
Get the default transaction isolation level as string. This method is complementary togetDefaultTransactionIsolation(), however it returns a string name instead of a numeric constant.- Returns:
- default transaction isolation as string.
- See Also:
-
setDefaultIsolation
Set the default transaction isolation level as string. This method is complementary tosetDefaultTransactionIsolation(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
- Returns:
- Configuration of scrollable cursors, either
EMULATED(default) orSERVER(case-insensitive) - See Also:
-
setScrollableCursor
Sets the type of scrollable cursor.Possible values are (case-insensitive):
EMULATED(default) - emulate scrollable cursors in memory by fetching all rowsSERVER- user server-side scrollable cursor (requires Firebird 5.0 and pure-java connection). Falls back toEMULATEDbehaviour when server-side support is not available, or when holdable cursors are requested
- Parameters:
scrollableCursor- Scrollable cursor type, one ofEMULATEDorSERVER(case-insensitive)
-
isUseServerBatch
default boolean isUseServerBatch()- Returns:
true(default) use server-side batch if supported by server,falsealways 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 aCallableStatement, 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,falsealways use emulated batch
-
getServerBatchBufferSize
default int getServerBatchBufferSize()- Returns:
- batch buffer size in bytes,
< 0to 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< 0to set server-side default (16MB as of Firebird 4.0), use0to 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:
truedatabase 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 fromDatabaseMetaData.getCatalogs(), andDatabaseMetaData.getFunctions(String, String, String),DatabaseMetaData.getFunctionColumns(String, String, String, String),DatabaseMetaData.getProcedures(String, String, String), andDatabaseMetaData.getProcedureColumns(String, String, String, String)will include information on packaged procedures and functions.The behaviour of the input parameter
catalogof 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) — notnull— to account for behaviour of parameterpackagewhen searching metadataSPECIFIC_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-truedatabase 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:
trueif execution ofCOMMIT [WORK],ROLLBACK [WORK]orSET 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
truewill 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 withConnection.prepareStatement(String)and siblings. Using callable statements (e.g. usingConnection.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
trueonly affects the JDBC API, and has no effect on direct use of the GDS-ng API.- Parameters:
allowTxStmts-trueto allow execution ofCOMMIT [WORK],ROLLBACK [WORK]orSET 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,falseif 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
ResultSetMetaDatafor itsgetPrecisionandisAutoIncrementmethods. If disabled, these methods will return an estimated precision, orfalsefor 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,trueif 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,trueif some classes of connection failures will result in an attempt to create the database- Since:
- 6
-
getReportSQLWarnings
- Returns:
ALL(default) ifSQLWarningshould be reported byConnection,StatementandResultSet,NONEifSQLWarningshould not be reported- Since:
- 6
- See Also:
-
setReportSQLWarnings
Sets ifSQLWarningshould be reported byConnection.getWarnings(),Statement.getWarnings(), andResultSet.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) ifSQLWarningshould be reported byConnection,StatementandResultSet,NONEifSQLWarningshould not be reported; settingnullwill useALL- Since:
- 6
- ALL — (default) report all
-
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,falseasync 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,falseasync fetching is disabled- Since:
- 6
-