Tips

These tips cover JumpStart 6.11.n.

Some other excellent resources are the Tapestry 5 How-To Page, and the Tapestry User mailing list which is archived and searchable at nabble and gmane. Also, these books.

Contents

JVM options.

Editing .tml files.
Use Loom.
Tapestry Tools plugin.

Debugging.

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:
  JBoss 7.1
  Tomcat 7.0
  GlassFish 3.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.
      -Xmx192m Gives more memory for the heap, avoiding "out of memory" errors. See JVM options.
      -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, first check you have the right web tools installed:

    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.

    TAPESTRY TOOLS PLUGIN
    Tapestry Tools is an Eclipse plugin giving content assist and more. It is reported to work fine with Helios and Indigo, but may have some wrinkles with Juno (see discussion at Nabble).

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

    To debug any part of JumpStart while running it in Eclipse (with RunJetty), use Run > Debug Configurations... instead of Run > Run Configurations.... Eclipse will then stop at breakpoints, display variables, enable single-stepping, etc.

    Source not found. At a breakpoint, Eclipse might display Source not found. Click Edit Source Lookup Path... > Add... > Java Project, select your jumpstart project and click OK, then OK again.

    Tapestry source. To read, step through, or debug Tapestry source you'll first need to download it from Tapestry 5 Download. Then unzip/untar/whatever it into your development directory, eg. /devel/tapestry-src-5.2.6.

    In Eclipse, choose File > Java Project, deselect Use default location, click Browse... and choose the Tapestry source folder. If Eclipse now complains that the project "overlaps the location of another project", re-select Use default location. Click Finish. The Tapestry source project will not compile, but that doesn't matter. Now you can find components and put breakpoints in them.

    As always at the first breakpoint, Eclipse might display Source not found. Click Edit Source Lookup Path... > Add... > Java Project, select the Tapestry source project and click OK, then OK again.

    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.

    In the past, JumpStart was also able to build an "exploded EAR" file which is readable by JBoss (and GlassFish?) and, for that matter, Jetty. This facility is no longer supported in JumpStart but the source, exploder.xml, is still present in the project for those who find it useful.

    Set the collapsed directory to derived. In Eclipse, right-click on the collapsed 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.

    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 HyperSQL 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 H2 database.

    VIEWING AND EDITING DATA
    HyperSQL 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 H2 database in JBoss, see Using JumpStart in JBoss.

    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 H2, see Using JumpStart in JBoss.
    3. Create the tables 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, H2, Derby, and MySQL. HSQLDB and H2 are 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" exception and no further information. JumpStart's class HibernatePersistenceExceptionInterpreter does its best to cope with this, and MySQL gives it much more specific exceptions to work with.

    Before switching to MySQL in another server, it is recommended to do it in your development environment first...

    To switch your development environment to use MySQL see using MySQL in development.

    There are 4 key ingredients to making JumpStart work with MySQL:

    Now build, deploy, and test JumpStart with MySQL:

    OTHER DATABASE BRANDS
    JumpStart has been tested with HSQLDB, H2, Derby, and MySQL. If you wish to modify JumpStart to work with another database type, it is probably best to base your modifications on JumpStart's handling of MySQL. See MYSQL.

    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, 2012 Geoff Callender, Sydney, Australia