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

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

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:

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:

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.

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.

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.

Table Component.
Three excellent resources for understanding the Table component
that's used in the Search pages:

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