Download Latest Version Firebird-5.0.3.1683-0-source.tar.xz (29.3 MB)
Email in envelope

Get an email when there's a new version of Firebird

Home / firebird-jca-jdbc-driver / 2.2.0-beta-1-src
Name Modified Size InfoDownloads / Week
Parent folder
Jaybird-2.2.0-beta-1-src.zip 2012-04-07 9.0 MB
0
README 2012-04-07 17.6 kB
0
Totals: 2 Items   9.0 MB 0 
Release Notes Jaybird 2.2.0 beta 1

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.0 beta 1 was tested against Firebird 2.1.4 and 2.5.1, 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 a Firebird-specific changes in the protocol and the database attachment parameters that are sent to the server.
Supported Java versions

Jaybird 2.2.0 beta 1 supports Java 5 (JDBC 3.0), Java 6 (JDBC 4.0) and Java 7 (JDBC 4.1). Support for earlier Java versions has been dropped1.
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:

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.0 beta 1 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).

This beta is deployed as version 2.2.0-beta-1

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 availabe 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

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 to 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)

A full list of changes is available at:

http://tracker.firebirdsql.org/secure/ReleaseNote.jspa?version=10053&styleName=Text&projectId=10002&Create=Create

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 implementations 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 them 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
.........................
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.

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).

Distribution package
====================
The following file groups can be found in distribution package:

    jaybird-2.2.0.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.0.jar – merge of jaybird-2.2.0.jar and connector-api-1.5.jar. This archive can be used for standalone Jaybird deployments

    jaybird-2.2.0-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.0-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 CVS at SourceForge.net. The CVSROOT is
:pserver:anonymous@cvs.sourceforge.net:/cvsroot/firebird, the module name is client-java

Alternatively source code can be viewed online at http://cvs.sourceforge.net/viewcvs.py/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)

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.

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.
Source: README, updated 2012-04-07