===========================================================

               Shipment Simulator application
               
               Installation guide

               Q-ImPrESS (c) 2008-2009

===========================================================


TABLE OF CONTENTS
-----------------
1. Prerequisites
2. Installation steps
3. Managing application
4. Troubleshooting


1. PREREQUISITES
----------------

In order to install and run Shipment Simulator, you need 
to install the following software first.

NOTE: Make sure that your installation paths do not contain
spaces.

- Java SE Development Kit: v1.6
- Apache Ant: v1.7
- PostgreSQL: v8.3
- Apache Tomcat: v6.0
- Apache ActiveMQ: v5.2


2. INSTALLATION STEPS
---------------------

1) Configure application

Edit build.properties to set the following properties:
- catalina.home      Points to your Tomcat installation root
- server.url         Contains the complete server URL of your 
                     Tomcat server
- db.admin.id        Contains your Postgres admin user name 
  db.admin.password  and password
- manager.username   Contains your Tomcat manager user name 
  manager.password   and password

Edit webservice.properties to adjust the Web Service URLs to
your deployment scenario (only server and ports might need to 
be adjusted).

Edit messaging.properties to adjust the JMS Broker URL to 
your deployment scenario.

2) Setup database

Run 'ant setup' to create the Shipment Simulator database and 
populate it with data as well as to update the WAR file with 
configured Web Service/JMS Broker URLs.

3) Deploy application

Ensure your Tomcat is running. Your may use the installation 
script for this purpose by running 'ant tomstart'.

Run 'ant deploy' to deploy the application on the Tomcat.
Open '<server.url>/Shipment_Simulator' in your browser
to access the Shipment Simulator application.


3. MANAGING APPLICATION
-----------------------

Your can either use all available tasks from the installation 
script to manage the lifecycle of the application, i.e. list, 
start, stop, reload, deploy, undeploy, or employ the Tomcat 
Manager application for this purpose. It should be normally
available at '<server.url>/manager/html'.


4. TROUBLESHOOTING
------------------

- Security exception after deployment
  
  In case your Tomcat instance is configured to run with 
  the Security Manager 
  (http://tomcat.apache.org/tomcat-6.0-doc/security-manager-howto.html),
  you will probably encounter Java security exceptions during
  the start of the application.
  Currently there is no other solution available to this issue
  except for adding the appropriate permissions to the Tomcat policy
  file. It is normally located under <CATALINA_BASE>/conf.

  The following permission needs to be added:

  grant codeBase "file:${catalina.base}/webapps/Shipment_Simulator/-" {
	permission java.security.AllPermission;
  };

  To apply changes, the Tomcat has to be restarted.

- java.lang.OutOfMemoryError exception after deployment

  In case you deploy all Showcase applications on a single 
  Tomcat instance, you may experience memory overflow problems.
  This is due to the default size of the PermGen space set
  to 64MB on most VMs, which is insufficient for the Showcase 
  applications installed altogether. You should then increase
  the PermGen size by specifying '-XX:PermSize=128M' in your 
  Tomcat startup options (i.e. through JAVA_OPTS or CATALINA_OPTS).