Jaybird 2.2.0

Changes and fixes since Jaybird 2.2.0 beta 1

The following was changed or fixed after the release of Jaybird 2.2.0 beta 1:

• ConcurrentModificationException when closing connection obtained from org.firebirdsql.ds.FBConnectionPoolDataSource with statements open (JDBC-250)
• Memory leak when obtaining multiple connections for the same URL (JDBC-249)
• CPU spikes to 100% when using events and Firebird Server is stopped or unreachable (JDBC-232)
• Events do not work on Embedded (JDBC-247)
• Provide workaround for character set transliteration problems in database filenames and other connection properties (JDBC-253); see also Support for Firebird 2.5.
• FBBackupManager does not allow 16kb page size for restore (JDBC-255)
• Log warning and add warning on Connection when no explicit connection character set is specified (JDBC-257)

Support for getGeneratedKeys()

Support was added for the getGeneratedKeys() functionality for Statement and PreparedStatement.

There are four distinct use-cases:

1. Methods accepting an int parameter with values of Statement.NO_GENERATED_KEYS and Statement.RETURN_GENERATED_KEYS

   When NO_GENERATED_KEYS is passed, the query will be executed as a normal query.

   When RETURN_GENERATED_KEYS is passed, the driver will add all columns of the table in ordinal position order (as in the (JDBC) metadata of the table). It is advisable to retrieve the values from the getGeneratedKeys() result set by column name.

   We opted to include all columns as it is next to impossible to decide which columns are filled by a trigger or otherwise and only returning the primary key will be too limiting.

2. Methods accepting an int[] parameter with column indexes.

   The values in the int[] parameter are the ordinal positions of the columns as specified in the (JDBC) metadata of the table. For a null or empty array the statement is processed as is. Invalid ordinal positions are ignored and silently dropped (be aware: the JDBC specification is not entirely clear if this is valid behavior, so this might change in the future).

3. Methods accepting a String[] parameter with column names.

   The values in the String[] are the column names to be returned. The column names provided are processed as is and not checked for validity or the need of quoting. Providing non-existent or incorrectly (un)quoted columns will result in an exception.

   This method is the fastest as it does not retrieve metadata from the server.

4. Providing a query already containing a RETURNING clause. In this case all of the previous cases are ignored and the query is executed as is. It is possible to retrieve the result set using getGeneratedKeys().

This functionality will only be available if the ANTLR 3.4 runtime classes are on the classpath. Except for calling methods with NO_GENERATED_KEYS, absence of the ANTLR runtime will throw FBDriverNotCapableException.

This functionality should work for INSERT (from Firebird 2.0), and for UPDATE, UPDATE OR INSERT and DELETE (from Firebird 2.1).

Java 6 and JDBC 4.0 API support

Support was added for the following JDBC 4.0 features:

• Automatic driver loading: on Java 6 and later it is no longer necessary to use Class.forName("org.firebirdsql.jdbc.FBDriver") to load the driver
• Implementation of java.sql.Wrapper interface on various JDBC classes; in general it only unwraps to the specific implementation class (and superclasses) and implemented interfaces
• Support for chained exceptions (use getNextException() and iterator() to view other, related exceptions) and getCause() to retrieve the cause (deprecating similar getInternalException())
• Support for getClientInfo() and setClientInfo() on Connection

Java 7 and JDBC 4.1 API support

Support was added for the following JDBC 4.1 features:

• try-with-resources
• Statement closeOnCompletion

Other methods added by JDBC 4.1 will throw FBDriverNotCapableException (a subclass of SQLFeatureNotSupportedException).

Jaybird on Maven

Jaybird 2.2.x is available on maven, with a separate artifact for each supported Java version.

Groupid: org.firebirdsql.jdbc, artifactid: jaybird-jdkXX (where XX is 15, 16, 17, 18).
Version: 2.2.x

When deploying to a JavaEE environment, exclude the avax.resource connector-api dependency as this will be provided by the application server.

Native and Embedded (JNI) 64-bit Windows and Linux support

The JNI libraries for native and embedded support now also have a 64 bit version.

Support for Firebird 2.5

Added support for Firebird 2.5 Services API enhancements:

• The security database can be set
• Support for SET/DROP AUTO ADMIN
• Mapping for new role RDB$ADMIN in security database
• Added new Firebird 2.1 shutdown/online modes available in Firebird 2.5 via the Services API
• Support for NBackup via Services API in Firebird 2.5
• Support for Trace/Audit via Services API in Firebird 2.5

Since Firebird 2.5, Firebird supports full UTF-8 database filenames and other connection properties (Database Parameter Buffer values). Jaybird does not yet support these changes, but a workaround is available:

This workaround consists of two steps

1. Ensure your Java application is executed with the system property file.encoding=UTF-8 (either because that is the default encoding for your OS, or by explicitly specifying this property on the commandline of your application using -Dfile.encoding=UTF-8)
2. Include property utf8_filename=1 in the JDBC URL or (non-standard) properties of the datasource

This will only work if the Firebird server is version 2.5 or higher.

Improved support for OpenOffice / LibreOffice Base

The interpretation of the JDBC standard by Jaybird differs from the interpretation by OpenOffice / LibreOffice. To address some of the problems caused by these differences, Jaybird now provides a separate protocol for OpenOffice / LibreOffice.

When connecting from Base, use the protocol prefix jdbc:firebirdsql:oo:. Be aware that this is a variant of the pure Java wire protocol and not the native or embedded protocol.

Issues addressed by this protocol:

• ResultSets are not closed when a statements is finished (eg fully read ResultSet or when creating a new Statement in autoCommit mode)
• DatabaseMetaData#getTablePrivileges(...) reports privileges granted to PUBLIC and to the current role (as reported by CURRENT_ROLE) as being granted to the user (after Jaybird 2.2.0 beta 1).

Other fixes and changes

• Replaced mini-j2ee.jar with connector-api-1.5.jar: make sure to remove the old mini-j2ee.jar from the classpath of your application.
• Dropped jaybird-pool jar from the distribution (all classes are include in the jaybird jar and the jaybird-full jar)
• FBResultSetMetaData#getcolumnName(int) will now return the original column name (if available) for compliance with the JDBC specification, getColumnLabel(int) will still return the alias (or the column name if no alias is defined). See Compatibility with com.sun.rowset.* for potential problems when using the reference implementation of CachedRowSet.
• FBDatabaseMetaData has been updated to include metadata columns defined by JDBC 3.0, 4.0 and 4.1. This also changes the position of OWNER_NAME column in the result set of getTables(..) as this column is Jaybird-specific and not defined in JDBC.
• FBDatabaseMetaData#getIndexInfo(..) now also returns expression indexes. The COLUMN_NAME column will contain the expression (if available).
• FBDatabaseMetaData#getIndexInfo(..) now correctly limits the returned indexes to unique indexes when parameter unique is set to true.
• The connection property octetsAsBytes can be used to identify fields with CHARACTER SET OCTETS as being (VAR)BINARY (in the resultsetmetadata only)
• The getTime(), getDate(), getTimestamp() methods which take a Calendar object now correctly handle conversions around Daylight Savings Time (DST) changes. Before the time was first converted to the local JVM timezone, and then to the timezone of the provided Calendar, this could lose up to an hour in time. Now the time is converted directly to the timezone of the provided Calendar. (JDBC-154)

See also the full release notes (2.2.2).