Section 4.5. JBoss DataSource Descriptors

4.5. JBoss DataSource Descriptors

Remember in Chapter 1 we dynamically deployed and undeployed a service? We used the Hypersonic database in the example. You can access any database as an MBean by simply including the appropriate *-ds.xml file in the deploy directory.

Hypersonic is completely implemented in Java and ships standard with JBoss. It is great for playing around with JDBC and not having to worry about installing and configuring an external database. We generally rely on a full-fledged external database for production applications, but we'd be lying if we told you that we didn't use Hypersonic all the time for rapid testing and prototyping.

Three types of Hypersonic instances include:

• The default Hypersonic configuration, which gives you a local database whose modifications are saved to disk (and therefore survive between JBoss restarts). We can access this configuration only through a DataSourceit is not accessible to out-of-container clients like Ant or third-party standalone GUIs. It is called an "In-Process Persistent DB".

• As a slight variation, we can configure the "In-Process Persistent DB" to run purely in memory. No files are written to disk, and therefore the database lives only as long as the container is running. This is called an "In-Memory DB."

• If you need to access the database from either a DataSource or an external client, you can configure Hypersonic to listen on a TCP port (1701 by default). This is called a "TCP DB."

The Hypersonic deployment descriptor is $JBOSS_HOME/server/default/deploy/hsqldb-ds.xml. Examples of deployment descriptors for all major databases (commercial or open source) are at $JBOSS_HOME/docs/examples/jca. The J2EE Connector Architecture (JCA) is a standard way for a J2EE container to connect to external datastores. These example files generally are very well commented. Take a moment to browse the examples/jca directory and look through some of the deployment descriptors.

We provide two customized Hypersonic database descriptors in the ch04/sql directory. Jaw-ds.xml strips out all the comments included in the original hsqldb-ds.xml filesometimes it can be hard to see the forest for the trees. We also included a version that retains the original comments. You might like to compare this version to the default Hypersonic version to see how we've tweaked it.

Let's step through jaw-ds.xml line by line.

 <datasources>    <local-tx-datasource>       <jndi-name>JBossAtWorkDS</jndi-name> 

This is the global/JBoss JNDI name of your DataSource. Since this DataSource is accessible to all EARs, it only makes sense to bind its name in the global context. (The local ENC name goes with the local EAR in web.xml.)

       <connection-url>jdbc:hsqldb:hsql://localhost:1701</connection-url>       <driver-class>org.hsqldb.jdbcDriver</driver-class>       <user-name>sa</user-name>       <password></password> 

These values should look familiar to you. They are the standard JDBC parameters that tell you how to connect to the database, which driver to use, and what credentials to supply when connecting.

       <min-pool-size>5</min-pool-size>       <max-pool-size>20</max-pool-size>       <idle-timeout-minutes>0</idle-timeout-minutes>       <track-statements/> 

These next settings allow you to optimize the start and peak number of connections in the pool. According to the comments in the default Hypersonic descriptor, <idle-timeout-minutes> should be left at 0 as a bug work-around.

       <metadata>          <type-mapping>Hypersonic SQL</type-mapping>       </metadata>       <depends>jboss:service=Hypersonic-JAW,database=jawdb</depends>     </local-tx-datasource> 

The <metadata> element is boilerplate for all Hypersonic instances, but the <depends> clause should be customized per instance. This is the unique identifier of the MBean defined in the last section of the file.

    <mbean code="org.jboss.jdbc.HypersonicDatabase"      name="jboss:service=Hypersonic-JAW,database=jawdb">      <attribute name="Port">1701</attribute>      <attribute name="Silent">true</attribute>      <attribute name="Database">jawdb</attribute>      <attribute name="Trace">false</attribute>      <attribute name="No_system_exit">true</attribute>    </mbean> </datasources> 

The <local-tx-datasource> section defines the DataSource. The <mbean> section defines the actual database instance. The Database attribute is especially interestingit tells Hypersonic what to name the physical files stored on disk. (These files are stored in $JBOSS_HOME/server/default/data/hypersonic, but they won't show up until you deploy the database. We'll see them in just a moment.)

Now we are ready to deploy the customized JAW datasource. Copy jaw-ds.xml to $JBOSS_HOME/server/default/deploy. You should see the following code in your server console window:

 23:06:52,077 INFO  [STDOUT] [Server@d27151]: [Thread[hypersonic-jawdb,5,jboss]]:  checkRunning(false) entered 23:06:52,079 INFO  [STDOUT] [Server@d27151]: [Thread[hypersonic-jawdb,5,jboss]]:  checkRunning(false) exited 23:06:52,080 INFO  [STDOUT] [Server@d27151]: Startup sequence initiated from main(  )  method 23:06:52,119 INFO  [STDOUT] [Server@d27151]: Loaded properties from  [/Library/jboss-4.0.1/bin/server.properties] 23:06:52,155 INFO  [STDOUT] [Server@d27151]: Initiating startup sequence... 23:06:52,158 INFO  [STDOUT] [Server@d27151]: Server socket opened successfully in  0 ms. 23:06:52,179 INFO  [STDOUT] [Server@d27151]: Database [index=0, id=2,  db=file:/Library/jboss-4.0.1/server/default/data/hypersonic/jawdb, alias=]  opened sucessfully in 18 ms. 23:06:52,181 INFO  [STDOUT] [Server@d27151]: Startup sequence completed in 23 ms. 23:06:52,263 INFO  [STDOUT] [Server@d27151]: 2005-04-28 23:06:52.263 HSQLDB server  1.7.2 is online 23:06:52,288 INFO  [STDOUT] [Server@d27151]: To close normally, connect and execute  SHUTDOWN SQL 23:06:52,309 INFO  [STDOUT] [Server@d27151]: From command line, use [Ctrl]+[C] to  abort abruptly 23:06:52,569 INFO  [WrapperDataSourceService] Bound connection factory for resource  adapter for ConnectionManager 'jboss.jca:name=JBossAtWorkDS,  service=DataSourceBinding to JNDI name 'java:JBossAtWorkDS' 

We can glean a couple of interesting nuggets from the console output:

• First, it tells us that the database is now listening on a TCP port (or server socket).

• It also tells us where to look for the physical database files: $JBOSS_HOME/server/default/data/hypersonic. After we add some data to this database, we'll nose around this directory to see the resulting changes.

• Finally, it tells us that our DataSource has been successfully bound to a JNDI name.

We now know that our database has been successfully deployed. We can use a couple of other tricks to confirm this if you'd like.

You can verify the ports that are open on your server by using the netstat command. Type netstat -an on a Windows PC or Mac; or netstat -anp on a Linux box. All platforms should give you a report similar to this:

 Active Internet connections (including servers) Proto Recv-Q Send-Q  Local Address          Foreign Address        (state) tcp46      0      0  *.1701                 *.*                    LISTEN tcp4       0      0  127.0.0.1.57918        127.0.0.1.631          CLOSE_WAIT tcp4       0      0  127.0.0.1.57917        127.0.0.1.631          CLOSE_WAIT tcp46      0      0  *.8008                 *.*                    LISTEN tcp46      0      0  *.8093                 *.*                    LISTEN tcp46      0      0  *.8088                 *.*                    LISTEN tcp46      0      0  *.4445                 *.*                    LISTEN tcp46      0      0  *.4444                 *.*                    LISTEN tcp46      0      0  *.8083                 *.*                    LISTEN tcp46      0      0  *.1099                 *.*                    LISTEN tcp46      0      0  *.1098                 *.*                    LISTEN tcp4       0      0  10.11.46.54.56015      207.178.165.2.80       CLOSE_WAIT tcp4       0      0  127.0.0.1.8005         *.*                    LISTEN tcp46      0      0  *.8009                 *.*                    LISTEN tcp46      0      0  *.8080                 *.*                    LISTEN 

In addition to our Hypersonic instance on port 1701, we can also see our embedded Tomcat instance listening on port 8080.

Since Hypersonic is an MBean, you can also use JBoss' JMX-Console webapp to verify that it is active. Visit http://localhost:8080/jmx-console (Figure 4-1). The Hypersonic-JAW MBean should be one of the first links in the list.

Click on the link to our database instance. From here, you can do basic things like start and stop the instance, or modify the port it is listening on. This is nothing you can't also do by hand-editing the configuration files, but some people prefer a GUI like that in Figure 4-2.

Now our database is configured and ready to be tested. To hit it, we'll need to make sure that your application can find the appropriate JDBC driver.