Defining Output Streams

You can define one or more output streams, where data exits a StreamBase module. In an EventFlow module, output streams are typically the last component in the flow.

Starting with StreamBase 7.2.6, the icons for output streams that are an implementation of a StreamBase interface are shown with a boxed uppercase I in the lower right corner of the icon's tile. Output streams that are used to update dynamic variables are shown with (x)= in the upper right of the icon.

The rest of this page describes the actions you can take on each tab of the output stream's Properties view.

Properties: General Tab

Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Always expose Streams for Dequeue: Designates that this output stream is to be available for dequeuing, no matter how deeply the module that contains this stream is nested in a complex application.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Properties: Schema Tab

The Schema tab lets you either:

  • View the inherited schema of tuples that exit this output stream, or

  • Declare a schema that must be matched by tuples as they exit this output stream.

Set the Output Schema property as described in the following table:

Setting Effect on the schema of this output stream
Let typechecking decide With this option selected (the default), the schema in the Current Schema grid is read-only, and shows the schema inherited from upstream components.
Declare By declaring an expected output schema, you ask StreamBase to compare the schema received by this output stream to the declared schema, and to report any discrepancies as typecheck errors.

When you select Declare, the Current Schema grid is replaced by both Declared Schema and Input Schema grids. The Input Schema grid is not editable and is shown for reference, since any schema you declare must match the existing schema entering this stream.

In the Declared Schema grid, specify the exact schema that you expect tuples to have as they exit this output stream. You can specify a named schema or parent schema as required by your application, or specify the rows of a private schema.

Properties: Advanced Tab

The Advanced tab has three controls:

Dequeue Predicate Expression Field

Use the Dequeue predicate expression field to optionally filter the output of this stream. The result can be similar to adding a Filter operator at an exit point of your application. The predicate expression might specify a value, a limit, or range of values, such as symbol=='IBM' && price > 85.0.

While editing your predicate expression, type Ctrl+Space to invoke StreamBase expression completion to help write your expression. As with other Properties view expression fields, click anywhere in the field, then click the three dots on the right side of the field to open an expression editing window that allows more editing room for multi-line expressions.

If you specify a predicate expression, any tuple dequeued from this stream must satisfy the restrictions of the predicate in order to exit the stream. If the predicate expression for a given tuple does not evaluate to true, the tuple is not emitted.

Note

Dequeue predicate expressions only apply to dequeue client connections. The predicate expression has no effect on tuples delivered over container connections to input streams in other containers. All tuples on the output stream are delivered to connected containers. (See below for the separate way to filter tuples on container connections.)

If the output stream is dequeued by a client application, any filtering in this tab's predicate expression occurs before any filtering performed by the client application (described in Narrowing Dequeue Results with Filtered Subscribe).

In addition to fields available on the stream, output stream predicate expressions can use the following special fields:

subscriptionid

The ID of the current subscription. A field of this name is available on the subscription stream in the system container.

connectionid

ID of the current client connection. A field of this name is available on the connection stream in the system container, and also as the first field returned from an sbadmin listConnections command.

tupleid

ID of the current tuple.

These fields can be used in conjunction with streams available in the system container, as described in Using Containers.

Tip

To avoid name collisions between fields in different containers, qualify your field names with its container name. For example, the field name system.subscriptions will not be confused with a field named subscriptions in another stream in this or another container.

When dequeuing occurs, tuples are delivered only to dequeuing clients for whom all of the predicates are true. For a given tuple, if a predicate resolves to null, it does not restrict the stream, and the tuple is sent to all connected dequeuing clients.

Container Connection Field

Use the Container connection field to specify a container connection to another module in another container. When so connected, tuples from this output stream flow into the specified input stream in the specified container. This field is one of several methods you can use to specify a container connection. See Container Connections to understand the differences between, and the advantages and disadvantages of each method.

The Container connection field takes a StreamBase expression that resolves to the qualified name of an input stream in another container. A qualified stream name follows this syntax:

container-name.stream-name

When using the Advanced tab for an output stream, you are already in the source stream, so you only need to specify the qualified name of the destination stream.

You must express the container-qualified stream name as a StreamBase expression. While editing the expression, type Ctrl+Space to invoke StreamBase's expression-completion feature to help write your expression. Click anywhere in the field, then click the three dots on the right side of the field to open an expression editing window that allows more editing room for multi-line expressions.

To express a fixed, known container and stream name, enclose the qualified name in single or double quotes to render the name as an expression.

The container connection expression can optionally include variables, constants, and expression language functions that resolve to a qualified container and stream name. However, remember that the container connection is established at container start time, so your container connection expression cannot reference tuple field names or field values, since no tuples have yet passed through at container startup. For the same reason, the expression cannot resolve any value of dynamic variables, including the default value.

The following example container connection expression specifies a connection to an input stream named IncomingBestBids in an application named SideReader.sbapp that runs in a container named sideplay:

"sideplay.IncomingBestBids"

Each container connection must be expressed only once for a connected pair of containers. Do not express a container connection in the output stream of the sending container and again in the input stream of the receiving container. You can express the connection in either the sending or receiving container to the same effect. Do not specify the container connection in both places.

The schemas of both the sending and receiving sides of a container connection must match exactly. See Schema Matching for Container Connections for details.

Starting with StreamBase 7.2.6, output streams with container connections are drawn with a

If you precede the container-name.stream-name expression with colon-equals, the container connection becomes synchronous, as described in Synchronous Container Connections. For example:

":=bids.OutgoingBids"

See Syntax for Expressing Container Connections for a discussion of other container connection options, including connecting to streams on separate servers. You can use this field to specify any type of container connection that is appropriate for this output stream and for your application as a whole, including CSV and JMS connections. However, Studio cannot typecheck and validate your container connection syntax. The actual connection is not attempted until you run the application, either in Studio or at the command line.

Important

There are restrictions on the order in which you start containers that have container connections, both at the command line and in Studio. See Container Start Order for details.

See Studio: Connections in Stream Property Advanced Tabs on the Container Connections page for further information.

Starting with StreamBase 7.2.6, the icons for output streams show an overlay decoration on their upper back corner to indicate that this stream initiates a container connection to another stream by means of the Advanced tab's Container connection field.

Streams on the other side of the connection in the receiving container are not decorated. Decorations are not applied for connections specified to start at runtime in a deployment file, in a Studio launch configuration, in StreamBase Manager, or from the command line with the sbadmin command.

Container Connection Filter Expression Field

When specifying a container connection in this tab, you can also specify a predicate expression filter to limit the tuples that cross to the destination container. This differs from the Dequeue predicate expression field, which filters all tuples exiting this stream. The container connection filter limits the tuples only on the specified container connection, while dequeuing from the stream in general can proceed independently.

The expression to enter must resolve to true or false, and should match against one or more fields in the schema of the connection's stream. Enter only the filter expression, such as tradeID % 2 == 0