Tips
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.
client:form.
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:
- set JAVA_OPTS= -XX:MaxNewSize=96m -XX:MaxPermSize=96m -Xms128m -Xmx128m -Dorg.apache.tapestry.disable-caching=true
- run.bat -Djboss.bind.address=0.0.0.0
In tcsh (the default shell in OS X Terminal):
- setenv JAVA_OPTS '-XX:MaxNewSize=96m -XX:MaxPermSize=96m -Xms128m -Xmx128m -Djava.net.preferIPv4Stack=true -Dorg.apache.tapestry.disable-caching=true'
- run.sh -Djboss.bind.address=0.0.0.0
Their purpose is:
- Auto-reload HTML and .page files: -Dorg.apache.tapestry.disable-caching=true tells Tapestry to reload the HTML and .page files automatically as you change them. By default this property is set to false, telling Tapestry to cache and reuse pages. When set to true, the application will run slower - so do not try this in production - but it's a worthwhile trade-off during development. This option is discussed along with many others in http://tapestry.apache.org/tapestry4/UsersGuide/configuration.html.
- Increase Java heap size: -Xms128m -Xmx128m gives JBoss more memory for its heap, avoiding "out of memory" errors.
- Increase Perm Gen memory: -XX:MaxNewSize=96m -XX:MaxPermSize=96m gives the Tomcat server inside JBoss more Perm Gen memory. If you encounter Perm Gen memory errors as you make mods to the app then consider raising this higher.
- Prefer IPv4: -Djava.net.preferIPv4Stack=true may speed up JBoss startup on some Unixes (clustered AIX?) or other operating systems that have IPv6 enabled by default.
- Enabling remote access:
-Djboss.bind.address=0.0.0.0
is a quick way to enable remote access to JumpStart from another computer.
Starting with JBoss 4.2.0, remote access is turned off by default.
JBoss does this by binding all its services to localhost (127.0.0.1).
A quick way to enable remote access is to bind JBoss to all available network interfaces (0.0.0.0),
which is what JBoss used to do.
Not for JAVA_OPTS: -Dbind.address must be specified as a parameter to run.bat or run.sh and not in JAVA_OPTS because it won't work.
Security risk: Be aware of the security risk of this setting - it exposes various parts of JBoss including the jmx-console to remote access. Depending on your needs you may still need to secure JBoss properly.
Clustering is not affected: the clustering address is specified by a different system property, bind.address, eg. run.sh -Djboss.bind.address=10.10.10.1 -Dbind.address=10.10.10.2 . Not for JAVA_OPTS: Do not try specifying -Djboss.bind.address or -Dbind.address in JAVA_OPTS (see next item) because it won't work. They must be specified as parameters to the run.bat or run.sh.
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.
-
<Context cookies="true" crossContext="true" reloadable="true">
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
- run them interactively (right-click on BusinessTestSuite and choose Run As > JUnit Test); or
- run the Ant task test-business in the build.xml file
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 get Firefox, go to Mozilla.
- To run the suite of tests, open Firefox and go to
http://localhost:8080/jumpstart-max/selenium/core/TestRunner.html?test=../tests/smoke-test/TestSuite.html
The screen you see is the Test Runner. The exploder includes it in the WAR file in a directory called selenium/. - There's documentation on Test Runner and Selenium Core at Usage and Selenium.
To edit the web tests, it's worth having Selenium IDE, which is a Firefox add-on:
- To get Selenium IDE, open Firefox and go to https://addons.mozilla.org/firefox/extensions/ and use its search to find Selenium IDE, then install it.
- To edit a test, in Firefox choose Tools > Selenium IDE and a new window will open. In the Selenium IDE window choose File > Open... and navigate to jumpstart-max-1.5.0/web/src/test/selenium/smoke-test/ or similar and choose a test eg. TestHelloWorld.html .
- There's documentation on Selenium IDE at Selenium IDE and Selenium.
Logging SQL and Hibernate. To log SQL statements, modify the JBoss server's conf/log4j.xml to include
-
<category name="org.hibernate.SQL">
<priority value="DEBUG"/>
</category>
Alternatively, to log everything Hibernate's doing, including SQL statements, schema export, transactions, etc., try
-
<category name="org.hibernate">
<priority value="DEBUG"/>
</category>
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:
-
<category name="org.hibernate">
<priority value="DEBUG"/>
<appender-ref ref="HIBERNATE"/>
</category>
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:
- Start JBoss in debug mode
We'll use port 8787 in this explanation, but it's OK to use any free port.
Earlier, we described setting JAVA_OPTS to get various startup options. To run JBoss in debug, include this in the JAVA_OPTS:
-
-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y
So if, for example, you also wanted the options described earlier, you'd set JAVA_OPTS to:
-
-Dorg.apache.tapestry.disable-caching=true -XX:MaxNewSize=96m -XX:MaxPermSize=96m
-Xms128m -Xmx128m -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y
In Windows, another way to turn on debug is to locate the run.bat file in the JBoss bin/ directory and edit it, removing the rem from the line that reads:
-
rem set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y %JAVA_OPTS%
-
Listening for transport dt_socket at address: 8787
In Eclipse, right-click on your project and choose Debug As > Debug... and the Debug window will appear.
- Right-click on Remote Java Application and choose New.
- Set the Port to 8787.
- Enable Allow termination of remote VM.
- Click on Debug.
JBoss will now resume startup, and in Eclipse you can now set breakpoints on any Java in the project - web and business.
- Use JBossIDE plug-in for Eclipse
This plug-in lets you control a JBoss server directly from Eclipse. It is available via Eclipse's update facility (Help > Software Updates > Find and Install...). The update site is http://download.jboss.org/jbosside/updates/stable . (OS X users check here.)
When configuring a server in JBossIDE, you can set system properties in the section called VM arguments. To use the settings described earlier, you'd put this into the VM arguments:
-
-Dorg.apache.tapestry.disable-caching=true -XX:MaxNewSize=96m -XX:MaxPermSize=96m -Xms128m -Xmx128m
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 hibernate.hbm2ddl.auto 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.
- 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 JBoss server. See Creating/updating 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.
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 JBossExceptionInterpreter.java 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:
- Database driver You won't need to do anything to work with HSQLDB or MySQL because JBoss provides the HSQLDB driver and JumpStart includes the MySQL driver (mysql-connector-java.jar).
- Data source definition To add a data source definition to JBoss create a new file similar to hsqldb-ds.xml in your exploded/ directory or the server's deploy/ directory or any other directory being scanned by JBoss. See here.
- persistence.xml Modify jumpstart-min.ear/jumpstart-min.jar/META-INF/persistence.xml - specify the data source name in the tag jta-data-source (eg. java:/DefaultDS), and specify the database type in the property hibernate.dialect in persistence.xml (jumpstart-min.ear/jumpstart-min.jar/META-INF/persistence.xml).
- JBossExceptionInterpreter.java As discussed above, if you use a database type other than HSQLDB or MySQL then you may need to add some logic to this custom class.
Table Component. Three excellent resources for understanding the Table component that's used in the Search pages:
- On the Tapestry web site is TableView component reference
- Mindbridge's interactive tutorial - download TapestryTables.war from here, drop it into the JBoss deploy/ directory and point your browser at http://localhost:8080/TapestryTables.
- Chapter 7 of Kent Tong's book Enjoying Web Development With Tapestry.
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:
- JBossExceptionInterpreter.java - create a new class like it - for example, GlassFishExceptionInterpreter. JBossExceptionInterpreter is tailored to interpreting the JBoss/Hibernate exceptions that bleed out of the persistence layer. It's a class that we shouldn't need, but it seems the EJB3 spec didn't identify and standardise all possible persistence exceptions so vendor-specific exceptions bleed out. Will this be fixed in EJB 3.1???
- BaseSvc.java - simple change - replace its JBossExceptionInterpreter references (see above).
- SessionLayerExceptionInterpreter.java - simple change - replace its JBossExceptionInterpreter references (see above).
- Persistence.xml - simple change - modify a few lines that are in there for Hibernate's benefit. JBoss uses Hibernate for EJB3 Persistence but other app servers might not, eg. GlassFish, uses TopLink Essentials. Hopefully EJB 3.1 will move this bit of config to somewhere outside the EAR.