Examining the Database | JBoss: A Developers Notebook

JBoss provides an embedded relational database called Hypersonic, and it automatically links CMP entity beans to that database in the absence of any other configuration. Using Hypersonic was a big help in getting an application up quickly. But instead of treating it like a big black box, we'll take a little time to dig into it a bit and understand exactly what JBoss is doing with the database.

How do I do that?

The Hypersonic database instance is completely embedded in JBoss and offers no connectivity to the world outside of the JBoss server, at least not by default. That means there is no convenient way to access the database from outside of JBoss. It does offer a simple management console, but we will need some co-operation from JBoss to get it running.

Note: The console is at http://localhost:8080/jmx-console, if you forgot.

Fortunately for everyone, all services in JBoss are represented by managed beans (MBeans). The MBean for Hypersonic is responsible for interfacing with the database. You can get to the Hypersonic MBean using the JMX Console. You can load the JMX Console and then locate the database=localDB,service=Hypersonic MBean in the jboss domain.

Following the link provides the list of attributes and operations available. If you look around a bit, you will notice a startDatabaseManager operation. Invoking this operation launches the HSQL Database Manager, shown in Figure 3-2.

Developer's Notebook 3-2. The HSQL Database Manager

The database manager is not an applet. It is a swing-based tool that is launched from within the JBoss instance. Even if you invoke the operation on a remote machine, the database manager runs on the machine that is actually running JBoss. This can be confusing if you are developing on a remote machine or if you are trying to run JBoss under a different user on the same machine, but it won't cause a problem for a typical development scenario.

Note: On a Unix or Linux machine, you can set the DISPLAY environment variable when you start JBoss to control where the windows will be displayed.

The left pane of the application shows the tables available in the database. Of these, only the COMMENT and TASK tables are related to the ToDo application. The other tables are used for persistent JMS messages, timers, and sequence number generation. Hypersonic is the default datastore for everything in JBoss that needs to use a relational database.

JBoss has derived the table name for the entity beans from the bean's name. Drilling down on the table name lets you view the schema for the table. The CMP fields of the bean map to columns of the same name.

The task-to-comment relationship is a simple, one-to-many relationship that can be mapped using a foreign key. The TASK column on the COMMENT table provides this. If you examine the constraints under the Indices item, you'll see a primary key constraint on the ID field but no foreign key constraint on the TASK column. This is due to a shortcoming of CMP entity beans. JBoss does give you the ability to work around this limitation, but most J2EE developers have learned to simply work without foreign keys.

You can issue SQL statements by typing them into the text box in the right pane and clicking Execute SQL Statement. The results will be shown in a column view below the text box, as shown in Figure 3-3

You should be able to view and modify the data you have entered here. Try updating the name of a task and reloading the view in the web application. You might notice that the default caching policy for entity beans does not cache data in memory between requests.

What just happened?

We've interacted with the Hypersonic database a bit more. Using the Hypersonic Database Manager, we've seen the default schema that JBoss created. We've also seen how to issue queries to inspect the data that's created. We didn't look at performance tuning or advanced configuration because Hypersonic is not the database you would want to use much further than the initial stages of development. It is, however, the perfect choice for the initial rapid development of J2EE applications.

Note: We'll change databases in Chapter 4.

Developer's Notebook 3-3. Viewing tables in Hypersonic

The data and tables created survive the redeployment, and even the undeployment, of the application. This is both convenient and inconvenient for early development. It is easy to remove the tables by issuing DROP statements from the database manager tool, but that is a very manual process.

A simpler, brute-force method is to just delete the Hypersonic data directory from the disk. The data directory in the server configuration contains permanent storage for many JBoss services. The Hypersonic database uses the hypersonic subdirectory to store its persistent data.

Note: If that is a bit too heavy-handed, JBoss provides a much more elegant solution to schema management. We'll look at that in Chapter 7.

     [jboss-4.0.2]$ rm -rf server/default/data/hypersonic/

You should do this only with the JBoss server stopped. Hypersonic caches data in memory, and deleting the data while it is running may cause problems.