Release Notes Jaybird 2.2.3
General Notes
=============
Jaybird is a JCA/JDBC driver suite to connect to Firebird database servers.
This driver is based on both the JCA standard for application server connections to enterprise information systems and the well-known JDBC standard. The JCA standard specifies an architecture in which an application server can cooperate with a driver so that the application server manages transactions, security, and resource pooling, and the driver supplies only the connection functionality. While similar to the JDBC XADataSource concept, the JCA specification is considerably clearer on the division of responsibility between the application server and driver.
Supported Firebird versions
Jaybird 2.2.3 was tested against Firebird 2.1.5 and 2.5.2, but should also support other Firebird versions from 1.0 and up. The Type 2 and embedded server JDBC drivers require the appropriate JNI library. Precompiled JNI binaries for Win32 and Linux platforms are shipped in the default installation, other platforms require porting/building the JNI library for that platform.
This driver does not supports InterBase servers due to Firebird-specific changes in the protocol and database attachment parameters that are sent to the server.
Supported Java versions
Jaybird 2.2.3 supports Java 5 (JDBC 3.0), Java 6 (JDBC 4.0) and Java 7 (JDBC 4.1). Support for earlier Java versions has been dropped.
Specification support
---------------------
Driver supports the following specifications:
* JDBC 4.1
Driver implements all JDBC 4.1 methods added to existing interfaces. The driver explicitly supports closeOnCompletion, most other JDBC 4.1 specific methods throw SQLFeatureNotSupportedException.
* JDBC 4.0
Driver implements all JDBC 4.0 interfaces and supports exception chaining.
* JDBC 3.0
Driver implements all JDBC 3.0 interfaces (but will throw FBDriverNotCapableException for some methods)
* JCA 1.0
Jaybird provides implementation of javax.resource.spi.ManagedConnectionFactory and related interfaces. CCI interfaces are not supported.
Although Jaybird depends on the JCA 1.5 classes, JCA 1.5 compatibility is currently not guaranteed.
* JTA 1.0.1
Driver provides an implementation of javax.transaction.xa.XAResource interface via JCA framework and XADataSource implementation.
* JMX 1.2
Jaybird provides a MBean to manage Firebird servers and installed databases via JMX agent.
What's new in Jaybird 2.2
=========================
Jaybird 2.2 introduces the following new features and fixes:
Changes and fixes in Jaybird 2.2.3
----------------------------------
The following has been changed or fixed in Jaybird 2.2.3:
* Fixed incorrect synchronization in native and embedded protocol (JNI) implementation for iscBlobInfo and iscSeekBlob (JDBC-300)
WARNING: Although Jaybird strives for correct synchronization, a JDBC Connection, and its dependent objects should be used from a single Thread at a time, sharing on multiple threads concurrently is not advisable.
* Fixed holdable ResultSet is closed on auto-commit (JDBC-304, JDBC-305)
* Fixed table names missing or padded with spaces in Database view of IntelliJ IDEA (JDBC-308, IDEA-100786)
* Fixed incorrect JDBC minor version reported under Java 7; this resulted in an incorrect column name (for Java 7) in the metadata of DatabaseMetaData.getColumns(...) (JDBC-309)
* Added IOException to cause of GDSException with error 335544721; "Unable to complete network request to host """ for further investigation (JDBC-306)
The following are known in issues in Jaybird 2.2.3 (and earlier):
* ResultSets opened with CLOSE_CURSORS_AT_COMMIT aren't correctly closed on commit when auto-commit is off (JDBC-307)
This list is not exhaustive, see the Jaybird tracker (http://tracker.firebirdsql.org/browse/JDBC) for a full list of open bugs.
Changes and fixes in Jaybird 2.2.2
----------------------------------
The following has been changed or fixed in Jaybird 2.2.2:
* Fixed: FBMaintenanceManager.listLimboTransactions() reports incorrect transaction id when the result contains multi-site transactions in limbo (JDBC-266)
* Fixed: Calling PreparedStatement.setClob(int, Clob) with a non-Firebird Clob (eg like Hibernate does) or calling PreparedStatement.setClob(int, Reader) throws FBSQLException: "You can't start before the beginning of the blob" (JDBC-281)
* Fixed: Connection property types not properly processed from isc_dpb_types.properties (JDBC-284)
* Fixed: JNI implementation of parameter buffer writes incorrect integers (JDBC-285, JDBC-286)
* Changed: Throw SQLException when calling execute, executeQuery, executeUpdate and addBatch methods accepting a query string on a PreparedStatement or CallableStatement as required by JDBC 4.0 (JDBC-288)
NOTE: Be aware that this change can break existing code if you depended on the old, non-standard behavior! With addBatch(String) the old behavior lead to a memory leak and unexpected results.
* Fixed: LIKE escape character JDBC escape ({escape '<char>'}) doesn't work (JDBC-290)
* Added: Support for a connect timeout using connection property connectTimeout. This property can be specified in the JDBC URL or Properties object or on the DataSource. If the connectTimeout property is not specified, the general DriverManager property loginTimeout is used. The value is the timeout in seconds. (JDBC-295)
For the Java wire protocol the connect timeout will detect unreachable hosts. In the JNI implementation (native protocol) the connect timeout works as the DPB item isc_dpb_connect_timeout which only works after connecting to the server for the op_accept phase of the protocol. This means that for the native protocol the connect timeout will not detect unreachable hosts within the timeout. As that might be unexpected, an SQLWarning is added to the connection if the property is specified with the native protocol.
* As part of the connect timeout change, hostname handling (if the hostname is an IP-address) in the Java wire protocol was changed. This should not have an impact in recent Java versions, but on older Java versions (Java 5 up to update 5) this might result in a delay in connecting using an IP-address, if that address can't be reverse-resolved to a hostname. Workaround is to add an entry for that IP-address to the /etc/hosts or %WINDIR%\System32\Drivers\etc\hosts file.
Changes and fixes in Jaybird 2.2.1
----------------------------------
The following has been changed or fixed in Jaybird 2.2.1:
* Fixed: UnsatisfiedLinkError in libjaybird22(_x64).so undefined symbol: _ZTVN10__cxxabiv117__class_type_infoE on Linux (JDBC-259)
* Added connection property columnLabelForName for backwards compatible behavior of ResultSetMetaData#getColumnName(int) and compatibility with bug in com.sun.rowset.CachedRowSetImpl (JDBC-260)
Set property to true for backwards compatible behavior (getColumnName() returns the column label); don't set the property or set it to false for JDBC-compliant behavior (recommended).
* Fixed: setString(column, null) on "? IS (NOT) NULL" condition does not set parameter to NULL (JDBC-264)
* The charSet connection property now accepts all aliases of the supported Java character sets (eg instead of only Cp1252 now windows-1252 is also accepted) (JDBC-267)
* Fixed: values of charSet property are case-sensitive (JDBC-268)
* Fixed: setting a parameter as NULL with the native protocol does not work when Firebird describes the parameter as not nullable (JDBC-271)
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 characterset 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() resultset 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 resultset 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-resources2
* Statement closeOnCompletion
Other methods added by JDBC 4.1 will throw FBDriverNotCapableException (a subclass of SQLFeatureNotSupportedException).
Jaybird on Maven
----------------
Jaybird 2.2.3 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 or 17).
Version: 2.2.3
When deploying to a JavaEE environment, exclude the javax.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)
A full list of changes is available at:
Jaybird 2.2.3: http://tracker.firebirdsql.org/secure/ReleaseNote.jspa?version=10510&styleName=Text&projectId=10002
Jaybird 2.2.2: http://tracker.firebirdsql.org/secure/ReleaseNote.jspa?projectId=10002&styleName=Text&version=10480
Jaybird 2.2.1: http://tracker.firebirdsql.org/secure/ReleaseNote.jspa?version=10474&styleName=Text&projectId=10002
Jaybird 2.2.0: http://tracker.firebirdsql.org/secure/ReleaseNote.jspa?version=10053&styleName=Text&projectId=10002
Compatibility changes
=====================
Jaybird 2.2 introduces some changes in compatibility and announces future breaking changes.
Java support
------------
We are currently considering to drop Java 5 support for Jaybird 2.3 as Java 5 has been on End-Of-Life3 status since October 2009. Please let us know your thoughts on the Firebird-Java list.
Firebird support
----------------
Jaybird 2.2 supports Firebird 1.0 and higher, but is only tested with Firebird 2.1 and 2.5. For Jaybird 2.3 formal support for Firebird 1.0 and 1.5 will be dropped. In general this probably will not impact the use of the driver, but might have impact on the availability and use of metadata information. This also means that from Jaybird 2.3 bugs that only occur with Firebird 1.0 and 1.5 will not be fixed.
Important changes to Datasources
--------------------------------
The ConnectionPoolDataSource and XADataSource implementations in org.firebirdsql.pool and org.firebirdsql.pool.sun contain several bugs with regard to pool and connection management when used by a JavaEE application server. The decision was made to write new implementations in the package org.firebirdsql.ds.
The following implementation classes have been deprecated and will be removed in Jaybird 2.3:
* org.firebirdsql.pool.DriverConnectionPoolDataSource
* org.firebirdsql.pool.FBConnectionPoolDataSource
* org.firebirdsql.pool.sun.AppServerDataSource
* org.firebirdsql.pool.sun.AppServerXADataSource
* org.firebirdsql.jca.FBXADataSource
* org.firebirdsql.pool.SimpleDataSource
Their replacement classes are:
* org.firebirdsql.ds.FBConnectionPoolDataSource
* org.firebirdsql.ds.FBXADataSource
* org.firebirdsql.pool.FBSimpleDataSource (a normal DataSource)
We strongly urge you to switch to these new implementations if you are using these classes in an application server. The bugs are described in JDBC-86, JDBC-93, JDBC-131 and JDBC-144.
The deprecated classes can still be used with the DataSource implementations WrappingDataSource as the identified bugs do not occur with this implementation, but we advise you to switch to FBSimpleDataSource. If you require a standalone connection pool (outside an application server) or statement pooling, please consider using a third-party connection pool like C3P0, DBCP or BoneCP.
The new ConnectionPoolDataSource and XADataSource implementations only provide the basic functionality specified in the JDBC specifications and do not provide any pooling itself. The ConnectionPoolDataSource and XADataSource are intended to be used by connection pools (as provided by application servers) and should not be connection pools themselves.
Future changes to Jaybird
-------------------------
The next versions of Jaybird will include some potentially breaking changes. We advise to check your code if you will be affected by these changes and prepare for these changes if possible.
Removal of deprecated classes, packages and (interface) methods
...............................................................
As announced above, the ConnectionPoolDataSource implementations in org.firebirdsql.pool and org.firebirdsql.jca will be removed in Jaybird 2.3. This may included removal of additional classes and interfaces from these packages (or the entire package).
The following (deprecated) classes will also be removed:
* org.firebirdsql.jdbc.FBWrappingDataSource (old deprecated class subclassing org.firebirdsql.pool.FBWrappingDataSource), only included in jaybird-full jar
Furthermore the following interfaces will be removed as they are no longer needed:
* FirebirdSavepoint (identical to java.sql.Savepoint)
The following interfaces will have some of the methods removed:
* FirebirdConnection
** setFirebirdSavepoint() replace with Connection#setSavepoint()
** setFirebirdSavepoint(String name) replace with Connection#setSavepoint(String name)
** rollback(FirebirdSavepoint savepoint) replace with Connection#rollback(Savepoint savepoint)
** releaseSavepoint(FirebirdSavepoint savepoint) replace with Connection#releaseSavepoint(Savepoint savepoint)
If you are still using these interfaces or methods, please change your code to use the JDBC interface or method instead.
Handling (VAR)CHAR CHARACTER SET OCTETS as (VAR)BINARY type
...........................................................
From Jaybird 2.3 on (VAR)CHAR CHARACTER SET OCTETS will be considered to be of java.sql.Types type (VAR)BINARY. This should not impact normal use of methods like get/setString(), but will impact the metadata and the type of object returned by getObject() (a byte array instead of a String).
Handling connections without explicit connection character set
..............................................................
When no connection character set has been specified (properties lc_ctype or encoding with Firebird character set, or charSet or localEncoding with Java character set), Jaybird will currently use the NONE character set. This means that the Firebird server will return the bytes for (VAR)CHAR columns as they are stored, while Jaybird will convert between bytes and Strings using the local platform encoding.
This default has the potential of corrupting data when switching platforms or using the same database with different local encoding, or for transliteration errors when the database character set does not accept some byte combinations. We are currently discussing changing this behavior (see JDBC-257). We haven't decided on the exact changes yet, but most likely the next version of Jaybird will refuse to connect without an explicit connection character set. For the time being, Jaybird will log a warning and add a warning on the Connection when no explicit character set was specified.
Review your use of the connection character sets and change it if you are not specifying it explicitly. Be aware that changing this may require you to fix the data as it is currently stored in your database if your database character set does not match the local platform encoding of your Java application. If you are sure that NONE is the correct character set for you, specify it explicitly in your connection string or connection properties.
Replacement or upgrade of logging library
.........................................
Logging in Jaybird 2.3 will be changed. We will either switch to slf4j, or upgrade Log4J to version 2.x.
Distribution package
====================
The following file groups can be found in distribution package:
* jaybird-2.2.3.jar archive containing JCA/JDBC driver, implementation of connection pooling and statement pooling interfaces, and JMX management class. It requires JCA 1.5
* jaybird-full-2.2.3.jar merge of jaybird-2.2.3.jar and connector-api-1.5.jar. This archive can be used for standalone Jaybird deployments
* jaybird-2.2.3-sources.jar archive containing the sources of Jaybird (specific to this JDK version); for including Jaybird sources in your IDE
* lib/connector-api-1.5.jar archive containing JCA 1.5 classes (required dependency)
* lib/antlr-runtime-3.4.jar archive containing ANTLR runtime classes, required for generated keys functionality (optional dependency)
* lib/log4j-core.jar archive containing core Log4J classes that provide logging (optional dependency)
Jaybird has compile-time and run-time dependencies to the JCA 1.5 classes. Additionally, if Log4J classes are found in the class path, it is possible to enable extensive logging inside the driver. If the ANTLR runtime classes are absent, the generated keys functionality will not be available.
Native dependencies (required only for Type 2 and Embedded):
* jaybird22.dll Windows 32-bit
* jaybird22_x64.dll Windows 64-bit
* libjaybird22.so Linux 32-bit (x86)
* libjaybird22_x64.so Linux 64-bit (AMD/Intel 64)
The Windows DLLs have been built with Microsoft Visual Studio 2010 SP1. To use the native or embedded driver, you will need to install the Microsoft Visual C++ 2010 SP 1 redistributable available at:
x86: http://www.microsoft.com/download/en/details.aspx?id=8328
x64: http://www.microsoft.com/download/en/details.aspx?id=13523
License
-------
Jaybird JCA/JDBC driver is distributed under the GNU Lesser General Public License (LGPL). Text of the license can be obtained from http://www.gnu.org/copyleft/lesser.html.
Using Jaybird (by importing Jaybird's public interfaces in your Java code), and extending Jaybird by subclassing or implementation of an extension interface (but not abstract or concrete class) is considered by the authors of Jaybird to be dynamic linking. Hence our interpretation of the LGPL is that the use of the unmodified Jaybird source does not affect the license of your application code.
Even more, all extension interfaces to which application might want to link are released under dual LGPL/modified BSD license. Latter is basically AS IS license that allows any kind of use of that source code. Jaybird should be viewed as an implementation of that interfaces and LGPL section for dynamic linking is applicable in this case.
Source Code
-----------
The distribution package contains the normal sources in jaybird-2.2.3-sources.jar; this file does not include the sources of the tests, nor the sourcecode for other JDK-versions.
Full source code, including tests and build files, can be obtained from the Subversion repository at SourceForge.net. The repository URL is
https://firebird.svn.sourceforge.net/svnroot/firebird/client-java
Alternatively source code can be viewed online at
http://firebird.svn.sourceforge.net/viewvc/firebird/client-java/
Documentation and Support
=========================
Where to get more information on Jaybird
----------------------------------------
The most detailed information can be found in the Jaybird Frequently Asked Questions (FAQ). The FAQ is included in the distribution, and is available on-line in several places.
JaybirdWiki is available at http://Jaybirdwiki.firebirdsql.org. (note: this resource is out of date and will be discontinued in the near future)
Jaybird 2.1 Programmers Manual: http://www.firebirdsql.org/file/documentation/drivers_documentation/Jaybird_2_1_JDBC_driver_manual.pdf
Where to get help
-----------------
The best place to start is the FAQ. Many details for using Jaybird with various programs are located there. Below are some links to useful web sites.
* The http://groups.yahoo.com/group/Firebird-Java and corresponding mailing list Firebird-Java@yahoogroups.com.
* The code for Firebird and this driver are on http://sourceforge.net/projects/firebird.
* The Firebird project home page http://www.firebirdsql.com.
Contributing
------------
There are several ways you can contribute to Jaybird or Firebird in general:
* Participate on the mailinglists (see http://www.firebirdsql.org/en/mailing-lists/)
* Report bugs or submit patches on the tracker (see below)
* Become a developer (for Jaybird contact us on Firebird-Java, for Firebird in general, use the Firebird-devel mailing-list)
* Become a paying member or sponsor of the Firebird Foundation (see http://www.firebirdsql.org/en/firebird-foundation/)
See also http://www.firebirdsql.org/en/consider-your-contribution/
Reporting Bugs
--------------
The developers follow the Firebird-Java@yahoogroups.com list. Join the list and post information about suspected bugs. This is a good idea because what is often thought to be a bug turns out to be something else. List members may be able to help out and get you going again, whereas bug fixes might take awhile.
If you are sure that this is a bug you can report it in the Firebird bug tracker, project "Java Client (Jaybird)" at http://tracker.firebirdsql.org/browse/JDBC
When reporting bugs, please provide a minimal reproduction, including databases and sourcecode to reproduce the problem.
Corrections/Additions To Release Notes
--------------------------------------
Please send corrections, suggestions, or additions to these Release Notes to to the mailing list at Firebird-Java@yahoogroups.com.
