These tips are for v1.5.0 to v2.0.0.
Some other excellent resources are the Tapestry 4.0 How-To Page, the forum at gmame, and its equivalent at nabble.

Startup options.
  Auto-reload HTML and .page files.
  Increase heap size.
  Increase Perm Gen memory size.
  Prefer IPV4.
  Enabling remote access.

Auto-reload web programs.
Reload the entire app without restarting.

Business tests.
Web tests.
Logging SQL and Hibernate.
Debugging and single-stepping.

Default database.
Creating/updating the database schema.
Rebuilding the database and schema.
Hypersonic Database Manager.
Using MySQL vs HSQLDB vs others.
Switching database brands.

Table Component.
Uncluttering HTML templates.

Packaging an EAR.
No JBoss.

Startup Options. During development, here are some useful startup options to use for running JBoss.
In Windows:

In tcsh (the default shell in OS X Terminal):

Their purpose is:

Auto-reload web programs. To make Tomcat reload your Java programs in the web tier automatically as you change them, modify the JBoss server's deploy/jboss-web.deployer/context.xml to include reloadable="true" in the Context tag, eg.

The reloading may be delayed a couple of seconds, and if you're too quick to use the page you might get a HTTP Status 404 error (page not found), but if you then hit the Back button and try again you will usually succeed.

Do not make this change in production. The application will slow as you make more and more changes but this is often a worthwhile trade-off during development. Eventually the JVM may run out of memory - you may have to combat this by increasing the Perm Gen memory and heap size. The reason for this is explained in PermGen space . The way to increase it is described below in other startup options.

Reload the entire app without restarting. To make JBoss reload the entire application (ie. the whole EAR) there is no need to restart JBoss or even to copy any files around. Instead, just run the Ant target touch-exploded-ear in JumpStart's build.xml file. On Unix-based systems you can touch exploded/jumpstart-min.ear/META-INF/application.xml. JBoss will detect the change in a couple of seconds and hot deploy the whole app. You can see it happening in the log.

Business Tests. JumpStart Max includes an automated suite of tests to confirm the business layer is operating correctly and reporting all possible exceptions correctly. The test suite is found at business/src/test/java/jumpstart/max/business/BusinessTestSuite.

To run the business tests, first make sure JumpStart is running in JBoss, then either

Problems? Eclipse might not be ready for junit - see Could not create task or type of type: junit.

Web Tests. JumpStart Max includes an automated suite of web layer tests. The tests are not exhaustive but they do visit every page and try every link and button - except in tables they only try the links and buttons in the first two rows. They are "smoke tests". The web test suite is found at web/src/test/selenium/smoke-test/TestSuite.html.

To run the web tests, first make sure JumpStart is running in JBoss, with disable-caching=false (see reloading HTML and .page files automatically. You will also need Firefox:

To edit the web tests, it's worth having Selenium IDE, which is a Firefox add-on:

Logging SQL and Hibernate. To log SQL statements, modify the JBoss server's conf/log4j.xml to include

Alternatively, to log everything Hibernate's doing, including SQL statements, schema export, transactions, etc., try

You will also have to change the logging threshold of the CONSOLE appender from INFO to DEBUG. Alternatively, to avoid cluttering up the console log, create a new appender definition called, say, HIBERNATE, by copying one of the appender definitions called FILE (look for appender name="FILE"). Then define your new category like this:

The new log will appear in the server's log/ directory when the first entry is written to it.

Debugging and single-stepping. To single-step through the code you'll need to be running JBoss in debug mode. There are a couple of ways to do it:

Default database. By default, JumpStart uses the data source whose JNDI name is DefaultDS and JBoss has DefaultDS configured to be a Hypersonic SQL database. See hsqldb-ds.xml in your server's deploy/ directory.

Creating/updating the database schema. The schema is defined by the classes containing the @Entity annotation. By default, JumpStart will automatically create/update the database schema to match. That includes creating tables and constraints when necessary. This behaviour is controlled by the property in persistence.xml (jumpstart-min.ear/jumpstart-min.jar/META-INF/persistence.xml).

Unfortunately, you can't just override the behaviour at runtime eg. with some settings in a properties file in the conf/ directory. It seems that either JBoss/Hibernate (or the EJB3 spec?) requires the Hibernate settings to be specified in persistence.xml, and the EJB3 spec requires persistence.xml to be inside the ear file. Hopefully this situation will change soon.

Rebuilding the database and schema. Some changes, like switching a field from nullable=false to nullable=true, don't seem to propagate to the database schema, so at times you may decide to rebuild the schema.

  1. Backup the data This is optional, but the next step will delete all your data. The initial JumpStart data is re-loadable in step 4.
  2. Drop the tables Use JumpStart's drop_tables.sql script, or modify it to suit. If your database is JBoss's Hypersonic, use the HSQL Database Manager
  3. Create the tables Either run the ant target touch-exploded-ear in JumpStart's build.xml, or restart the JBoss server. See Creating/updating the database schema above for details.
  4. Restore the data or re-load the initial data If you backed up the data in step 1, then you can restore it now. Alternatively, re-load the initial data with JumpStart's initial_data.sql script.

Hypersonic Database Manager. JumpStart's default database type is JBoss's Hypersonic. A handy way to open the Hypersonic Database Manager is by pointing your web browser at http://localhost:8080/jmx-console/, click on database=localDB,service=Hypersonic, find the section labelled void startDatabaseManager() and click on Invoke. In a few moments a Java GUI called HSQL Database Manager will start up.

Using MySQL vs HSQLDB vs others. JumpStart has been tested with HSQLDB and MySQL. HSQLDB is very convenient but, in general, MySQL returns better exception information for JumpStart to work with. For example, a simple duplicate key situation in HSQLDB can result in a "failed JDBC batch" and no further information. JumpStart does its best to cope with this.

To use a database type other than MySQL or HSQLDB you may have to add some logic to the class in business/src/main/java/jumpstart/min/business/commons/interpreter/. It's a custom class responsible for interpreting vague exceptions like "constraint violation" into specific JumpStart exceptions. After modifying it, verify it is operating correctly with your database by running the unit tests.

Switching database brands. See the notes above on MySQL vs HSQLDB vs others. To switch database brands:

Unfortunately, you can't just override the database type at runtime eg. with some settings in a file in the conf/ directory. It seems that JBoss/Hibernate requires the database "dialect" to be specified in persistence.xml, and the EJB3 spec requires persistence.xml to be inside the ear file. Hopefully this situation will change soon.

Table Component. Three excellent resources for understanding the Table component that's used in the Search pages:

client:form. Favour @Persist("client:form") over @Persist("client"). The latter will encode the persisted properties into the URL of every link, not just those in the form. For example, a page that has 50 links in its navigation bar and a form that needs to persist 1k of data: if @Persist("client:form") is used then the page size increases by 1k, but if @Persist("client") is used then the page size increases by a whopping 51k. The pros-and-cons are discussed here. Both strategies are available in JumpStart.

Uncluttering HTML templates. In JumpStart we chose to put all the parameters of each component in the .html file, but if you or your web designers find this is too cluttered you should consider moving them to annotations in the java or to .page files.

Packaging an EAR. There's an Ant target called package in the build.xml file. It creates file /tmp/jumpstart.ear which you can deploy by dropping into any JBoss deploy/ directory.

No JBoss. A couple of alternatives to consider:
(1) No app server - just the lightweight JBoss Embeddable EJB 3.0 container. It strays from the final EJB3 API in a couple of places (JBoss has work to do) so you would have to temporarily modify JumpStart in a couple of places. Verify the mods with the unit tests.
(2) JBoss MC (MicroContainer). This looks set to replace the Embeddable container above, with work on it having resumed in mid-2007, but I have not seen release dates.
(3) A different EJB3 app server, eg. GlassFish. In theory this would this would be possible with just 4 modifications:

Either way, you can verify it is operating correctly by running the unit tests.


©2006, 2007 Geoff Callender, Sydney, Australia