StreamBase Legacy Feed Simulation Configuration XML

<feed-simulation> Element

Required.

The root element in .sbfs files. The <feed-simulation> element contains zero or more <define-enum> elements, followed by an <application...> element, and one or more <stream> elements.

Format

<feed-simulation>
    ...
</feed-simulation>

<define-enum> Element

Optional.

Defines an enumeration, a set of possible values for a field. <define-enum> contains one or more <value> tags.

Format

<define-enum name="enumeration-name">
    <value weight="w1">value1</value>
    <value weight="w2">value2</value>
    <value>value3</value>
         ...
</define-enum>

Attributes

Attribute Name	Required?	Description
`name`	Yes	A unique name for the enumeration. This name is used later as the `ref` attribute to the `<enum>` tag in order to actually use the enumeration.

Example

<define-enum name="tickers">
    <value weight="4">MSFT</value> <!-- Chosen 4 out of 8 times -->
    <value weight="3">AAPL</value> <!-- Chosen 3 out of 8 times -->
    <value>SUNW</value>            <!-- Chosen 1 out of 8 times -->
</define-enum>

<application> Element

No.

This element is optional for *.sbfs files used with the sbfeedsim-old command in a terminal or Windows command prompt window.

Format

<property name="application" value="filename.sbapp"/>

<value> Element

Optional.

A value within an enumeration.

Format

<value weight="integer">enumeration-value</value>

Attributes

Attribute Name	Required?	Description
`weight`	No	A relative weight for this value in the enumeration; defaults to 1 if not specified. The probability that this value will be chosen out of all the values in the enumeration is `weight` divided by the sum of the `weight`s for all values. (Thus if you simply specify no weights for any value, each value is equally as likely to be selected.)

Example

See <define-enum>.

<stream> Element

Required.

A specification for load on a single stream. A <stream> tag contains, in order:

A single rate specification (either <rate>, <interval>, or <timestamp>).
One or more <field> elements.
Zero or more <switch> or <group-by> elements.

There must be a <field> element for every field in the stream, either inside <stream>, or inside a <switch> or <group-by>.

Format

<stream name="stream-name">
    rate-specification
    <field name="field1"> ... </field>
    <field name="field2"> ... </field>
        ...
    <switch ...> ... </switch>
    <group-by ...> ... </group-by>
</stream>

Attributes

Attribute Name	Required?	Description
`name`	Yes	The name of the stream on which to generate load. There can be more than one `<stream>` element with a given name, in which case load is generated independent based on the individual `<stream>` specifications and merged together.
`drop-probability`	No	The fraction of tuples on this stream, from 0.0 to 1.0 inclusive, to drop randomly. For instance, to drop 25% of tuples, use `drop-probability="0.25"`. Defaults to 0.0, i.e., don't drop any tuples.
`max-time`	No	The maximum amount of time, in seconds, to generate tuples on this stream. For instance, to stop generating on this stream after 10 seconds, use `max-time="10"`. Defaults to nothing, i.e., generate tuples on this stream forever.
`max-tuples`	No	The maximum number of tuples to generate on this stream. For instance, to stop generating on this stream after 20 tuples, use `max-tuples="20"`. Defaults to nothing, i.e., generate tuples on this stream forever.
`trace-file`	No	A file to use for any `<trace>` elements that appear within the specification for this stream.
`trace-file-delimiter`	No	The delimiter separating fields in the trace file; must be a single character, or `comma` or `tab` or `space`. Defaults to `comma`.
`trace-file-quote`	No	The quotation mark that may be used for some fields in the trace file. Must be a single character. Defaults to a double quote.

Example

<stream name="Stream1" max-time="10" max-tuples="12">
    <!-- Generate 1 tuple per second on average, stopping after
         10 seconds or 12 tuples, whichever comes first. -->
    <rate per-second="1.0"/>
    <field name="tick-id"> <step/> </field>
    <field name="symbol"> <enum ref="symbols"/> </field>
    <field name="shares"> <uniform min="-10" max="10"/> </field>
</stream>

<field> Element

Optional.

Specifies the source to use to generate a value for a particular field in a stream.

Format

<field name="field-name"> source </field>

Attributes

Attribute Name	Required?	Description
`name`	Yes	The name of the field whose value will be generated by the specified source.

Example

See <stream>.

<rate> Element

One of the following must be specified: <timestamp>, or <interval>, or <rate>.

Indicates that tuples should be generated at a certain average rate per second, with exponential interarrival time (that is, equally likely to be generated at any point in time). This element is always empty.

Format

<rate per-second="average-frequency"/>

Attributes

Attribute Name	Required?	Description
`per-second`	Yes	The average tuple rate per second.

Example

See <stream>.

<interval> Element

One of the following must be specified: <timestamp>, or <interval>, or <rate>.

Indicates that tuples should be separated in time with intervals according to a particular source. This element must contain a source; for example, <constant> or <uniform>.

Format

<interval> some-source </interval>

Example

<stream name="InputStream"/>
    <interval> <constant value="1"/> </interval>
    <!-- Generate tuples exactly 1 second apart. -->
        ....
</stream>

<stream name="InputStream"/>
    <interval> <uniform min="0" max="10"/> </interval>
    <!-- Generate tuples between 0 and 10 seconds apart. -->
        ...
</stream>

<stream name="InputStream"/>
    <interval> <step min="1"/> </interval>
    <!-- Generate tuples 1 second apart, then 2 seconds apart,
         then 3 seconds apart... -->
        ...
</stream>

<stream name="InputStream" trace-file="in.csv"/>
    <interval> <trace column="1"/> </interval>
    <!-- The first column in the trace file is the number
         of seconds between that tuple and the previous tuple. -->
        ...
</stream>

<timestamp> Element

One of the following must be specified: <timestamp>, or <interval>, or <rate>.

Indicates that tuples should be generated at absolute points in time according to a particular source. This element must contain a source whose values are strictly nondecreasing over time; it is usually used with a trace file.

Format

<timestamp> some-source </timestamp>
<timestamp origin="some-origin"> some-source </timestamp>

Attributes

Attribute Name	Required?	Description
`origin`	No	The origin value for timestamps in the source; the origin is effectively subtracted from each generated timestamp. For example, if timestamps in the trace file begin at 100 but you want generation to begin immediately, use a value of 100 as the origin. Defaults to 0 if unspecified.

Example

<stream name="InputStream" trace-file="in.csv"/>
    <timestamp> <trace column="1"/> </timestamp>
    <!-- The first column in the trace file is the absolute timestamp
         of the tuple. -->
        ...
</stream>

<stream name="InputStream" trace-file="in.csv"/>
    <timestamp> <step min="1" delta="3"/> </timestamp>
    <!-- Generate tuples at t=1, t=4, t=7, ... seconds. -->
        ...
</stream>

<stream name="InputStream"/>
    <timestamp> <constant value="1"/> </timestamp>
    <!-- Nonsensical; this says "generate every tuple 1 second
         after sbfeedsim starts." -->
        ...
</stream>

<stream name="InputStream" trace-file="in.csv"/>
    <timestamp> <step min="10" delta="-1"/> </timestamp>
    <!-- Illegal; says to "generate tuple at t=10, t=9, t=8,
         ... seconds, but values are required to be
         nondecreasing over time. -->
        ...
</stream>

<switch> Element

Optional.

Indicates that different sources should be used for certain fields in a tuple, based on values generated for another field. When processing a switch, the feed simulator examines the switch field; finds the <case> whose value matches that field's value (or <default> if none match); and applies the <field> specifications contained in that <case> or <default>.

No two <case> elements should have the same value. An error occurs if the switch field does not match any <case> value and there is no <default>.

Each <case> and <default> must have the same set of <field> specifications.

Format

<switch field="switch-field">
    <case value="optionA">
        <field name="field1"> source1A </field>
        <field name="field2"> source2A </field>
    </case>
    <case value="optionB">
        <field name="field1"> source1B </field>
        <field name="field2"> source2B </field>
    </case>
        ....
    <default>
        <field name="field1"> source1C </field>
        <field name="field2"> source2C </field>
    </default>
</switch>

Attributes

Attribute Name	Required?	Description
`field`	Yes	The field whose value should be examined in choosing which sources to use for certain other fields.

Example

<!-- We want every ticker symbol to get its own random-walk.
     Most tickers will have a random-walk from 8 to 30; but
     MSFT will have a random-walk from 10 to 50 and AMZN will
     have a random-walk from 5 to 25. -->
<stream name="Stream1">
    <rate per-second="1.0"/>
    <field name="tick-id"> <step/> </field>
    <field name="symbol"> <enum ref="symbols"/> </field>

    <switch field="symbol">
        <case value="MSFT">
            <!-- MSFT gets this random-walk... -->
            <field name="value"> <random-walk min="10" max="50" delta="1"/> </field>
        </case>
        <case value="AMZN">
            <!-- ...AMZN gets this random-walk... -->
            <field name="value"> <random-walk min="5" max="25" delta="0.5"/> </field>
        </case>
        <default>
            <!-- ...and every other ticker gets its own separate copy of this random-walk. -->
            <field name="value"> <random-walk min="8" max="30" delta="0.5"/> </field>
        </default>
    </switch>
</stream>

<case> Element

Optional.

A particular case in a <switch> element. Contains one or more <field> elements to be used when the switch field's value matches case-value.

Format

<case value="case-value">
    <field name="field1"> source1 </field>
    <field name="field2"> source2 </field>
        ...
</case>

Attributes

Attribute Name	Required?	Description
`value`	Yes	The value which the switch field's value must match for the enclosed `<field>` elements to apply.

<group-by> Element

Optional.

Indicates that a separate copy of the enclosed sources should be used for certain field in a tuple, based on values generated for another field field-name. This is useful for sources that have state, like <random-walk> (see the example below).

Format

<group-by field="field-name">
    <field name="field1"> source1 </field>
    <field name="field2"> source2 </field>
        ...
</case>

Attributes

Attribute Name	Required?	Description
`field`	Yes	The field whose value should be examined in choosing which sources to use for certain other fields.

Example

<!-- Every second, generate a ticker symbol from the "symbols"
     enumeration.  Each symbol has its own random walk. -->
<stream name="InputStream">
    <rate per-second="1.0"/>
    <field name="tick-id"> <step/> </field>
    <field name="symbol"> <enum ref="symbols"/> </field>

    <group-by field="symbol">
        <!-- a separate value random-walk for each symbol -->
        <field name="value"> <random-walk min="10" max="100"/> </field>
    </group-by>
</stream>

This might generate the following output:

    1,AMZN,29
    2,SUNW,93
    3,MSFT,57
    4,AMZN,29.5
    5,MSFT,57.5
    6,AMZN,29

Note that AMZN is random-walking around 29, and MSFT is random-walking around 57. Without a group-by around the <field name="value">, the output might be more like the following

    1,AMZN,29
    2,SUNW,29.5
    3,MSFT,30
    4,AMZN,29.5
    5,MSFT,30
    6,AMZN,30.5

Sources

A source is a generator of data for a particular field or rate specification. The following sources are defined (optional attributes are enclosed in square brackets):

<enum ref="enum-name"/>: select a value from an enumeration (which must have been previously declared using the <define-enum> tag).
<trace column="col"/>: use the value from the colth column of the stream's trace file. col is 1-relative (use 1, not 0, for the first column). This source may only be used if the enclosing <stream> tag has the trace-file attribute.
<random-string [random-length="rl"]/>: generate a series of random uppercase characters (valid for string fields only). If rl is false (the default) then fill the field completely with random characters; if rl is true then generate a random-length string.
<constant value="value"/>: use a constant value for the field (valid for rates, numeric, and string fields only).
<uniform [min="min"] [max="max"]/>: use a uniformly-generated random number in the range [min,max). min defaults to 0 and max defaults to 1.
<exp [scale="scale"] [location="location"]/>: use a random number according to an exponential distribution with mean scale and shifted to the right by location, i.e.,

location - scale * ln(uniform(0, 1))

scale defaults to 1 and location defaults to 0.
<step [min="min"] [max="max"] [delta="delta"] [start="start"] [cycle="cycle?"]>: Start at start. Increment by delta each iteration until outside the range [min, max]; when outside the range stop if cycle? is false, else reset to min (if delta is positive) or max (if delta is negative) and repeat. min defaults to 0, max defaults to a very large integer value (, delta defaults to 1, start defaults to min (if delta is positive) or max (if delta is negative), and cycle defaults to true.
<random-walk [min="min"] [max="max"] [delta="delta"] [start="start"]>: Start at start. Each iteration, add either delta or -delta (chosen at random) and pin the resulting value to [min, max]. min defaults to 0, max defaults to a very large integer value, delta defaults to 1, and start defaults to a randomly-chosen value between min and max (subject to the constraint that start - min is a multiple of delta).
<normal [location="location"] [scale="scale"]>: Choose a randomly-generated number with standard deviation scale centered at location. location defaults to 0 and scale defaults to 1.
<log-normal [location="location"] [scale="scale"] [shape="shape"]>: choose a random number according to a log-normal distribution with the given parameters, i.e.,

location + exp(scale + shape * normal())

location defaults to 0, scale defaults to 0, and shape defaults to 1.
<pareto [shape="shape"]>: choose a random number according to a Pareto distribution with the given parameters, i.e.,

pow(uniform(), -1.0 / shape)

shape defaults to 1.

Booleans

For Boolean fields, a number with absolute value 0.5 or greater is considered true. This means that for a Boolean field <uniform/> will be true on average half the time, and <step min="0" max="1"> will alternate between true and false.