The Hypersonic Client

Within BIE is an internal Hypersonic database that contains configuration, state, and audit information. The actual messages and data used by workflows is stored in an internal eXist database. It is occasionally useful to access the internal Hypersonic database to perform maintenance or correct an error; fortunately BIE contains an embedded GUI Hypersonic client.

Before starting the database client you should shut down BIE. Hypersonic in BIE operates in an in-memory mode and does not support multiple connections. Then to start the client -

$ export BIE_HOME=/usr/local/BIE
$ java -Xmx1536m -cp $BIE_HOME/services/jboss/server/default/lib/hsqldb.jar \
org.hsqldb.util.DatabaseManager

The client requires a GUI display so if you are accessing the server via SSH remember to include the -X option unless you have X11 forwarding enabled by default. The -Xmx1536m parameter specifies that the JVM can allocate up to 1,536 megabytes of RAM. If your Hypersonic database is very large you may need to allocate a significant amount of RAM in order not to encounter out-of-memory type errors during operation.

Note: If you are accessing the server from an M$-Windows client you are out of luck as Microsoft has chosen not to support the ubiquitous and extremely useful X11 protocol or display technology - so you will not be able to use the client. Please install a real operating system.

Once the client starts you must enter the connection information so that the client can locate the database. The login dialog looks like this.

Type: “HSQL Database Engine In-Memory”
Driver: org.hsqldb.jdbcDriver
URL: jdbc:hsqldb:/usr/local/BIE/services/hypersonic/BIE
User: sa
Password: BIE

Note: The URL of the database depends on where you installed BIE. This string is really $BIE_HOME/services/hypersonic/BIE.

If the parameters you entered were correct then the Hypersonic client window should appear. if the Hypersonic database is very large it may take a few minutes for the window to become responsive even on a very powerful machine - Hypersonic does not seem to deal well with very large datasets.

Compacting the database

A very common use of the client is in order to compact the database. If the BIE database gets large you will notice that the $BIE_HOME/services/hypersonic/BIE.data file does not reduce in size even if routine maintenance is in place. Hypersonic, much like other databases, does not release allocated space back to the filesystem even if the amount of data in a table or database is reduced. But you can instruct Hypersonic to reogranize the database with a SHUTDOWN COMPACT command from the client. This should reduce the size of BIE.data.

Note: You must do this while the BIE service is stopped.