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
- serverId: unique identifier of the entity assigned by the server
- competition: associates the Shout with a certain competition instance
- product: reference to the product that the person wants to buy or sell
- buySellIndicator: one of BUY (stored as 1) or SELL (stored as -1)
- remainingQuantity: the quantity to be bought or sold
- orderType: either MARKET or LIMIT, defaults to MARKET
- limitPrice: max buy price or min sell price respectively the property limitPrice must be set for LIMIT orders and must not be set for MARKET orders
- modReasonCode: Indicates the action that lead to the creation of this entity.
- INSERT(1): The order was newly entered to the system
- MODIFICATION(2): The order was modified by the person who entered the order originally
- DELETIONBYUSER(3): The order was deleted by the user who entered the order originally
- EXECUTION(4): The order was executed by the system, i.e. the full quantity of the order was executed against a matching order in the orderbook
- PARTIALEXECUTION(5): The order was partially executed by the system, i.e. the order quantity was partially executed against a matching order in the order book but there is still some more quantity remaining that was not executed yet.
- DELETIONBYSYSTEM(6): The system deleted the order. This happens for example if a market oder is entered into the system and no matching limit order is found.
- executionQuantity: That amount of the
remainingQuantity
of this order that was executed in the market (<= remainingQuantity
).
- executionPrice: Settlement price for this (partial) execution
- dateCreated: Date of the initial order creation. This date remains the same across all cloned instances of a shout
- dateMod: Date of the modification of this shout instance
- outdated: indicates if this entity is the latest in the list of shout clones
- transactionID: unique id that pertains to the current (partial) execution and thus can be used to reconstruct which particular orders were matched against each other during an execution
- shoutID: identifier that is identical across all cloned instances of an order
- auctionTradeFlag: indicates during which market phase the order is traded. At the moment this flag will be always set to C indicating that the order was issued during continuous trading
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.person | product | buySellIndicator | remainingQuantity | limitPrice | orderType | executionQuantity | executionPrice | dateCreated | dateMod | modReasonCode | shoutID | outdated |
---|
tacenergy1 | Product 24.04 21:00 | SELL | 10 | 40 | LIMIT | null | null | 24.04.2010 20:45:11 CEST | 24.04.2010 20:45:11 CEST | INSERT | 1 | true |
tacenergy1 | Product 24.04 21:00 | SELL | 0 | 40 | LIMIT | 10 | 40 | 24.04.2010 20:45:11 CEST | 24.04.2010 20:45:11 CEST | EXECUTION | 1 | false |
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.