Chapter 2   Defining the Exchange Attributes


This chapter provides instructions for setting up attributes to identify order matching criteria for the iPlanet Market Maker Exchange module.

This chapter contains the following sections:

• Overview

• Implementing the Exchange Attributes

Overview

---

To be able to match buy and sell orders, the Exchange module must first know what criteria to use to identify whether a match does, or does not, exist. This is accomplished by defining a common set of attributes, also known as the matching criteria. This set of attributes, such as price and quantity, is the basis for comparing orders in an exchange. After you have defined these attributes, the Exchange module compares these attributes to identify potential matches between buy orders and sell orders.

Symbols in an exchange are similar and share common matching attributes. To set up an exchange, you need to specify the symbols you want to trade and the attributes associated with those symbols. Because of the flexible nature of the iPlanet Market Maker Exchange module, you can define whatever attributes are necessary to compare orders.

An exchange has the following types of attributes:

• Criteria attributes

• Dimensions attributes

• Axes attributes

Criteria

Criteria define all the information required to place an order in an exchange. Each criteria has a set of criteria fields, which you enter in the Exchange module user interface. The criteria fields specify the quantity you want to buy or sell, at what price, and so on. These are the front-end, or human-entered, or specified, matching attributes in an exchange.

Dimension

Axes and criteria are based on dimensions, which define their internal value types.

Axes

Axes provide a set of values to allow comparisons between orders. They are the back-end matching engine-readable representations of matching criteria.

Flattening

To convert the criteria to a set of matching attribute values that the Exchange module can interpret, you define a flatten function, which is a Java class that translates the criteria to the values of the exchange axes. The Exchange module processes the axes values to identify potential matches.

Figure 2-1 shows an example of the relationship between axes and criteria. The left side shows the defined criteria and criteria fields that appear in an Exchange module user interface. In this example, the Order Criteria of Market means that the buyer or seller accepts the current market price, so no explicit price is specified. Other criteria types might require you to specify a price.

The right side of Figure 2-1 represents the exchange processing that takes place after the flatten function converts the criteria fields to a value of the axis that the Exchange module uses to identify potential order matches.

Figure 2-1    Criteria and Axes in an Exchange

There is a flatten function for each criteria. It is possible for a flatten function to convert more than one criteria field to the same axis, as shown in Figure 2-1. Figure 2-2 shows another representation of how a flatten function converts criteria to axes.

Figure 2-2    Flattening More Than One Criteria Field to the Same Axis

Often there is a one-to-one correspondence between axes and criteria, but not always. In an Exchange module user interface you might specify a quantity criteria field as an amount, and also have an option to accept a partial quantity.

Example
Suppose that Figure 2-3 is a buy order, willing to accept a partial quantity, for 10 widgets. There is a previous buy order in the exchange for 10 widgets only, and a sell order for 7 widgets. Because there are orders to buy 20 widgets and sell 7 widgets, the Exchange module needs a method for comparing 20 to 7 to determine if there is a potential match. In this case, quantity is not a single value as specified in the user interface, but is a range of values.

In the example, the buy order for 10 widgets willing to accept a partial quantity is a potential match with the sell order for 7 widgets. The other buy order for 10 widgets not willing to accept a partial quantity is not a potential match with the order to sell 7 widgets.

Figure 2-3    Buy Order Accepting a Partial Quantity

To determine if there are potential matches, the Exchange module compares all the axes of all the buy and sell orders. If there is any non-zero overlap in all the axes of a buy and sell order, there is a potential match. Figure 2-4 shows a representation of the axes associated with the criteria fields in Figure 2-3.

Figure 2-4    Exchange Axes for Matching Buy and Sell Orders

Example
Suppose, given the criteria and axes in Figure 2-3 and Figure 2-4, there is a buy order for 10 symbols and a sell order for 7 symbols. The Exchange module compares the buy and sell order axes values to determine if there is a potential match.

Table 2-1 shows another interpretation of the axes in Figure 2-4. A potential match requires a Yes in the Potential Match column for all axes in a buy and sell order. Because the order is for the market price, and not for a specific price or range of prices, the Price axis is irrelevant in the comparison. If both the buy and sell orders accept the market price, the Price axis has an overlap by default. Note that this potential match need not be exact, as is the case with the Quantity axis.

Table 2-1    Matching Potential Buy and Sell Orders

Axis	Order Number	Buy Order	Sell Order	Potential Match
Quantity	Order 1 Order 2	10, will accept a partial quantity 10 only	7 7	Yes No
Capacity Available Date	Order 1 Order 2	03/30/01 03/30/01	03/30/01 06/01/01	Yes No

Implementing the Exchange Attributes

---

The requirements that define the schema for an exchange depend on the symbols you want to trade. The exchange symbols, criteria, axes, and the user interface in which to enter the criteria are defined using an XML file.

The iPlanet Market Maker software comes with two sample exchange implementations. The schema files for these exchanges are in this directory:

<ias_inst_dir>/ias/APPS/imm40/imm40/WEB-INF/classes/exchange

where <ias_inst_dir> is where you installed your iPlanet Application Server software.

The sample schema files are:

• BasicSchema.xml file

• TransportSchema.xml file

You can copy these files and use them as templates to edit and set up the schema for your exchange. The ExchangeList.xml file in the same directory lists the exchanges in a marketplace. This file lets you define multiple exchanges on a single host.

The following sections explain the tasks of implementing the symbols, criteria, and axes for a sample exchange (this sample is for trading natural gas energy services):

• Defining the Symbols to be Traded

• Defining Axes

• Defining Criteria

• Defining Dimensions

• Defining the Life Spans for Orders

• Defining an Exchange User Interface

Defining the Symbols to be Traded

The names of the symbols to be traded in the sample energy exchange are.

• Arg Gas Phy (Buenos Aires)

• Arg Gaos Phy (GBA)

• Arg Gas Phy (Litoral)

• BEL Gas Phy Fwd

• BEL Gas Phy (ZEE HUB)

• US Gas Swap (Nymex)

• US Gas Phy Index (IF Transco Z6NY)

• US Gas Basis (NGI Chicago)

• CAN Gas Phy (NIT)

• CAN Gas Basis (GD/D Dawn)

• UK Gas Phy (NBP)

• NL Gas Phy Fwd (Oude/BEB H-Gas)

By default, the symbol catalog data store is located in the same directory as the schema file. This can be changed by modifying the service property FILE for the SymbolCatalogService.

Language-specific symbol stores can be added in the standard Java fashion. For example, a French version of the <exchange_name>Symbol.properties file should be named <exchange_name>Symbol_fr.properties; it can be referenced in the exchange schema descriptor file with its path.

To locate the file containing the definitions of symbols for an exchange, search for SymbolCatalogService in the schema descriptor file of the exchange. The definition of Symbol Catalog Service in the XML schema descriptor file, and the syntax, are shown in Table 2-2 and Table 2-4 respectively.

<SERVICE name="SymbolCatalogService" impl_class ="com.reference.energyb.service.PropertyBasedSymbolCatalogServiceImpl">       <SERVICE_PROPERTIES>               <SERVICE_PROPERTY name="FILE" value="exchange/EnergyBSymbols"/>       </SERVICE_PROPERTIES> </SERVICE>

The Table 2-3 below shows the contents of the EnergyBsymbol.xml file which defines the symbols for the exchange EnergyB. This file defines the order in which the exchange symbols are loaded and displayed in the user interface. To localize the exchange, language-specific symbols, for example, French, can be stored in the ExchangeBSymbol_fr.properties file. This file can then be referenced in the exchange XML schema descriptor EnergyBSchema.xml file

---

Note	The symbol GUID should not be localized.

---

SYMBOL0=Arg_Gas_Phy_Buenos_Aires;Arg Gas Phy (Buenos Aires);Arg Gas Phy (Buenos Aires) SYMBOL1=Arg_Gas_Phy_GBA;Arg Gas Phy (GBA);Arg Gas Phy (GBA) SYMBOL2=Arg_Gas_Phy_Litoral;Arg Gas Phy (Litoral);Arg Gas Phy (Litoral) SYMBOL3=BEL_Gas_Phy_Fwd;BEL Gas Phy Fwd;BEL Gas Phy Fwd SYMBOL4=BEL_Gas_Phy_ZEE_HUB;BEL Gas Phy (ZEE HUB);BEL Gas Phy (ZEE HUB) SYMBOL5=US_Gas_Swap_Nymex;US Gas Swap (Nymex);US Gas Swap (Nymex) SYMBOL6=US_Gas_Phy_Index_IF_Transco_Z6NY;US Gas Phy Index (IF Transco Z6NY);US Gas Phy Index (IF Transco Z6NY) SYMBOL7=US_Gas_Basis_NGI_Chicago;US Gas Basis (NGI Chicago);US Gas Basis (NGI Chicago) SYMBOL8=CAN_Gas_Phy_NIT;CAN Gas Phy (NIT);CAN Gas Phy (NIT) SYMBOL9=CAN_Gas_Basis_GD/D_Dawn;CAN Gas Basis (GD/D Dawn);CAN Gas Basis (GD/D Dawn) SYMBOL10=UK_Gas_Phy_NBP;UK Gas Phy (NBP);UK Gas Phy (NBP) SYMBOL11=NL_Gas_Phy_Fwd_Oude/BEB_H-Gas;NL Gas Phy Fwd (Oude/BEB H-Gas);NL Gas Phy Fwd (Oude/BEB H-Gas)

Table 2-4    SERVICE and SERVICE_PROPERTY Tag Arguments

Symbol Argument	Value Type	Description
SERVICE name	SymbolCatalogService	Name of the service.
impl_class	STRING	Name of the Java class file that reads the symbol definitions in the <exchange_name>Symbol.properties file.
SERVICE_PROPERTY
name	FILE	Indicates that the symbols are contained in a file.
value	STRING	Points to the file containing the symbols.

Defining Axes

To locate the definitions for the axes in one of the sample XML files, search for >AXIS_CONFIG. The syntax and definitions for the quantity axis in this exchange are shown in Table 2-6. Table 2-5    Sample Quantity Axis Definition

---

<AXIS_CONFIG guid="energy_quantityAxis_guid"

name="QuantityAxis"

index="1"

dimension="energy_quantity_guid"

is_aggregation="true"/>

The arguments for the AXIS_CONFIG tag are described Table 2-6.

Table 2-6    AXIS_CONFIG Tag Arguments

Axis Argument	Value Type	Description
guid	guidid	Unique identifier for the axis.
name	STRING	A name that identifies the axis.
index	INTEGER	Specifies the sequence number for the axis (1, 2, 3, and so on).
dimension	STRING	Specifies the GUID of the dimension on which the axis is based.
is_aggregation	BOOLEAN	Specifies whether to add (aggregate) the axes values for orders. Set this value to True for only one axis that contains the values that need to be combined, usually for the quantity axis. For all the other axes, set this value to False.

Defining Criteria

To locate the definitions for the criteria in one of the sample XML files, search for <CRITERIA>.

---

Note	You specify the flatten function file name in the flatten argument for the CRITERIA tag. This class contains the logic that converts the data defined in each CRITERIA_FIELD tag to an axis.

---

In an exchange XML file, there are two types of Java class files:

• Classes prefaced with com.iplanet—These are exchange system classes that you generally do not have to customize to create your own exchange.

• Classes prefaced with com.reference—These are classes that you might need to customize or replace, depending on the needs of your exchange. The flatten class file is an example.

If you want to introduce a new criteria, you must write a flattening class function and specify the function name for the flatten argument. You can also extend the flattening class of one criteria and implement the flattening logic for another criteria.

The syntax and definitions for the market order criteria in the energy exchange is shown in Table 2-8. Table 2-7    Sample Market Criteria Definition

---

<CRITERIA guid="energy_market_guid"

name="Market"

action="ANY"

flatten="com.reference.energy.flatten.Market">

<CRITERIA_FIELDS>

<CRITERIA_FIELD name="Quantity"

dimension="energy_quantity_guid"/>

<CRITERIA_FIELD name="Partials"

dimension="energy_boolean_guid"/>

<CRITERIA_FIELD name="CapacityAvailableDate"

dimension="energy_date_guid"/>

</CRITERIA_FIELDS>

</CRITERIA>

The arguments for the CRITERIA and CRITERIA_FIELD tags are listed in Table 2-8.

Table 2-8    CRITERIA Tag Arguments

Criteria Argument	Value Type	Description
CRITERIA guid	guidid	Unique identifier for the criteria.
name	STRING	A string that identifies the criteria.
action	BUY	BUY specifies that the criteria applies to a buy order, SELL to a sell order, and ANY to both.
	SELL
	ANY
flatten	Java class	Specifies the Java class file used to flatten the criteria to a set of axis values that the Exchange module can use to identify potential matching buy and sell orders.
CRITERIA_FIELD
	name	Name of the criteria field that appears in the Exchange module user interface.
	dimension	GUID for the dimension associated with the criteria field.

Defining Dimensions

To locate the definitions for the dimensions in one of the sample XML files, search for <DIMENSION>. The syntax and definitions for the market order criteria in this exchange is shown in and Table 2-10. Table 2-9    Sample Quantity Dimension Definition

---

<DIMENSION guid="energy_quantity_guid"

name="Quantity"

type="INT"

compare_function="DEFAULT"

distance_function="DEFAULT"

aggregation_function="DEFAULT"

boundary_min="1">

</DIMENSION>

The arguments for the DIMENSION tag are described in Table 2-10.

Table 2-10    DIMENSION Tag Arguments 

Dimension Argument	Value Type	Description
guid	guidid	Unique identifier for the dimension.
name	STRING	A string that identifies the dimension
type		Defines the type of the dimension: int, REAL, TIME, SET, FREEFORM.
	int	A positive whole number that maps to a Java primitive int.
	REAL	An irrational or rational number that maps to a Java primitive double.
	TIME	A date and time that maps to a Java type java.util.Date.
	SET	A collection of values that maps to a Java type java.util.Map.
	FREEFORM	A value expressed as a string. This attribute type is used to match values that are not known in advance, such as the member ID for a preferred customer. FREEFORM dimensions do not have an associated Order or Distance function.
compare_function		Specifies if the dimension values are ordered and how they can be compared based on that order. This attribute lets you define a non-alphanumeric type of comparison. You usually do not have to change this attribute and can leave it set to DEFAULT.
	DEFAULT
distance_function		Allows for the computation of the distance between two values. For example, you can specify if the dimension values have a distance between them, such as the distance between two airports. You usually do not have to change this attribute and can leave it set to DEFAULT.
	DEFAULT
aggregation_function
	DEFAULT	Specifies if the dimension allows its values to be combined (aggregated). You can specify an aggregation attribute (DEFAULT) for only one dimension, usually the quantity dimension of the symbol to be traded in the exchange. For the other dimensions, specify NONE.
	NONE
boundary_min	Null or number	Value that represents the minimum value for the dimension. Null represents infinity. This attribute is optional.
boundary_max	Null or number	Value that represents the minimum value for the dimension. Null represents infinity. This attribute is optional.
DIMENSION_SET	Set	Defines a set of dimension values, such as True and False to define a Boolean set.

Defining the Life Spans for Orders

To control how long orders are eligible to be matched in an exchange, specify the information for the LIFESPANS tag. Search for <LIFESPANS> in one of the sample files.

Table 2-11    Sample Life Span Definitions 

---

<LIFESPAN guid="energyb_goodUntilCancel_guid"

name="GoodUntilCancel"

action="ANY"

calculator="com.reference.energyb.lifespan.GoodUntilCancel">

<LIFESPAN_FIELDS>

</LIFESPAN_FIELDS>

</LIFESPAN>

<LIFESPAN guid="energyb_immediateOrCancel_guid"

name="ImmediateOrCancel"

action="ANY"

calculator="com.reference.energyb.lifespan.ImmediateOrCancel">

<LIFESPAN_FIELDS>

</LIFESPAN_FIELDS>

</LIFESPAN>

<LIFESPAN guid="energyb_goodUntilDate_guid"

name="GoodUntilDate"

action="ANY"

calculator="com.reference.energyb.lifespan.GoodUntilDate">

<LIFESPAN_FIELDS>

<LIFESPAN_FIELD name="ExpireDate"

dimension="energyb_date_guid"/>

</LIFESPAN_FIELDS>

</LIFESPAN>

</LIFESPANS>

The syntax and definitions for life spans in this exchange is shown in Table 2-12.

Table 2-12    LIFEPANS> Tag Arguments 

Life Span Argument	Value Type	Description
LIFESPAN guid	guidid	Unique identifier for the life span.
name	STRING	A string that identifies the life span.
action	BUY	BUY specifies that the criteria applies to a buy order, SELL to a sell order, and ANY to both.
	SELL
	ANY
calculator	Java class	Specifies the Java class file used to calculate the life span of an order.
LIFESPAN_FIELD
	name	Name of the life span field that appears in the exchange user interface.
	dimension	GUID for the dimension associated with the life span field.

Defining an Exchange User Interface

To locate the definitions for the Exchange module user interface, search for <UI_CRITERIAS>. Table 2-13    Sample User Interface Definitions

---

<UI_CRITERIAS guid="energy_ui_criterias_guid"

widgettype="RADIOBUTTON"

ask_default_guid="energy_ui_criteria_market_guid"

bid_default_guid="energy_ui_criteria_market_guid">

<UI_CRITERIA guid="energy_ui_criteria_market_guid"

name="Market"

descriptor_guid="energy_market_guid"

action="ANY">

<UI_CRITERIA_FIELDS>

<UI_CRITERIA_FIELD criteria_field_name="Quantity"

label="Quantity"

widgettype="TEXT"

row="1"

col="1"

screen="2">

</UI_CRITERIA_FIELDS>

The arguments for the UI_CRITERIA tag are described in Table 2-14

Table 2-14    UI_CRITERIA Tag Arguments 

UI Criteria Argument	Value Type	Description
guid	guidid
label	STRING
widgettype	RADIOBUTTON, CHOICE, or LIST
ask_default_guid	UI_CRITERIA.guid
bid_default_guid	UI_CRITERIA.guid
UI_CRITERIA
guid	guidid
name	STRING
descriptor_guid	CRITERIA guid
action	BUY, SELL, or ANY
UI_CRITERIA_FIELD
criteria_field_name	STRING
label	STRING	Specifies the default name for the i18n string.
widgettype	TEXT, PASSWRD, HIDDEN, STRING, RADIOBUTTON, CHECKBOX, CHOICE, LIST, MULTILIST, DATE	Specifies the HTML component type for the criteria field.
row	INTEGER	Specifies the row number in which the criteria field is displayed relative to the other criteria fields.
column	INTEGER	Specifies the column number in which the criteria field is displayed relative to the other criteria fields.
screen	INTEGER	Specifies the screen number in which the criteria field is displayed.
UI_CRITERIA_FIELD_ITEM
description	STRING	Name in list of choices displayed for a criteria field.
value	STRING	Value of the description attribute.
default	INTEGER	Specifies the order of the entry in a list of choices displayed for a criteria field.

.