<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<body link="#355491" alink="#4262a1" vlink="#355491" style="background: #e2e2e2; margin: 0; padding: 20px;">
<div>
<table cellpadding="0" bgcolor="#FFFFFF" border="0" cellspacing="0" style="border: 1px solid #dadada; margin-bottom: 30px; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td>
<table border="0" cellpadding="0" cellspacing="0" bgcolor="#FFFFFF" style="border: solid 2px #ccc; background: #dadada; width: 100%; -moz-border-radius: 6px; -webkit-border-radius: 6px;">
<tbody>
<tr>
<td bgcolor="#000000" valign="middle" height="58px" style="border-bottom: 1px solid #ccc; padding: 20px; -moz-border-radius-topleft: 3px; -moz-border-radius-topright: 3px; -webkit-border-top-right-radius: 5px; -webkit-border-top-left-radius: 5px;">
<h1 style="color: #333333; font: bold 22px Arial, Helvetica, sans-serif; margin: 0; display: block !important;">
<!-- To have a header image/logo replace the name below with your img tag -->
<!-- Email clients will render the images when the message is read so any image -->
<!-- must be made available on a public server, so that all recipients can load the image. -->
<a href="http://community.jboss.org/index.jspa" style="text-decoration: none; color: #E1E1E1">JBoss Community</a></h1>
</td>
</tr>
<tr>
<td bgcolor="#FFFFFF" style="font: normal 12px Arial, Helvetica, sans-serif; color:#333333; padding: 20px; -moz-border-radius-bottomleft: 4px; -moz-border-radius-bottomright: 4px; -webkit-border-bottom-right-radius: 5px; -webkit-border-bottom-left-radius: 5px;"><h3 style="margin: 10px 0 5px; font-size: 17px; font-weight: normal;">
Data Source Configuration in AS 7
</h3>
<span style="margin-bottom: 10px;">
created by <a href="http://community.jboss.org/people/andy.miller">Andrig Miller</a> in <i>JBoss AS7 Development</i> - <a href="http://community.jboss.org/docs/DOC-16657">View the full document</a>
</span>
<hr style="margin: 20px 0; border: none; background-color: #dadada; height: 1px;">
<div class="jive-rendered-content"><p>In older versions of the application server, data source configuration was tied to a *-ds.xml file schema that you would deploy in the deploy directory of your configuration.  In AS 7, the entire structure of the AS is different, and as you would expect, creating your own data sources is different as well.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>There are two ways in which you can create your own data sources, but this article will focus on creating one, using MySQL as the example, using the new AS 7 module system.  In AS 7, the application server services themselves are no longer tied into the deployment.  If you look at the directory structure, you will actually see an empty "deployments" folder, after you unzip the archive.  That's because all of the AS services are now modules.  In fact, you can see what used to be called the DefaultDS, and used Hypersonic, is now a module, and its the H2 database.  You can see that in the modules directory directly under the jboss-7.0.0.<release> directory, where <release> is the binary release you downloaded, whether the current Beta, or future Beta's, CR's or the Final release.  So, let's talk about how we can create our own data source as a module, and then reference that in the configuration.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Under the root directory of the application server, is a directory called modules (e.g. jboss-7.0.0.<release>/modules).  In this example, I will create the MySQL module in the same tree as the H2 database.  The H2 database, which comes preconfigured, like the old DefaultDS with Hypersonic, is under the com/h2database/h2 directory, under the modules directory.  So, the first step is to create a directory structure simlar to that for MySQL.  I created, under com, a mysql directory, plus a main directory.  So, at this point it should like like the following:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;">jboss-7.0.0.<release>/modules/com/mysql/main</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>Under the main directory, you need to define your module with a module.xml file, and the actual jar file that contains your database driver.  In my case, the mysql-connector-java-5.1.15.jar file.  This is in contrast to putting the database driver jar file in the old lib directory under your configuration where you deployed your *-ds.xml file.  Also, the jar file must have a META-INF/services/java.sql.Driver file.  This is due to the way AS 7 will load the driver.  Fortunately, the MySQL JDBC driver jar file has this.  So, what's the content of the module.xml file.</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>It's fairly straightforward, and is as follows:</p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><?xml version="1.0" encoding="UTF-8"?></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><!--</span></p><p><span style="font-family: courier new,courier;">  ~ JBoss, Home of Professional Open Source.</span></p><p><span style="font-family: courier new,courier;">  ~ Copyright 2010, Red Hat, Inc., and individual contributors</span></p><p><span style="font-family: courier new,courier;">  ~ as indicated by the @author tags. See the copyright.txt file in the</span></p><p><span style="font-family: courier new,courier;">  ~ distribution for a full listing of individual contributors.</span></p><p><span style="font-family: courier new,courier;">  ~</span></p><p><span style="font-family: courier new,courier;">  ~ This is free software; you can redistribute it and/or modify it</span></p><p><span style="font-family: courier new,courier;">  ~ under the terms of the GNU Lesser General Public License as</span></p><p><span style="font-family: courier new,courier;">  ~ published by the Free Software Foundation; either version 2.1 of</span></p><p><span style="font-family: courier new,courier;">  ~ the License, or (at your option) any later version.</span></p><p><span style="font-family: courier new,courier;">  ~</span></p><p><span style="font-family: courier new,courier;">  ~ This software is distributed in the hope that it will be useful,</span></p><p><span style="font-family: courier new,courier;">  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of</span></p><p><span style="font-family: courier new,courier;">  ~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU</span></p><p><span style="font-family: courier new,courier;">  ~ Lesser General Public License for more details.</span></p><p><span style="font-family: courier new,courier;">  ~</span></p><p><span style="font-family: courier new,courier;">  ~ You should have received a copy of the GNU Lesser General Public</span></p><p><span style="font-family: courier new,courier;">  ~ License along with this software; if not, write to the Free</span></p><p><span style="font-family: courier new,courier;">  ~ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA</span></p><p><span style="font-family: courier new,courier;"><span>  ~ 02110-1301 USA, or see the FSF site: </span><a class="jive-link-external-small" href="http://www.fsf.org" target="_blank">http://www.fsf.org</a><span>.</span></span></p><p><span style="font-family: courier new,courier;">  --></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;"><module xmlns="urn:jboss:module:1.0" name="com.mysql"></span></p><p><span style="font-family: courier new,courier;">  <resources></span></p><p><span style="font-family: courier new,courier;">    <resource-root path="mysql-connector-java-5.1.15.jar"/></span></p><p><span style="font-family: courier new,courier;">  </resources></span></p><p><span style="font-family: courier new,courier;">  <dependencies></span></p><p><span style="font-family: courier new,courier;">    <module name="javax.api"/></span></p><p><span style="font-family: courier new,courier;">  </dependencies></span></p><p><span style="font-family: courier new,courier;"></module></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">As you can see from above, we give the module name, which in this example is com.mysql, which matches the directory structure we had created under the modules directory.  If we had followed exactly the way the H2 database module was created we would have created something like com/mysqldatabase/mysql, and in that case the module name would have been com.mysqldatabase.mysql.  I chose a shorted name in this case, but its just a matter of personal preference.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">Besides the module name, we need to tell it where the implementation is, which is the resource-root tag with the path element.  In that path element, we simply put the jar name.  The path appears to be relative, and default to the main directory under the directory structure you created, which of course is com/mysql in our case.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">Finally, you define any dependencies you might have.  In this case, as the case with all JDBC data sources, we would be dependent on the Java JDBC API's, which in this case in defined in another module called javax.api, which you can find under modules/javax/api/main as you would expect.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">That's really all there is to creating the module, but it will not be started as a service by AS 7, unless its referenced in the configuration.  Now, just like everything else in AS 7, configuration is now completely different.  There are two main configurations.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">The first configuration is called domain, and has a domain directory under the root directory of the AS 7 distribution.  This is a configuration that is geared toward multiple server instances and multiple server installations.  The second is standalone, which is geared for a single instance of the server running on a single server, as you would expect.  In regards to data source configuration, there really is no difference, as the datasource schema definition is the same in both cases.  So regardless of which one you may be using in your particular case, the configuration is the same.  For reference you can see the data source information here:</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;"><a class="jive-link-external-small" href="http://docs.jboss.org/ironjacamar/userguide/1.0/en-US/html/deployment.html#deployingds_descriptor">http://docs.jboss.org/ironjacamar/userguide/1.0/en-US/html/deployment.html#deployingds_descriptor</a></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">In either standalone.xml or domain.xml you add the reference to the MySQL module as follows:</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;">                 <datasource jndi-name="java:/MySqlDS" pool-name="MySqlDS" enabled="true" use-java-context="true"></span></p><p><span style="font-family: courier new,courier;">                    <connection-url></span></p><p><span style="font-family: courier new,courier;">                        jdbc:mysql://localhost:3306/EJB3</span></p><p><span style="font-family: courier new,courier;">                    </connection-url></span></p><p><span style="font-family: courier new,courier;">                    <driver-class></span></p><p><span style="font-family: courier new,courier;">                        com.mysql.jdbc.Driver</span></p><p><span style="font-family: courier new,courier;">                    </driver-class></span></p><p><strong style="font-family: courier new,courier;">                    <module></strong></p><p><strong style="font-family: courier new,courier;">                        com.mysql.jdbc.Driver#5.1</strong></p><p><strong style="font-family: courier new,courier;">                    </module></strong></p><p><span style="font-family: courier new,courier;">                    <transaction-isolation></span></p><p><span style="font-family: courier new,courier;">                        TRANSACTION_READ_COMMITTED</span></p><p><span style="font-family: courier new,courier;">                    </transaction-isolation></span></p><p><span style="font-family: courier new,courier;">                    <pool></span></p><p><span style="font-family: courier new,courier;">                        <min-pool-size></span></p><p><span style="font-family: courier new,courier;">                            200</span></p><p><span style="font-family: courier new,courier;">                        </min-pool-size></span></p><p><span style="font-family: courier new,courier;">                        <max-pool-size></span></p><p><span style="font-family: courier new,courier;">                            300</span></p><p><span style="font-family: courier new,courier;">                        </max-pool-size></span></p><p><span style="font-family: courier new,courier;">                        <prefill></span></p><p><span style="font-family: courier new,courier;">                            true</span></p><p><span style="font-family: courier new,courier;">                        </prefill></span></p><p><span style="font-family: courier new,courier;">                        <use-strict-min></span></p><p><span style="font-family: courier new,courier;">                            false</span></p><p><span style="font-family: courier new,courier;">                        </use-strict-min></span></p><p><span style="font-family: courier new,courier;">                    </pool></span></p><p><span style="font-family: courier new,courier;">                    <security></span></p><p><span style="font-family: courier new,courier;">                        <user-name></span></p><p><span style="font-family: courier new,courier;">                            test<br/></span></p><p><span style="font-family: courier new,courier;">                        </user-name></span></p><p><span style="font-family: courier new,courier;">                        <password></span></p><p><span style="font-family: courier new,courier;">                            test<br/></span></p><p><span style="font-family: courier new,courier;">                        </password></span></p><p><span style="font-family: courier new,courier;">                    </security></span></p><p><span style="font-family: courier new,courier;">                    <validation></span></p><p><span style="font-family: courier new,courier;">                        <validate-on-match></span></p><p><span style="font-family: courier new,courier;">                            false</span></p><p><span style="font-family: courier new,courier;">                        </validate-on-match></span></p><p><span style="font-family: courier new,courier;">                        <background-validation></span></p><p><span style="font-family: courier new,courier;">                            false</span></p><p><span style="font-family: courier new,courier;">                        </background-validation></span></p><p><span style="font-family: courier new,courier;">                        <useFastFail></span></p><p><span style="font-family: courier new,courier;">                            false</span></p><p><span style="font-family: courier new,courier;">                        </useFastFail></span></p><p><span style="font-family: courier new,courier;">                    </validation></span></p><p><span style="font-family: courier new,courier;">                    <statement></span></p><p><span style="font-family: courier new,courier;">                        <prepared-statement-cache-size></span></p><p><span style="font-family: courier new,courier;">                            100</span></p><p><span style="font-family: courier new,courier;">                        </prepared-statement-cache-size></span></p><p><span style="font-family: courier new,courier;">                        <share-prepared-statements/></span></p><p><span style="font-family: courier new,courier;">                    </statement></span></p><p><span style="font-family: courier new,courier;">                </datasource></span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">As you can see from above this looks remarkable similar to the old *-ds.xml file, and in fact, I carried over all the attributes I had in my old data source definition.  The thing to point out here, is that this is within an outer tag called <datasources>, so obviously there can be more than one, just like before, but unlike before, they are all included in the one configuration file, either standalone.xml or domain.xml depending on which you are using.  In each case the directory structure is as follows:</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;">jboss-7.0.0.<release>/domain/configuration/domain.xml or</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: courier new,courier;">jboss-7.0.0.<release>/standalone/configuration/standalone.xml</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">The other important things to point out, besides the standard JDBC parameters, is the module tag above, and a new section called drivers which is within the "datasources" subsystem in the schema, but below the data sources themselves.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p><span style="font-family: arial,helvetica,sans-serif;">In the module tag above, you should specify the fully qualtified name of the JDBC driver class, appended with a pound sign (#), with the major and minor version number.  In my example above its 5.1, since I am using the 5.1.15 driver from MySQL.  It does not support the micro version number, so if you are tempted, as I was, to add it, it will cause your module to fail loading, which will then cascade to your application using this data source.  So, then the drivers tag.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>            <drivers></p><p>                <driver module="com.mysql"/></p><p>            </drivers></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>As you can see, what we put in this is the actual module name we defined in module.xml under <span style="font-family: courier new,courier;">jboss-7.0.0.<release>/modules/com/mysql/main/module.xml.</span></p><p style="min-height: 8pt; height: 8pt; padding: 0px;"> </p><p>That's all there is to it.  I have also attached a zip archive of the MySQL module that I created, plus my standalone.xml file, that you can use to make your own.  If you want to create a MySQL module and data source, you can simply unzip the com.mysql.tar.gz under the modules directory of your AS 7 distribution, and cut and past the datasource tag in standalone.xml into your configuration, and of course change the database you are connecting to, plus the username and password, and other relevant parameters to suit your needs, and you will have a working MySQL data source.</p><p><span style="font-family: arial,helvetica,sans-serif;"><br/></span></p></div>
<div style="background-color: #f4f4f4; padding: 10px; margin-top: 20px;">
<p style="margin: 0;">Comment by <a href="http://community.jboss.org/docs/DOC-16657">going to Community</a></p>
<p style="margin: 0;">Create a new document in JBoss AS7 Development at <a href="http://community.jboss.org/choose-container!input.jspa?contentType=102&containerType=14&container=2225">Community</a></p>
</div></td>
</tr>
</tbody>
</table>
</td>
</tr>
</tbody>
</table>
</div>
</body>
</html>