- Index

< Previous |  | Next >

# Capture Fields and Parent Schemas Sample

## 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 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.

## Importing This Sample into StreamBase Studio

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

- From the top-level 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.

## Running the Provided Unit Test

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

1. In the Project Explorer view, 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 Project Explorer view, 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 Output Streams 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 Terminate EventFlow Fragment 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 Output Streams 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 Terminate EventFlow Fragment button.

## 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 permission problems. The default workspace location for this sample is:

    studio-workspace/sample_CaptureParentSchemas

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