Previous     Contents     Index     Next     
iPlanet Market Maker 4.5 Exchange Customization Guide



Chapter 3   Defining the Matching and
Trading Rules



This chapter provides instructions for defining the matching and trading rules for the iPlanet Market Maker Exchange module.

This chapter contains the following sections:



Overview

After you have defined the axes, criteria, and dimensions for your exchange as explained in Chapter 2 "Defining the Exchange Attributes," the Exchange module can convert the order criteria to a common set of values in the axes of the exchange to identify potential matching of buy and sell orders. The method for doing this is to specify the modules that contain the matching rules in the same XML file in which you defined your axes, criteria, and dimensions.

The next step is to define the matching rules that determine which potential matching buy and sell orders are actually considered matches in the exchange. There might be cases when you want to further refine what constitutes a match beyond a comparison of values for a common set of axes. For example, you can define a matching rule that identifies companies that belong to a black list, which means they are precluded from participating in the exchange. A potential matching buy and sell order that has a buyer or seller on the black list would not produce a match.



Specifying Matching Rules Services



There are two types of exchange matching services that specify the matching rules:

  • System services

  • Module services


System Services Classes

System service classes implement the logic for the core exchange matching functionality. You usually do not have to customize them. These class names have a suffix of EngineService. Their paths have the com.iplanet prefix.

There are two system service classes that specify matching rules:

  • MatchingEngineServiceImpl

  • ExtendedMatchingEngineServiceImpl

The MatchingEngineServiceImpl service class and its module service classes control automatic and manual matching of buy and sell orders in an exchange.

The ExtendedMatchingEngineServiceImpl service class and its module service classes let you extend matching to suggest potential matching buy and sell orders in the user interface. See Figure 3-1.


Example
Suppose you want users in your exchange user interface to be able to match buy and sell orders that are a close, but not exact, match. This capability is called extended matching. Within the ExtendedMatchingEngineServiceImpl service class is a module class called BallonServiceImpl (see the last highlighted lines in Table 3-3) that specifies the logic to expand, or balloon, the axes of your exchange. This results in order matches that are typically beyond the number of exact matches.

Figure 3-1    System and Module Service Classes

An active order entered in the Exchange module user interface is compared against a set of previously entered passive orders (order that are not yet matched). The matching engine compares each active order to the passive orders, one active order at time. For example, if there is an active order for the symbol X, that order is compared against the passive orders first before another active order for X can enter the matching engine for comparison.

You can use the module service classes to determine which potential matches become actual matches. These services let you refine your matching rules depending on your exchange requirements as shown Figure 3-2.

Figure 3-2    Refining Order Matches


Module Services Classes

Under each system matching service class you can specify module service classes. You can customize the module service classes to implement specific matching rules in your exchange. These class names have a suffix of ModuleService. Their paths have a prefix that is not com.iplanet. For example, in the BasicSchema.xml and the TransportSchema.xml sample exchange schema files, the module service classes have the com.reference prefix.

You can edit the sample module service classes in the iPlanet Market Maker Exchange module, or use them as templates to create new module service classes. You can find the .java files for the sample exchanges in the following directory:

<imm_install_dir>/iMM/doc/exchange/sample

where <imm_install_dir>is the directory where you installed your iPlanet Market Maker software.


Example
Suppose you want to specify a preferential trading arrangement for a list of preferred companies so that orders on this list are automatically matched before all other orders. The name of your module service class to implement this capability might be PreferredListMatchingModuleServiceImpl.java. Because you want rule to be applied for automated matching, you add this class under the MatchingEngineService system service class. See the highlighted text in Table 3-1.

Table 3-1    Specifying an Additional Module Class

<SERVICE name="MatchingEngineService"

impl_class="com.iplanet.ecommerce.vortex.exchange.service.impl.MatchingEngineServiceImpl">

    <SERVICE_PROPERTIES>

       <SERVICE_PROPERTY name="SystemMatchingEnabled" value="true"/>

        <SERVICE_PROPERTY name="SystemMatchingModuleServiceKey.0" value="NVPMatchingModuleService"/>

        <SERVICE_PROPERTY name="SystemMatchingModuleServiceKey.1" value="BlackListMatchingService"/>

        <SERVICE_PROPERTY name="SystemMatchingModuleServiceKey.2" value="PreferredListMatchingModuleServiceImpl"/>

        <SERVICE_PROPERTY name="SystemAggregationAxesMatchingModuleServiceKey" value="PruneAggregatedAxisMatchingModuleService"/>

       <SERVICE_PROPERTY name="ManualMatchingEnabled" value="true"/>

        <SERVICE_PROPERTY name="ManualMatchingModuleServiceKey.0" value="BlackListMatchingService"/>

        <SERVICE_PROPERTY name="ManualMatchCalculatorImplClass" value="com.reference.energyb.service.ManualMatchCalculatorImpl" />

        <SERVICE_PROPERTY name="message.topic.matches" value="matches"/>

    </SERVICE_PROPERTIES>

</SERVICE>

<SERVICE name="NVPMatchingModuleService" impl_class="com.reference.energyb.service.NVPMatchingModuleServiceImpl">

        <SERVICE_PROPERTIES>

        <SERVICE_PROPERTY name="NVPAxisName.0" value="PriceAxis" />

        <SERVICE_PROPERTY name="NVPAxisName.1" value="QuantityAxis"/>

    <SERVICE_PROPERTY name="NVPAxisName.2" value="CapacityAvailableDateAxis"/>

    </SERVICE_PROPERTIES>

</SERVICE>

<SERVICE name="BlackListMatchingService" impl_class="com.reference.energyb.service.BlackListMatchingModuleServiceImpl">

    <SERVICE_PROPERTIES>

    </SERVICE_PROPERTIES>

</SERVICE>

<SERVICE name="PreferredListMatchingModuleServiceImpl" impl_class="com.reference.energyb.service.PreferredListMatchingModuleServiceImpl">

    <SERVICE_PROPERTIES>

    </SERVICE_PROPERTIES>

</SERVICE>

...


Table 3-1 lists the module service classes that define the logic for the matching rules.

Table 3-2    Module Service Classes 

Module Class Name

Description

BallonImpl  

Contains the logic to increase, or balloon, axes to enable extended matches for buy and sell orders with axes that are a close, but not exact, matches.  

BlackListMatchingModuleServiceImpl  

The logic to filter out matching orders from companies on a black list. Users on a black list are not allowed to trade with a particular company.  

ManualMatchCalculatorImpl  

Contains the logic to calculate the remaining quantity, if any, of manually matched buy and sell orders.  

NVPMatchingModuleServiceImpl  

Compares all the axes to determine which potential matching buy and sell orders are exact matches.  

OrderSequenceServiceImpl  

Lets you customize the priority order in which to process incoming orders. The sample implementation specifies that orders are passed to the matching engine according to their time stamp.  

PruneAggregatedAxisMatchingModuleServiceImpl  

Prunes a list of matching orders and returns a subset of orders that collectively satisfy an aggregated axis, which is usually the quantity axis. This class also computes the remaining value of the aggregated axis to enable matching partial orders.  

TransportQuoteServiceImpl  

Contains the logic to determine the current market price for a symbol.  


Matching Orders in the Exchange User Interface

To determine actual matching orders from a set of potential matching orders, the ExtendedMatchingEngineServiceImpl service class uses a mechanism similar to that of the MatchingEngineServiceImpl class. But the ExtendedMatchingEngineServiceImpl service class does not produce actual matches. Instead, it and suggests identifies potential matching orders to be displayed in the Exchange module user interface, allowing you to manually perform matching of the buy and sell orders in the user interface. This is referred to as lifting orders. You can further refine this lifting as either standalone lifting or reference lifting.


Standalone Lifting

In a standalone lift, passive orders are displayed in the Exchange module user interface. When you lift an order, the Exchange module automatically creates an opposing matching order. For example, if your lift is for a buy order, a matching sell order is created automatically.

If you specify a quantity in your lift order that is less than the quantity of the symbols available in the exchange, the remaining quantity is returned to the exchange as a new active order with the original order number.


Reference Lifting

In a reference lift, passive orders are also displayed in the Exchange module user interface. However, the Exchange module does not automatically create an opposing matching order. Instead, you specify a reference order to lift in relation to a list of passive orders. For example, if your reference order is a buy order, you must lift a passive sell order.

A reference lift also lets you determine, per order, whether any quantity remaining from the lifted order is to be canceled or returned to the exchange as an active order. See Figure 3-3.

Figure 3-3    Potential Manual Order Matches

Table 3-3 shows an example of system and module service classes. To see a similar example, open the BasicSchema.xml or TransportSchema.xml file in the <ias_inst_dir>/ias/APPS/imm40/imm40/WEB-INF/classes/exchange directory (where <ias_inst_dir> is the location where you installed your iPlanet Applications Server software) in a text editor and search for MatchingEngineService.


Note In code, the ellipses (...) mean that some syntax is omitted.



In Table 3-3, MatchingEngineService is a system service class and NVPMatchingModuleService is a module class. ExtendedMatchingEngineService is a system service class and BallonServiceImp is a module service class. Each module and system service has an implementation class name and a set of service properties. Each service property has a name and value. Table 3-3    Matching Engine Services 

<SERVICE name="MatchingEngineService"

impl_class="com.iplanet.ecommerce.vortex.exchange.service.impl.MatchingEngineServiceImpl">

    <SERVICE_PROPERTIES>

       <SERVICE_PROPERTY name="SystemMatchingEnabled" value="true"/>

        <SERVICE_PROPERTY name="SystemMatchingModuleServiceKey.0" value="NVPMatchingModuleService"/>

...

</SERVICE>

<SERVICE name="NVPMatchingModuleService" impl_class="com.reference.energyb.service.NVPMatchingModuleServiceImpl">

        <SERVICE_PROPERTIES>

        <SERVICE_PROPERTY name="NVPAxisName.0" value="PriceAxis" />

        <SERVICE_PROPERTY name="NVPAxisName.1" value="QuantityAxis"/>

    <SERVICE_PROPERTY name="NVPAxisName.2" value="CapacityAvailableDateAxis"/>

    </SERVICE_PROPERTIES>

</SERVICE>

...

<SERVICE name="ExtendedMatchingEngineService"

impl_class="com.iplanet.ecommerce.vortex.exchange.service.impl.ExtendedMatchingEngineServiceImpl">

    <SERVICE_PROPERTIES>

        <SERVICE_PROPERTY name="MatchingModuleServiceKey.0" value="NVPExtMatchingModuleService"/>

        <SERVICE_PROPERTY name="MatchingModuleServiceKey.1" value="BlackListMatchingService"/>

        <SERVICE_PROPERTY name="BalloonServiceKey" value="BalloonService"/>

        <SERVICE_PROPERTY name="message.topic.extended_matches" value="extended_matches"/>

    </SERVICE_PROPERTIES>

</SERVICE>

...

<SERVICE name="BalloonService"

impl_class="com.iplanet.ecommerce.vortex.exchange.service.impl.BalloonServiceImpl">

    <SERVICE_PROPERTIES>

        <SERVICE_PROPERTY name="BalloonFunction" value="com.reference.energyb.balloon.BalloonImpl" />

    </SERVICE_PROPERTIES>

</SERVICE>




Defining Trading Rules Services



If your exchange has a price axis, you must define trading rules to convert matched orders to traded orders. The TradeEngineService system service class implements the logic for the trading rules. You can use the sample PricingTradeModuleServiceImp module service class as a template, or create your own trading rules in a different class. See Table 3-4. Table 3-4    Trade Engine Services

<SERVICE name="TradeEngineService"

impl_class="com.iplanet.ecommerce.vortex.exchange.service.impl.
TradeEngineServiceImpl">

    <SERVICE_PROPERTIES>

        <SERVICE_PROPERTY name="TradeModuleServiceKey.0" value="PriceTradeModuleService"/>

        <SERVICE_PROPERTY name="message.topic.trades" value="trades" />

    </SERVICE_PROPERTIES>

</SERVICE>

...

</SERVICE>

<SERVICE name="PriceTradeModuleService" impl_class="com.reference.transport.service.PricingTradeModuleServiceImpl">

    <SERVICE_PROPERTIES>

        <SERVICE_PROPERTY name="PricingAxisName" value="PriceAxis" />

    </SERVICE_PROPERTIES>

</SERVICE>


You specify trading rules to assign attributes to matched buy and sell orders. A final trade price is a typical type of attribute. The trading rules follow a model similar to that of the matching rules shown in Figure 3-2, except that there is no refining, or pruning, of matched orders. Every matched order becomes a traded order. See Figure 3-4. The difference is that traded orders have attributes that specify the basis for settling trades, such as price, or whatever is relevant to the requirement of the exchange.


Example
Suppose that as a result of the matching rules you defined, there is a matching order with a buy price of $8 and a sell price of $10. The Exchange module needs a trading rule to determine whether the final trade price is $8, $10, or some price in between the two.

Figure 3-4    Matched and Traded Orders


Previous     Contents     Index     Next     
Copyright © 2001 Sun Microsystems, Inc. All rights reserved.

Last Updated April 03, 2002