Tips

These tips are for v4.2.n.

Some other excellent resources are the Tapestry 5.0 How-To Page, and the Tapestry User mailing list which is archived and searchable at gmane, and nabble. Also, the book Tapestry 5: Building Web Applications by Alexander Kolesnikov, although it is getting a bit out of date.

Editing .tml files.

The database.
Viewing and editing data.
Logging SQL and Hibernate.

Unit tests.
Deployment servers:
  JBoss 4
  Glassfish 2.1
  Tomcat 5.5 or 6.0
Integration tests.
Creating a fresh project.

Altering the database schema.
Rebuilding the database and schema.
HSQLDB vs MySQL and others.
Switching database brands.



JBoss startup options.
  Increase heap size.
  Increase Perm Gen memory size.
  Prefer IPV4.
  Enabling remote access.




EDITING .tml FILES
Any HTML editor will do. In Eclipse, associate .tml files with the HTML editor:

THE DATABASE
JumpStart session beans specify to use a persistence unit called jumpstart.
The persistence.xml file maps jumpstart to 1 or 2 data sources. Their JNDI names are java:/JumpStartDS and java:/JumpStartDSUnmanaged.

By default, OpenEJB overrides the JNDI names to its own which use the Hypersonic database in OpenEJB's data/hsqldb/ directory. This is handy.
To override this behaviour, supply an openejb.xml configuration file. You can see this being done in the integration tests.

When running in JBoss, a jumpstart-ds.xml configuration file maps the JNDI names to a database. The file goes in the server's deploy/ directory.

VIEWING AND EDITING DATA
Hypersonic provides a handy GUI tool for viewing the database and executing SQL requests, the HSQL Database Manager. To use it:

To view and edit an HSQLDB that runs in JBoss, JBoss provides a handy way to open the HSQL Database Manager:

LOGGING SQL AND HIBERNATE
Logging is configured by log4j.properties in business/src/dev/conf/.

To log SQL statements, add Alternatively, to log everything Hibernate is doing, including SQL statements, schema export, transactions, etc., try For finer control of Hibernate logging, see the section on Logging here.

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.

UNIT TESTS
JumpStart has a simple unit test suite in the business tier. Its name is BusinessUnitTestSuite. You can run it as a JUnit Test in Eclipse, or in Ant.

Run with Ant

Run as JUnit Test in Eclipse

DEPLOYMENT SERVERS
JumpStart is usually developed in Eclipse with an in-line Jetty server...

...but the build script produces packages suitable for deployment to the following server environments: You can learn how to create a server environment and the right package for it by following the Integration Tests instructions

The package has to be a little bit different depending on the type of server we're deploying to. In addition, three classes automatically vary their behaviour depending on the server type:

INTEGRATION TESTS
JumpStart's integration test suite confirms the business layer is operating correctly and reporting all possible exceptions correctly. Its name is BusinessIntegrationTestSuite.

A good place to start with the integration tests is to run and/or debug them in Eclipse. This uses embedded OpenEJB and an in-memory HSQLDB.

Later you would test them against an integration test server of the same type as your production server, with the same database type as your production server.

CREATING A FRESH PROJECT
Choose a project name, root package name, etc., then edit the values in tools/tools.properties . Run the Ant target create-fresh-project in the tools/tools.xml file. A new project will have been created with an Index page, Login page, the User and UserPassword entities and a few pages to maintain them. Then do much the same as you did from Step 5 onwards of Installation.

ALTERING 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 hibernate.hbm2ddl.auto property in 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 SCHEMA
Some changes don't seem to propagate to the database schema, for example switching a field from nullable=false to nullable=true. 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 Altering 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.

HSQLDB VS. MySQL AND 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 HSQLDB or MySQL you may have to add some logic to the class HibernateExceptionInterpreter in business/src/main/java/jumpstart/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 integration tests.

SWITCHING DATABASE PRODUCTS
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.

JBOSS STARTUP OPTIONS
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:

 

©2006, 2007 Geoff Callender, Sydney, Australia