USING JUMPSTART IN JBOSS 5.0.1

WARNING Use JBoss 5.0.1 in preference to JBoss 5.1.0. JBoss 5.1.0 is NOT recommended for JumpStart because it fails JumpStart's integration tests due to https://issues.jboss.org/browse/JBTM-575. In a nutshell, the exceptions returned by JBoss from the business layer (ie. from session beans) do not always include the root cause. This makes it impossible for JumpStart's BusinessExceptionInterpreter to interpret the cause. JBoss 5.0.1 does not have this failing.

Contents
Prepare JBoss
Build and deploy JumpStart
Build and deploy and integration test JumpStart
Use JumpStart
How to run integration tests from Eclipse
How to debug the client side
How to debug the server side

Prepare JBoss
These instructions prepare JBoss with the following elements:

Web Server	Business Server	Persistence	Database Server	Logger
Tomcat	JBoss's EJB3	Hibernate	HSQLDB	Log4j
(JBoss's default)	(JBoss's default)	(JBoss's default)	(JBoss's default)	(JBoss's default)

• Start by doing a normal working JBoss 5.0.1 installation...
  • To get it, go to JBoss Application Server Downloads, locate 5.0.1 (AND NOT LATER VERSIONS such as 5.1.0) and choose the Download link. Choose to download jboss-5.0.1.GA-jdk6.zip.
  • Once downloaded, unzip it. Move it to a suitable location, eg. /devel/jboss-5.0.1.GA.


• Create a jumpstart server:
  • Duplicate JBoss's server/default/ directory and name it jumpstart.


• For JumpStart 5.10.1 and later, add a data source descriptor:
  • Copy JumpStart's business/src/main/resources/datasource-descriptor/jumpstart-hsqldb-ds.xml to JBoss's server/jumpstart/deploy/ directory.


• Set VM arguments:
  
  • Here are some VM arguments to consider. They are explained further here: tapestry, uploading files, hibernate, JVM technology and JVM options.

    -Dtapestry.production-mode=false	Tells the Tapestry ExceptionReport page to display full details of the exception, which is great during development. When set to true (which is the default since T5.0.10), Tapestry's ExceptionReport page will display an abbreviated report so as to avoid disclosing details of your application's internals.
    -Dtapestry.compress-whitespace=false	Tells Tapestry not to compress whitespace as it generates a page from a template. Makes the generated page source much easier to read eg. when you tell your browser to display the page source.
    -Dupload.filesize-max=8000000	Tells Apache Commons Upload to limit the size, in bytes, of upload files.
    -Djumpstart.upload-path=/tmp	Tells JumpStart where to save uploaded files.
    -Dhibernate.hbm2ddl.auto=update	ESSENTIAL for JumpStart initially. Great during development, but NOT RECOMMENDED IN A PRODUCTION ENVIRONMENT because data can be lost. Tells Hibernate to automatically bring the database structure into line with the app's entity definitions at every restart. A better value for production is validate.
    -server	Chooses the "server" JVM (which is optimised for speed).
    -Xmx512m	Gives the JVM more heap memory (to avoid "out of memory" errors). 300m may be sufficient unless you do hot deploys.
    -XX:MaxPermSize=192m	Gives the JVM more Perm Gen memory. If you encounter Perm Gen memory errors then consider this or an even higher setting. 120m may be sufficient unless you do hot deploys.
    -Djava.net.preferIPv4Stack=true	Might speed up JBoss startup on some Unixes (clustered AIX?) or other operating systems that have IPv6 enabled by default.

  • You can set them from the command line:
    ...eg. in Windows:
    • set JAVA_OPTS=-Dhibernate.hbm2ddl.auto=update -Dtapestry.production-mode=false -Dtapestry.compress-whitespace=false -Dupload.filesize-max=8000000 -Djumpstart.upload-path=/tmp -server -Xmx512m -XX:MaxPermSize=192m
    ...eg. in tcsh (the default shell in OS X Terminal):
    • setenv JAVA_OPTS "-Dhibernate.hbm2ddl.auto=update -Dtapestry.production-mode=false -Dtapestry.compress-whitespace=false -Dupload.filesize-max=8000000 -Djumpstart.upload-path=/tmp -server -Xmx512m -XX:MaxPermSize=192m -Djava.net.preferIPv4Stack=true"
  • Or you can modify JBoss's run.conf or properties-service.xml:
    • See Setting Java System Properties in JBoss.


• Start JBoss, eg.
  ...in Windows:
  • cd /devel/jboss-5.0.1.GA/bin
  • run.bat -c jumpstart
  ...in tcsh (the default shell in OS X Terminal):
  • cd /devel/jboss-5.0.1.GA/bin
  • ./run.sh -c jumpstart


• When you start JBoss you might wish to enable remote access to the web site from other computers:
  
  • Starting with JBoss 4.2.0, remote access is turned off by default (is this still true in JBoss 5?). JBoss does this by binding all its services to localhost (127.0.0.1). A quick way to enable remote access is to bind JBoss to all available network interfaces (0.0.0.0), which is what JBoss used to do.
  • To enable remote access, when you start JBoss you specify -Djboss.bind.address=0.0.0.0 as a parameter, eg.
        run.bat -c jumpstart -Djboss.bind.address=0.0.0.0
        ./run.sh -c jumpstart -Djboss.bind.address=0.0.0.0
    You cannot specify this in JAVA_OPTS - it won't work.
  • Security risk: There is a security risk with this setting: it exposes various parts of JBoss including the jmx-console and web-console to remote access. Depending on your needs you may wish to secure the JMX Console and Web Console.
  • Clustering is not affected: the clustering address is specified by a different system property, bind.address, eg.
        run.bat -Djboss.bind.address=10.10.10.1 -Dbind.address=10.10.10.2 .


• Enhance Tapestry's classpath resolver: in the JumpStart project's web/src/main/java/jumpstart/web/services/AppModule.java file, ensure the ClasspathURLConverterJBoss5 line is active and the alternatives are not active, like this:
  • configuration.add(ClasspathURLConverter.class, new ClasspathURLConverterJBoss5());
  • // configuration.add(ClasspathURLConverter.class, new ClasspathURLConverterJBoss60());
  • // configuration.add(ClasspathURLConverter.class, new ClasspathURLConverterJBoss61());


• Set the build properties: in the JumpStart project's build.properties file, edit the value of these properties:
  • deployment.server.type
  • deployment.persistence.descriptor
  • deployment.web.descriptor
  • deployment.server.dir

Build and deploy JumpStart

Here we use Ant to clean, compile, unit test, package, deploy to the server, and wait for it to load.
The deployed package is jumpstart.ear.

• In Eclipse, drag build.xml to the Ant view and run its target clean-compile-test-package-deploytoserver-checkactive.
• If you get an error about JAVA_HOME, read this. Use a JDK 1.6 tools.jar.

Build and deploy and integration test JumpStart

Here we use Ant to clean, compile, unit test, package, deploy to the server, wait for it to load, and run the business integration test suite.
The deployed package is jumpstart.ear. The tests remotely call the JumpStart business layer services exposed by the server.

• In Eclipse, drag build.xml to the Ant view and run its target clean-compile-test-package-deploytoserver-integrationtest.
• If you get an error about JAVA_HOME, read this. Use a JDK 1.6 tools.jar.

Use JumpStart

Ensure the command line is using Java 1.6: the commands java -version and javac -version must return a variant of 1.6, eg. 1.6.0_24.

If JBoss is not running, start it (as above).

Before you use JumpStart for the first time in a new server, you need to build it, deploy it, and run the integration tests.

Populate the Hypersonic database (HSQLDB) within JBoss with data. JBoss provides a handy way to open the HSQL Database Manager:

• Point your web browser at http://localhost:8080/jmx-console/
• Click on database=localDB,service=Hypersonic
• Find the section labelled startDatabaseManager
• Click on Invoke.
• In a few moments a Java GUI called HSQL Database Manager will start up. Note that it will only start on the machine that JBoss is in. It cannot be used on a "headless" server.
• In Eclipse, locate business/src/test/data/initial_data.sql in the project. Open it.
  In JumpStart 5.7.2 to 5.10.0 (inclusive), the file is not suitable to use with HSQL Database Manager, so replace the file's contents with the contents of this.
• Copy the contents of business/src/test/data/initial_data.sql into the HSQL Database Manager.
• Click on Execute SQL.

Now you can visit JumpStart with your web browser at http://yourserver:8080/jumpstart.

How to run integration tests from Eclipse

First, build and deploy JumpStart as described above.

Second, create a User Library over JBoss:

• In Eclipse, choose Window > Preferences > Java > Build Path > User Libraries (or in OS X, choose Eclipse > Preferences > Java > Build Path > User Libraries), and
• Create a new user library called jboss-5.0.1-client-lib, then
• Add these JBoss jars to the new user library:
  • client/jbossall-client.jar
  • common/lib/hibernate-core.jar

Third, run the business integration test suite from Eclipse:

Choose Run > Run Configurations.... The relevant window will appear. Right-click on JUnit and choose New. Set Test Runner to JUnit 4. Set the other variables to values similar to those shown in the screen shot on the right.

Click on the Classpath tab. Remove the (default classpath) entry. Click on User Entries. Add folder business/src/test/conf-remote-jboss/ . Add folder collapsed/jumpstart.war/WEB-INF/classes/ or, if you're using an exploded EAR then add folder exploded/jumpstart.ear/jumpstart.jar/ . Add user library jboss-5.0.1-client-lib. Add all JARs from these folders: business/src/main/lib-compile/ business/src/main/lib-runtime/ (actually, it's empty) business/src/test/lib-test/ Move the two folders to the top. It avoids conflicts.

• Click Run.
• Watch the results in the JUnit View panel. In the Console View you might see lots of exceptions but that's normal. The JUnit View will tell you quickly whether the tests succeeded or not.
• Problems? Eclipse might not be ready for junit - see Could not create task or type of type: junit.

How to debug the client side

To debug, for example, the client side of the integration tests, use Run > Debug Configurations... instead of Run > Run Configurations.... Eclipse will then stop at breakpoints, display variables, enable single-stepping, etc. in the test suite.

How to debug the server side

To debug any part of JumpStart as it runs in the server you'll need to be running JBoss in debug mode. There are a couple of ways to do it:

• Start JBoss in debug mode

  We'll use port 8787 in this explanation, but it's OK to use any free port.

  Earlier, we described setting various JVM options. To run JBoss in debug, include these JVM options:

  -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y

  Restart JBoss, and you will see it pauses at this message:

  Listening for transport dt_socket at address: 8787

  In Eclipse, right-click on your project and choose Debug As > Debug Configurations... and the Debug Configurations window will appear.

  1. Right-click on Remote Java Application and choose New.
  2. Set the Port to 8787.
  3. Enable Allow termination of remote VM.
  4. Click on Debug.

  JBoss resumes startup, and Eclipse will now stop at breakpoints, display variables, do single-stepping, etc. on any Java in the project.

• Control JBoss server from Eclipse
  
  In Eclipse's Server view, add your JBoss 5.0 server.
  
  You can set the JVM options, as described above, by right-clicking on the server entry and choosing Open > Open launch configuration > Arguments.
  
  You can start the server by right-clicking on the server entry and choosing Start or Debug.