== Instructions ==

This file contains the directory structure of this package, instructions for 
running the FXTradingServer and connecting to it using the SimpleFXMessenger 
API, and a description of the ExampleTrader.java and ExampleSubscriber.java
files.

== Directory structure ==

The top-level directory contains the following files:

  FXTradingServer-<version>.jar      (the server)
  SimpleFXMessenger-<version>.jar    (the API)
  ExampleTrader.java                 (an example trading application)
  ExampleSubscriber.java             (an example pricing application)
  Instructions.txt                   (this file)

The javadoc directory contains the Javadoc for the API.

== Running the server ==

To run the server, execute the jar file: 'FXTradingServer-<version>.jar'. This 
can be achieved by opening up a terminal in the directory of the jar file and 
running the command: "java -jar FXTradingServer-<version>.jar".

== Using the SimpleFXMessenger API ==

-- Setup --

1. Add the jar file: 'SimpleFXMessenger-<version>.jar' to your project's build 
path. This provides you with access to the following classes and interfaces:

     * messenger.FXTradingMessenger: the class which contains the API functions
       for trading
     * messenger.FXPricingMessenger: the class which contains the API functions
       for subscribing to prices
     * messenger.FXTradingListener: the interface specifying call-back methods 
       dealing with FX trades from the server
     * messenger.FXPricingListener: the interface specifying call back methods 
       dealing with FX pricing from the server
     * messenger.FXQuote: the class which contains the fields for a currency 
       pair quotation
     * messenger.FXTradeReport: the class which contains the fields for a trade
       report

2. In order to use the API functions, you must first create a class which 
implements either FXTradingListener or FXPricingListener, depending on whether
you want to do trading or subscribing. Please refer to the Javadoc for 
descriptions of the call-back methods in these interfaces. 

3. In your application code, create an instance of your class which implements 
either FXTradingListener or FXPricingListener. Then pass this instance through 
to the constructor of the corresponding messenger class, i.e. 
FXTradingMessenger or FXPricingMessenger.

-- Connecting --

Call the connect() method on your FXTradingMessenger or FXPricingMessenger 
instance to connect to the server. You will receive an onConnect() call-back to 
your implemented listener instance if the connection is successful and you can 
then call the other API functions.

-- Subscribing --

To subscribe to an FX price, call the subscribe(currencyPair) method on your
FXPricingMessenger instance. You must specify the currencyPair in the format 
XXX/YYY, where XXX and YYY are the ISO 4217 international three-letter codes of 
the currencies, e.g. GBP/USD. If the subscription is successful, you will 
receive call-backs every 2 seconds to your onPriceUpdate(fxQuote) method, where 
fxQuote contains the latest quotation for the subscribed currency pair. If the 
subscription is rejected by the server, you will receive an 
onSubscriptionError(currencyPair, message) call-back.

-- Unsubscribing --

To unsubscribe from an FX price, use unsubscribe(currencyPair).

-- Trading --

To execute a trade, call the executeTrade(username, clientOrderID, currencyPair, 
amount, side, price) method on your FXTradingMessenger instance. You should
specify username and clientOrderID as strings e.g. "user1" and "ID12", the 
currency pair as described above, the amount you want to trade, the side which 
should be either FXTradeReport.BUY or FXTradeReport.SELL and the price. 
You will receive a call-back to onTradeReport(tradeReport), where tradeReport 
contains fields for the FX trade, including a status field which is either 
FXTradeReport.FILLED or FXTradeReport.REJECTED.

-- Disconnecting --

To disconnect from the server, use disconnect(). You will receive an 
onDisconnect() call-back.

== Example applications ===

-- ExampleSubscriber.java --

ExampleSubscriber.java contains example code for using the API to connect to 
the server and subscribe to price updates for GBP/USD. The class implements 
FXPricingListener to provide call-back methods and has a main method to run 
the application.

-- ExampleSubscriber.java --

ExampleTrader.java contains example code for using the API to connect to the 
server and execute a trade for GBP/USD. The class implements FXTradingListener 
to provide call-back methods and has a main method to run the application.