= The AriesTrader Sample

== Prereqs

{blank} +

NOTE:;
These instructions are for the 0.2-incubating release of Aries.
Instructions for older releases can be found link:archiveinstructions.html[here] . In the 0.2-incubating release the AriesTrader sample was changed such that it is no longer required for you to install Derby independently.
The Derby version included in the sample is fully leveraged internally in the sample and therefore no additional Derby installation is required.
However, there are steps required to initialize the Database from within the sample itself (see instructions below).

=== Creating the OSGi platform (equinox-test-harness) for AriesTrader

Download and unzip the source zip for the link:aries:downloads.html[latest release]  of Aries Samples and build the equinox-test-harness module under ariestrader:

 cd samples-0.2-incubating/ariestrader/assemblies/equinox-test-harness
 mvn install

This procedure will pull in the binaries from the latest release and its dependencies.

=== Alternative build using Apache Aries trunk.

As an alternative to using the released version you can also choose to work with the latest, unreleased code.
This will require the use of subversion to checkout the code followed by building the entire Apache Aries project.
Directions are provided here:  link:aries:buildingaries.html[Building Aries instructions] .

=== Starting the Equinox Test Harness to run the AriesTrader sample

AriesTrader needs a test harness to run in.
For this purpose we are using an Equinox assembly that pulls in all of the necessary dependencies.

The first task is to start the Apache Aries modules in an OSGi framework using the Eclipse Equinox test harness

 cd samples-0.2-incubating/ariestrader/assemblies/equinox-test-harness/target
 java -jar osgi-3.5.0.v20090520.jar -console

The OSGi console should start up, the 'ss' command should show the active bundles but the AriesTrader application is not yet installed (with the exception of the ariestrader derby datasource which is started with the test harness for convenience).

=== Installing AriesTrader in the Equinox Test Harness

To install the AriesTrader application simply copy the eba for AriesTrader into the target/load directory, you will need to create this directory first.
+ For convenience the AriesTraders EBAs are copied into the target directory as part of creating the OSGi Equinox test harness.

When using the "JDBC" only AriesTrader configuration which supports only jdbc persistence:

 cp org.apache.aries.samples.ariestrader.jdbc-*.eba load/

When using the "All" AriesTrader configuration which supports all currently available persistence modes:

 cp org.apache.aries.samples.ariestrader.all-*.eba load/

Now the 'ss' command should show all of the AriesTrader bundles in state 'ACTIVE'.

If you subsequently delete org.apache.aries.samples.ariestrader.jdbc-_.eba or org.apache.aries.samples.ariestrader.all-_.eba from the target/load directory the application will be uninstalled.

=== Accessing and using the AriesTrader sample

Point your browser at http://localhost:8080/ariestrader/

Select the "Configuration" tab and the "Configure AriesTrader run-time parameters" choice.
Then select from among the available runtime modes (defauls to JDBC).
Be sure to click "update config" to save your selection.

At the moment the following persistence modes are available when using the "all" EBA:

* JDBC persistence
* JPA application managed entity manager persistence
* JPA container managed entity managers using declarative transaction support

By default, the sample starts with JDBC persistence.
To select another persistence mechanism see the directions under "Accessing and using the AriesTrader sample.

After selecting the persistence mode you must create the AriesTrader Database tables and indexs.
Select the "Configuration" tab and the "(Re)-create AriesTrader Tables and Indexes".

Next, you must seed the database with test content.
Once again go to the "Configuration" tab but this time select "(Re)-populate AriesTrader Database" from the available choices to seed the database with a default set of users and stock quotes.
You will see a number of quotes (default is 400) and users (default is 200) created.

Select the "Trading & Portfolios" tab to use the mock trade application or the "Primitives" tab to run some of the web primitive tests (PingJSPEL is not currently working).
You can also run the "Test AriesTrader Scenario" from the "Configuration" tab which will launch a new browser window and step through a trading scenario with each reload of the page.

=== About the AriesTrader Sample

The AriesTrader sample is a modified version of the Apache Geronimo DayTrader sample.
It has been somewhat simplified and reorganized to support the Apache Aries programming model.

The AriesTrader sample bundles are organized like this:

image::downloads/archived/0.1-incubating/ariesTraderOverview2.png[at2]