Overview

This document is meant to serve as a guide for installing the Metro implementation of the Stonehenge StockTrader Sample Application.

This guide was written against Windows Server 2008 and there may be platform specific instructions. This guide assumes that you wish to create a single machine running all of the available implementations. If you are well versed in another platform not addressed by this guide, please feel free to provide alternative instructions where appropriate.


Table of Contents


Prerequisites

The following components are required for the Apache Stonehenge Metro StockTrader Sample Application to properly function.

Installing SQL Server Express 2008

To install a Microsoft SQL Server Express 2008, follow the instructions in the Installing Microsoft SQL Server Express 2008 document in the Installing Common Prerequisites section of this wiki.

Configuring an Existing Microsoft SQL Server Installation

To configure the Microsoft SQL Server installation, follow the instructions in the Configuring Microsoft SQL Server 2008 Express document in the Installing Common Prerequisites section of this wiki.

Installing Java EE 5 SDK (w/JDK and Glassfish)

To install Java EE 5 SDK (w/JDK and Glassfish)

  1. Follow the instructions in the Installing Java EE 5 SDK document in the Installing Common Prerequisites section of this wiki.

To create aliases for the Glassfish domain in Windows:

  1. Click the Start menu, type notepad %windir%\system32\drivers\etc\hosts, and then press Enter.
  2. Add the following line to the bottom of the file: 
    127.0.0.1       apps.stonehenge.dev

    This domain name will now be resolved to the IP address 127.0.0.1 without an external DNS lookup.

  3. Save the file, and then close Notepad.

Installing Apache Ant

Apache Ant is a Java based build tool that is relied upon extensively throughout the Metro implementation of the StockTrader sample.

To install Apache Ant:

  1. Navigate to the Apache Ant download page.
  2. Download the ZIP archive listed at the bottom of the page.
  3. Extract and copy the contents of the folder contained at the root of the ZIP archive to a path on your computer (e.g., C:\Ant)
  4. Configure the following environment variable:

    Name

    Sample Value

    ANT_HOME

    C:\Ant

    This path will be the same path to which you extracted the zip file.

  5. Add the following paths to your PATH environment variable:

    Description

    Example Path

    Ant binaries folder

    C:\Ant\bin

Installing Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6

To install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6, follow the instructions in the Installing Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 6 document in the Installing Common Prerequisites section of this wiki.

Installing Jersey 1.1.5

Jersey is a JAX-RS reference implementation for building RESTful Web services.

To install Jersey 1.1.5:

  1. Download the Jersey 1.1.5 JAR archive.
  2. Copy the archive to the lib folder of the Glassfish installation (e.g., C:\Sun\SDK\lib)

Installing Metro 2.0

Metro is a Java-based Web Services development framework that supports various W3C and WS-I standards for web services. Metro-based services can be deployed to, and hosted in GlassFish, a Java-based application server.

To install Metro 2.0:

  1. Download the Metro 2.0 ZIP archive.
  2. Extract and copy the contents of the folder contained at the root of the ZIP archive to a path on your computer (e.g., C:\Installations\Metro)
  3. At a command prompt, browse to the path to which you extracted the contents of the ZIP archive.
  4. At the command prompt, type and execute the following commands: 
    asadmin stop-domain domain1
ant -Das.home=%AS_HOME% -f metro-on-glassfish.xml install
asadmin start-domain domain1

    This version of Glassfish comes bundled with an earlier version of Metro. This command will stop the Glassfish domain created during setup (if it is already running), and then upgrade the bundled version of Metro.

  5. Create a folder named endorsed under %JAVA_HOME%\jre\lib.
  6. Copy C:\Installations\Metro\lib\webservices-api.jar to %JAVA_HOME%\jre\lib\endorsed

Installing a Subversion Client

To install a Subversion client, follow the instructions in the Installing a Subversion Client document in the Installing Common Prerequisites section of this wiki.

Installing the Apache Stonehenge StockTrader Application

Retrieving Source Code

To retrieve the source code, follow the instructions in the Retrieving the Source Code document in the Installing Common Prerequisites section of this wiki.

Installing Final Prerequisites

To prepare a directory structure for final prerequisites:

  1. Navigate to *\stocktrader\metro* under the directory where you checked out the source code.
  2. In this folder, create a new folder named lib.
  3. Under the lib folder, create the folders shown in the table below (the Final Contents column can be used to verify that all prerequisites are in their proper locations after you have completed the #Installing Final Prerequisites section):

    Folder Name

    Final Contents

    ant

    ant-contrib-1.0b3.jar

    commons

    commons-beanutils-1.8.0.jar
    commons-codec-1.3.jar
    commons-collections-3.2.1.jar
    commons-digester-2.0.jar
    commons-el.jar
    commons-logging-1.1.1.jar

    facelets

    jsf-facelets.jar
    richfaces-api-3.3.1.GA.jar
    richfaces-impl-3.3.1.GA.jar
    richfaces-ui-3.3.1.GA.jar

    javaee

    javaee.jar

    jsf

    jsf-api.jar
    jsf-impl.jar
    jstl.jar

    log4j

    log4j-1.2.15.jar

    metro

    webservices-api.jar
    webservices-extra.jar
    webservices-extra-api.jar
    webservices-rt.jar
    webservices-tools.jar

    mssql

    jtds-1.2.2.jar

    mysql

    mysql-connector-java-5.1.7-bin.jar

To provide the required files from Ant Contrib:

  1. Download the ZIP archive for Ant-Contrib 1.0b3.
  2. Extract ant-contrib\ant-contrib-1.0b3.jar from the archive to the lib\ant folder you created earlier.

To provide the required files from Apache Commons Beanutils 1.8.0:

  1. Download the ZIP archive for Apache Commons Beanutils 1.8.0.
  2. Extract commons-beanutils-1.8.0\commons-beanutils-1.8.0.jar from the archive to the lib\commons folder you created earlier.

To provide the required files from Apache Commons Codec 1.3:

  1. Download the ZIP archive for Apache Commons Codec 1.3.
  2. Extract commons-codec-1.3\commons-codec-1.3.jar from the archive to the lib\commons folder you created earlier.

To provide the required files from Apache Commons Collections 3.2.1:

  1. Download the ZIP archive for Apache Commons Collections 3.2.1.
  2. Extract commons-collections-3.2.1\commons-collections-3.2.1.jar from the archive to the lib\commons folder you created earlier.

To provide the required files from Apache Commons Digester 2.0:

  1. Download the ZIP archive for Apache Commons Digester 2.0.
  2. Extract commons-digester-2.0\commons-digester-2.0.jar from the archive to the lib\commons folder you created earlier.

To provide the required files from Apache Commons EL 1.0:

  1. Download the ZIP archive for Apache Commons EL 1.0.
  2. Extract commons-el-1.0\commons-el.jar from the archive to the lib\commons folder you created earlier.

To provide the required files from Apache Commons Logging 1.1.1:

  1. Download the ZIP archive for Apache Commons Logging 1.1.1.
  2. Extract commons-logging-1.1.1\commons-logging-1.1.1.jar from the archive to the lib\commons folder you created earlier.

To provide the required files from Facelets 1.0.14:

  1. Download the ZIP archive for Facelets 1.0.14.
  2. Extract facelets-1.0.14\jsf-facelets.jar from the archive to the lib\facelets folder you created earlier.

To provide the required files from RichFaces 3.3.1 GA:

  1. Download the ZIP archive for RichFaces 3.3.1 GA.
  2. Extract the contents of richfaces-ui-3.3.1GA\lib from the archive to the lib\facelets folder you created earlier.

To provide the required files from Java EE 5 SDK:

  1. Copy the file %AS_HOME%\lib\javaee.jar to the lib\javaee folder you created earlier.

To provide the required files from JSF 1.2_03:

  1. Download the ZIP archive for JSF 1.2_03.
  2. Extract jsf-1.2_03-b09-FCS\lib\jsf-api.jar and jsf-1.2_03-b09-FCS\lib\jsf-impl.jar from the archive to the lib\jsf folder you created earlier.

To provide the required files from Apache Jakarta Taglibs 1.1.2:

  1. Download the ZIP archive for Apache Jakarta Taglibs 1.1.2.

    The Jakarta Taglibs sub-project is now known as Apache Taglibs, a part of the Apache Tomcat project.

  2. Extract jakarta-taglibs-standard-1.1.2\lib\jstl.jar from the archive to the lib\jsf folder you created earlier.

To provide the required files from Apache log4j 1.2.15:

  1. Download the ZIP archive for Apache log4j 1.2.15.
  2. Extract apache-log4j-1.2.15\log4j-1.2.15.jar from the archive to the lib\log4j folder you created earlier.

To provide the required files from Metro 2.0:

  1. Browse to the lib folder under the directory you extracted the Metro 2.0 (e.g., C:\Installations\Metro\lib).
  2. Copy the following files from that directory to the lib\metro directory you created earlier:

To provide the required files from jTDS 1.2.2:

  1. Download the ZIP archive for jTDS 1.2.2.
  2. Extract jtds-1.2.2.jar from the archive to the lib\mssql directory you created earlier.

To provide the required files from MySQL Connector/J 5.1.7:

  1. Download the ZIP archive for MySQL Connector/J 5.1.7.
  2. Extract mysql-connector-java-5.1.7\mysql-connector-java-5.1.7-bin.jar from the archive to the lib\mysql directory you created earlier.

Preparing the Database

To initialize the database and create accounts:

  1. Follow the instructions in the Preparing the StockTrader Database document in the Installing Common Prerequisites section of this wiki.

To update the service endpoints in the database:

  1. On the Start menu, click All Programs > Microsoft SQL Server 2008 > SQL Server Management Studio
  2. In the Connect to Server dialog, click the Connect button.
  3. In Object Explorer, expand the Databases > StockTraderDB > Tables node.
  4. In Object Explorer, right-click the dbo.SERVICE table, and then click Edit Top 200 Rows.
  5. Update the URLs for the services shown in the table below:

    Service Name

    URL

    METRO_BS

    http://apps.stonehenge.dev:8080/business_service/TradeServiceWsas

    METRO_OPS

    http://apps.stonehenge.dev:8080/order_processor/OrderProcessor

    METRO_OPSSEC

    http://apps.stonehenge.dev:8080/order_processor/OrderProcessorSec
  6. Close the dbo.SERVICE table.
  7. Close Microsoft SQL Server Management Studio.

Updating StockTrader Configuration

To configure the Configuration Service endpoint:

  1. In a text editor, open the file C:\stonehenge\stocktrader\metro\resources\conf\TradeServiceConfig.properties
  2. Change the value of org.apache.stonehenge.stocktrader.TradeConfigService.url to the endpoint address of the configuration service that will be used (e.g., http://apps.stonehenge.dev:8080/config_service/ConfigService)

    You could use the configuration service from either the Metro or .NET implementation.

  3. Save and close the file.

To configure the database location:

  1. In a text editor, open the file C:\stonehenge\stocktrader\metro\resources\conf\db.properties
  2. Modify the values of the properties contained within to be appropriate for your target environment.

Configuring Active STS

To configure the ActiveSTS endpoint:

  1. In a text editor, open the file C:\stonehenge\stocktrader\metro\trader_client\src\wsit-client.xml.
  2. Replace all instances of the text http://apps.stonehenge.dev:1316 with http://apps.stonehenge.dev:8080.
  3. Save the file.
  4. In a text editor, open the file C:\stonehenge\stocktrader\metro\etc\active_sts\ActiveSTS.wsdl.
  5. Replace all instances of the text http://apps.stonehenge.dev:1316 with http://apps.stonehenge.dev:8080.
  6. Save the file.

Add Certificates to Java Key Store

To add the certificates to the java key store:

  1. Download the ZIP archive for the pkcs12import utility.
  2. Extract the files from the \pkcs12import\pkcs12import directory in the archive to the a directory on your hard disk.
  3. Open a command prompt at the directory that you extracted the files into.
  4. Type and execute the following commands: 
    pkcs12import.bat -file C:\stonehenge\stocktrader\dotnet\setup_utilities\Util\BSLClient.pfx -pass yyy -keystore C:\stonehenge\stocktrader\metro\etc\key\stonehenge-truststore.jks -storepass changeit -keypass changeit -alias BSL
pkcs12import.bat -file C:\stonehenge\stocktrader\dotnet\setup_utilities\Util\OPSHost.pfx -pass yyy -keystore C:\stonehenge\stocktrader\metro\etc\key\stonehenge-keystore.jks -storepass changeit -keypass changeit -alias OPS

Deploying StockTrader Sample Application

To deploy the web application on GlassFish:

  1. At a command prompt, navigate to C:\stonehenge\stocktrader\metro
  2. At the command prompt, type and execute the following command: 
    ant deploy
  3. At the command prompt, type and execute the following command: 
    asadmin start-domain domain1