From 5081df2032aac108bf8da5b1966229753c58748a Mon Sep 17 00:00:00 2001 From: markpollack Date: Fri, 8 Aug 2008 20:10:24 +0000 Subject: [PATCH] start of nms quickstart docs quartz doc cleanup --- doc/reference/src/index.xml | 5 + doc/reference/src/nms-quickstart.xml | 241 ++++++++++++++++++++++++ doc/reference/src/quartz-quickstart.xml | 34 ++-- 3 files changed, 264 insertions(+), 16 deletions(-) create mode 100644 doc/reference/src/nms-quickstart.xml diff --git a/doc/reference/src/index.xml b/doc/reference/src/index.xml index 747d1beb..00c86dcd 100644 --- a/doc/reference/src/index.xml +++ b/doc/reference/src/index.xml @@ -43,6 +43,7 @@ + @@ -366,6 +367,9 @@ + + + &quickstarts; @@ -376,6 +380,7 @@ &data-quickstart; &tx-quickstart; &quartz-quickstart; + &nms-quickstart; Spring.NET for Java developers diff --git a/doc/reference/src/nms-quickstart.xml b/doc/reference/src/nms-quickstart.xml new file mode 100644 index 00000000..eb0619a4 --- /dev/null +++ b/doc/reference/src/nms-quickstart.xml @@ -0,0 +1,241 @@ + + + NMS QuickStart + +
+ Introduction + + The NMS quick start application demonstrates how to use asynchronous + messaging to implement a system for purchasing a stock. To purchase a + stock, a client application will send a stock request message containing + the information about the stock, i.e. ticker symbol, quantity, etc. The + client request message will be recieved by the server where it will + perform business processing on the requst, for example to determine if the + user has sufficient credit to purchase the stock or if the user is even + allowed to make the purchase due to existing account restrictions. Usually + the server application will persist state about the request and forward it + on to an execute venue where the actual execution of the stock request is + peformed. In addition, market data for the stock will be sent from the + server process to the client. The high level messaging flow is shown + below. + + + + +
+ +
+ Message Destinations + + To implement this flow using messaging the following queues and + topics will be used. All requests from the client to the server will be + sent on the queue named APP.STOCK.REQUEST. Responses to the requests will + be sent from the server to the client on a queue unique to each client. In + this example the queue name is of the form APP.STOCK.<UserName>, and + more specifically is configured to be APP.STOCK.JOE. Market data does not + need to be delivered to an individual client as many client applications + are interested in this shared information. As such, the server will send + market data information on a topic named APP.STOCK.MARKETDATA. The + messaging communication between the server and the execution venue is not + included as part of the application. An local implementation of the + service interface that represents the execution venue is used instead of + one based on messaging or another middleware technology. The messaging + flow showing the queues and topics used is shown below. + + + + +
+ +
+ Gateways + + Gateways represent the service operation to send a message. The + client will send a stock request to the server based on the contract + defined by the IStockService interface . + + public interface IStockService + { + void Send(TradeRequest tradeRequest); + } + + The server will send market data to the clients based on the + contract defined by the IMarketDataService + interface. + + public interface IMarketDataService + { + void SendMarketData(); + } + + The market data gateway has no method parameters as it is assumed + that implementations will manage the data to send internally. The + TradeRequest object is one of the data objects that + will be exchanged in the application and is discussed in the next + section. + + The use of interfaces allows for multiple implementations to be + created. Implementations that use messaging to communicate will be based + on the Spring's NmsGateway class and will be + discussed later. stub or mock implementations can be used for testing + purposes. +
+ +
+ Message Data + + The TradeRequest object shown above contains + all the information required to process a stock order. To promote the + interoperability of this data across different platforms the + TradeRequest class is generated from an XML Schema + using Microsoft's Schema Definition Tool (xsd.exe). The schema for trade + request is shown below + + <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" + targetNamespace="http://www.springframework.net/nms/common/2008-08-05"> + + <xs:element name="TradeRequest"> + <xs:complexType> + <xs:sequence> + <xs:element name="Ticker" type="xs:string"/> + <xs:element name="Quantity" type="xs:long"/> + <xs:element name="Price" type="xs:decimal"/> + <xs:element name="OrderType" type="xs:string"/> + <xs:element name="AccountName" type="xs:string"/> + <xs:element name="BuyRequest" type="xs:boolean"/> + <xs:element name="UserName" type="xs:string"/> + <xs:element name="RequestID" type="xs:string"/> + </xs:sequence> + </xs:complexType> + </xs:element> + +</xs:schema> + + + Running xsd.exe on this schema will result in a class that contains + properties for each of the element names. A parital code listing of the + TradeRequest class is shown below + + // This code was generated by a tool. + public partial class TradeRequest { + + public string Ticker { + get { + return this.tickerField; + } + set { + this.tickerField = value; + } + } + + public long Quantity { + get { + return this.quantityField; + } + set { + this.quantityField = value; + } + } + + // Additional properties not shown for brevity. + + } + + The schema and the TradeRequest class are + located in the project Spring.NmsQuickStart.Common. + This common project will be shared between the server and client for + convenience. + + When sending a response back to the client the type + TradeResponse will be used. The schema for the + TradeResponse is shown below + + <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" + targetNamespace="http://www.springframework.net/nms/common/2008-08-05"> + + <xs:element name="TradeResponse"> + <xs:complexType> + <xs:sequence> + <xs:element name="Ticker" type="xs:string"/> + <xs:element name="Quantity" type="xs:integer"/> + <xs:element name="Price" type="xs:decimal"/> + <xs:element name="OrderType" type="xs:string"/> + <xs:element name="Error" type="xs:boolean"/> + <xs:element name="ErrorMessage" type="xs:string"/> + </xs:sequence> + </xs:complexType> + </xs:element> + +</xs:schema> + + The TradeResponse type also generated from a + schema using xsd.exe. A partial code listing is shown below + + // This code was generated by a tool. + + public partial class TradeResponse { + + public string Ticker { + get { + return this.tickerField; + } + set { + this.tickerField = value; + } + } + + public long Quantity { + get { + return this.quantityField; + } + set { + this.quantityField = value; + } + } + + // Additional properties not shown for brevity. + + } + + The market data information will be sent using a Hashtable data + structure. +
+ +
+ Mesage Handlers + + When the TradeRequest message is received by + the server, it wll be handled by the class + Spring.NmsQuickStart.Server.Handlers.StockAppHandler + shown below + + public class StockAppHandler + { + private IExecutionVenueService executionVenueService; + + private ICreditCheckService creditCheckService; + + private ITradingService tradingService; + + public TradeResponse Handle(TradeRequest tradeRequest) + { + TradeResponse tradeResponse; + IList errors = new ArrayList(); + if (creditCheckService.CanExecute(tradeRequest, errors)) + { + tradeResponse = executionVenueService.ExecuteTradeRequest(tradeRequest); + tradingService.ProcessTrade(tradeRequest, tradeResponse); + } + else + { + tradeResponse = new TradeResponse(); + tradeResponse.Error = true; + tradeResponse.ErrorMessage = errors[0].ToString(); + } + return tradeResponse; + } + } + + +
+ \ No newline at end of file diff --git a/doc/reference/src/quartz-quickstart.xml b/doc/reference/src/quartz-quickstart.xml index 41420c88..757872c0 100644 --- a/doc/reference/src/quartz-quickstart.xml +++ b/doc/reference/src/quartz-quickstart.xml @@ -9,9 +9,9 @@ a given time without any user interaction, usually to perform some administrative tasks. These tasks need to be scheduled, say to perform a job in the early hours of the morning before the start of business. This - functionality is provided by a using job scheduling software. Quartz.NET - is an excellent open source job scheduler that can be used for these - purposes. It provides a wealth of features ,such as persistent jobs and + functionality is provided by using job scheduling software. Quartz.NET is + an excellent open source job scheduler that can be used for these + purposes. It provides a wealth of features, such as persistent jobs and clustering. To find out more about Quartz.NET visit their web site. Spring integration allows you to use Spring to configure Quartz jobs, triggers, @@ -31,12 +31,13 @@ in order to pass information between different job instances you stash data away in a hashtable that gets passed to the each Job instance upon its creation. Quartz's JobDetail class combines the - IJob and this hashtable of data. Instead of a - generic hashtable the class JobDataMap is used. - Triggers are registered with a Quartz IScheduler - implementation that manages the overall execution of the triggers and - jobs. The implementation StdSchedulerFactory is - generally used. + IJob and this hashtable of data. Instead of the + standard System.Collections.Hashtable the class + JobDataMap is used. Triggers are registered with a + Quartz IScheduler implementation that manages the + overall execution of the triggers and jobs. The + StdSchedulerFactory implementation is generally + used.
@@ -46,9 +47,9 @@ Spring's convenience base class QuartzJobObject and another which does not inherit from any base class. The latter class is adapted by Spring to be a Job. Two triggers, one for each of the jobs, are - created, and these triggers are in turn registered with a scheduler. In - each case the job implementation will write information to the - console. + created. These triggers are in turn registered with a scheduler. In each + case the job implementation will write information to the console when it + is executed.
@@ -187,10 +188,11 @@ </object> This creates an instances of Quartz's SimpleTrigger class (as - compared to its CronTrigger class used in the previous section. StartDelay - and RepeatInterval properties are TimeSpan objects than can be set using - the convenient strings such as 10s, 1h, etc, as supported by Spring's - custom TypeConverter. + compared to its CronTrigger class used in the previous section). + StartDelay and RepeatInterval + properties are TimeSpan objects than can be set using the convenient + strings such as 10s, 1h, etc, as supported by Spring's custom + TypeConverter for TimeSpans. This trigger can then be added to the scheduler's list of registered triggers as shown below.