JBoss Hints and Tips

These hints and tips relate to JBoss version 3.0.6.


CVS Checkout

See also CvsHintsAndTips.

JBoss source can be obtained from http://www.sourceforge.net.

Instructions for checking out code can also be found by going to www.sf.net/projects/jboss and selecting the CVS link. Look under the heading 'Anonymous CVS Access'.

  • cd /cvs_work/

  • cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jboss login

You'll only need to login again if you specifically logout.

The 'd' option overrides whatever your environment variable CVSROOT might be set to.

  • cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/jboss co -r JBoss306 jbossall

This will checkout the module jboss_all which specifies all other modules, so you will get absolutely everything. The 'z' option tells CVS to compress network traffic. The 'r' option fetches only those items with the specified tag. I'd recommend fetching a tagged module. The very latest revision has the risk that it won't build.

If you want to see what modules there are to checkout, browse the CVS repository from sourceforge. You'll find a link on the CVS page.

To see what tags exist, browse the sourceforge repository to somewhere likely to have been tagged, .e.g. [SourceForge]/jboss/build/jboss. At the bottom of the list of files there will be a combo-box listing all the tags. Alternativley, if you've already got a checkout, try the following in the build sub-directory.

  • cvs status -v build.xml

Running build.sh or build.bat

Run a command window and change your working directory to jboss-all/build/ and then run either build.sh or build.bat depending on your operating system.

  • build

If you want to include the javadocs too...

  • build all

The build script creates a default 'local.properties' file in the build directory which has entries you can override yourself. E.g. defining the property docs-javadocs.disabletrue= will disable the building of the javadocs. Note: this property must not be defined at all to allow the javadocs to be built.

Browsing through the main build script shows a few more options. You can build different pre-defined groups of modules. E.g.

  • build all -Dgroups=core

or build a specific module

  • build all -Dgroups=single -Dsingle-module=tomcat41

In building 3.0.6 I found 'build all' failed on tomcat41 as it's build.xml does not have an 'all' target defined. I simply added a target of 'all' that depends on 'main' to keep the main build happy.

  • <target name="all" depends="main"/>

The resultant build is in jboss-all\build\output.

Hypersonic Database

To run the Hypersonic database manager, find hsqldb.jar. In version 3.0.6 there is a copy in $JBOSS_HOME/server/all/lib

Issue a command similar to the following:

  • java -cp $JBOSS_HOME/server/all/lib/hsqldb.jar org.hsqldb.util.DatabaseManager

Select the following entries. Note you'll need to add the port number to the URL.

Type:     "HSQL Database Engine Server"
--------- -----------------------------------
Driver:   "org.hsqldb.jdbcDriver"
URL:      "jdbc:hsqldb:hsql://localhost:1476"
User:     "sa"
Password: leave blank

The url assumes you are running Hypersonic on the local machine. The url may change in later versions. See Connection URL

Other tools can be kicked off with commands similar to:

  • java -cp $JBOSS_HOME/server/default/lib/hsqldb.jar org.hsqldb.util.DatabaseManager

  • java -cp $JBOSS_HOME/server/default/lib/hsqldb.jar org.hsqldb.util.QueryTool

  • java -cp $JBOSS_HOME/server/default/lib/hsqldb.jar org.hsqldb.util.Transfer

Too see available command line options for a tool add -? as a command line option. E.g.

  • java -cp $JBOSS_HOME/server/default/lib/hsqldb.jar org.hsqldb.util.QueryTool -?

Go to http://hsqldb.sourceforge.net/ for the documentation

Connection URL

You can confirm the url being used to create the connection by looking in hsqldb-service.xml located in the appropriate server directory, e.g. $JBOSS_HOME/server/default/deploy. Look for the <config-property/> tag with a name attribute of ConnectionURL. The UserName and Password attributes are similarly specified in this file.

The $JBOSS_HOME/server/default/conf/login-config.xml also contains UserNames and Passwords.


See JbossLog4J - how to change the log4j log level.

See MySql - for how to see the queries being submitted to MySql.

See PostgreSQL#Debugging - how to see queries submiteed to PostgreSQL


Logging output via javax.servlet.GenericServlet is output under the log4j category of org.jboss.jbossweb with a priority of INFO. Therefore, to see these messages, ensure you've configured log4j accordingly. See JbossLog4J. This includes Struts logging which is delegated to javax.servlet.GenericServlet.

Hot deployment

Edit jboss/server/xxxx/conf/jboss-service.xml to change or add directories and files that are watched by the deployment scanner. Comments in the file describe the options.

By placing your expoloded, ear, jar or war in a directory scanned by the deployment scanner, it will be hot-deployed. You can then simply update files that change using the ant copy task, or simply edit them in place. This greatly improves the speed of JSP development.

JSP changes are recognised as soon ast the page is next accessed. To get JBoss to recognise other changes, you neeed get it to redeploy the application. This is done by simply touching (updating the time stamp) of the top-level deployment descriptor. In the case of an EAR file, ../myapp.ear/META-INF/application.xml. There is an ant touch task.

Defining System Properties

Sytem properties can be defined in ../server/xxx/deploy/properties-service.xml

The file gives an example. Properties can then be retrieved with System.getProperty(KEY);

Apache Integration

See ApacheJbossIntegration

Trouble Shooting

Losing sessions between requests

Check your deployed web.xml does not have the <distributable> tag set. If it is set, you need to enable session replication within JBoss.

Can't shutdown - wrong ip address

Typically you have an error message that includes your external IP address rather than the ip address of the machine we're running on.

"Exception in thread "main" javax.naming.CommunicationException [Root exception is java.rmi.ConnectException: Connection refused to host: x.x.x.x; nested exception is:"

This seems to be caused by JBoss at some stage failing to relate your ip address to your host name. If you ensure that your IP address resolves to your hostname on the machines concerned, the problem should go away. E.g. Place an appropriate entrie in /etc/hosts. (There's a similar hosts or lmhosts file buried away somewhere in the depths of Windows too - something like c:\windows\system32\drivers\etc\hosts).

For the local machine;

  • localhost jbosshostname.domain.tld

For a remote machine stopping the service

  • ip.address.jboss.server jbosshostname.domain.tld

A more elegant solution would be to create the correct entries in your DNS server.

See also DnsTools.

Client JNDI Lookups

If you're using something like JUnit to run test cases from JUnit clients on your EJBs, you'll need to add a jndi.properties file to your classpath and also the jbossall-client.jar which in JBoss 4.0.2 is in $JBOSS_HOME/client/. See InitialContext for an example properties file.

The following code will perform a remote lookup relying on the jndi.properties file and jbossall-client.jar being on your classpath.

  InitialContext initialContext = new InitialContext();
  MyRemote remote = ((MyRemoteHome) PortableRemoteObject.narrow(


URI Encoding

Where Tomcat is being used as the web container, you must also specify the character encoding that Tomcat uses in addition to JBoss.

In JBoss 4.2.2, Tomcat's server.xml is under $JBOSS_HOME/server/default/deploy/jboss-web.deployer/

See TomcatTips for details of the changes to be made.

-- Frank Dean - 25 Mar 2008

Class Loading

See http://www.jboss.org/wiki/Wiki.jsp?page=ClassLoadingConfiguration

-- Frank Dean - 25 Mar 2008

See also JbossMySql, JbossPostgreSql, MySql, JbossLog4J, InitialContext, JbossAndJonas

-- Frank Dean - 06 June 2003