Shale MailReader (with JPA) Sample Application
==============================================

(1) INTRODUCTION

This example application is based on the original Struts MailReader example application, but uses
a relational database for persistence (accessed via beans compatible with the Java Persistence
Architecture, or JPA), rather than an XML file.  It also showcases non-trivial usage of the
View Controller APIs.

As currently implemented, this application will deploy *only* to a Java EE 5 container (such as
Glassfish at java.net), which you will have needed to deploy on your system already.  In addition,
there are some manual steps required to configure the runtime environment for the database to be used.

(2) INSTALLING GLASSFISH

In order to run the resulting application, download and install a copy of Glassfish from
<https://glassfish.dev.java.net>, following the setup directions found there.  Use a
recent build from either the "v1" or "v2" series.  In the instructions below,
$GLASSFISH_HOME stands for the directory into which you installed Glassfish.


(3) CONFIGURING THE RUNTIME ENVIRONMENT

The sample application utilizes a JPA persistence unit that uses a JDBC data source named
"jdbc/mailreader".  Before you can successfully deploy the application for the first time,
you must manually configure such a data source into your server.  The following directions
assume you are using Glassfish, and its included Java DB (a.k.a. Derby) database system,
and that you want to create a new Derby database for this application.  To configure the
new data source, perform the following steps:

* Start Glassfish, and the database, if they are not already running.

* Using your browser, navigate to the Administration Console (default
  URL is <http://localhost:4848/>), and log on.

* Using the navigation controls, navigate to Resources --> JDBC --> Connection Pools
  and press the "New ..." button.

* On Page 1, fill out the main identifying characteristics of your new
  connection pool.  The name itself is arbitrary, as long as it is unique
  and you also use the same name later when setting up the data source.

  Name:            MailReaderPool
  Resource Type:   javax.sql.DataSource
  DB Vendor:       Derby

* On Page 2, customize any settings you like.  Under "Additional Properties",
  you must set appropriate values that identify a logon to a Derby
  database, which will be created for you if it does not already exist:

  PortNumber:              1527
  User:                    app
  Password:                app
  ServerName:              localhost
  DatabaseName:            mailreader
  ConnectionAttributes:    ;create=true

  If you are using a different database, or different logon credentials,
  adjust these values accordingly.

* Using the navigation controls, navigate to Resources --> JDBC --> JDBC Resources
  and press the "New ..." button.

* On the setup dialog, enter the following values:

  JNDI Name:      jdbc/mailreader      (this value is required)
  Pool Name:      MailReaderPool       (or whatever name you used for the connection pool)
  Description:    (optional description)
  Enabled:        yes

(4) DEPLOYING THE EXAMPLE APPLICATION

If you have unpacked the example app distribution (or built the app from source), you will find a WAR file
named "shale-mailreader-jpa.war".  Copy this file to the autodeploy directory of
your Glassfish installation ($GLASSFISH_HOME/domains/domain1/autodeploy/), and the app server will deploy
it for you automatically.  The first time this occurs, the JPA framework will create the tables that
correspond to the entity classes automatically (courtesy of a setting in the persistence.xml file that
defines the persistence unit), and the application will populate these tables with dummy data that
corresponds to the default xml file that ships with other versions of the MailReader example.

You can redeploy the application at any time by repeating the above copying procedure, or remove it by
using the admin console of the app server.