Tips

These tips cover JumpStart 4.12.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 very out of date.

Contents

JVM options.

Editing .tml files.
Use Loom.

Testing: WAR or EAR?
Unit tests.
Integration tests.
 The database.
Viewing and editing data.
Logging SQL and Hibernate.

Altering the database schema.
Rebuilding the database and schema.

MySQL.
Other database brands.
 Creating a fresh project.

Other servers:
  Glassfish 2.1
  Tomcat 6.0 or 5.5
  JBoss 5.0.1

Portability

JVM OPTIONS

  • Set JVM options:
    • When running Jetty we already set several JVM options, including -Dtapestry.production-mode=false and -Dhibernate.hbm2ddl.auto=update
      Here are some to consider:
      -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. See Configuring Tapestry.
      -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. See Configuring Tapestry.
      -Dhibernate.hbm2ddl.auto=update Necessary for JumpStart initially, and 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. See hibernate optional configuration properties.
      -Xms192m -Xmx192m Gives more memory for the heap, avoiding "out of memory" errors. See JVM options.
      -XX:MaxNewSize=96m -XX:MaxPermSize=96m Gives more Perm Gen memory. If you encounter Perm Gen memory errors then consider this or an even higher setting. See JVM options

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

    USE LOOM
    Loom is a delight to use. It's an Eclipse plug-in that allows you to switch between a template and a java file by using a keyboard shortcut (Ctrl+Alt+X). To install it:

    Now open a page's .tml or .java file and try the keyboard shortcut.

    TESTING: WAR OR EAR?
    By default, the project automatically builds a WAR file for testing with Jetty. It's in a directory called collapsed/ and its format is "collapsed EAR", which is nice and simple. It's automatically kept up-to-date by a builder called collapser which you can see by displaying the project's properties and choosing Builders.

    If you prefer, the project can automatically build an "exploded EAR" file which is readable by JBoss (and Glassfish?) and, for that matter, Jetty. It goes in a directory called "exploded/" and it can be automatically kept up-to-date by a builder called exploder which you can see by displaying the project's properties and choosing Builders. Just select exploder and, if you like, de-select collapser .

    Set collapsed and/or exploded directory to derived. In Eclipse, right-click on the collapsed or exploded directory, choose Properties, and tick the derived checkbox. Then click OK.

    To run the collapsed EAR in Jetty, follow the instructions on the installation page.

    To run the exploded EAR with JBoss, configure your JBoss server to scan the exploded/ directory, which you can do by editing the server's conf/bootstrap/profile.xml file to add the exploded/ directory to the "VFSDeploymentScanner" bean, eg. 

    <!-- Scan for applications -->
<bean name="VFSDeploymentScanner" class="org.jboss.system.server.profileservice.VFSDeploymentScannerImpl">
   <property name="profileService">
   <property name="filterInstance">
   <property name="URIList">
      <list elementClass="java.net.URI">
         <!-- Standard hot deployment directory -->
         <value>${jboss.server.home.url}deploy/,/devel/jumpstart/exploded/
      </list>
    </property>
</bean>

    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

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

    Run as JUnit Test in Eclipse

    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 data sources 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 other servers.

    For running in JBoss, the build script puts a configuration file called jumpstart-hsqldb-ds.xml in deploy/. The file maps the JNDI names to an HSQLDB database.

    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.

    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 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. This seems like an oversight, but in fact is probably just right because it forces you to make your test environment match your production environment.

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

    MYSQL
    JumpStart has been tested with HSQLDB, MySQL, and Derby. 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's HibernatePersistenceExceptionInterpreter does its best to cope with this, but MySQL gives it much more specific exceptions to work with.

    To develop using MySQL see using MySQL in development.

    To make deployable packages suited to MySQL, follow the instructions in other servers.

    OTHER DATABASE BRANDS
    To use a database type other than HSQLDB, MySQL, or Derby, you may have to add some logic to the class HibernatePersistenceExceptionInterpreter 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.

    To develop using that database the steps will be very similar to using MySQL in development.

    To make deployable packages suited to that database, follow the instructions in other servers.

    CREATING A FRESH PROJECT
    Choose a project name, root package name, etc., then edit the values in tools/tools.properties . Drag tools/tools.xml to the Ant view and run the target create-fresh-project. 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 2 onwards of Installation.

    OTHER SERVERS
    The following links show how to prepare other servers and how to build, deploy and test JumpStart on them:

    PORTABILITY
    The package produced by a build is tailored to a particular server type, persistence provider, and database server type.
    So can a package be moved between servers? Yes, but only if they have the same...

    You tailor the build by editing the build.properties file. Here's what it affects:

     

    ©2006, 2007 Geoff Callender, Sydney, Australia