Integration Reference Implementation for the ARCHER Metadata Editor
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


General
~~~~~~~
  This project provides a reference implementation for integration of
  the metadata editor via Web CGI and the Java SPI persistence interfaces.
  It also provides an environment for development and testing of the
  SPI and Metadata Editor

  It includes a minimal Web application to list and edit metadata records.
  It also includes a simple implementation of the SPI interface
  to list, load and save XML documents from a filesystem directory.
  On startup, the application registers it's SPI implementation.

  Once installed on localhost the browser should be pointed to:

    http://localhost[:port]/mde.refimpl
  or,
    http://localhost[:port]/mde.refimpl/index.html

  The first URL invokes the default JSP page which displays a list of metadata records
  with associated View and Edit action links.
  - The View link will display the raw metadata XML record.
  - The Edit link lauches the metadata editor which sould be installed at:
      http://localhost[:port]/mde

  The second URL illustrates an alternate implementation using a servlet
  invoked through a static HTML page.  Although physically different, it
  is finctionally identical to the JSP version.

  If you need to only test the SPI independantly of the Metadata Editor, there is
  also a simpler (single XML text box) editor included in this project that employs
  the same mechanism used by the Metadata Editor to load/save records.
  See index.jsp and index.jsp for more details.


Dependencies
~~~~~~~~~~~~
  (see the MDE_README file)


Deployment
~~~~~~~~~~
  1. Ensure that the SPI and JSON jars have been correctly deployed as described in the
     READMEs and that the Tomcat server has been restarted after the deployment.
  2. Ensure that the MDE WAR has been deployed as described in the MDE README.
  3. Deploy the reference impl WAR file by copying to $CATALINA_HOME/webapps.


Confidence Testing
~~~~~~~~~~~~~~~~~~
  Cross-checking is performed by the three components.
  - The MDE servlet will not "start" unless its event listener was able to confirm
    that the Record Broker contained in the SPI jar is available and functional.
  - The Reference Impl servlet will not start unless its event listener was able
    to locate and register the SPI impl object with the Record Broker.  Any of these
    unhappy occurences will prevent both the JSP and HTML "applications" from
    displaying the record edit page.

  If no startup errors are detected, select the "view" option on the first metadata record.
  The raw XML record will be fetched using the SPI wrapper and displayed (probably) as
  indented XML in your browser.  Use the browser "back" button to return to your
  starting point.

  Select the "Edit" option of the "Crystal_v0.3_1.xml" record.
  This will invoke the Metadata Editor causing the displayed page to be replaced by a
  tree and detail view of the record.  Modification of the values may be performed and
  the record saved.  Confirm that reloading the same record displayed the changed value(s).
  By default, the ref impl uses a flat-file based SPI impl.  This may be changed to the
  in-memory version through the deployment descriptor.  The file based SPI persistes to
  disk, so changes will survive a server restart.  The in-memory one will revert to the
  original state after a Tomcat restart.


Data Reset
~~~~~~~~~~
  When using the default flat-file based metadata repository implementation, files
  are read and written from:

    $CATALINA_HOME/webapps/mde.refimpl/web/client/records

  To restore the flat files to their original state, replace these from those packed
  in the distribution tarball, or undeploy and re-deploy the servlet.


Limitations and Restrictions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1.  For simplicity, the flat-file based ref impl ignores concurrency control.
      Application developers should consider an appropriate strategy (such as
      timestamp based optimistic locking) in their actual deployments.
  2.  Refer to the MDE_README for current editor restrictions.


                                    oOo