Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

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 JBoss EAP 6 can use them. JBoss EAP 6 allows you to deploy these drivers like any other deployment. This means that you can deploy them across multiple servers in a server group, if you use a managed domain.

Prerequisites

Before performing this task, you need to meet the following prerequisites:

  • Download the JDBC driver from your database vendor.

Note

Any JDBC 4-compliant driver is automatically recognized and installed in the system by name and version. A JDBC JAR is identified using the Java service provider mechanism. Such JARs contain the META-INF/services/java.sql.Driver text, which contains the name of the Driver classes in that JAR.

Procedure 6.3. Modify the JDBC Driver JAR

If the JDBC driver JAR is not JDBC 4-compliant, it can be made deployable using the following method.
  1. Change to, or create, an empty temporary directory.
  2. Create a META-INF subdirectory.
  3. Create a META-INF/services subdirectory.
  4. Create a META-INF/services/java.sql.Driver file, which contains one line indicating the fully-qualified class name of the JDBC driver.
  5. Use the JAR command-line tool to update the JAR like this: 
    jar \-uf jdbc-driver.jar META-INF/services/java.sql.Driver
  6. Section 3.3.2, “Log in to the Management Console”
  7. If you use a managed domain, deploy the JAR file to a server group. Otherwise, deploy it to your server. See Section 10.2.2, “Enable a Deployed 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:

Procedure 6.4. Install a JDBC Driver as a Core Module Using the Management CLI

  1. Start the Server.
  2. Start the Management CLI, but do not use the --connect or -c argument to connect to the running instance.
  3. Use the module add CLI command to add the new module.

    Example 6.1. Example CLI command to add a MySQL JDBC driver module

    module add --name=com.mysql --resources=/path/to/mysql.jar --dependencies=javax.api,javax.transaction.api

    Note

    Using the module management CLI command to add and remove modules is provided as technology preview only, and should not be used to add modules to a remote JBoss EAP instance. Modules should be added and removed manually in a production environment.
    Perform the following steps to add a module manually.
    1. A file path structure will be created under the EAP_HOME/modules/ directory. For example, for a MySQL JDBC driver, the following will be created: EAP_HOME/modules/com/mysql/main/.
    2. The JAR files specified as resources will be copied to the main/ subdirectory.
    3. A module.xml file with the specified dependencies will be created in the main/ subdirectory. See Section 7.1.1, “Modules” for an example of a module.xml file.
    Execute module --help for more details on using this command to add and remove modules.
  4. Use the connect CLI command to connect to the running instance.
  5. Run the CLI command to add the JDBC driver module to the server configuration.
    The command you choose depends on the number of classes listed in the /META-INF/services/java.sql.Driver file located in the JDBC driver JAR. For example, the /META-INF/services/java.sql.Driver file in the MySQL 5.1.20 JDBC JAR lists two classes:
    • com.mysql.jdbc.Driver
    • com.mysql.fabric.jdbc.FabricMySQLDriver
    When there is more than one entry, you must also specify the name of the driver class. Failure to do so results in an error similar to the following:

    Example 6.2. Driver class error

    JBAS014749: Operation handler failed: Service jboss.jdbc-driver.mysql is already registered
    • Run the CLI command for JDBC JARs containing one class entry. 
      /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.3. CLI Command for Standalone Mode for JDBC JARs with one driver class

      /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)

      Example 6.4. CLI Command for Domain Mode for JDBC JARs with one driver class

      /profile=ha/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)
    • Run the CLI command for JDBC JARs containing multiple class entries. 
      /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, driver-class-name=DRIVER_CLASS_NAME)

      Example 6.5. CLI Command for Standalone Mode for JDBC JARs with multiple driver class entries

      /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, driver-class-name=com.mysql.jdbc.Driver)

      Example 6.6. CLI Command for Domain Mode for JDBC JARs with multiple driver class entries

      /profile=ha/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, driver-class-name=com.mysql.jdbc.Driver)

      Example 6.7. CLI Command for Domain Mode for JDBC JARs with multiple non-XA driver class entries

      /profile=ha/subsystem=datasources/jdbc-driver=oracle/:add(driver-module-name=com.oracle,driver-name=oracle,jdbc-compliant=true,driver-datasource-class-name=oracle.jdbc.OracleDriver)
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 JBoss EAP 6.

Note

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.
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

Procedure 6.5. Add a Dependency to the Application

You can add a dependency to an application using either of the following methods. Choose whichever method you prefer.

    • Configure the MANIFEST.MF file

      1. Open the application's META-INF/MANIFEST.MF file in a text editor.
      2. Add a dependency for the JDBC module and save the file. 
        Dependencies: MODULE_NAME

        Example 6.8. MANIFEST.MF file with com.mysql declared as a dependency

        Dependencies: com.mysql

      1. Create a jboss-deployment-structure.xml file

        Create a file called jboss-deployment-structure.xml in the META-INF/ or WEB-INF folder of the application.

        Example 6.9. jboss-deployment-structure.xml file with com.mysql declared as a dependency

        <jboss-deployment-structure>
  <deployment>
    <dependencies>
      <module name="com.mysql" />
    </dependencies>
  </deployment>
</jboss-deployment-structure>

Example 6.10. Access the Vendor Specific API

The example below accesses the MySQL API. 
import java.sql.Connection;
import org.jboss.jca.adapters.jdbc.WrappedConnection;

  Connection c = ds.getConnection();
  WrappedConnection wc = (WrappedConnection)c;
  com.mysql.jdbc.Connection mc = wc.getUnderlyingConnection();
Report a bug