USING JUMPSTART IN TOMCAT 7.0

These notes apply to Tomcat 7.0 within Apache TomEE+ 1.5.n. They were tested with apache-tomee-1.5.1-plus and JumpStart 6.9.0.

Contents
Prepare Tomcat
Build and deploy JumpStart
Build, 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 Tomcat
These instructions prepare Tomcat with the following elements:

Web Server	Business Server	Persistence	Database Server	Logger
Tomcat	OpenEJB3	Hibernate	HSQLDB	Log4j
(Part of TomEE)	(Part of TomEE)	(Added by us)	(Part of TomEE)	(Added by us)

• Start by installing Apache TomEE+, which is Tomcat with embedded OpenEJB:
  You could install standard Tomcat 7.0 and add OpenEJB, but for simplicity we will install Apache TomEE. Here is a comparison of the options.
  1. Go to Apache TomEE Downloads and, from the Plus section, download apache-tomee-1.5.n-plus.zip.
  2. Unpack the archive.
  3. Move the unpacked directory to your somewhere suitable, eg. /devel/apache-tomee-plus-1.5.n
  4. Change directories to the tomcat directory, eg. cd /devel/apache-tomee-plus-1.5.n
  5. If on Unix/Linux/OS X, make the binaries executable: chmod u+x bin/*.sh
  6. If on Windows, set the JAVA_HOME environment variable: set JAVA_HOME=C:\your\java\installation
  7. Start Tomcat, eg.
     ...in Windows:
     • cd bin
     • startup.bat
     ...in Unix/Linux/OS X:
     • cd bin
     • ./startup.sh
  8. Verify Tomcat is running: in a browser visit http://localhost:8080/ and you should see the Tomcat welcome page.
  9. Stop Tomcat, eg.
     ...in Windows:
     • shutdown.bat
     ...in Unix/Linux/OS X:
     • ./shutdown.sh


• Add Hibernate to Tomcat:
  • Open the JumpStart project's data_util.properties file and modify the property add.hibernate.to.dir eg. to /devel/apache-tomee-plus-1.5.n/lib .
  • Drag data_util.xml to the Ant view and run its target add-hibernate-to-a-server.
  • Check Tomcat's lib/ now has the Hibernate jars, eg. hibernate-core-n.n.n.jar.


• Modify the data source:
  • Open ${catalina.base}/conf/tomee.xml for edit.
  • Find the 2 DataSource entries.
    The entries point to an HSQLDB with this URL: jdbc:hsqldb:file:data/hsqldb/hsqldb . The database already exists in ${catalina.base}/data/hsqldb/.
    There is a problem - the URL uses a relative path to the database, file:data/hsqldb/hsqldb.
    The database will not be found if you start Tomcat from ${catalina.base}/bin/ or any directory other than ${catalina.base}!
  • Change the paths to absolute paths, eg. file:/devel/apache-tomee-plus-1.5.1/data/hsqldb/hsqldb; save, and exit.
    


• Add log4j. Actually, this needs investigation. It does not succeed in overriding OpenEJB's logging defaults. If you find a solution please please send it here.
  • From business/src/main/resources/conf-log4j-server-side/, copy log4j.properties to Tomcat's lib/.


• 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.
    -Dtapestry.application-version=xxxx	RECOMMENDED FOR A PRODUCTION ENVIRONMENT. It is explained here.
    -Dtapestry.hmac-passphrase=xxxx	ESSENTIAL FOR A PRODUCTION ENVIRONMENT. It is explained here.
    -Dupload.filesize-max=8000000	ESSENTIAL for JumpStart. Tells Apache Commons Upload to limit the size, in bytes, of upload files.
    -Djumpstart.upload-path=/tmp	ESSENTIAL for JumpStart. 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.
    -Djava.naming.factory.initial= org.apache.openejb.client.LocalInitialContextFactory -Djava.naming.factory.url.pkgs=org.apache.openejb.core.ivm.naming	Normally we'd provide a jndi.properties file in a configuration directory on the classpath, but Tomcat doesn't work that way, so an alternative is to use system properties instead.
    -server	Chooses the "server" JVM (which is optimised for speed).
    -Xmx256m	Gives the JVM more heap memory (to avoid "out of memory" errors).
    -XX:MaxPermSize=96m	Gives the JVM more Perm Gen memory. If you encounter Perm Gen memory errors then consider this or an even higher setting.

  • You can set them from the command line:
    ...eg. in Windows:
    • set CATALINA_OPTS=-Dtapestry.production-mode=false -Dtapestry.compress-whitespace=false -Dupload.filesize-max=8000000 -Djumpstart.upload-path=/tmp -Dhibernate.hbm2ddl.auto=update -Djava.naming.factory.initial=org.apache.openejb.client.LocalInitialContextFactory -Djava.naming.factory.url.pkgs=org.apache.openejb.core.ivm.naming -server -Xmx256m -XX:MaxPermSize=96m
    ...eg. in bash (the default shell in OS X Terminal since 10.3):
    • export CATALINA_OPTS="-Dtapestry.production-mode=false -Dtapestry.compress-whitespace=false -Dupload.filesize-max=8000000 -Djumpstart.upload-path=/tmp -Dhibernate.hbm2ddl.auto=update -Djava.naming.factory.initial=org.apache.openejb.client.LocalInitialContextFactory -Djava.naming.factory.url.pkgs=org.apache.openejb.core.ivm.naming -server -Xmx256m -XX:MaxPermSize=96m"


• Start Tomcat, eg. from the command line like this:
  ...in Windows:
  • cd /devel/apache-tomee-plus-1.5.n/bin
  • startup.bat
  ...in Unix/Linux/OS X:
  • cd /devel/apache-tomee-plus-1.5.n/bin
  • ./startup.sh


• 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.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.war.

• 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 7 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.war. 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 7 tools.jar.

Use JumpStart

Ensure the command line is using Java 7: the commands java -version and javac -version must return a variant of 1.7, eg. 1.7.0_21.

Start Tomcat (as above).

Confirm Tomcat is using Java 7: when you start Tomcat it returns 5 messages, with one giving the JRE_HOME path. The JRE_HOME must be a Java 1.7 JRE or JDK. If it is not, then shut down Tomcat and fix this before proceeding.

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

Stop Tomcat (as above).

Populate the HyperSQL DataBase (HSQLDB) within Tomcat: in Eclipse...

• Open the data_util.properties file and modify the property database.url.
  Use a relative path eg. jdbc:hsqldb:file:/devel/apache-tomee-plus-1.5.1/data/hsqldb/${database.name} .
• With the data_util.xml file in the Ant view, run its target start-hsqldb-manager.
• Execute the SQL found in business/src/dev/data/initial_data.sql . Using copy and paste is fine.
• Exit the HSQLDB Database Manager. This clears its lock on the database.

Start Tomcat (as above).

When the server is running 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 Tomcat:

• 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 tomcat-7.0-client-lib, then
• Add these Tomcat server jars to the new user library:
  • lib/openejb-client-4.*.jar.
  • lib/hibernate-commons-annotations-4.*.jar
  • lib/hibernate-core-4.*.jar
  • lib/hibernate-entitymanager-4.*.jar
  • lib/javassist-3.*.jar
  • lib/jboss-logging-3.*.jar.
  • lib/jboss-logging-processor-1.*.jar.

Third, run or debug the business integration test suite from Eclipse:

Choose Run > Run Configurations... or Run > Debug 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-tomcat/ . Add folder collapsed/jumpstart.war/WEB-INF/classes/ . Add all JARs from these folders: business/src/main/lib-compile/ business/src/main/lib-runtime/ (actually, lib-runtime is empty) business/src/test/lib-test/ Add user library tomcat-7.0-client-lib . 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 Tomcat in debug mode. There are a couple of ways to do it:

• Start Tomcat 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 Tomcat in debug, include these JVM options:

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

  Restart Tomcat, 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.

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

• Control Tomcat server from Eclipse
  
  See TomEE and Eclipse.
  
  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.