9:01 a.m.
Jesper Pedersen [http://community.jboss.org/people/jesper.pedersen] modified the
document:
"Data Source Configuration in AS 7"
To view the document, visit: http://community.jboss.org/docs/DOC-16657
--------------------------------------------------------------
*
#Using_DataSourceDefinition_to_configure_a_DataSource Using @DataSourceDefinition to
configure a DataSource
*
#Defining_a_Managed_DataSource Defining a Managed DataSource
**
#Installing_the_JDBC_Driver Installing the JDBC Driver
***
#Installing_a_JDBC_driver_as_a_deployment Installing a JDBC driver as a deployment
****
#Modify_the_JAR Modify the JAR
***
#Installing_a_JDBC_driver_as_a_module Installing a JDBC driver as a module
**
#Defining_the_DataSource_itself Defining the DataSource itself
**
#Links Links
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.
h1. Using @DataSourceDefinition to configure a DataSource
Since Java EE6, the new annotation "@DataSourceDefinition" has existed to allow
users to configure a data source directly from within their application. (Note that this
annotation bypasses the management layer and as such it is recommended only for
development and testing purposes.) This annotation requires that a data source
implementation class (generally from a JDBC driver JAR) be present on the class path
(either by including it in your application, or deploying it as a top-level JAR and
referring to it via MANIFEST.MF's Class-Path attribute) and be named explicitly.
h1. Defining a Managed DataSource
In order for a data source to be managed by the application server (and thus take
advantage of the management and connection pooling facilities it provides), you must
perform two tasks. First, you must make the JDBC driver available to the application
server; then you can configure the data source itself. Once you have performed these
tasks you can use the data source via standard JNDI injection.
h2. Installing the JDBC Driver
The JDBC driver can be installed into the container in one of two ways: either as a
deployment or as a core module. There are pros and cons to each approach, which will be
outlined below.
h3. Installing a JDBC driver as a deployment
The recommended way to install a JDBC driver into the application server is to simply
deploy it as a regular JAR deployment. The reason for this is that when you run your
application server in domain mode, deployments are automatically propagated to all servers
to which the deployment applies; thus distribution of the driver JAR is one less thing for
administrators to worry about.
cp jdbc.jar <as7>/standalone/deployments
Any JDBC 4-compliant driver will automatically be recognized and installed into the system
by name and version. A JDBC JAR is identified using the Java service provider mechaism.
Such JARs will contain a text a file named "META-INF/services/java.sql.Driver",
which contains the name of the class(es) of the Drivers which exist in that JAR.
If your JDBC driver JAR is not JDBC 4-compliant, it can be made deployable in one of a few
ways.
h4. Modify the JAR
The most straightforward solution is to simply modify the JAR and add the missing file.
You can do this from your command shell by:
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 -
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
h3.
h3. Installing a JDBC driver as a module
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:
jboss-7.0.0.<release>/modules/com/mysql/main
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.
It's fairly straightforward, and is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<!--
~ JBoss, Home of Professional Open Source.
~ Copyright 2010, Red Hat, Inc., and individual contributors
~ as indicated by the @author tags. See the copyright.txt file in the
~ distribution for a full listing of individual contributors.
~
~ This is free software; you can redistribute it and/or modify it
~ under the terms of the GNU Lesser General Public License as
~ published by the Free Software Foundation; either version 2.1 of
~ the License, or (at your option) any later version.
~
~ This software is distributed in the hope that it will be useful,
~ but WITHOUT ANY WARRANTY; without even the implied warranty of
~ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
~ Lesser General Public License for more details.
~
~ You should have received a copy of the GNU Lesser General Public
~ License along with this software; if not, write to the Free
~ Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
~ 02110-1301 USA, or see the FSF site: http://www.fsf.org.
-->
<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"/>
</dependencies>
</module>
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.
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.
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.
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.
h2. Defining the DataSource itself
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:
http://docs.jboss.org/ironjacamar/userguide/1.0/en-US/html/deployment.htm...
In either standalone.xml or domain.xml you add the reference to the MySQL module as
follows:
<datasources>
<datasource jndi-name="java:jboss/datasources/MySqlDS"
pool-name="MySqlDS">
<connection-url>jdbc:mysql://localhost:3306/EJB3</connection-url>
* <driver>**com.mysql**</driver>*
<transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
<pool>
<min-pool-size>10</min-pool-size>
<max-pool-size>100</max-pool-size>
<prefill>true</prefill>
</pool>
<security>
<user-name>test</user-name>
<password>test</password>
</security>
<statement>
<prepared-statement-cache-size>32</prepared-statement-cache-size>
<share-prepared-statement/>
</statement>
</datasource>
<drivers>
<driver name="com.mysql" module="com.mysql">
<xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
</driver>
</drivers>
</datasources>
The <datasources> tag can contain multiple datasource and XA datasource
definitions.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:
jboss-7.0.0.<release>/domain/configuration/domain.xml or
jboss-7.0.0.<release>/standalone/configuration/standalone.xml
The other important things to point out, besides the standard JDBC parameters, is the
*driver* tag above, and a new section called drivers which is within the
"datasources" subsystem in the schema, but below the data sources themselves.
In the *driver* tag above, you should specify the unique name that you gave the driver
definition in the *drivers* section.
As you can see, what we put in this is the actual module name we defined in module.xml
under jboss-7.0.0.<release>/modules/com/mysql/main/module.xml.
That's all there is to it. The MySQL module is attached as example.
h2. Links
* https://docs.jboss.org/author/display/AS7/Admin+Guide#AdminGuide-DataSources
*
http://docs.jboss.org/ironjacamar/userguide/1.0/en-US/html/deployment.htm...
--------------------------------------------------------------
Comment by going to Community
[http://community.jboss.org/docs/DOC-16657]
Create a new document in JBoss AS7 Development at Community
[http://community.jboss.org/choose-container!input.jspa?contentType=102&am...]