Shout Domain Class

General Description

A Shout domain class is the representation of limit or market order issued by a particular user for a particular product. Over time a shout may change, e.g. if it is executed partially or fully. In order to record all changes made to a shout over time a particular shout instance is never changed (with the outdated flag described later on being the only exception). Instead on each change a new clone of the latest shout instance is generated, changed appropriately (e.g. by filling in execution price and quantity) and then saved as a new instance to the database.

All shout instances that were cloned from one initial object can be easily identified as they all possess the same shoutID and the same dateCreated. Like this changes and adjustments to an order over time can always be reconstructed ex-post.

Domain Properties

A Shout domain class possesses the following properties:

Long serverId
  Competition competition
  Product product
  BuySellIndicator buySellIndicator
  BigDecimal remainingQuantity
  BigDecimal limitPrice
  OrderType orderType
  BigDecimal executionQuantity
  BigDecimal executionPrice
  Date dateCreated
  Date dateMod
  ModReasonCode modReasonCode
  boolean outdated
  Long transactionID
  Long shoutID
  AuctionTradeFlag auctionTradeFlag

Property Descriptions

Example

In the following example a limit sell order for product 10 units of Product 24.04 21:00 and a minimum sell price of 40 is issued by person _tacenergy1_. In this case we assume that this order can be matched immediately against another order in the orderbook (which is not listed in the table below). Consequently a cloned instance of the order is created and the modifications from the execution of the order are entered. In particular the modReasonCode is set to EXECUTION, the remainingQuantity is set to 0, the executionQuantity is set to 40 and the executionPrice is set to 10.

personproductbuySellIndicatorremainingQuantitylimitPriceorderTypeexecutionQuantityexecutionPricedateCreateddateModmodReasonCodeshoutIDoutdated
tacenergy1Product 24.04 21:00SELL1040LIMITnullnull24.04.2010 20:45:11 CEST24.04.2010 20:45:11 CESTINSERT1true
tacenergy1Product 24.04 21:00SELL040LIMIT104024.04.2010 20:45:11 CEST24.04.2010 20:45:11 CESTEXECUTION1false

The word Order is a reserved word in most SQL dialects thus Shout was chosen as a replacement to avoid unwanted inferences with the underlying persistence technologies.

Shout Command Objects

For the submission, updating, or deletion of shouts, only reduced property sets (as compared to the list above) are required by the server.

Submitting a new Order

For submitting a new order, the following information encoded as xml needs to be submitted:

<?xml version="1.0" encoding="UTF-8"?>
<shoutSubmitCommand>
	<username>tacenergy1</username>
	<orderType>LIMIT</orderType>
	<action>Create</action>
	<remainingQuantity>10.0</remainingQuantity>
	<class>edu.kit.iism.tacdemo.ShoutSubmitCommand</class>
	<limitPrice>20.0</limitPrice>
	<buySellIndicator>BUY</buySellIndicator>
	<productId>20</productId>
	<apikey>secret</apikey>
</shoutSubmitCommand>

Updating an existing order

In order to update an existing order on the TAC Energy server the following information encoded as xml needs to be submitted:

<?xml version="1.0" encoding="UTF-8"?>
<shoutUpdateCommand>
	<username>tacenergy1</username>
	<orderType>LIMIT</orderType>
	<action>Update</action>
	<remainingQuantity>10.0</remainingQuantity>
	<limitPrice>20.0</limitPrice>
	<shoutID>20</shoutID>
	<apikey>secret</apikey>
</shoutUpdateCommand>

Deleting an existing order

In order to delete an existing order on the TAC Energy server the following information encoded as xml needs to be submitted:

<?xml version="1.0" encoding="UTF-8"?>
<shoutDeleteCommand>
	<username>tacenergy1</username>
	<action>Delete</action>
	<shoutID>20</shoutID>
	<apikey>secret</apikey>
</shoutDeleteCommand>

Note: The order of the properties is not important. Properties other than the above mentioned (e.g creationDate property) are ignored by the server. As soon as an order was processed by the server an order status update message is sent to the respective user queue users.userName.Orderstatus. In this notification message all shout properties (e.g. creation date) are filled in.