README

#   Licensed to the Apache Software Foundation (ASF) under one or more
#   contributor license agreements.  See the NOTICE file distributed with
#   this work for additional information regarding copyright ownership.
#   The ASF licenses this file to You under the Apache License, Version 2.0
#   (the "License"); you may not use this file except in compliance with
#   the License.  You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.

(C) Copyright 2006-2010 The Apache Software Foundation.
----------------------------------------------------------------------

The code in this directory contains the code for the benchmark sample called
Day Trader.  This sample was contributed by IBM to the Apache Geronimo project
under the ASF license to further functional and performance testing of Geronimo.  

-----------
|  BUILD  |
-----------
To build DayTrader, you need to have Java SE 5 and Maven 2.0.9 or later
installed, which can be found at http://maven.apache.org.
Once installed you can build DayTrader by executing the following command
from the dayTrader root directory (the directory containing this README):

        mvn clean install

This will build the daytrader-jms, daytrader-derby-datasource, daytrader-jetty
and daytrader-tomcat plugins.


-------------
|  INSTALL  |
-------------
You can install Daytrader either as a set of Geronimo Plugins or as an EAR.
Both methods support using either the comand-line deployer or the Admin Console.

In following steps, you need to replace <version> with the real version number of daytrader release.

Plug-ins
--------
After building daytrader, you can go to admin console to install the
daytrader-jetty or daytrader-tomcat plugin, which will automatically install and
use the daytrader-derby-datasource. Alternatively, you can install them
via the "deploy/list-plugins" command, for example:

    gsh deploy/list-plugins -u system -w manager -r file:/<your-local-maven-repo> org.apache.geronimo.daytrader/daytrader-tomcat/<version>/car

For app clients, you'll have to install them using deploy install-plugin
commands for now, before we publish the app client plugins on a public repo,
for example: 

    gsh deploy/install-plugin -u system -w manager $DAYTRADER_HOME/daytrader-tomcat/target/daytrader-ws-client-<version>.car
    gsh deploy/install-plugin -u system -w manager $DAYTRADER_HOME/daytrader-tomcat/target/daytrader-streamer-client-<version>.car 

You will need to create the database and populate the initial data into the
database.  Make sure Geronimo is started and the GERONIMO_HOME environment
variable is defined.

1. If you want to use the embedded Apache Derby database, you can populate
tables and data by visiting http://localhost:8080/daytrader/ in your browser.

2. If you want to use a DB2 database as a back-end database provider, please
copy DB2 jdbc drivers to server's repository and then build and install the 
daytrader-db2-datasource plugin before installing the daytrader-jetty/tomcat
plugin.    

3. If you want to use an Oracle database as a back-end database provider,
please copy the ojdbc14.jar file from your oracle server to
$GERONIMO_HOME\repository\oracle\ojdbc14\10g and rename the ojdbc14.jar to a
maven-recognizable format like ojdbc14-10g.jar.  Then build and install the 
daytrader-oracle-datasource plugin before installing the daytrader-jetty/tomcat
plugin.


Deployer
--------
1. Create the sample's database tables according to your database provider:
   - If you use the embedded Apache Derby database provider, please perform the
     following steps:
      a. Ensure you have JAVA_HOME and GERONIMO_HOME environment variables set
      b. Execute these commands from a command prompt:
           cd $DAYTRADER_HOME/bin/dbscripts/derby
           createDerbyDB.[bat|sh]
  - If you use another back-end database provider, please perform the following
    steps:
    To create the database tables:
      a. Set up a database or reuse an existing database. For this sample, a
         database named "tradedb" is used.
      b. Create a user with a user name of "trade" and a password of "trade".
         Grant appropriate permissions to this user.
      c. Load the database schema for this user by running the following at a
         DBM command window:
         - For IBM DB2 Express-C and Universal Database (UDB):
              db2 connect to tradedb
              db2 -tvf bin\dbscripts\db2\Table.ddl
         - For Oracle:
              sqlplus trade/trade@tradedb @bin\dbscripts\oracle\Table.ddl
    To prep the datasource:
      a. Download your DBM's JDBC driver from an authorized source.
      b. Copy this driver to the Geronimo repository, and rename it to a
         maven-recognizable format.  For example,
         - For IBM DB2 Express-C and Universal Database (UDB):
              $GERONIMO_HOME/repository/
         - For Oracle:
              $GERONIMO_HOME/repository/oracle/ojdbc14/10g/ojdbc14-10g.jar
      c. Modify the database resource adapter configuration in your XML plan
         (see below) to your database environment.  For example, UserName,
         Password, PortNumber, DatabaseName, ServerName.

2. Use the deployer tool to install the application:
   - Execute these commands from a command prompt:
         cd $GERONIMO_HOME/bin
         deploy.[bat|sh] deploy $DAYTRADER_HOME/modules/ear/target/daytrader-ear-<version>.ear $DAYTRADER_HOME/plans/<My plan>
           where <My plan> is
               For Apache Derby:  dayTrader-derby-plan.xml
               For IBM DB2 v9.1:  dayTrader-db2-9.1-XA-plan.xml
               For Oracle:        dayTrader-oracle-XA-plan.xml
               For MS SQL Server: dayTrader-sqlserver-plan.xml

3. Use the admin console to install the application:
   - Under Applications -> Deploy new
     a. Select the EAR file indicated above as your archive.
     b. Select the XML file indicated above as your plan.
     c. Ensure the checkbox is selected to "start app after install".


---------
|  RUN  |
---------
1. Access the dayTrader application at:
         http://<hostname>:<port>/daytrader.
2. Before you begin using DayTraader, theres are a couple setup steps:
   - Populate the database with a set of fictional users, stocks, prices, etc.
     by selecting:
         'Configuration -> (Re)-populate Trade Database'.
     Note: This may take a minute or two depending on your database server.
   - After populating the database, the DayTrader Configuration options will
     appear.  Just accept the defaults.
3. Now you can begin trading by going to:
         'Trading & Portfolios'
   Or run the sample test scenario to verify it is installed and working:
         'Configuration -> Test DayTrader Scenario'

There are two optional application clients you can run, the streamer client and
web services client.  To run these (from $GERONIMO_HOME/bin):
   TradeStreamerAppClient:
      client.[bat|sh] org.apache.geronimo.daytrader/daytrader-streamer-client/<version>/car -waitForMain
   WSAppClient:
      client.[bat|sh] org.apache.geronimo.daytrader/daytrader-ws-client/<version>/car -waitForMain


---------------
|  UNINSTALL  |
---------------
To uninstall DayTrader, issue the following commands:
1. If you installed DayTrader as a plugin:
  - If you installed the DayTrader :: Tomcat plugin:
      deploy.[bat|sh] undeploy org.apache.geronimo.daytrader/daytrader-tomcat/<version>/car
  - If you installed the DayTrader :: Jetty plugin:
      deploy.[bat|sh] undeploy org.apache.geronimo.daytrader/daytrader-tomcat/<version>/car
  - To remove the DayTrader :: JMS plugin (Tomcat or Jetty):
      deploy.[bat|sh] undeploy org.apache.geronimo.daytrader/daytrader-jms/<version>/car
  - To remove the DayTrader :: Derby DataSource (Tomcat or Jetty):
      deploy.[bat|sh] undeploy org.apache.geronimo.daytrader/daytrader-derby-datasource/<version>/car

2. If you installed DayTrader as an application (EAR) using the deployer:
      deploy.[bat|sh] undeploy org.apache.geronimo.daytrader/daytrader/<version>/car