JBoss 7.1 - Datasource Configuration and App Deployment

JBoss 7.1.1.Final has been released in 3月份 2012. Lets take a look at its directories, how to deploy and how to configure data source.

1. Directory Layout: JBoss 7 is fundamentally different from previous releases. It's module based and has a new directory layout. My understanding is that it has a "smaller" core and lots of stuff are configured as extensions/modules.

The following is the screen shot of its directories:



2. Standalone/Domain Server Confiurations: JBoss 7 has two server "configurations", the "domain" and "standalone". The "domain" configuration provides a means to manage multiple JBoss instances (probably) running on difference servers. The "standalone" configuration is similar to previous "default" configurations in JBoss 4/5/6. So lets take a look at the "standalone" configuration.

The main conf file is "JBOSS_HOME/standalone/configuration/standalone.xml"

The deployment place is "JBOSS_HOME/standalone/deployments".

To deploy an application, you can just drop the application archive (ear or war) to the above dir, or you can use the CLI(Command Line Interface) instead. After deployed, depends on the status, you've got a "your-app-archive-name.deployed" or ""your-app-archive-name.failed" mark file, as following screen shot shows:




3. Configure data source for JBoss 7.1.1

Two steps to configure a datasource for JBoss 7.1, to deploy a jdbc driver and to add the datasource entry in the server conf file.

There're many ways to deploy the jdbc driver. This article finds two ways handy: as deploying the jdbc driver directly OR as a module. Takeing oracle for instace:

3.1.1 Deploying the jdbc driver directly

This requires that the jdbc driver conforms to the jdbc4 spec. That is, the jdbc jar must contain a file "META-INF\services\java.sql.Driver". It is a text file and contains only one line, which is the driver class name. For instance "oracle.jdbc.OracleDriver" for Oracle driver "ojdbc6.jar".

Deploying is simple, just drop the jdbc driver jar file to "deployments" and it's done.

3.1.2 To configure a datasource: to use the deployed jdbc driver, you need to edit "standalone/configuration/standalone.xml", ie, the "datasource" section. It already has an example entry there. The only thing need to take care is the content of the <driver/> element: is has to match the jar file name "ojdbc6.jar". If you have a long jar name, like "mysql-abc-blah-5_15.jar", it has to be "mysql-abc-blah-5_15.jar". The following is the entry for this Oracle data source:

<subsystem xmlns="urn:jboss:domain:datasources:1.0">
	<datasources>
	    <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true">
		    <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
		    <driver>h2</driver>
		    <security>
		        <user-name>sa</user-name>
		        <password>sa</password>
		    </security>
	    </datasource>
		<datasource jta="true" jndi-name="java:/ProJee6DS" pool-name="ProJee6DS" enabled="true" use-java-context="true">
			<connection-url>jdbc:oracle:thin:@127.0.0.1:1521:jwTestOra</connection-url>
                    <!-- driver name must match jdbc jar file name -->
			<driver>ojdbc6.jar</driver>
			<pool>
				<min-pool-size>5</min-pool-size>
				<max-pool-size>10</max-pool-size>
			</pool>
			<security>
				<user-name>jwtest</user-name>
				<password>jwtest</password>
			</security>
			<timeout>
				<blocking-timeout-millis>30000</blocking-timeout-millis>
			</timeout>
			<statement>
				<prepared-statement-cache-size>100</prepared-statement-cache-size>
			</statement>
		</datasource>
		<drivers>
			<driver name="h2" module="com.h2database.h2">
				<xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
			</driver>
		</drivers>
	</datasources>
</subsystem>

One should pay attention to the sequence of the elements, it's not random and controlled by the schema. For anyone familiar with XSDs, you may want to take a look at the datasource schema and figure out what elements are available and in what sequence. These are available under this folder: "JBOSS_HOME/docs/jboss-as-datasources_1_0.xsd".

3.2 Deploying the jdbc driver as a module
Now take a look at the alternative way of configure a data source for the JBoss 7.1.1. JBoss seems to promote the direct jdbc driver deployment, but some jdbc drivers are missing the text file "META-INF\services\java.sql.Driver". Although one can manually add this simple text file to the jdbc driver jar file, a preferable approach is to deploy the jdbc driver as a module, as the following describes:

step1: create folder "JBOSS_HOME/modules/com/oracle/main"
step2: copy the jdbc driver "ojdbc6.jar" to the folder just created in step1.
step3: create an xml file "module.xml" in the folder just created in step1. Following is the content of this xml file:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.1" name="com.oracle">
    <resources>
        <resource-root path="ojdbc6.jar"/>
    </resources>
    <dependencies>
        <module name="javax.api"/>
        <module name="javax.transaction.api"/>
        <module name="javax.servlet.api" optional="true"/>
    </dependencies>
</module>

The screen shot of folder "JBOSS_HOME/modules/com/oracle/main":



3.2.2 Configure the datasource
OK, now the jdbc driver has been configured as a module. We can configure a datasource to using the new module, again by editing the entry in file "standalone/configuration/standalone.xml". It's necessary to add a "<driver/>" which references the configured module for the jdbc driver.

<subsystem xmlns="urn:jboss:domain:datasources:1.0">
	<datasources>
		<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true">
	        <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1</connection-url>
	        <driver>h2</driver>
	        <security>
	            <user-name>sa</user-name>
	            <password>sa</password>
	        </security>
	    </datasource>
	    <datasource jta="true" jndi-name="java:/ProJee6DS" pool-name="ProJee6DS" enabled="true" use-java-context="true">
	        <connection-url>jdbc:oracle:thin:@127.0.0.1:1521:jwTestOra</connection-url>
	        <driver>jwOracle</driver>
	        <pool>
	            <min-pool-size>5</min-pool-size>
	            <max-pool-size>10</max-pool-size>
	        </pool>
	        <security>
	            <user-name>jwtest</user-name>
	            <password>jwtest</password>
	        </security>
	        <timeout>
	            <blocking-timeout-millis>30000</blocking-timeout-millis>
	        </timeout>
	        <statement>
	            <prepared-statement-cache-size>100</prepared-statement-cache-size>
	        </statement>
	    </datasource>
	    <drivers>
	        <driver name="h2" module="com.h2database.h2">
	            <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
	        </driver>
             <!-- module name must match that defined in "module.xml" -->
	        <driver name="jwOracle" module="com.oracle">
	            <xa-datasource-class>oracle.jdbc.OracleDriver</xa-datasource-class>
	        </driver>
	    </drivers>
	</datasources>
</subsystem>

What's an XA datasource?
XA datasources operates across multiple resources. Resources can be databases, JMS connections etc. For instance, if your datasource requires two databases to work together, you should configure it as XA datasource. Otherwise, it's a local data source.