Tuesday Apr 26, 2005

Easy JBoss Connection Pooling with NetBeans IDE 4.1 and XDoclet

Create the application described in the "Use a Java Class to Access the Data Source" section in the Connecting to Databases chapter of "Using NetBeans IDE 4.1", which is currently a work in progress. It consists of a Java class that accesses one of the default PointBase databases and displays two fields ("name" and "city") on a JSP page.

Fast Track: Too lazy to create the application yourself? Or maybe you just want to see how JBoss connection pooling works with NetBeans IDE 4.1. Either way, you can download the application here. And then open it in the IDE and take all the steps below to quickly set up JBoss connection pooling.

Note that the org.me.customer.CustomerDAO class accesses the database via a data source called jdbc/poolDB. It uses this code to make the connection to the data source:

private javax.sql.DataSource getPoolDB() throws javax.naming.NamingException {
        javax.naming.Context c = new javax.naming.InitialContext();
        return (javax.sql.DataSource) c.lookup("java:comp/env/jdbc/poolDB");

(The code above was generated by the IDE, as described in this blog entry.)

The jdbc/poolDB data source referred to in the code above doesn't exist yet. In the Connecting to Databases chapter you can see how to set up a data source on the Sun Java System Application Server and on the Tomcat Web Server, since both servers are officially supported in NetBeans IDE 4.1.

In the following steps, you will create a data source on the JBoss server and access it from NetBeans IDE 4.1.

  1. Create the data source. In the JBoss installation directory, go to docs/examples/jca and copy pointbase-ds.xml to your JBoss deployment directory. (The pointbase-ds.xml file, along with many other database-server-specific templates, is kindly provided by the JBoss folks.) For this example, the JBoss deployment directory is its autodeploy directory: server/default/deploy. Now customize the pointbase-ds.xml template so that it looks as follows:


    That's it. You now have a JBoss data source. It is called jdbc/poolDB and provides access to the Sample database that is part of the default PointBase installation.

  2. Set the JBoss Port Number. Make sure that you like JBoss's port number. The default port number is 8080. This may conflict with other port numbers (especially if you have been playing with multiple servers). Therefore, go here in the JBoss installation directory and take a look:


    Just search for "8080" in the file and change it to something else.

  3. Make the PointBase database driver available to JBoss. Do this by copying pbclient from the PointBase installation directory to the lib directory within the JBoss server's installation directory. For the JBoss autodeploy directory, the applicable lib directory is server/default/lib.
  4. Get Ant targets for starting and stopping JBoss from the IDE. Download servers-build.xml and servers-build.properties from Brian Leonard's article Integrating NetBeans with other J2EE Server Vendors. Put them in the same directory as where your application's build.xml file is found. Now open the build.xml file and add the following import statement after the existing import statement:

    <import file="servers-build.xml"/>
  5. Start JBoss from the IDE. Modify the jboss.home property in servers-build.properties and run the jboss-start target. Run it from inside the IDE (you can create a menu item, toolbar button, or shortcut key for it, as described in earlier blog entries). JBoss starts up and the Output window displays output received from JBoss. You'll see a lot of output and it might take a while. Somewhere near the end you should see something similar to the following (truncated here for easier reading):

    12:34:14,906 INFO  [WrapperDataSourceService] 
    Bound connection factory for resource adapter 
    for ConnectionManager 'jboss.jca:service=DataSourceBinding,name=jdbc/poolDB 
    to JNDI name 'jdbc/poolDB'

    This means that the jdbc/poolDB is available and that you can access it.

  6. Build the project to the JBoss autodeploy directory. Right-click the project in the Projects window to build it. (You can also build it in the Files window -- choose File > Set Main Project, set the current project as the main project, and click F11 whenever you want to build.) Modify the jboss-deploy target in servers-build.xml so that war.name is used instead of jar.name. Now run the jboss-deploy target. (If you haven't built the project, you'll get errors because the WAR file that the target tries to copy to the JBoss deployment directory hasn't been built yet.) This copies the application's WAR file to the JBoss autodeploy directory. In the Output window you should see something similar to the following:

    Copying 1 file to C:\\jboss\\jboss-4.0.1sp1\\server\\default\\deploy
    BUILD SUCCESSFUL (total time: 0 seconds)

    Now that the application is in the JBoss autodeploy directory, JBoss deploys it automatically...

  7. Start PointBase. In the IDE, choose Tools > Pointbase Database > Start Local Pointbase Database.
  8. Access the application's URL. Modify the jboss.client.url property in servers-build.properties so that it points to the JBoss port number and so that the name of the project replaces the name used by Brian's project. Now run the jboss-runapp target. This opens the IDE's default browser and displays the application as found in the JBoss autodeploy directory. You will get a 404 error message in your browser, with this helpful description: "The requested resource (/CustomerNameAndCity) is not available." Back in the IDE, run the jboss-stop target. Once JBoss has stopped, run the jboss-start target again. JBoss will produce this error in the Output window (truncated here for readability):

    javax.naming.NamingException: resource-ref: 
    jdbc/poolDB has no valid JNDI binding. 
    Check the jboss-web/resource-ref.

    This means... we need a jboss-web.xml file, containing a <resource-ref> section. We will use XDoclet to generate the file as well as its <resource-ref> section.

This is how to add XDoclet to the mix:

  1. Get XDoclet. Download and extract XDoclet 1.2.2.
  2. Get the Ant target for creating the jboss-web.xml file from the IDE. Download xdoclet-web-build and xdoclet-web-build.properties from Brian Leonard's article Integrating NetBeans with other J2EE Server Vendors. Put them in the same directory as where your application's build.xml file is found. Open the xdoclet-web-build.properties file and make sure the xdoclet.root.dir property is set appropriately. Now open build.xml and add the following import statement after the existing import statement:

    <import file="xdoclet-web-build.xml"/>
  3. Add @jboss comments to a Java class. In org.me.customer.CustomerDAO, add the following as comments right above the class declaration:

    \*  @jboss.resource-ref  res-ref-name="jdbc/poolDB"
    \*                       jndi-name="jdbc/poolDB"

    This must be in the right place -- i.e., not in the comments right at the top of the file, but in the comments that come in between the import statements and the class declaration.

  4. Customize and run the target from the IDE. Modify the webdoclet target in xdoclet-web-build.xml so that the fileset looks as follows:

    <fileset dir="${src.dir}">
        <include name="\*\*/\*\*.java"/>

    Now run the webdoclet target. You'll see a nice big comment block in the Output window (thanks to Demi Moore) and when you go to your application's web/WEB-INF directory you will see your brand new jboss-web.xml file. This file contains the following important tags:

  5. Redeploy, including the jboss-web.xml file. Now build the project again, run the jboss-deploy target to deploy the WAR file to the JBoss deployment directory, and then run the jboss_runapp target again. You will now see the PointBase Sample database's "name" and "city" fields displayed in the IDE's default browser:


Geertjan Wielenga (@geertjanw) is a Principal Product Manager in the Oracle Developer Tools group living & working in Amsterdam. He is a Java technology enthusiast, evangelist, trainer, speaker, and writer. He blogs here daily.

The focus of this blog is mostly on NetBeans (a development tool primarily for Java programmers), with an occasional reference to NetBeans, and sometimes diverging to topics relating to NetBeans. And then there are days when NetBeans is mentioned, just for a change.


« April 2005 »