6.2. JDBC Drivers

Procedure 6.3. Modify the JDBC Driver JAR

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

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)

Procedure 6.5. Add a Dependency to the Application

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