8/18/2019 Jay bird

1/37

Jaybird

Firebird JCA/JDBC Driver 

Release Notes v 2.2.7

Table of Contents

General NotesSupported Firebird versions

Supported Java versionsSpecification support

What's new in Jaybird 2.2Changes and fies in Jaybird 2.2.!Changes and fies in Jaybird 2.2."Changes and fies in Jaybird 2.2.#Changes and fies in Jaybird 2.2.$Changes and fies in Jaybird 2.2.%Changes and fies in Jaybird 2.2.2Changes and fies in Jaybird 2.2.&Changes and fies since Jaybird 2.2. beta &Support for getGenerated(eys)*

Java " and J+,C $. -/ supportJava ! and J+,C $.& -/ supportJava 0 and J+,C $.2 -/ supportJaybird on 1aven

 Native and 3bedded )JN/* "$4bit Windows and 5inu supportSupport for Firebird 2.#Support for Firebird %./3proved support for 6pen6ffice 7 5ibre6ffice ,ase6ther fies and changes

Co3patibility changesJava supportFirebird support

/3portant changes to +atasourcesFuture changes to Jaybird

+istribution pac8age5icenseSource Code

+ocu3entation and SupportWhere to get 3ore infor3ation on JaybirdWhere to get helpContributing9eporting ,ugsCorrections7-dditions :o 9elease Notes

J+,C ;95 For3ature Java;sing Firebird client library3bedded Server 

8/18/2019 Jay bird

2/37

;sing :ype 2 and 3bedded Server driver Configuring :ype 2 J+,C driver Configuring 3bedded Server J+,C driver Support for 3ultiple JN/ libraries

;sage and 9eference 1anualvents;pdatable result setsFirebird 3anage3ent interfacesJaybird J+,C etensionsJ+,C connection properties

J+,C Co3patibilityJ+,C deviations and uni3ple3ented features

Jaybird Specifics9esult sets;sing euristic transaction co3pletion supportCo3patibility with co3.sun.rowset.?Support for Firebird % ,665-N type

Connection pooling with Jaybird+escription of deprecated org.firebirds=l.pool classes;sage scenarioConnection ool Classes )deprecated*org.firebirds=l.pool.F,Connectionool+ataSource )deprecated*org.firebirds=l.pool.F,Wrapping+ataSource9unti3e ob

8/18/2019 Jay bird

3/37

General Notes

Jaybird is a JC-7J+,C driver suite to connect to Firebird database servers.

:his driver is based on both the JC- standard for application server connections to enterprise

infor3ation syste3s and the well48nown J+,C standard.

:he JC- standard specifies an architecture in which an application server can cooperate with adriver so that the application server 3anages transactions@ security@ and resource pooling@ and thedriver supplies only the connection functionality. While si3ilar to the J+,C XADataSource concept@ the JC- specification is considerably clearer on the division of responsibility between theapplication server and driver.

Suorted Firebird versions

Jaybird 2.2.! was tested against Firebird 2.&.!@ Firebird 2.#.% ;pdate & and Firebird % beta &@ butshould also support other Firebird versions fro3 &. and up. :he :ype 2 and e3bedded server

J+,C drivers re=uire the appropriate JN/ library. reco3piled JN/ binaries for Win%2 and 5inu platfor3s are shipped in the default installation@ other platfor3s re=uire porting7building the JN/library for that platfor3.

Connecting to Firebird % re=uires so3e additional configuration@ see Jaybird and Firebird %. ,eta &for details.

:his driver does not support /nter,ase servers due to Firebird4specific changes in the protocol anddatabase attach3ent para3eters that are sent to the server.

Suorted Java versions

Jaybird 2.2.! supports Java # )J+,C %.*@ Java " )J+,C $.*@ Java ! )J+,C $.&* and Java 0 )J+,C$.2*. Support for earlier Java versions has been dropped.

Se!ifi!ation suort

+river supports the following specificationsA

J+,C $.2 +river does not fully support J+,C $.2 features@ but i3ple3ents large updatecount 3ethods by calling the nor3al update count 3ethods@ and 3ethods withSQLType by calling 3ethods accepting the java.sql.Types integer value.

Supports new java.Time classes with so3e caveats.

J+,C $.& +river i3ple3ents all J+,C $.& 3ethods added to eisting interfaces. :he drivereplicitly supports closeOnCompletion@ 3ost other 3ethods introduced withJ+,C $.& throw SQLFeatureNotSupportedEception .

J+,C $. +river i3ple3ents all J+,C $. interfaces and supports eception chaining.

J+,C %. +river i3ple3ents all J+,C %. interfaces )but will throwF!DriverNotCapa"leEception for so3e 3ethods*

JC- &. Jaybird provides i3ple3entation ofjava.resource.spi.#ana$edConnectionFactory  and related interfaces. CC/interfaces are not supported.

-lthough Jaybird depends on the JC- &.# classes@ JC- &.# co3patibility iscurrently not guaranteed.

J:- &..& +river provides an i3ple3entation of java.transaction.a.XA%esource  

http://jaybirdwiki.firebirdsql.org/jaybird/doku.php?id=tip:firebird30b1http://jaybirdwiki.firebirdsql.org/jaybird/doku.php?id=tip:firebird30b1

8/18/2019 Jay bird

4/37

interface via JC- fra3ewor8 and XADataSource i3ple3entation.

J1B &.2 Jaybird provides a 1,ean to 3anage Firebird servers and installed databases viaJ1B agent.

8/18/2019 Jay bird

5/37

"#at$s ne% in Jaybird 2.2

Jaybird 2.2 introduces the following new features and fiesA

C#an&es and fi'es in Jaybird 2.2.7:he following has been changed or fied in Jaybird 2.2.!A

• FiedA blob return value of eecutable procedure obtained through getters onCalla"leStatement is 0 byte blob id@ instead of epected blob content ) JDBC-381*:his was a regression caused by the changes of JDBC-350.

(no%n issues in Jaybird 2.2.7

:he following are 8nown in issues in Jaybird 2.2.! )and earlier*A

•   %esultSets opened with CLOSE&C'%SO%S&AT&CO##(T  aren't correctly closed on co33it

when auto4co33it is off ) JDBC-307 *:his list is not ehaustive@ see the Jaybird tracker  for a full list of open bugs.

C#an&es and fi'es in Jaybird 2.2.)

:he following has been changed or fied in Jaybird 2.2."A

• 9everted Firebird % wor8around for updatable result sets as bug has been fied in Firebird) JDBC-330*

• FiedA rocessing and closing the %esultSet fro3 callable state3ent and then using thegetters throws Null)ointerEception  ) JDBC-350*

;sing both the getters and the result set for the sa3e callable state3ent is incorrect theability to do this 3ight be re3oved in a future version of Jaybird. - %esultSet should beused for selectable procedures@ while the getters should be used with eecutable procedures.

• FiedA F!#ana$edConnectionFactory.tryComplete(nLim"oTransaction  doesn't wor8with recent Firebird % builds ) JDBC-353*

• FiedA Jaybird can throw a Null)ointerEception  when a fatal connection error hasoccurred ) JDBC-359*

• FiedA Calling close on a JC- connection triggers eception Connection enlisted indistributed transaction ) JDBC-362*

• FiedA otential 3e3ory4lea8 when using a lot of different connection strings and7or properties ) JDBC-36*

• FiedA F!%o*'pdater."uild(nsertStatement doesn't =uote colu3n na3es ) JDBC-370*

• FiedA Encodin$Factory doesn't handle 'nsupportedC+arsetEception  ) JDBC-371*

• FiedA Current 3ethod of =uoting in F!%o*'pdater incorrect for dialect & ) JDBC-372*

C#an&es and fi'es in Jaybird 2.2.*

:he following has been changed or fied in Jaybird 2.2.#A

• FiedA $etCross%e,erence bro8en by changes of J+,C4%%& ) JDBC-335*

• -ddedA basic support for Java 0

8/18/2019 Jay bird

6/37

 been increased fro3 & 3illisecond to the 3ai3u3 Firebird precision of & 3icroseconds)or .& 3illisecond*&.

• FiedA +eadloc8s and other thread safety issues with classes in or$.,ire"irdsql.pool ) JDBC-31*

C#an&es and fi'es in Jaybird 2.2.+

:he following has been changed or fied in Jaybird 2.2.$A

• FiedA ceptions during state3ent preparation leave connection and transaction open aftereplicit close ) JDBC-311*

• Fied batch update )or insert* with blob set through set!inaryStream- sets e3pty blobfor all but the first batch entry ) JDBC-312*

• Fied inco3plete chec8s of database@ transaction@ state3ent and blob handle validity beforecontinuing with actions. :hese inco3plete chec8s could lead to unepected eceptions )for

ea3ple a Null)ointerEception  in iscData"ase(n,o* ) JDBC- 313*

• Fied error when setting connection charset e=ual to D,ile.encodin$D ibernate reverse engineering wiEard in Net,eans ) JDBC-325*

• FiedA Jaybird should specify dialect % in dpb when no eplicit dialect was set ) JDBC-327 *

• FiedA several DatabaseMetaData 3ethods defined by J+,C to only accept the actual tablena3e also accepted a LIKE4pattern or e3pty string or null. :his was changed to confor3 toJ+,C. :his change can brea8 applications that relied on the incorrect behavior ) JDBC-331*-ffected 3ethods areA getPrimaryKeys@ getBestRowIdentifier@ getImportedKeys@getExportedKeys and getCrossReference. -s part of this change getIndexInfo now handlesna3es in the wrong case slightly different.

Jaybird %. will further 3odify and restrict the pattern 3atching and case sensitivity of3etadata 3ethods. See Future changes to Jaybird.

C#an&es and fi'es in Jaybird 2.2.,

:he following has been changed or fied in Jaybird 2.2.%A

• Fied incorrect synchroniEation in native and e3bedded protocol )JN/* i3ple3entation forisc!lo"(n,o and iscSee0!lo" ) JDBC-300*W-9N/NGA -lthough Jaybird strives for correct synchroniEation@ a J+,C Connection@ andits dependent ob

8/18/2019 Jay bird

7/37

• Fied table na3es 3issing or padded with spaces in +atabase view of /ntelliJ /+- ) JDBC-308@ !D"# -100786 *

• Fied incorrect J+,C 3inor version reported under Java ! this resulted in an incorrectcolu3n na3e )for Java !* in the 3etadata of Data"ase#etaData.$etColumns-...  

) JDBC-309*

• -dded (OEception to cause of /DSEception with error %%##$$!2& $nable to co%&letenet'ork re(uest to )ost *+ for further investigation ) JDBC-306 *

C#an&es and fi'es in Jaybird 2.2.2

:he following has been changed or fied in Jaybird 2.2.2A

• FiedA F!#aintenance#ana$er.listLim"oTransactions-  reports incorrect transactionid when the result contains 3ulti4site transactions in li3bo ) JDBC-266 *

• FiedA Calling )reparedStatement.setClo"-int1 Clo" with a non4Firebird Clo" )eg

li8e >ibernate does* or calling )reparedStatement.setClo"-int1 %eader throwsF!SQLEceptionA Hou can't start before the beginning of the blob ) JDBC-281*

• FiedA Connection property types not properly processed fro3 isc&dp"&types.properties) JDBC- 28*

• FiedA JN/ i3ple3entation of para3eter buffer writes incorrect integers ) JDBC-285@  JDBC-286 *

• ChangedA :hrow SQLEception when calling eecute@ eecuteQuery@ eecute'pdate and add!atc+ 3ethods accepting a =uery string on a )reparedStatement  orCalla"leStatement as re=uired by J+,C $. ) JDBC-288*

 N6:A ,e aware that this change can brea8 eisting code if you depended on the old@ non4standard behaviorI With add!atc+-Strin$ the old behavior lead to a 3e3ory lea8 andunepected results.

• FiedA L(3E escape character J+,C escape )4escape 56c+ar758* doesn't wor8 ) JDBC-290*

• -ddedA Support for a connect ti3eout using connection property connectTimeout. :his property can be specified in the J+,C ;95 or )roperties ob

8/18/2019 Jay bird

8/37

C#an&es and fi'es in Jaybird 2.2.-

:he following has been changed or fied in Jaybird 2.2.&A

• FiedA 'nsatis,iedLin0Error  in li"jay"ird>>-&?@.so unde,ined sym"ol

&BTN&&ca"iv&&class&type&in,oE  on 5inu ,  JDBC-259  • -dded connection property columnLa"elForName  for bac8wards co3patible behavior of

%esultSet#etaDataG$etColumnName-int  and co3patibility with bug incom.sun.ro*set.Cac+ed%o*Set(mpl  ,  JDBC-260 Set property to true for bac8wards co3patible behavior )$etColumnName- returns thecolu3n label* don't set the property or set it to ,alse for J+,C4co3pliant behavior)reco33ended*.

• FiedA setStrin$-column1 null on H (S -NOT N'LL condition does not set para3eter to N'LL ,  JDBC-26 

• :he c+arSet connection property now accepts all aliases of the supported Java charactersets )eg instead of only Cp>I> now *indo*sJ>I> is also accepted* ,  JDBC-267  

• FiedA values of c+arSet property are case4sensitive ,  JDBC-268 

• FiedA setting a para3eter as N'LL with the native protocol does not wor8 when Firebirddescribes the para3eter as not nullable ,  JDB C-271 

C#an&es and fi'es sin!e Jaybird 2.2. beta -

:he following was changed or fied after the release of Jaybird 2.2. beta &A

•   Concurrent#odi,icationEception when closing connection obtained fro3or$.,ire"irdsql.ds.F!Connection)oolDataSource  with state3ents open ,  JDBC-250 

• 1e3ory lea8 when obtaining 3ultiple connections for the sa3e ;95 ,  JDBC-29 

• C; spi8es to &K when using events and Firebird Server is stopped or unreachable,  JDBC- 232 

• vents do not wor8 on 3bedded ,  JDBC-27  

• rovide wor8around for character set transliteration proble3s in database filena3es andother connection properties ,  JDBC-253  see also Support for Firebird 2.#.

•   F!!ac0up#ana$er does not allow &"8b page siEe for restore ) JDBC-255*

• 5og warning and add warning on Connection when no eplicit connection character set is

specified ) JDBC-257 *

Suort for getGeneratedKeys()

Support was added for the $et/enerated3eys-  functionality for Statement and)reparedStatement.

:here are four distinct use4casesA

&. 1ethods accepting an int para3eter with values of Statement.NO&/ENE%ATED&3EKS andStatement.%ET'%N&/ENE%ATED&3EKS

When NO&/ENE%ATED&3EKS is passed@ the =uery will be eecuted as a nor3al =uery.

When %ET'%N&/ENE%ATED&3EKS  is passed@ the driver will add all  colu3ns of the table inordinal position order )as in the )J+,C* 3etadata of the table*. /t is advisable to retrieve thevalues fro3 the $et/enerated3eys-  resultset by colu3n na3e.

http://tracker.firebirdsql.org/browse/JDBC-259http://tracker.firebirdsql.org/browse/JDBC-260http://tracker.firebirdsql.org/browse/JDBC-264http://tracker.firebirdsql.org/browse/JDBC-267http://tracker.firebirdsql.org/browse/JDBC-268http://tracker.firebirdsql.org/browse/JDBC-271http://tracker.firebirdsql.org/browse/JDBC-250http://tracker.firebirdsql.org/browse/JDBC-249http://tracker.firebirdsql.org/browse/JDBC-232http://tracker.firebirdsql.org/browse/JDBC-247http://tracker.firebirdsql.org/browse/JDBC-253http://tracker.firebirdsql.org/browse/JDBC-255http://tracker.firebirdsql.org/browse/JDBC-257http://tracker.firebirdsql.org/browse/JDBC-259http://tracker.firebirdsql.org/browse/JDBC-260http://tracker.firebirdsql.org/browse/JDBC-264http://tracker.firebirdsql.org/browse/JDBC-267http://tracker.firebirdsql.org/browse/JDBC-268http://tracker.firebirdsql.org/browse/JDBC-271http://tracker.firebirdsql.org/browse/JDBC-271http://tracker.firebirdsql.org/browse/JDBC-250http://tracker.firebirdsql.org/browse/JDBC-249http://tracker.firebirdsql.org/browse/JDBC-232http://tracker.firebirdsql.org/browse/JDBC-232http://tracker.firebirdsql.org/browse/JDBC-247http://tracker.firebirdsql.org/browse/JDBC-253http://tracker.firebirdsql.org/browse/JDBC-255http://tracker.firebirdsql.org/browse/JDBC-257

8/18/2019 Jay bird

9/37

We opted to include all colu3ns as it is net to i3possible to decide which colu3ns arefilled by a trigger or otherwise and only returning the pri3ary 8ey will be too li3iting

2. 1ethods accepting an intM para3eter with colu3n indees.

:he values in the intM para3eter are the ordinal positions of the colu3ns as specified inthe )J+,C* 3etadata of the table. For a null or e3pty array the state3ent is processed as is./nvalid ordinal positions are ignored and silently dropped )be awareA the J+,C specificationis not entirely clear if this is valid behavior@ so this 3ight change in the future*

%. 1ethods accepting a Strin$M para3eter with colu3n na3es.

:he values in the Strin$M are the colu3n na3es to be returned. :he colu3n na3es provided are processed as is and not chec8ed for validity or the need of =uoting. rovidingnon4eistent or incorrectly )un*=uoted colu3ns will result in an eception when thestate3ent is processed by Firebird.

:his 3ethod is the fastest as it does not retrieve 3etadata fro3 the server.

$. roviding a =uery already containing a %ET'%N(N/ clause. /n this case all of the previouscases are ignored and the =uery is eecuted as is. /t is possible to retrieve the resultset using$et/enerated3eys- .

:his functionality will only be available if the -N:59 %.$ runti3e classes are on the classpath.cept for calling 3ethods with NO&/ENE%ATED&3EKS@ absence of the -N:59 runti3e will throwF!DriverNotCapa"leEception .

:his functionality should wor8 for (NSE%T )fro3 Firebird 2.*@ and for ')DATE@ ')DATE O% (NSE%T and DELETE )fro3 Firebird 2.&*.

Java ) and JDBC +. A0 suortSupport was added for the following J+,C $. featuresA

• -uto3atic driver loadingA on Java " and later it is no longer necessary to useClass.,orName-or$.,ire"irdsql.jd"c.F!Driver  to load the driver 

• /3ple3entation of java.sql.9rapper  interface on various J+,C classes in general it onlyunwraps to the specific i3ple3entation class )and superclasses* and i3ple3ented interfaces

• Support for chained eceptions )use $etNetEception-  and iterator- to view other@related eceptions* and $etCause- to retrieve the cause )deprecating si3ilar$et(nternalEception-*

• Support for $etClient(n,o- and setClient(n,o- on Connection

Java 7 and JDBC +.- A0 suort

Support was added for the following J+,C $.& featuresA

• try4with4resources2

• State3ent closeOnCompletion

6ther 3ethods added by J+,C $.& will throw F!DriverNotCapa"leEception  )a subclass ofSQLFeatureNotSupportedEception *.

2 See httpA77docs.oracle.co37

8/18/2019 Jay bird

10/37

Java 1 and JDBC +.2 A0 suort

1ini3al support for J+,C $.2 was added in Jaybird 2.2.$ and etended in 2.2.#A

• 5arge update countsA no actual support is provided@ 3ethod call is forwarded to the nor3al

update count 3ethod returning an int.• 1ethods accepting java.sql.SQLTypeA no actual support is provided@ 3ethod call is

forwarded to e=uivalent 3ethod accepting a java.sql.Types integer value.

•   )reparedStatement.setO"ject- and %esultSet.updateO"ject-  now acceptjava.time ob

8/18/2019 Jay bird

11/37

:his wor8around consists of two steps

&. nsure your Java application is eecuted with the syste3 property ,ile.encodin$'TFJP )either because that is the default encoding for your 6S@ or by eplicitly specifying this

 property on the co33andline of your application using JD,ile.encodin$'TFJP*

2. /nclude property ut,P&,ilename in the J+,C ;95 or )non4standard* properties of thedatasource

:his will only wor8 if the Firebird server is version 2.# or higher.

Suort for Firebird ,.

Jaybird 2.2. only supports Firebird %. using the legacy authentication. :he new authentication3odel and wire protocol encryption is not yet supported. :echnically these new protocol optionswill wor8 when using the :ype 2 driver@ but this hasn't been fully tested.

When using Jaybird with Firebird %.@ 3a8e sure that

• Wire protocol encryption is not re=uired

• 5egacy authentication is enabled

• :he user has been created with the legacy user3anager 

:he new !OOLEAN data type is supported

See the Jaybird Wi8i for 3ore details.

04roved suort for 9en9ffi!e / 8ibre9ffi!e Base

:he interpretation of the J+,C standard by Jaybird differs fro3 the interpretation by 6pen6ffice 7

5ibre6ffice. :o address so3e of the proble3s caused by these differences@ Jaybird now provides aseparate protocol for 6pen6ffice 7 5ibre6ffice.

When connecting fro3 ,ase@ use the protocol prefi jd"c,ire"irdsqloo . ,e aware that this isa variant of the pure Java wire protocol and not the native or e3bedded protocol.

/ssues addressed by this protocolA

• 9esult sets are not closed when a state3ents is finished )eg fully read %esultSet or whencreating a new State3ent in auto4co33it 3ode*

•   Data"ase#etaDataG$etTa"le)rivile$es-...  reports privileges granted to )'!L(C andto the current role )as reported by C'%%ENT&%OLE* as being granted to the user ,ater Jaybird 

2.2.0 beta 1.

9t#er fi'es and !#an&es

• 9eplaced miniJj>ee.jar with connectorJapiJ.I.jar A 3a8e sure to re3ove the oldminiJj>ee.jar fro3 the classpath of your application.

• +ropped jay"irdJpool 

8/18/2019 Jay bird

12/37

8/18/2019 Jay bird

13/37

Co4atibility !#an&es

Jaybird 2.2 introduces so3e changes in co3patibility and announces future brea8ing changes. :heversion previously announced as Jaybird 2.% will be released as Jaybird %..

Java suort

Java # support will be dropped for Jaybird %. as Java # has been on nd46f4ublic4;pdates% statussince 6ctober 2.

Java " support will be dropped for Jaybird %.& as Java " has been on nd46f4ublic4;pdates statussince February 2&%.

Firebird suort

Jaybird 2.2 supports Firebird &. and higher@ but is only tested with Firebird 2.&@ 2.# and %.. WithJaybird %. for3al support for Firebird &. and &.# will be dropped. /n general this should not

i3pact the use of the driver@ but 3ight have i3pact on the availability and use of 3etadatainfor3ation. :his also 3eans that fro3 Jaybird %. bugs that only occur with Firebird &. and &.#will not be fied. With Jaybird %.& support for Firebird 2. will be dropped.

04ortant !#an&es to Datasour!es

:he Connection)oolDataSource  and XADataSource i3ple3entations in or$.,ire"irdsql.pooland or$.,ire"irdsql.pool.sun  contain several bugs with regard to pool and connection3anage3ent when used by a Java application server. :he decision was 3ade to write newi3ple3entations in the pac8age or$.,ire"irdsql.ds .

:he following i3ple3entation classes have been deprecated and will be re3oved in Jaybird %.A

•   or$.,ire"irdsql.pool.DriverConnection)oolDataSource

•   or$.,ire"irdsql.pool.F!Connection)oolDataSource

•   or$.,ire"irdsql.pool.sun.AppServerDataSource

•   or$.,ire"irdsql.pool.sun.AppServerXADataSource

•   or$.,ire"irdsql.jca.F!XADataSource

•   or$.,ire"irdsql.pool.SimpleDataSource

:heir replace3ent classes areA

•   or$.,ire"irdsql.ds.F!Connection)oolDataSource

•

  or$.,ire"irdsql.ds.F!XADataSource

•   or$.,ire"irdsql.pool.F!SimpleDataSource )a nor3al DataSource*

We strongly urge you to switch to these new i3ple3entations if you are using these classes in anapplication server. :he bugs are described in J+,C40"@ J+,C4%@ J+,C4&%& and J+,C4&$$.

:he deprecated classes can still be used with the DataSource i3ple3entations9rappin$DataSource  as the identified bugs do not occur with this i3ple3entation@ but we adviseyou to switch to F!SimpleDataSource . /f you re=uire a standalone connection pool )outside anapplication server* or state3ent pooling@ please consider using a third4party connection pool li8eC%@ +,C or >i8ariC.

:he new Connection)oolDataSource  and XADataSource i3ple3entations only provide the basicfunctionality specified in the J+,C specifications and do not provide any pooling itself. :he

% See httpA77www.oracle.co37technetwor87

8/18/2019 Jay bird

14/37

Connection)oolDataSource  and XADataSource are intended to be used by connection pools )as provided by application servers* and should not be connection pools the3selves.

Future !#an&es to Jaybird

:he net versions of Jaybird will include so3e potentially brea8ing changes. We advise tochec8 your code if you will be affected by these changes and prepare for these changes if possible.

Re4oval of dere!ated !lasses: a!;a&es and 5interfa!e6 4et#ods

-s announced above@ the Connection)oolDataSource  i3ple3entations inor$.,ire"irdsql.pool  and or$.,ire"irdsql.jca will be re3oved in Jaybird %.. :he entireor$.,ire"irdsql.pool  pac8age will be re3oved.

:he following )deprecated* classes will also be re3ovedA

•   or$.,ire"irdsql.jd"c.F!9rappin$DataSource )old deprecated class subclassing

or$.,ire"irdsql.pool.F!9rappin$DataSource *@ only included in jay"irdJ,ull 

8/18/2019 Jay bird

15/37

Jaybird will log a warning and add a warning on the Connection when no eplicit character set wasspecified.

9eview your use of the connection character sets and change it if you are not specifying it eplicitly.,e aware that changing this 3ay re=uire you to fi the data as it is currently stored in your database

if your database character set does not 3atch the local platfor3 encoding of your Java application. /f you are sure that NONE is the correct character set for you@ specify it eplicitly in your connectionstring or connection properties.

Rela!e4ent or u&rade of lo&&in& library

5ogging in Jaybird %. will be changed. We will probably switch to java.util.lo$$in$@ but weare also considering slf$

8/18/2019 Jay bird

16/37

Distribution a!;a&e

:he following file groups can be found in distribution pac8ageA

•   jay"irdJ>.>..jar  archive containing JC-7J+,C driver@ i3ple3entation of connection

 pooling and state3ent pooling interfaces@ and J1B 3anage3ent class. /t re=uires JC- &.#.

•   jay"irdJ,ullJ>.>..jar  3erge of .>.Jsources.jar  archive containing the sources of Jaybird )specific to thisJ+( version* for including Jaybird sources in your /+.

•   li":connectorJapiJ.I.jar  archive containing JC- &.# classes )re=uired dependency*.

•   li":antlrJruntimeJ=.@.jar  archive containing -N:59 runti3e classes@ re=uired forgenerated 8eys functionality )optional dependency*.

•   li":lo$@jJcore.jar  archive containing core 5og$J classes that provide logging)optional dependency*.

Jaybird has co3pile4ti3e and run4ti3e dependencies on the JC- &.# classes. -dditionally@ if 5og$Jclasses are found in the class path@ it is possible to enable etensive logging inside the driver. /f the-N:59 runti3e classes are absent@ the generated 8eys functionality will not be available.

 Native dependencies )re=uired only for :ype 2 and 3bedded*A

•   jay"ird>>.dll  Windows %24bit

•   jay"ird>>&?@.dll  Windows "$4bit

•   li"jay"ird>>.so  5inu %24bit )0"*•   li"jay"ird>>&?@.so  5inu "$4bit )-1+7/ntel "$*

:he Windows +55s have been built with 1icrosoft Lisual Studio 2& S&. :o use the native ore3bedded driver@ you will need to install the 1icrosoft Lisual COO 2& S & redistributableavailable atA

• 0"A +ttp::***.microso,t.com:do*nload:en:details.aspHidP=>P

• "$A +ttp::***.microso,t.com:do*nload:en:details.aspHid=I>=

8i!ense

Jaybird JC-7J+,C driver is distributed under the GN; 5esser General ublic 5icense )5G5*.:et of the license can be obtained fro3 +ttp::***.$nu.or$:copyle,t:lesser.+tml .

;sing Jaybird )by i3porting Jaybird's public interfaces in your Java code*@ and etending Jaybird bysubclassing or i3ple3entation of an etension interface )but not abstract or concrete class* isconsidered by the authors of Jaybird to be dyna3ic lin8ing. >ence our interpretation of the 5G5 isthat the use of the un3odified Jaybird source does not affect the license of your application code.

ven 3ore@ all etension interfaces to which application 3ight want to lin8 are released under dual5G573odified ,S+ license. 5atter is basically -S /S license that allows any 8ind of use of thatsource code. Jaybird should be viewed as an i3ple3entation of that interfaces and 5G5 section for dyna3ic lin8ing is applicable in this case.

http://www.microsoft.com/download/en/details.aspx?id=8328http://www.microsoft.com/download/en/details.aspx?id=13523http://www.gnu.org/copyleft/lesser.htmlhttp://www.microsoft.com/download/en/details.aspx?id=8328http://www.microsoft.com/download/en/details.aspx?id=13523http://www.gnu.org/copyleft/lesser.html

8/18/2019 Jay bird

17/37

Sour!e Code

:he distribution pac8age contains the nor3al sources in jay"irdJ>.>.Jsources.jar this filedoes not include the sources of the tests@ nor the sourcecode for other J+(4versions.

Full source code@ including tests and build files@ can be obtained fro3 the Subversion repository atSourceForge.net. :he repository ;95 issvnA77svn.code.sf.net7p7firebird7code7client4

8/18/2019 Jay bird

18/37

Do!u4entation and Suort

"#ere to &et 4ore infor4ation on Jaybird

:he 3ost detailed infor3ation can be found in the Jaybird Fre=uently -s8ed Puestions )F-P*. :heF-P is included in the distribution@ and is available on4line in several places.

JaybirdWi8i is available at +ttp::jay"ird*i0i.,ire"irdsql.or$:

Jaybird 2.& rogra33ers 1anualA+ttp::***.,ire"irdsql.or$:,ile:documentation:drivers&documentation:ay"ird&>&&D!C&driver&manual.pd,

"#ere to &et #el

:he best place to start is the F-P. 1any details for using Jaybird with various progra3s are locatedthere. ,elow are so3e lin8s to useful web sites.

• :he +ttp::$roups.ya+oo.com:$roup:Fire"irdJava and corresponding 3ailing4listFire"irdJavaya+oo$roups.com

• :he code for Firebird and this driver are on +ttp::source,or$e.net:projects:,ire"ird

• :he Firebird pro

8/18/2019 Jay bird

19/37

JDBC =R8 For4at

Jaybird provides different J+,C ;95s for different usage scenariosA

ure Javajd"c,ire"irdsql::+ostportM:6data"ase7

+efault ;95@ will connect to the database using :ype $ J+,C driver using the Java i3ple3entationof the Firebird wire4protocol. ,est suited for client4server applications with dedicated databaseserver. ort can be o3itted )default value is %#*@ host na3e 3ust be present.

:he 6data"ase7 part should be replaced with the database alias or the path to the database. /ngeneral it is advisable to uses database aliases instead of the path the file.

6n 5inu the root : should be included in the path. - database located on :opt:,ire"ird:d".,d"  should use the ;95 below )note the double slash after portI*.jd"c,ire"irdsql::+ostport::opt:,ire"ird:d".,d"

+eprecated but still available alternative ;95A

jd"c,ire"irdsql+ost:portM6data"ase7

=sin& Firebird !lient library

jd"c,ire"irdsqlnative+ost:portM6data"ase7

:ype 2 driver@ will connect to the database using client library ),"client.dll on Windows@ andli","client.so on 5inu*. 9e=uires correct installation of the client library.

jd"c,ire"irdsqllocal6data"ase7

:ype 2 driver in local 3ode. ;ses client library as in previous case@ however will not use soc8etco33unication@ but rather access database directly. 9e=uires correct installation of the clientlibrary.

34bedded Server 

jd"c,ire"irdsqlem"edded6data"ase7

Si3ilar to the Firebird client library@ however ,"em"ed.dll on Windows and li","em"ed.so on5inu are used. 9e=uires correctly installed and configured Firebird e3bedded library.

8/18/2019 Jay bird

20/37

=sin& Tye 2 and 34bedded Server driver 

Jaybird 2.2 provides a :ype 2 J+,C driver that uses the native client library to connect to thedatabases. -dditionally Jaybird 2.2 can use the e3bedded version of Firebird so Java applications

do not re=uire a separate server setup.>owever the :ype 2 driver has its li3itationsA

+ue to 3ulti4threading issues in the Firebird client library as well as in the e3bedded serverversion@ it is not possible to access a single connection fro3 different threads si3ultaneously. Whenusing the client library only one thread is allowed to access a connection at a ti3e. -ccess todifferent connections fro3 different threads is however allowed. Client library in local 3ode ande3bedded server library on 5inu do not allow 3ultithreaded access to the library. Jaybird providesnecessary synchroniEation in Java code@ however the 3ute is local to the classloader that loadedthe Jaybird driver .

Care should be taken when deploying applications in web or application servers: put jar files

in the main library directory of the web and/or application server, not in the library directoryof the web or enterprise application (WE!"#$/lib directory or in the %E&' file%

Confi&urin& Tye 2 JDBC driver 

:he :ype 2 J+,C driver re=uires the Jaybird JN/ library to be installed and available to the JavaLirtual 1achine. reco3piled binaries for Windows and 5inu platfor3s are distributed withJaybird.

)lease note that *aybird +%+ provides an update to the *#" libraries to support new features%

"t is not compatible with the *#" library for *aybird +% or earlier%

•   jay"ird>>.dll : jay"ird>>&?@.dll is a preco3piled binary for the Windows platfor3. /twas successfully tested with Windows B and Windows !@ but there should be no issues in other Windows 6S versions )as long as the 1S Lisual COO 2& S& distributable is available*.:he library should be copied into a directory in the )AT environ3ent variable@ or be 3adeavailable to the JL1 using the java.li"rary.pat+ syste3 property.

•   li"jay"ird>>.so : li"jay"ird>>&?@.so is a preco3piled binary for the 5inu platfor3)-1+7/ntel*. /t 3ust be available via the LD&L(!%A%K&)AT environ3ent variable@ or be 3adeavailable to the JL1 using the java.li"rary.pat+ syste3 property.+ependent libraries )li","client.so or li","em"ed.so* need to be on the LD&L(!%A%K&)AT.:he java.li"rary.pat+ is ignored for these libraries as they are loaded fro3 the JN/ library@and not fro3 Java.So3e Firebird distributions will not create li","client.so )but only li","client.so.>  and.so.>.I*@ you will need to add a sy3lin8 with the na3e as epected by Jaybird.

• 6ther platfor3s can easily co3pile the JN/ library by chec8ing out the Jaybird sources fro3 theCLS and using .:"uild.s+ compileJnative co33and in the directory with chec8ed outsources.

-fter 3a8ing Jaybird JN/ library available to the JL1@ the application has to tell driver to startusing this by either specifying :H2 or 56C-5 type in the connection pool or data source

 properties or using appropriate J+,C ;95 when connecting via java.sql.Driver#ana$er .

Confi&urin& 34bedded Server JDBC driver 

:he 3bedded Server J+,C driver uses the sa3e JN/ library and configuration steps for the :ype 2J+,C driver.

8/18/2019 Jay bird

21/37

:here is however one issue related to the algorith3 of Firebird 3bedded Server installationdirectory resolution. Firebird server uses pluggable architecture for internationaliEation. ,y defaultserver loads ,"intl.dll or li","intl.so library that contains various character encodings andcollation orders. :his library is epected to be installed in the intl: subdirectory of the server

installation. :he algorith3 of directory resolution is the followingA&.  F(%E!(%D environ3ent variable.

2. %ootDirectory para3eter in the ,ire"ird.con, file.

%. :he directory where server binary is located.

When 3bedded Server is used fro3 Java and no F(%E!(%D environ3ent variable is specified@ ittries to find ,ire"ird.con, in the directory where application binary is located. /n our caseapplication binary is JL1 and therefore 3bedded Server tries to find its configuration file in the"in: directory of the J+( or J9 installation. Sa3e happens to the last ite3 of the list. /n 3ostcases this is not desired behavior.

:herefore@ if the application uses character encodings@ ;+Fs or wants to fine4tune server behaviorthrough the configuration file@ the F(%E!(%D environ3ent variable 3ust be specified and point tothe installation directory of the 3bedded Server@ e.g. current wor8ing directory.

Suort for 4ultile JN0 libraries

;pto Jaybird 2. only one client library could be loaded in a single JL1. :hat could be either ane3bedded Firebird library ),"em"ed.dll7li","em"ed.so*@ or Firebird client library),"client.dll7li","client.so*. :his could lead to proble3s@ For ea3ple@ if e3bedded Firebirdwas used first@ the J+,C driver would access the database file directly instead of using the local /C

 protocol if only the path to the database was specified. /t was not possible to change this without

restarting the JL1.Since Jaybird 2.&@ Jaybird is able to correctly load arbitrary nu3ber of shared libraries thati3ple3ent the /SC -/ and forward the re=uests correctly depending on the type of the driver beingused.

8/18/2019 Jay bird

22/37

=sa&e and Referen!e anual

3vents

vents is one of the uni=ue features in the Firebird 9+,1S and allows asynchronous notificationof the applications about na3ed events that happen in the database. /nfor3ation on this feature canfound in the free /, ". docu3entation set as well as in :he Firebird ,oo8 by >elen ,orrie.

:he interfaces and classes for the event support can be found in or$.,ire"irdsql.event  pac8age@which includesA

●   Event#ana$er interface to register for the synchronous and asynchronous notification aboutthe events in the database

●  EventListener interface which has to be i3ple3ented by the application that wants to participate in the asynchronous notification

●

 Data"aseEvent interface which represents the ob

8/18/2019 Jay bird

23/37

• the SELECT references a single table

• all colu3ns not referenced in SELECT per3it N'LLs )otherwise (NSE%Ts will fail*

• the SELECT state3ent does not contain D(ST(NCT predicate@ aggregate functions@

8/18/2019 Jay bird

24/37

*C e.tensions

encoding.

2.  $etTransaction)arameters-  int isolationLevel

Get the :, para3eters for

the specified transactionisolation level.

2.  createTransaction)arameter!u,,er-

Create an e3pty transaction para3eter buffer.

2.  setTransaction)arameters-  int isolationLevel1 Transaction)arameter!u,,ertp"

Set :, para3eters for thespecified transaction isolationlevel. :he newly specified3apping is valid for the wholeconnection lifeti3e.

2.  setTransaction)arameters- Transaction)arameter!u,,ertp"

3eters are effective until thetransaction isolation ischanged.

Fire"irdData"ase#etaData

$et)rocedureSourceCode-Strin$

Get source code for thespecified stored procedurena3e.

$etTri$$erSourceCode-Strin$

Get source code for thespecified trigger na3e.

$etie*SourceCode-Strin$ Get source code for the

specified view na3e.Fire"irdStatement &.#   $et(nserted%o*sCount-

$et'pdated%o*sCount-$etDeleted%o*sCount-

tension that allows to get3ore precise infor3ationabout outco3e of so3estate3ent.

&.#   +asOpen%esultSet- Chec8 if this state3ent hasopen result set. Correctlywor8s only when auto4co33itis disabled. Chec8 3ethoddocu3entation for details.

&.#   $etCurrent%esultSet- Get current result set.,ehaviour of this 3ethod issi3ilar to the behavior of theStatement.$et%esultSet- @ecept that this 3ethod can becalled as 3uch as you li8e.

&.#   isalid- Chec8 if this state3ent is stillvalid. State3ent 3ight beinvalidated when connection isauto3atically recycled

 between transactions due toso3e irrecoverable error.

2.   $etLastEecution)lan- Get eecution plan for the last

8/18/2019 Jay bird

25/37

*C e.tensions

eecuted state3ent.

Fire"ird)reparedStatement

2.   $etEecution)lan- Get the eecution plan of this

 prepared state3ent.

2.   $etStatementType- Get the state3ent type of this prepared state3ent.

Fire"irdCalla"leStatement

&.#   setSelecta"le)rocedure-  "oolean selecta"le

1ar8 this callable state3ent asa call of the selectable

 procedure. ,y default callablestate3ent uses EXEC'TE)%OCED'%E SP5 state3ent toinvo8e stored procedures thatreturn single row of output

 para3eters or a result set. /nfor3er case it retrieves onlythe first row of the result set.

Fire"ird%esultSet 2.   $etEecution)lan- Get eecution plan for thisresult set.

Fire"ird!lo" &.#   detac+- 1ethod detaches a ,56,ob

8/18/2019 Jay bird

26/37

JDBC !onne!tion roerties

:he table below lists the properties for the connections that are obtained fro3 this data source.Co33only used para3eters have the corresponding getter and setter 3ethods@ the rest of the+atabase ara3eters ,loc8 para3eters can be set using setNonStandard)roperty  setter 3ethod.

)roperty 2etter 0etter escription

data"ase O O (deprecated ath to the database inthe for3at

+ost:portM6data"ase7

:his property is not specified in theJ+,C standard. ;se the the standarddefined serverName@ portNum"er anddata"aseName instead

serverName O O >ostna3e or / address of the Firebirdserver 

portNum"er O O ortnu3ber of the Firebird server  

data"aseName O O +atabase alias or full4path

type O O :ype of the driver to use. ossiblevalues areA

•   )'%E&AA or TK)E@ for type $J+,C driver

•   NAT(E or TK)E> for type 2

J+,C driver•   E#!EDDED for using e3bedded

version of the Firebird.

"lo"!u,,erSiWe O O SiEe of the buffer used to transfer,56, content. 1ai3u3 value is"$84&.

soc0et!u,,erSiWe O O SiEe of the soc8et buffer. Needed onso3e 5inu 3achines to fi

 perfor3ance degradation.

"u,,ersNum"er O O Nu3ber of cache buffers )in database pages* that will be allocated for theconnection. 1a8es sense forClassicServer only.

c+arSet O O Character set for the connection.Si3ilar to encodin$ property@ butaccepts Java na3es instead of Firebirdones.

encodin$ O O Character encoding for the connection.See Firebird docu3entation for 3oreinfor3ation.

useTranslation O O ath to the properties file containingcharacter translation 3ap.

8/18/2019 Jay bird

27/37

)roperty 2etter 0etter escription

pass*ord O O Corresponding password.

roleName O O SP5 role to use.

userName O O Na3e of the user that will be used bydefault.

useStream!lo"s O O ,oolean flag tells driver whetherstrea3 ,56,s should be created bythe driver@ by default false. Strea3,56,s allow see8 operation to becalled@ however due to a bug in gba8utility they are disabled by default.

useStandard'd, O O ,oolean flag tells driver to assu3e thatstandard ;+Fs are defined in thedatabase. :his etends the set offunctions available via escapedfunction calls. :his does not affectnon4escaped use of functions.

de,ault%esultSetolda"le

O O ,oolean flag tells driver to constructthe default result set to be holdable.:his prevents it fro3 closing in auto4co33it 3ode if another state3ent iseecuted over the sa3e connection.

tp"#appin$

O O :, 3apping for different transactionisolation 3odes.

de,ault(solation O O +efault transaction isolation level. -llnewly created connections will havethis isolation level. 6ne ofA

•  T%ANSACT(ON&%EAD&CO##(TTED

•  T%ANSACT(ON&%E)EATA!LE&%EAD

•   T%ANSACT(ON&SE%(AL(BA!LE 

de,aultTransaction(

solation

O O /nteger value fro3

java.sql.Connection  interfacecorresponding to the transactionisolation level specified in isolation 

 property.

nonStandard)roperty $etNonStandard)roperty-Str

in$

O

setNonStandard)roperty-S

trin$

setNonStandard)roperty-S

trin$1

Strin$

-llows to set any valid connection property that does not havecorresponding setter 3ethod. :wosetters are availableA

setNonStandard)roperty-Strin$  3ethod ta8es only one para3eter in

for3propertyNamepropertyalueMY @this allows setting non4standard

8/18/2019 Jay bird

28/37

)roperty 2etter 0etter escription

 para3eters using configuration files.

setNonStandard)roperty-Strin$1

Strin$ ta8es property na3e as first para3eter@ and its value as the second para3eter.

connectTimeout O O :he connect ti3eout in seconds. Forthe Java wire protocol detectsunreachable hosts@ for JN/ )native

 protocol* only defines a ti3eout duringthe op&accept phase after connectingto the server.

8/18/2019 Jay bird

29/37

JDBC Co4atibility

:he Jaybird driver is not officially J+,C4co3pliant as the certification procedure is too epensive.:he following lists so3e of the differences between J+,C specification and Jaybird

i3ple3entation. :his list is not ehaustive.

JDBC deviations and uni4le4ented features

:he following optional features and the 3ethods for their support are not i3ple3entedA

● java.sql.Array data type is not )yet* supported

● java.sql.!lo" does not i3ple3ent following 3ethodsA

 – position-!lo"1 lon$ and position-"yteM1 lon$ Firebird does not provideany server4side opti3iEation for these calls@ client application 3ust fetch co3plete,56, content fro3 the server to do pattern search.

 –  truncate-lon$ Firebird does not provide such functionality on the server side@application 3ust fetch old ,56, fro3 the server and pu3p old content into a newlycreated ,56,.

● java.sql.Connection

 –  $etCatalo$- and setCatalo$-Strin$  are not supported by Firebird server 

 –  $etType#ap- and setType#ap-#ap are not supported

● java.sql.%e, data type is not supported by Firebird server 

● java.sql.SQLData data type is not supported by Firebird server 

●

 java.sql.SQL(nput is not supported● java.sql.SQLOutput is not supported

● java.sql.SQLX#L is not supported

● java.sql.%o*(d is not supported

● java.sql.NClo" is not supported

● java.sql.Statement

 –  cancel- is i3ple3ented@ but not fully supported by Jaybird

● java.sql.Struct data type is not supported by server.

:he following 3ethods are i3ple3ented@ but deviate fro3 the specificationA

● java.sql.Statement 

 – $et:set#aFieldSiWe does nothing@ Firebird server does not support this feature.

 – $et:setQueryTimeout does nothing@ Firebird server does not support this feature.

●  java.sql.)reparedStatement 

 – setO"ject-int inde1 O"ject o"ject1 int type :arget SP5 type isdeter3ined fro3 the class of the passed ob

8/18/2019 Jay bird

30/37

 –  is%eadOnly- always returns false

 –  is9rita"le- always returns true

 –  isDe,initively9rita"le- always returns true

8/18/2019 Jay bird

31/37

Jaybird Se!ifi!s

Jaybird has so3e i3ple3entation4specific issues that should be considered during develop3ent.

Result setsJaybird behaves differently not only when different result set types are used but also whether theconnection is in auto4co33it 3ode or not.

•   %esultSet.TK)E&FO%9A%D&ONLK result sets when used in auto4co33it 3ode areco3pletely cached on the client before the eecution of the =uery is finished. :his leads tothe increased ti3e needed to eecute state3ent@ however the result set navigation happensal3ost instantly. When auto4co33it 3ode is switched off@ only part of the result setspecified by the fetch siEe is cached on the client.

•   %esultSet.TK)E&SC%OLL&(NSENS(T(E result sets are always cached on the client. :hereason is =uite si3ple the Firebird -/ does not provide scrollable cursor support@

navigation is possible only in one direction.

•   %esultSet.OLD&C'%SO%S&OE%&CO##(T holdability is supported in Jaybird only for resultsets of type %esultSet.TK)E&SC%OLL&(NSENS(T(E. For other result set types driver willthrow an eception.

=sin& >ava.s?l.ara4eteretaData %it# Callable State4ents

:his interface can be used only to obtain infor3ation about the /N para3eters. -lso it is not allowedto call the )reparedStatement.$et)arameter#etaData  3ethod before all of the 6;: para3etersare registered. 6therwise the corresponding 3ethod of Calla"leStatement  throws anSQLEception@ because the driver tries to prepare the procedure call with incorrect nu3ber of

 para3eters.

=sin& ResultSet.&etC#ara!terStrea4 %it# B89B fields

Jaybird J+,C driver always uses connection encoding when converting array of bytes into character strea3. :he ,56, S;,Q:H & fields allow setting the character encoding for the field. >oweverwhen the contents of the field is sent to the client@ it is not converted according to the character settranslation rules in Firebird@ but is sent as is. When such fields are accessed fro3 a Javaapplication via Jaybird and character set of the connection does not 3atch the character encoding ofthe field@ conversion errors 3ight happen. :herefore it is reco33ended to convert such fields in theapplication using the appropriate encoding.

8/18/2019 Jay bird

32/37

com.sun.ro*set.Cac+ed%o*Set(mpl *.

We advise you to either only access colu3ns by their inde or use an i3ple3entation whichcorrectly uses the colu3n label for colu3n loo8up )which is either the alias or the original colu3nna3e if no alias was defined*.

Jaybird 2.2.& introduced the connection property columnLa"elForName  for bac8wards co3patible behavior of %esultSet#etaDataG$etColumnName-int . Set property to true for bac8wardsco3patible behavior )$etColumnName- returns the colu3n label* don't set the property or set it to,alse for J+,C4co3pliant behavior )reco33ended*.

Suort for Firebird , BOO&EAN tye

Jaybird 2.2.$ introduces support for the Firebird % !OOLEAN type. - boolean field can also be setwith all nu3eric setters and the string setter )as i3plied by J+,C $.& appendi ,*.

For nu3eric types@ currently only  will set to ,alse and all other values will set to true. :his is

so3ething that 3ight change in the future. 6nly  for ,alse and  for true are guaranteed@ in thefuture we 3ight decide to throw a conversion eception for other valuesI

For string types we currently set true for true@ T@ K and  )case insensitive@ ignoringwhitespace*@ all other values will set ,alse this is for co3patibility with the current $et!oolean 

 behaviour of F!Strin$Field. :his is so3ething that 3ight change in the future. 6nly true and for true and ,alse and  for ,alse are guaranteed )case insensitive@ ignoringwhitespace*@ in the future we 3ight decide to throw a conversion eception for other valuesI

When using string or nu3eric setters for a boolean field we strongly recommend to only use theguaranteed values )@ @ @ @ true and ,alse*. ,etter yetA use the boolean setter instead.

8/18/2019 Jay bird

33/37

Conne!tion oolin& %it# Jaybird

-s described in /3portant changes to +atasources@ the Connection)oolDataSourcei3ple3entations in or$.,ire"irdsql.pool  contain so3e serious issues. :he connection pool

capability which depends on these classes will be re3oved in Jaybird %..:his change leaves only the Connection)oolDataSource  i3ple3entations inor$.,ire"irdsql.ds  )for use by application server connection pools*. :here are no plans toreintroduce a new standalone connection pooling capability. We probably will 3igrate so3e of thefeatures li8e state3ent pooling to the nor3al J+,C driver.

/f you re=uire standalone connection pooling@ or use an application server which has no built4inconnectionpool@ please consider using a third4party connection pool li8e c%p@ +,C or >i8ariC.

Des!rition of dere!ated rg"'rerds*+",+ !lasses

W&'#"#2: -his section provides information on deprecated classes,

See /3portant changes to +atasources

Connection pooling provides effective way to handle physical database connections. /t is believedthat establishing new connection to the database ta8es so3e noticeable a3ount or ti3e and in orderto speed things up one has to reuse connections as 3uch as possible. While this is true for so3esoftware and for old versions of Firebird database engine@ establishing connection is hardlynoticeable with Firebird &..% and Firebird &.#. So why is connection pooling neededR

:here are few reasons for this. ach good connection pool provides a possibility to li3it nu3ber of physical connections established with the database server. :his is an effective 3easure to localiEeconnection lea8s. -ny application cannot open 3ore physical connections to the database than

allowed by connection pool. Good pools also provide so3e hints where connection lea8 occurred.-nother big advantage of connection pool is that it beco3es a central place where connections areobtained@ thus si3plifying syste3 configuration. >owever@ 3ain advantage of good connection poolco3es fro3 the fact that in addition to connection pooling@ it can pool also prepared state3ent.:ests eecuted using -S%- bench3ar8 suite show that prepared state3ent pooling 3ight increasespeed of the application by &K 8eeping source code clean and understandable.

=sa&e s!enario

When so3e state3ent is used 3ore than one ti3e@ it 3a8es sense to use prepared state3ent. /t will be co3piled by the server only once@ but reused 3any ti3es. /t provides significant speedup whenso3e state3ent is eecuted in a loop. ,ut what if so3e prepared state3ent will be used duringlifeti3e of so3e ob

8/18/2019 Jay bird

34/37

E.ample % -ypical *C code with statement pooling

>=

@I?PZ>=@I?

P

...Connection connection dataSource.$etConnection-[try 4

  )reparedStatement ps connection.prepareStatement-  SELECT V F%O# test&ta"le 9E%E id HY[  try 4  ps.set(nt-1 id[  %esultSet rs ps.eecuteQuery-[  *+ile -rs.net- 4  :: do somet+in$ +ere  8  8 ,inally 4  ps.close-[  88 ,inally 4  connection.close-[8

...5ines &4&0 show typical code when prepared state3ent pooling is used. -pplication obtainsJ+,C connection fro3 the data source )instance of java.sql.DataSource  interface*@ preparesso3e SP5 state3ent as if it is used for the first ti3e@ sets para3eters@ and eecutes the =uery. 5ines&2 and ensure that state3ent and connection will be released under any circu3stances. Wheredo we benefit fro3 the state3ent poolingR Call to prepare a state3ent in lines $4# isintercepted by the pool@ which chec8s if there's a free prepared state3ent for the specified SP5=uery. /f no such state3ent is found it prepares a new one. /n line &% prepared state3ent is notclosed@ but returned to the pool@ where it waits for the net call. Sa3e happens to the connectionob

8/18/2019 Jay bird

35/37

escription of some connection pool classes%

connections are physically opened in $etConnection- 3ethod and physically closed in their close- 3ethod.

F!9rappin$DataSource /3ple3entation of java.sql.DataSource  interface thatuses F!Connection)oolDataSource  to allocateconnections. :his class defines so3e additional propertiesthat affect allocated connections. Can be used as JN+/ob

8/18/2019 Jay bird

36/37

ool roerties

:his group of properties are specific to the Jaybird i3ple3entation of the connection poolingclasses.

)roperty 2etter 0etter escription"loc0in$Timeout O O 1ai3u3 ti3e in 3illiseconds during

which application can be bloc8edwaiting for a connection fro3 the

 pool. /f no free connection can beobtained@ eception is thrown.

retry(nterval O O eriod in which pool will try to obtainnew connection while bloc8ing theapplication.

poolin$ O O -llows to switch connection poolingoff.

statement)oolin$ O O -llows to switch state3ent poolingoff.

pin$Statement O O State3ent that will be used to pingJ+,C connection@ in other words@ tochec8 if it is still alive. :his state3ent3ust always succeed.

pin$(nterval O O :i3e during which connection is believed to be valid in any case. ool

pings connection before giving it tothe application only if 3ore thanspecified a3ount of ti3e passed sincelast ping.

Runti4e ool roerties

:his group contains read4only properties that provide infor3ation about the state of the pool.

)roperty 2etter 0etter escription

,reeSiWe O 4 :ells how 3any free connections are

in the pool. Lalue is between andtotalSiWe.

*or0in$SiWe O 4 :ells how 3any connections wereta8en fro3 the pool and are currentlyused in the application.

totalSiWe O 4 :otal siEe of open connection. -t the pool creation @ after obtaining firstconnection between min)oolSiWe and ma)oolSiWe.

connectionCount O 4  De&recated . Sa3e as ,reeSiWe.

8/18/2019 Jay bird

37/37

or&.firebirds?l.ool.FB"rain&DataSour!e

:his class is a wrapper for F!Connection)oolDataSource  converting interface fro3java.sql.Connection)oolDataSource  to java.sql.DataSource . /t defines sa3e properties asF!Connection)oolDataSource  does.

Runti4e ob>e!t allo!ation and deallo!ation #ints

ool i3ple3entation shipped with Jaybird can provide hints for the application where theconnection was obtained fro3 the pool@ when it was released bac8 to the pool@ when the state3entwas prepared. Such infor3ation is written into the log when appropriate syste3 properties are set totrue.

8ist of roerties

)roperty name escription

F!Lo$@j nables logging inside driver. :his is the essential property@ if it isnot present or set to ,alse@ no debug infor3ation is available.

When it is set to true@ pool auto3atically prints the followinginfor3ationA

• When physical connection is added to the pool DE!'/

• When a 3ai3u3 pool capacity is reached DE!'/

• When connection is obtained fro3 pool DE!'/

• When connection is released bac8 to pool DE!'/

• Whether pool supports open state3ents across transaction boundaries (NFO

F!)oolS+o*Trace nables logging of the thread stac8 trace when debugging is enabledandA

• Connection is allocated fro3 the pool DE!'/

• :hread is bloc8ed while waiting for a free connection 9A%N

F!)oolDe"u$StmtCac+e When state3ent caching is used and debugging is enabled@ followinginfor3ation is loggedA

• When a state3ent is prepared (NFO

• When state3ent cache is cleaned (NFO

• When state3ent is obtained fro3 or returned bac8 to pool (NFO