Configuring JBoss Datasource for Firebird DB

Accessing a relational database system from Java is a basic step required for many applications. The JEE architecture defines a standard for gaining this access, calls Java Connector Architecture (JCA). This article is a short HOWTO of configuring JCA-compliant datasource to a Firebird 2.x RDBMs using JBoss AS 5.1.0 as example. This tutorial is based on a Windows installation, but can be easily ported to Linux, or other OS.

For the configuration of the datasource two steps are required:

• Deployment of the Firebird RAR resource adapter (jaybird-*.rar)
• Creation of the firebird-ds.xml configuration

RAR Resource Adapter

The RAR Resource Adapter is a version of RDBMs drivers packaged in a special way, defined by the JCA specifcation. The
latest versions of Type 4 JCA-JDBC Firebird Driver (JayBird) can be downloaded from the IBPhoenix site. Inside of the downloaded archive you will find jaybird-*.rar (The version used during the creation of this tutorial was jaybird-2.1.6.rar). Since deployment in JBoss AS is performed by simple file copy, make sure to put the RAR-adapter-file into the deployment location of the application server. (e.G. ${JBOSS_ROOT}\server\default\deploy\).

After deployment, you can check the status of the resource adapter, by looking on the Administration Console of the JBoss (by default accessing the server URL http://localhost:8080/admin-console/ if run locally).

Datasource Description

After a successful deployment of the Resource RAR, the configuration of the datasource has to be created. The Firebird datasource configuration is supplied in a file, located in the default deployment location. JBoss AS auto-deplyoer will automatically look for the *-ds.xml files, so we name it e.G. firebird-ds.xml.

The following datasource configuration defines a local transactional datasource. You just need to replace placeholders USERNAME, PASSWORD and path to your database-file (In the used installation the file was located in: c:\databses\tesdb.fdb)

<?xml version="1.0" encoding="UTF-8"?>

  <!-- ==================================================================== -->
  <!-- New ConnectionManager setup for firebird dbs using jca-jdbc xa driver-->
  <!-- Build jmx-api (build/build.sh all) and view for config documentation -->
  <!-- ==================================================================== -->

<connection-factories>
	<local-tx-datasource>
		<jndi-name>DataSourceFirebirdDS</jndi-name>
		<connection-url>jdbc:firebirdsql:localhost/3050:c:${/}databses${/}tesdb.fdb</connection-url>
		<driver-class>org.firebirdsql.jdbc.FBDriver</driver-class>
		<transaction-isolation>TRANSACTION_REPEATABLE_READ</transaction-isolation>
		<connection-property name="lc_ctype" type="java.lang.String">ISO8859_1</connection-property>
		<connection-property name="maxStatements">10</connection-property>
		<user-name>USERNAME</user-name>
		<password>PASSWORD</password>
		<min-pool-size>0</min-pool-size>
		<max-pool-size>10</max-pool-size>

		<blocking-timeout-millis>5000</blocking-timeout-millis>

		<idle-timeout-minutes>15</idle-timeout-minutes>
		<check-valid-connection-sql>SELECT CAST(1 as INTEGER) FROM rdb$database</check-valid-connection-sql>
		<track-statements>false</track-statements>
		<prepared-statement-cache-size>0</prepared-statement-cache-size>
		<metadata>
			<type-mapping>Firebird</type-mapping>
		</metadata>
	</local-tx-datasource>
</connection-factories>

Usage

The datasource in the example above is registered in the java JNDI namespace and is called DataSourceFirebirdDS. In the source code, this resource should be accessible via java:/DataSourceFirebirdDS. Here is the example using Dependency Injection (DI):

@Ressource(mappedName = "java:/DataSourceFirebirdDS")
private DataSource firebirdDataSource;

In order to use the datasource in a JPA, the persistence unit has to be configured. For example, for using Hibernate, the following persistence unit can be configured.

...
<persistence-unit name="testunit">
	<jta-data-source>java:/DataSourceFirebirdDS</jta-data-source>
	<provider>org.hibernate.ejb.HibernatePersistence</provider>
	...
	<properties>
		<property name="hibernate.dialect" value="org.hibernate.dialect.FirebirdDialect"/>
		<property name="hibernate.show_sql" value="true" />
		...
	</properties>
</persistence-unit>
...

Then in the DAO for manipulation of Persistent Entities, the Persistence Context can be injected by:

@Stateless
public class TestDAOBean implements TestDAO {

	@PersistenceContext(unitName = "testunit")
	private EntityManager manager;

	...
}

Have fun and please provide some feedback.