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.
- 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
- choose Window > Preferences > General > Editors > File Associations (or in OS X, choose Eclipse > Preferences > General > Editors > File Associations), and
- in File types, add *.tml.
- in Associated Editors, add HTML Editor, Web Page Editor, Web Browser, and Text Editor,
- click OK.
- choose Window > Preferences > General > Content Types (or in OS X, choose Eclipse > Preferences > General > Content Types), and
- in Content types, choose Text > HTML,
- in File associations, add *.tml.
- click OK.
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:
- Open the Eclipse update facility (Help > Install New Software).
- Click Add.... The Add Site dialog will appear.
- Set Name to Loom.
- Set Location to http://digitalsoul.org/loom/update-site. Click OK.
- Choose the site from the list (I use the stable release, 1.0.2) and click Next >, then Next >, then read the license text, accept it, and click Finish.
- Loom will be installed.
- Choose Window > Preferences > Loom (or in OS X, choose Eclipse > Preferences > Loom), and
- Select .tml and click Apply.
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">
Run with Ant
- Run the Ant target clean-compile-test in the project's build.xml file.
- If you get an error about JAVA_HOME, read this. Use a JDK 1.5 tools.jar.
Run as JUnit Test in Eclipse
- Here are the instructions for unit test in eclipse
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
- Here are the instructions for integration test in eclipse with embedded OpenEJB.
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.
- In the project's data_util.properties file, set the properties hsqldb.data.dir and hsqldb.jar.dir.
- With the data_util.xml file in the Ant view, run the target start-hsqldb-manager.
- In a few moments the HSQL Database Manager will start up.
- Point your web browser at the JMX console, eg. http://localhost:8080/jmx-console/.
- Click on database=localDB,service=Hypersonic.
- Find the section labelled void startDatabaseManager().
- Click on Invoke.
- In a few moments the HSQL Database Manager will start up. Note that it will start on the machine that JBoss is running.
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:
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.
- 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.
- 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
- 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.
- 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.
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.
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...
- server type (eg. glassfish 2.1, tomcat 6.0 or 5.5, JBoss 5.0.1) AND
- persistence provider (eg. hibernate) AND
- database server type (eg. hsqldb, mysql, derby).
- web.xml is different for Glassfish because Glassfish requires ejb-local-refs elements.
The build finds this alternative web.xml from web/src/main/java/jumpstart/web/WEB-INF/
- persistence.xml varies based on the combination of deployment server type, persistence provider, and database server type.
The build finds these alternatives in business/src/main/resources/persistence-descriptor/
- The package is an EAR file for Glassfish and JBoss.
- The package is a WAR file for Jetty and Tomcat,
in "collapsed EAR" format.