Capture Fields and Parent Schemas Sample

Contents

Introduction
Running the Provided Unit Test
Running This Sample in StreamBase Studio
Running This Sample in Terminal Windows
Importing This Sample into StreamBase Studio
Sample Location

Introduction

This sample demonstrates how to use capture fields in conjunction with parent schemas to create a reusable module that can match orders for FX trading in one instance and can match orders for Equities trading in another copy of the identical, unchanged module. The module uses abstract schemas for its input stream and Query Table that become concrete schemas in actual use.

This sample consists of the following files:

File Purpose
SharedSchemas.sbint A StreamBase interface file that defines named schemas and a table schema used by the two EventFlow modules.
TopLevelFX.sbapp A simple EventFlow module used in this sample as the top-level outer module. It accepts a stream of foreign exchange (FX) trade orders and sends them to the OrderMatcher.sbapp inner module for processing. This module has an output stream that reports filled orders, and a second input stream that triggers a read-all-rows operation of the inner module's Query Table.
OrderMatcher.sbapp An EventFlow module that implements an asset-agnostic order matching engine, used in this sample as the inner module. This module matches parties who would like to sell assets with parties who would like to buy those assets.

Notice that there are no FX-specific schemas in this module. The input stream and Query Table are both defined with abstract schemas that include capture fields, which means the module can handle any generic traded asset. This allows the same module to be re-used to handle different asset classes.

TestFxOrderMatching.java A StreamBase sbunit test file In the java-src subdirectory. Run this file as a StreamBase unit test to verify that the sample accepts input and returns the expected results.

The important lessons of this sample are in the six named schemas and one table schema defined in SharedSchemas.sbint. The alphabetic order of the schemas in the interface file is also the best order to study them and understand how they work.

Named Schema Description
AbstractInstrument Consists of a single capture field named placeholder with data type placeholderFields.
AbstractOrder Consists of a number of fields for data that is in orders for all instrument types, plus a tuple field named Instrument consisting of a single sub-field, the capture field with data type placeholderFields. This schema is used in the OrderMatcher.sbapp module's input stream, which allows copies of that module to handle orders for varying asset types.
EquitiesInstrument A schema for an equities trade instrument, consisting of parent schema AbstractInstrument plus a single Symbol field.
EquitiesOrder Consists of one parent schema, AbstractOrder, plus one concrete override field that replaces the abstract field of the same name. The Instrument field with data type EquitiesInstrument overrides the abstract Instrument field with type AbstractInstrument because and only because it has the exact same field name, case sensitive.

Notice that the Fields grid that defines this schema uses seven rows to define six fields. This is because the Instrument field is defined once in the parent schema and again in this schema so that the concrete field can override the abstract one.

FXInstrument A schema for a foreign exchange trade instrument, consisting of parent schema AbstractInstrument plus two string fields to hold the two currencies being traded.
FXOrder Like EquitiesOrder above, consists of one parent schema, AbstractOrder, plus one concrete override field that replaces the abstract field of the same name. The Instrument field with data type FXInstrument overrides the abstract Instrument field with type AbstractInstrument because it has the exact same field name, case sensitive.
Table Schema Description
AbstractOrderBookSchema A schema for Query Tables that uses the AbstractOrder named schema and defines keys for it.

It is important to understand that a Query Table can only use a concrete schema at runtime. Using the AbstractOrder schema here allows the Query Tables in different copies of the containing module to take on different concrete schemas based on the same abstract schema defined here.

Running the Provided Unit Test

Follow these steps to run the provided unit test in StreamBase Studio:

  1. In the Package Explorer, open the java-src tree, and open the TestFxOrderMatching.java file. Make sure the file is the currently active tab in the EventFlow Editor.

  2. From Studio's top-level menu, invoke Run → Run As → StreamBase Unit Test.

  3. In the JUnit view, observe the test running to completion, with a solid green bar indicating success.

  4. Edit and re-run the test file as desired to test different scenarios.

Running This Sample in StreamBase Studio

  1. In the Package Explorer, double-click to open the TopLevelFX.sbapp module. Make sure the module is the currently active tab in the EventFlow Editor.

  2. Click the Run button. This opens the SB Test/Debug perspective and starts the module.

  3. Open the Manual Input view and select the Orders stream. notice that the Instrument tuple field shows only the concrete Currency1 and Currency2 fields. The capture field that comprised the original abstract Instrument field was overridden by the concrete Instrument field. This replaced the capture field that has data type placeholderFields with the concrete fields Currency1 and Currency2.

  4. Enqueue two tuples to the Orders stream in the Manual Input view:

    Field Tuple 1 Tuple 2
    Id 1 2
    Instrument.Currency1 USD USD
    Instrument.Currency2 CAD CAD
    Price 1.0525 1.0564
    IsBid no yes
    Quantity 1000 1000
    Party A B

  5. Observe a matching order emitted from the Fills stream in the Application Output view.

  6. Enter other tuples as desired. Remember that no order emits from the Fills stream until there is a match between IsBid=no and IsBid=yes tuples.

  7. When done, press F9 or click the Stop Running Application button.

To understand how the inner module can be re-used to handle a different asset type, perform the following additional steps:

  1. Open the TopLevelFX.sbapp module.

  2. Select all six components and invoke Ctrl+C, Ctrl+V to make a second copy of the module on the same canvas. The copied components take the same names as their counterparts with "Copy" appended.

  3. Double-click the OrdersCopy input stream to open its Properties view.

  4. In the Edit Schema tab, select the EquitiesOrder schema in the drop-down control. This is the only step necessary to convert the OrderMatcherRefCopy module to process order matching for equities orders instead of FX orders.

  5. Save the module and click the Run button.

  6. In the Manual Input view, select the OrdersCopy stream. Notice that the Instrument tuple field now shows only a single field, Symbol.

  7. Enqueue two tuples to the OrdersCopy stream in the Manual Input view:

    Field Tuple 1 Tuple 2
    Id 10 20
    Instrument.Symbol GOOG GOOG
    Price 580.50 580.75
    IsBid no yes
    Quantity 50 50
    Party AA BB

  8. Observe a matching order emitted from the FillsCopy stream in the Application Output view.

  9. Enter other tuples as desired, matching IsBid=no and IsBid=yes tuples to see output from the FillsCopy stream.

  10. When done, press F9 or click the Stop Running Application button.

Running This Sample in Terminal Windows

This section describes how to run the sample in UNIX terminal windows or Windows command prompt windows. On Windows, be sure to use the StreamBase Command Prompt from the Start menu as described in the Test/Debug Guide, not the default command prompt.

The following steps presume you have modified the TopLevelFX.sbapp module as described in the additional steps section above.

  1. Open four terminal windows on UNIX, or four StreamBase Command Prompts on Windows. In each window, navigate to your workspace copy of the sample, as described below.

  2. In window 1, launch StreamBase Server running TopLevelFX.sbapp:

    sbd TopLevelFX.sbapp

  3. In window 2, run a dequeuer for the two output streams:

    sbc deq Fills FillsCopy

    (You can optionally run separate dequeuers in separate windows.)

  4. In window 3, run an enqueuer to the Orders stream:

    sbc enq Orders

  5. In window 4, run an enqueuer to the OrdersCopy stream:

    sbc enq OrdersCopy

  6. In window 3, enter the following tuples: 

    1,"USD,CAD",1.0525,no,1000,A
2,"USD,CAD",1.0564,yes,1000,B

  7. In window 2, observe a fill order tuple: 

    Fills,"2,""USD,CAD"",1.0564,true,0,B","1,""USD,CAD"",1.0525,false,0,A",1000

  8. In window 4, enter the following tuples: 

    10,GOOG,580.50,no,50,AA
20,GOOG,580.75,yes,50,BB

  9. In window 2, observe a fill order tuple: 

    FillsCopy,"20,GOOG,580.75,true,0,BB","10,GOOG,580.5,false,0,AA",50

  10. To stop the sample, type Ctrl+C in one of the enqueuer windows, then run sbadmin shutdown.

Importing This Sample into StreamBase Studio

In StreamBase Studio, import this sample with the following steps:

  • From the top menu, select File → Load StreamBase Sample.

  • In the search field, type capture to narrow the list of samples.

  • Select CaptureParentSchemas from the Data Constructs and Operators category.

  • Click OK.

StreamBase Studio creates a single project containing the sample files.

Sample Location

When you load the sample into StreamBase Studio, Studio copies the sample project's files to your Studio workspace, which is normally part of your home directory, with full access rights.

Important

Load this sample in StreamBase Studio, and thereafter use the Studio workspace copy of the sample to run and test it, even when running from the command prompt.

Using the workspace copy of the sample avoids the permission problems that can occur when trying to work with the initially installed location of the sample. The default workspace location for this sample is: 

studio-workspace/sample_CaptureParentSchemas

See Default Installation Directories for the location of studio-workspace on your system.

In the default TIBCO StreamBase installation, this sample's files are initially installed in: 

streambase-install-dir/sample/CaptureParentSchemas

See Default Installation Directories for the location of streambase-install-dir on your system. This location may require administrator privileges for write access, depending on your platform.