Installing the JDBC driver
In JBoss AS 5 and 6, you used to install the JDBC driver into the common/lib folder of your server distribution. In the new modular server architecture, you have more than one option to install your JDBC driver. The first and recommended approach consists of installing the driver as a module.
In the section named Installing the driver as a deployment unit, we will account for another approach, which is usually a bit faster. However, it has a few limitations.
As we have seen in the previous chapter, the procedure for installing a new module requires copying the .jar libraries in the appropriate modules path and adding a module.xml file, which declares the module and its dependencies.
The actual path for the module will be: JBOSS_HOME/modules/<module>/main The main folder is where all key module components are installed. So, in our example, we will add the following units: JBOSS_HOME/modules/com/mysql/main/mysql-connector-java-5.1.17-bin.jar JBOSS_HOME/modules/com/mysql/main/module.xml Here’s an image of the module tree:
The JDBC driver used in this example, also known as Connector/J can freely be downloaded from the MySQL site: (http://dev.mysql.com/downloads/connector/j/). The module.xml contains the actual module definition. The most interesting part of it is the module name (com.mysql), which corresponds to the module attribute defined in the your datasource.
Next, you need to state the path to the JDBC driver resource and finally the module dependencies.
<module xmlns=”urn:jboss:module:1.0″ name=”com.mysql”>
Adding a local datasource
Once the JDBC driver is installed, you need to configure the datasource in the application server. In JBoss AS 7, you can configure two kind of datasources, local datasources and xa-datasources .
A local datasource does not support two phase commit using a java.sql.Driver. On the other hand, an xa-datasource supports two phase commit using a javax.sql.XADataSource.
Adding a datasource definition can be completed in several ways: you can just add the datasource definition within the server configuration file, or you can use the management interfaces that will accurately do the work for you.
Showing all possible approaches in this section would maybe add too much information at once, so we will let you digest at first the most intuitive approach, that is cutting and pasting the datasource definition into your server configuration file. In the Chapter 7, Managing the Application Server, which is about server management, we will show the other available options in more detail. So, here’s a sample MySQL datasource configuration:
<datasource jndi-name=”java:/MySqlDS” pool-name=”MySqlDS_Pool” enabled=”true”
jta=”true” use-java-context=”true” use-ccm=”true”>
<driver name=”mysql” module=”com.mysql”/>
As you can see, the new configuration file borrows the same XML schema definition from the earlier -*.ds.xml file, so it should not be difficult to migrate to the new configuration. Basically, you would define the connection path to the database using the connection-url and the JDBC driver class with the driver section.
Since JBoss AS 7.1.0, it’s mandatory that the datasource is bound into the java:/ or java:jboss/ JNDI namespace. The pool section can be used to define the JDBC Connection pool properties, leaving in this case to the default values. Then the security section lets you configure the connection credentials.
The statement section as well is added just as place holder for statement caching options.
The optional timeout section contains a set elements, such as the query-timeout, which is a static configuration of the maximum of seconds before a query times out. Also the included idle-timeout-minutes element indicates the maximum time a connection may be idle before being closed. Setting to 0 disables it. Default is 15 minutes.
Configuring the connection pool
One key aspect of the datasource configuration is the pool section. Strictly speaking, in order to use connection pooling, no configuration is required, because without any configuration JBoss AS will choose some default settings. However, if you want to customize how pooling is done, such as to control the size of the pools and which types of connections are pooled, you would be better learning about its available attributes.
Here’s an example of pool configuration, which can be added to your datasource configuration:
The attributes included in the pool configuration are actually borrowed from earlier releases, so we include them here for your reference:
Configuring the statement cache
For each connection in a connection pool in your system, JBoss AS Server is able to create a statement cache. When a prepared statement or callable statement is used on a connection, JBoss AS caches the statement so that it can be reused. In order to activate the statement cache, you have to specify a value of prepared-statement-cache-size greater than 0:
Notice, we have also included the track-statements to true in the statement section, which enable automatic closing of statements and ResultSets. This is important if you want to use prepared statement caching and/or don’t want to leak cursors in your database.
The last element, share-prepared-statements , can be used only with prepared statement cache enabled and determine whether the two requests in the same transaction should return the same statement (default false).
Adding an xa-datasource
Adding an xa-datasource requires some tweaks in the datasource configuration. As a matter of fact, the connection information is now acquired as xa-datasource properties. Also the xa-datasource class needs to be specified in the driver section.
In the following code, we are adding the equivalent configuration for our MySQL JDBC driver, which now is used to set up an xa-datasource:
<xa-datasource jndi-name=”java:/XAMySqlDS” pool-name=”MySqlDS_Pool” enabled=”true” use-java-context=”true” use-ccm=”true”>
<driver name=”mysql-xa” module=”com.mysql”>
A shortcut for installing a datasource
As we said at the beginning of the book, with the new release of the application server, every library is a module. Thus simply deploying the JDBC driver to the application server will trigger its installation. When using this option, we will just copy the mysql-connector-java-5.1.17-bin.jar driver into the JBOSS_HOME/standalone/deployments folder of your installation as shown in the following image:
When using this option, we will just copy the mysql-connector-java-5.1.17-bin.jar driver into the JBOSS_HOME/standalone/deployments folder of your installation as shown in the following image:
Once deployed, you need to add the datasource configuration to your server. You can do it in various ways. The most intuitive approach is pasting the datasource definition into the configuration file:
<datasource jndi-name=”java:/MySqlDS” pool-name=”MySqlDS_Pool”
enabled=”true” jta=”true” use-java-context=”true” use-ccm=”true”>
Alternatively, you can use the new Command Line Interface or the Web administration console to achieve the same result. Chapter 7, Managing the Application Server, details some practical examples of adding datasources using the management interfaces.
What about domain deployment?
In this chapter, we are discussing about the configuration of standalone servers and, as we said, the services configuration can be applied also to domain servers. Domain servers, however, don’t have a specified folder which is scanned for deployment, rather the management interfaces are used to inject resources in the domain. Configuring a JBoss AS Domain, will detail all the steps to deploy a module when using a domain server.