README
~~~~~~

hivemodule.xml
~~~~~~~~~~~~~~

In jumpstart-max we have 2 different hivemodule.xml files:

1) One that is part of our web application.  It's in web/src/main/webapp/WEB-INF/hivemodule.xml.
	It describes aspects of our application, eg. our custom validators and translators.
	It is compiled into our EAR file as a part of the application.

2) One that we can tailor to each deployed environment.  It's META-INF/hivemodule.xml in this directory
	and we copy it to a location in the environment's classpath and edit it.
	It describes things we might want to do differently in some environments, like:
		- whether we want to use our own Exception page instead of Tapestry's.


How the 2nd hivemodule.xml works
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When Tapestry starts up, HiveMind looks for and loads every META-INF/hivemodule.xml on the classpath.
Each JBoss server includes its conf/ on the classpath, so all we have to do is create conf/META-INF/ 
and copy the 2nd hivemodule.xml into it.


An example: A Custom Exception Page for production
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Tapestry's Exception page is excellent for developers but is rarely suitable in production due to the mass of 
technical data it presents.  JumpStart includes a simple alternative called UserFriendlySystemExceptionPage,
that you can use as the starting point for creating your own.

To override Tapestry's Exception page with, for example, JumpStart's UserFriendlySystemExceptionPage, in production:

1. Locate the production JBoss server's conf/ directory.  
2. Copy directory web/src/main/examples/conf/META-INF/ to the JBoss server's conf/ directory.
3. Open the JBoss server's conf/META-INF/hivemodule.xml file.  You will see it specifies that the exceptionPageName 
	is "pages/exception/UserFriendlySystemExceptionPage".  Edit this if you wish.
4. Restart JBoss.
5. Test it by causing a system exception (eg. by going to the Custom Exception Page example on JumpStart's login page,
	or by stopping the database and then trying to log in to JumpStart), and checking that the UserFriendlySystemExceptionPage 
	is displayed.
	
For more information, see:
- the Custom Exception Page example on JumpStart's login page
- the Tapestry documentation at http://tapestry.apache.org/tapestry4.1/developmentguide/exceptionpages.html
