Numerical port offsets
Chapter 6. Datasource Management
6.1. Introduction
6.1.1. About JDBC
The JDBC API is the standard that defines how databases are accessed by Java applications. An application configures a datasource that references a JDBC driver. Application code can then be written against the driver, rather than the database. The driver converts the code to the database language.
This means that if the correct driver is installed, an application can be used with any supported database.
The JDBC 4.0 specification is defined here: http://jcp.org/en/jsr/detail?id=221.
To get started with JDBC and datasources, refer to the JDBC Driver section of the Administration and Configuration Guide for JBoss Enterprise Application Platform 6.
Report a bug
6.1.2. JBoss Enterprise Application Platform 6 Supported Databases
The list of JDBC compliant databases supported by JBoss Enterprise Application Platform 6 is available here: http://www.redhat.com/resourcelibrary/articles/jboss-enterprise-application-platform-supported-configurations.
Report a bug
6.1.3. Types of Datasources
The two general types of resources are referred to as datasources and XA datasources.
Non-XA datasources are used for applications which do not use transactions, or applications which use transactions with a single database.
XA datasources are used by applications whose transactions are distributed across multiple databases.
XA datasources introduce additional overhead.
You specify the type of your datasource when you create it in the Management Console or Management CLI.
Report a bug
6.1.4 . The Example Datasource
JBoss Enterprise Application Platform 6 includes a H2 database. It is a lightweight, relational database management system that provides developers with the ability to quickly build applications, and is the example datasource for the platform.
Warning
However, it should not be used in a production environment. It is a very small, self-contained datasource that supports all of the standards needed for testing and building applications, but is not robust or scalable enough for production use.
For a list of supported and certified datasources, refer here: Section 6.1.2, “JBoss Enterprise Application Platform 6 Supported Databases”.
Report a bug
6.1.5. Deployment of -ds.xml files
In JBoss Enterprise Application Platform 6, datasources are defined as a resource of the server subsystem. In previous versions, a *-ds.xml datasource configuration file was required in the deployment directory of the server configuration. *-ds.xml files can still be deployed in JBoss Enterprise Application Platform 6, following the schema available here:
http://docs.jboss.org/ironjacamar/schema/datasources_1_1.xsd.
Warning
This feature should only be used for development. It is not recommended for production environments, because it is not supported by the JBoss administrative and management tools.
Important
It is mandatory to use a reference to an already deployed / defined <driver> entry when deploying
* -ds.xm l files.
Report a bug
6.2. JDBC Drivers
6.2.1. Install a JDBC Driver with the Management Console
Summary
Before your application can connect to a JDBC datasource, your datasource vendor's JDBC drivers need to be installed in a location where the JBoss Enterprise Application Platform can use them. JBoss Enterprise Application Server allows you to deploy these drivers just like any other deployment. This means that you can deploy them across multiple servers in a server group, if you use a managed domain.
Note
The preferred installation method for JDBC drivers is to install them as a core module. To install the JDBC driver as a core module, refer here: Section 6.2.2, “Install a JDBC Driver as a Core Module”.
Prerequisites
Before performing this task, you need to meet the following prerequisites:
Download the JDBC driver from your database vendor.
Procedure 6.1. Task
1. Access the Management Console.
Section 3.2.2, “Log in to the Management Console”
2. Deploy the JAR file to your server or server group.
If you use a managed domain, deploy the JAR file to a server group. Otherwise, deploy it to your server. See Section 8.2.2, “Deploy an Application Using the Management Console”.
Result:
The JDBC driver is deployed, and is available for your applications to use.
Report a bug
6.2.2. Install a JDBC Driver as a Core Module
Prerequisites
Before performing this task, you need to meet the following prerequisites:
Download the JDBC driver from your database vendor. JDBC driver download locations are listed here: Section 6.2.3, “JDBC Driver Download Locations”.
Extract the archive.
Procedure 6.2. Task
1. Create a file path structure under the EAP_HOME/modules/ directory. For example, for a MySQL JDBC driver, create a directory structure as follows: EAP_HOME/modules/com/mysql/main/.
2. Copy the JDBC driver JAR into the main/ subdirectory.
3. In the main/ subdirectory, create a module.xml file similar to the example below:
Example 6.1. Example module.xml file
<module xmlns="urn:jboss:module:1.0" name="com.mysql">
<resources>
<resource-root path="mysql-connector-java-5.1.15.jar"/>
</resources>
<dependencies>
<module name="javax.api"/>
<module name="javax.transaction.api"/>
</dependencies>
</module>
The module name, com.mysql, should match the directory structure for the module.
4. Start the Server.
5. Start the Management CLI.
6. Run the following CLI command to add the JDBC driver module as a driver:
/subsystem=datasources/jdbc-driver=DRIVER_NAME:add(driver- name=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xa-datasource-class-name=XA_DATASOURCE_CLASS_NAME)
Example 6.2. Example CLI Command
/subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-
module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource)
Result
The JDBC driver is now installed and set up as a core module, and is available to be referenced by application datasources.
Report a bug
6.2.3. JDBC Driver Download Locations
The following table gives the standard download locations for JDBC drivers of common databases used with the JBoss Enterprise Application Platform. These links point to third-party websites which are not controlled or actively monitored by Red Hat. For the most up-to-date drivers for your database, check your database vendor's documentation and website.
Table 6.1. JDBC driver download locations
Vendor Download Location
MySQL http://www.mysql.com/products/connector/
PostgreSQL http://jdbc.postgresql.org/
Oracle http://www.oracle.com/technology/software/tech/ja
va/sqlj_jdbc/index.html
IBM http://www-306.ibm.com/software/data/db2/java/
Sybase
http://www.sybase.com/products/allproductsa-z/softwaredeveloperkit/jconnect
Microsoft http://msdn.microsoft.com/data/jdbc/
Report a bug
6.2.4 . Access Vendor Specific Classes
Summary
This topic covers the steps required to use the JDBC specific classes. This is necessary when an application needs to use vendor specific functionality that is not part of the JDBC API.
Warning
This is advanced usage. Only applications that need functionality not found in the JDBC API should implement this procedure.
Important
This process is required when using the reauthentication mechanism, and accessing vendor specific classes.
Important
Follow the vendor specific API guidelines closely, as the connection is being controlled by the IronJacamar container.
Prerequisites
Section 6.2.2, “Install a JDBC Driver as a Core Module”.
Procedure 6.3. Add a Dependency to the Application