From 61a39d23f74dbdfc6f95970e9251e006c703e6c4 Mon Sep 17 00:00:00 2001
From: Mark Rotteveel
Date: Sat, 6 Apr 2019 10:04:21 +0200
Subject: [PATCH] Update FAQ from master
---
src/etc/faq.html | 287 ++++++++++++++++++++++++++++++-----------------
1 file changed, 183 insertions(+), 104 deletions(-)
diff --git a/src/etc/faq.html b/src/etc/faq.html
index c7fb6b23ac..6aadc9acf3 100644
--- a/src/etc/faq.html
+++ b/src/etc/faq.html
@@ -1,49 +1,82 @@
-
+
-
-
-
+
+
+
Jaybird 3.0 is available from Maven central: Groupid: Jaybird Frequently Asked Questions
NONE
work?
@@ -119,36 +153,36 @@
1.1.1.1 Jaybird 3.0
org.firebirdsql.jdbc
,
Artifactid: jaybird-jdkXX
(where XX
is 17
or 18
)
-Version: 3.0.3
3.0.5
For example, for Java 8:
-<dependency>
- <groupId>org.firebirdsql.jdbc</groupId>
- <artifactId>jaybird-jdk18</artifactId>
- <version>3.0.3</version>
-</dependency>
<dependency>
+ <groupId>org.firebirdsql.jdbc</groupId>
+ <artifactId>jaybird-jdk18</artifactId>
+ <version>3.0.5</version>
+</dependency>
If your application is deployed to a Java EE application server, you will need to exclude the javax.resource:connector-api
dependency, and add it as a provided dependency:
<dependency>
- <groupId>org.firebirdsql.jdbc</groupId>
- <artifactId>jaybird-jdk18</artifactId>
- <version>3.0.3</version>
- <exclusions>
- <exclusion>
- <groupId>javax.resource</groupId>
- <artifactId>connector-api</artifactId>
- </exclusion>
- </exclusions>
-</dependency>
-<dependency>
- <groupId>javax.resource</groupId>
- <artifactId>connector-api</artifactId>
- <version>1.5</version>
- <scope>provided</scope>
-</dependency>
<dependency>
+ <groupId>org.firebirdsql.jdbc</groupId>
+ <artifactId>jaybird-jdk18</artifactId>
+ <version>3.0.5</version>
+ <exclusions>
+ <exclusion>
+ <groupId>javax.resource</groupId>
+ <artifactId>connector-api</artifactId>
+ </exclusion>
+ </exclusions>
+</dependency>
+<dependency>
+ <groupId>javax.resource</groupId>
+ <artifactId>connector-api</artifactId>
+ <version>1.5</version>
+ <scope>provided</scope>
+</dependency>
If you want to use Type 2 support (native, local or embedded), you need to explicitly include JNA as a dependency:
-<dependency>
- <groupId>net.java.dev.jna</groupId>
- <artifactId>jna</artifactId>
-</dependency>
The version can be excluded, as it is already specified in the Jaybird pom.
Jaybird 2.2 is available on maven, with a separate artifact for each supported Java version.
Groupid: org.firebirdsql.jdbc
,
Artifactid: jaybird-jdkXX
(where XX
is 16
, 17
or 18
)
-Version: 2.2.14
2.2.15
For example:
-<dependency>
- <groupId>org.firebirdsql.jdbc</groupId>
- <artifactId>jaybird-jdk18</artifactId>
- <version>2.2.14</version>
-</dependency>
<dependency>
+ <groupId>org.firebirdsql.jdbc</groupId>
+ <artifactId>jaybird-jdk18</artifactId>
+ <version>2.2.15</version>
+</dependency>
When deploying to a JavaEE environment, exclude the javax.resource connector-api
dependency as this will be provided by the application server.
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 an 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 the LGPL section for dynamic linking is applicable in this case.
+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 an 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 the LGPL section for dynamic linking is applicable in this case.
Current releases of Jaybird do not explicitly specify an LGPL version. This means that you can choose which version applies. Future versions of Jaybird may specify an explicit version, or be released under a different license.
@@ -190,7 +224,7 @@Jaybird 3.0 supports Java 7 and 8 and has rudimentary support for Java 9.
+Jaybird 3.0 supports Java 7 and 8 and has basic support for Java 9.
Jaybird 2.2 supports Java 6, 7 and 8.
Jaybird 2.2.4 added basic support for Java 8 (JDBC 4.2), although not all JDBC 4.2 features are supported or fully implemented.
Jaybird 2.2.7 is the last version to support Java 5, support has been dropped with Jaybird 2.2.8.
@@ -247,7 +281,7 @@The developers follow the firebird-java@yahoogroups.com list. Join the list and post information about suspected bugs. List members may be able to help out to determine if it is an actual bug, provide a workaround and get you going again, whereas bug fixes might take awhile.
-You can report bugs in the Firebird bug tracker, project "Java Client (Jaybird)"
+You can report bugs in the Firebird bug tracker, project “Java Client (Jaybird)”
When reporting bugs, please provide a minimal, but complete reproduction, including databases and sourcecode to reproduce the problem. Patches to fix bugs are also appreciated. Make sure the patch is against a recent master version of the code. You can also fork the jaybird repository and create pull requests.
NONE
work?The Firebird character set NONE
is a special case, it essentially means "no character set". You can store anything in it, but conversions to or from this character set are not defined.
The Firebird character set NONE
is a special case, it essentially means “no character set”. You can store anything in it, but conversions to or from this character set are not defined.
Using character set NONE
can result in incorrect character set handling when the database is used from different locales.
When used as a connection character set, Jaybird handles NONE
as follows:
When no character set has been specified explicitly, Jaybird 2.2 and earlier, and Jaybird 3.0.2 and higher default to connection character set NONE
. See How does character set NONE
work? for details on character set NONE
.
Jaybird 3.0.0 and 3.0.1, however, will reject the connection, see How can I solve the error "Connection rejected: No connection character set specified".
+Jaybird 3.0.0 and 3.0.1, however, will reject the connection, see How can I solve the error “Connection rejected: No connection character set specified”.
In Jaybird 3 it is possible to override the default connection character set by specifying system property org.firebirdsql.jdbc.defaultConnectionEncoding
with a valid Firebird character set name.
Jaybird 3.0.2 introduces the system property org.firebirdsql.jdbc.requireConnectionEncoding
, which - when set to true
- will reject connections without a character set (which was the default behavior in Jaybird 3.0.0 and 3.0.1).
If no character set has been set, Jaybird 3.0 will reject the connection with an SQLNonTransientConnectionException
with message "Connection rejected: No connection character set specified (property lc_ctype, encoding, charSet or localEncoding). Please specify a connection character set (eg property charSet=utf-8) or consult the Jaybird documentation for more information."
If no character set has been set, Jaybird 3.0 will reject the connection with an SQLNonTransientConnectionException
with message “Connection rejected: No connection character set specified (property lc_ctype, encoding, charSet or localEncoding). Please specify a connection character set (eg property charSet=utf-8) or consult the Jaybird documentation for more information.”
In Jaybird 3.0.0 and 3.0.1 this error will be thrown if the character set has not been set explicitly. In Jaybird 3.0.2 and higher this error will only be thrown if system property org.firebirdsql.jdbc.requireConnectionEncoding
has been set to true
.
To address this error, you can set the default connection character set using one of the following options:
Firebird 3.0.2 adds support for "TCP Loopback Fast Path" (SIO_LOOPBACK_FAST_PATH
socket option). This is available in Windows 8 / Windows Server 2012 and higher. This feature enables performance optimizations when connecting through localhost (127.0.01 / ::1). It requires support on both client and server side.
Java support for "TCP Loopback Fast Path" was introduced in Java 8 update 60, it can be enabled by specifying the system property jdk.net.useFastTcpLoopback
with value true
(eg specify -Djdk.net.useFastTcpLoopback=true
in your Java commandline).
Unfortunately, Java only has an 'all-or-nothing' support for the "TCP Loopback Fast Path", so Jaybird cannot enable this for you: you must specify this property on JVM startup. On the other hand, this has the benefit that this works for all Jaybird versions, as long as you use Java 8 update 60 or higher (and Firebird 3.0.2 or higher).
+Firebird 3.0.2 adds support for “TCP Loopback Fast Path” (SIO_LOOPBACK_FAST_PATH
socket option). This is available in Windows 8 / Windows Server 2012 and higher. This feature enables performance optimizations when connecting through localhost (127.0.01 / ::1). It requires support on both client and server side.
Java support for “TCP Loopback Fast Path” was introduced in Java 8 update 60, it can be enabled by specifying the system property jdk.net.useFastTcpLoopback
with value true
(eg specify -Djdk.net.useFastTcpLoopback=true
in your Java commandline).
Unfortunately, Java only has an ‘all-or-nothing’ support for the “TCP Loopback Fast Path”, so Jaybird cannot enable this for you: you must specify this property on JVM startup. On the other hand, this has the benefit that this works for all Jaybird versions, as long as you use Java 8 update 60 or higher (and Firebird 3.0.2 or higher).
With Jaybird 3.0.x connecting to Firebird 3 or higher, this usually means that the setting WireCrypt
is set to its (default) value of Required
.
Relax this setting (in firebird.conf
) to WireCrypt = Enabled
.
With Jaybird 3.0.0 - 3.0.3 connecting to Firebird 3 or higher, this usually means that the setting WireCrypt
is set to its (default) value of Required
.
Upgrade to Jaybird 3.0.4 or higher, or relax this setting (in firebird.conf
) to WireCrypt = Enabled
.
See also Jaybird Wiki - Jaybird and Firebird 3
-With Jaybird 4, this error means that you have requested a connection with a mismatch in encryption settings. For example, you specified connection property wireCrypt=required
while Firebird is set to WireCrypt = Disabled
(or vice versa).
With Jaybird 3.0.4 or higher, or Jaybird 4, this error means that you have requested a connection with a mismatch in encryption settings. For example, you specified connection property wireCrypt=required
while Firebird is set to WireCrypt = Disabled
(or vice versa).
In general this error means that Jaybird requested a connection with properties not supported by Firebird. It can have other causes than described below.
+With Jaybird 3 and higher connecting to Firebird 3 or higher, leaving user name or password null will lead to Jaybird not trying any authentication plugin, and as a result, Firebird will reject the connection.
+With Firebird 2.5 and earlier, or Jaybird 2.2, this situation will normally yield error “Your user name and password are not defined. Ask your database administrator to set up a Firebird login.”.
+With Jaybird 2.2.x connecting to Firebird 3 or higher, this usually means that the setting WireCrypt
is set to its (default) value of Required
.
Relax this setting (in firebird.conf
) to WireCrypt = Enabled
.
See also Jaybird Wiki - Jaybird and Firebird 3
-Make sure you check the other settings mentioned in that article, otherwise you'll get the next error.
+Make sure you check the other settings mentioned in that article, otherwise you’ll get the next error.
+with Jaybird 2.2.x connecting to Firebird 3 or higher, this means that the setting AuthServer
does not include the Legacy_Auth
plugin.
Enable Legacy_Auth
(in firebird.conf
) by adding this value to the property AuthServer
, for example: AuthServer = Srp, Legacy_Auth
.
With Jaybird 4 and higher this can also mean that none of the default authentication plugins or those specified using connection property authPlugins
, are listed in the AuthServer
setting. Either revise the Firebird configuration, or explicitly configure connection property authPlugins
with authentication plugins that are configured in Firebird.
You also need to make sure your user is created with the legacy user manager, see Jaybird Wiki - Jaybird and Firebird 3 for details.
If the exception cause is java.security.InvalidKeyException: Illegal key size or default parameters, this means that your Java install applies a security policy that does not allow ARCFOUR with a 160 bit encryption key.
+If wireCrypt=ENABLED
(the default), this is just logged as a warning. The connection will succeed, but it does mean that the connection will not be encrypted. If wireCrypt=REQUIRED
, this is thrown as an exception, and the connection will fail.
This could indicate that your Java version applies the limited strength Cryptographic Jurisdiction Policy (this was the default in Java 8 Update 152 and earlier), or has been explicitly configured to apply the limited policy, or has a custom security policy to restrict the cryptographic key size.
+Solutions and workarounds:
+WireCrypt = Disabled
in firebird.conf
wireCrypt=DISABLED
in the connection propertiesBe aware that the first two options may have legal implications depending on the local law in your country regarding cryptography.
+Jaybird 3 follows the JDBC 4.3 specification with some features and methods not implemented as they are not supported by Firebird.
Implemented features:
TransactionManager
and JCA deployment support) as well as when used via javax.sql.XADataSource
implementation.ObjectFactory
implementation for use in environments with JNDI but no TransactionManager
.setObject(index,object,type)
This method is implemented but behaves as setObject(index,object)
setObject(index,object,type,scale)
This method is implemented but behaves as setObject(index,object)
java.sql.CallableStatement
+getBigDecimal(index,scale)
This method is implemented but behaves as getBigDecimal(index)
. The method is deprecated, and we suggest to use getBigDecimal(index)
and adjust the scale of the returned BigDecimal
using BigDecimal.setScale(newScale,roundingMode)
java.sql.ResultSetMetaData
isReadOnly(i)
always returns falseisWritable(i)
always returns trueisDefinitivelyWritable(i)
always returns truejava.sql.ResultSet
+getBigDecimal(index,scale)
This method is implemented but behaves as getBigDecimal(index)
. The method is deprecated, and we suggest to use getBigDecimal(index)
and adjust the scale of the returned BigDecimal
using BigDecimal.setScale(newScale,roundingMode)
The minimal module.xml
to use Jaybird 3 under Wildfly is:
<?xml version="1.0" encoding="UTF-8"?>
-<module xmlns="urn:jboss:module:1.0" name="org.firebirdsql">
- <resources>
- <resource-root path="jaybird-3.0.x.jar"/>
- </resources>
- <dependencies>
- <module name="javax.api"/>
- <module name="javax.transaction.api"/>
- <module name="javax.resource.api"/>
- </dependencies>
-</module>
<?xml version="1.0" encoding="UTF-8"?>
+<module xmlns="urn:jboss:module:1.0" name="org.firebirdsql">
+ <resources>
+ <resource-root path="jaybird-3.0.x.jar"/>
+ </resources>
+ <dependencies>
+ <module name="javax.api"/>
+ <module name="javax.transaction.api"/>
+ <module name="javax.resource.api"/>
+ </dependencies>
+</module>
With Jaybird 3.0.4 and higher for Java 7 (but not Java 8!) in Wildfly (or JBoss), you will need to add the module javax.xml.bind.api
to your module:
<?xml version="1.0" encoding="UTF-8"?>
+<module xmlns="urn:jboss:module:1.0" name="org.firebirdsql">
+ <resources>
+ <resource-root path="jaybird-3.0.x.jar"/>
+ </resources>
+ <dependencies>
+ <module name="javax.api"/>
+ <module name="javax.transaction.api"/>
+ <module name="javax.resource.api"/>
+ <module name="javax.xml.bind.api"/> <!-- Add this -->
+ </dependencies>
+</module>
Alternatively, use Jaybird for Java 8 (or higher).