EventFlow Container Overview

Using EventFlow containers enables a number of useful features. You can:

The following is an example of command-line container commands:

sbadmin addContainer c1 newapp.sbapp
sbadmin addContainer c2 myapp-same-schema.sbapp c2.InputStream=c1.OutputStream

This example defines two containers, c1 and c2, and associates each with an EventFlow module. The last expression specifies that the output of the c1 container is to be consumed by the input stream of the c2 container. Both containers are running in the same EventFlow engine process.

Each container has its own thread of execution within the containing EventFlow engine. Containers behave much like operators or modules marked with the Run this component in a parallel region setting on the Concurrency tab of the Properties view. On a multi-core machine, one container does not block the execution of another container.

The following set of conceptual diagrams illustrates the ideas behind containers. The first diagram illustrates a configuration running multiple unrelated EventFlow modules in a single sbd process:

In the next diagram, we add two reader modules (B and C) to a running EventFlow engine that was already hosting module A:

In the next diagram, we add two writer modules (B and C) to a running engine that was already hosting module A. Then we added module D to write its output stream to the output stream of module A.

The name you assign to containers must follow the StreamBase identifier naming rules, as described in Identifier Naming Rules.

StreamBase's formal path notation is designed to avoid naming conflicts when you run multiple modules in the same server, when you use modules, and when operators are run in separate threads.

StreamBase path notation uses the following syntax, with a period separator between each element:

[containerName.][moduleRefName[[.moduleRef2Name].[..]]entityName

The container name is shown as optional because in most contexts the default container is used and need not be specified.

For additional information, see StreamBase Path Notation.

When an EventFlow engine process starts up, an EventFlow container named system is always included alongside the container, usually named default, that holds the top-level EventFlow module. The system container and the streams it emits are described in a separate page, System Container and Control Streams.

The URI syntax for addressing EventFlow modules with legacy sb* commands allows you to connect to a particular container in a running module. The URI syntax is:

sb://host:port/containerName

For example:

sb://localhost:10000/holder2

If you leave off the container-name portion of the URI, the container named default is assumed. Thus, the following commands are equivalent:

sbc -u sb://localhost:10000/default
sbc -u sb://localhost:10000

When you specify a container name in the URI, you can omit the container name from any subsequent stream or operator names in the same command. For example, the following commands are equivalent:

sbc -u sb://localhost/holder2 enqueue InputStream1
sbc -u sb://localhost enqueue holder2.InputStream1

See sburi for the details of StreamBase URI syntax.

Some sbc commands that accept StreamBase URIs can specify a comma-separated list of URIs to address two or more EventFlow engines at once. This feature is used primarily to support a cluster of EventFlow engines that are using high availability features.

See Multiple URI Syntax for HA Scenarios for a discussion of this subject.

If a server process has multiple containers, you can enqueue to or dequeue from multiple containers at the same time. For example, you can dequeue with a command like the following:

sbc dequeue holder1.OutputStream1 holder2.OutputStream1

If you specify a container name in the URI, you can still dequeue or enqueue from different containers. For example:

sbc -u sb://localhost/holder1 dequeue OutputStream1 holder2.OutputStream1

OutputStream1 will be dequeued from the module in container holder1, while holder2.OutputStream1 will be dequeued from the container holder2.

Because tuples are queued between modules, there is overhead introduced when tuples cross modules.

There are several ways to add a container to a running EventFlow engine process:

You can remove containers from a running server process with:

When a container is removed:

Use the epadmin --ad=adminport display container command to show a list of containers, including details about each container. For example:

Engine = com_tibco_sb_sample_bestbidsandasks_BestBidsAsks0
Path = system
Type = SYSTEM
Enqueue = ENABLED
Dequeue = ENABLED
State = RUNNING
...

Engine = com_tibco_sb_sample_bestbidsandasks_BestBidsAsks0
Path = BBA
Type = NORMAL
Enqueue = ENABLED
Dequeue = ENABLED
State = RUNNING
Main Module = com.tibco.sb.sample.bestbidsandasks.BestBidsAsks
Data Distribution Policy = 
Availability Zone = 
Partition = 
Backup Nodes = 
Input Streams = NYSE_Feed
Output Streams = BestAsks,BestBids
Trace Status = Disabled

You can also use the sbc list command, which produces output like the following example:

container   default
container   holder2
container   system

The above example shows three containers. One is added and populated by the user, while the other two are standard container in each EventFlow engine.

As shown in the previous section, the epadmin display container command shows several lines of detail about each container. You can add the --detailed parameter to add the list of referenced modules. For example:

...
Engine = com_tibco_sb_sample_bestbidsandasks_BestBidsAsks0
Path = BBA
Type = NORMAL
Enqueue = ENABLED
Dequeue = ENABLED
State = RUNNING
Main Module = com.tibco.sb.sample.bestbidsandasks.BestBidsAsks
Referenced Modules = {"Module":"com.tibco.sb.sample.bestbidsandasks.BestBidsAsks", 
  "Referenced Modules":"none"}
Data Distribution Policy = 
Availability Zone = 
Partition = 
Backup Nodes = 
Input Streams = NYSE_Feed
...

You can also use the sbc describe command, which shows you the container name and any connections specified when that container was added.

<container name="BBA" enqueue="ENABLED" dequeue="ENABLED" state="RUNNING">
</container>

You can manage multiple container-bound modules running in a single engine process using either epadmin or sbadmin commands.

The epadmin commands are:

epadmin shutdown container --name=container-name
epadmin suspend container --name=container-name
epadmin resume container --name=container-name
epadmin restart container --name=container-name
epadmin modify container --name=container-name

Use modify container to:

The relevant sbadmin commands are:

sbadmin {shutdown | suspend | resume} container-name
sbadmin restartContainer container-name
sbadmin removeContainer container-name
sbadmin modifyContainer container-name

Use sbadmin modifyContainer to:

You can dynamically start, stop, and pause enqueuing or dequeuing to and from running containers. Use any of the following commands:

epadmin modify container --name=container-name
epadmin add container --name=container-name

sbadmin addContainer container-name
sbadmin modifyContainer container-name

All four commands take the following options:

--enqueue=STREAMSTATUS
--dequeue=STREAMSTATUS

The values for STREAMSTATUS can be:

When you interrupt queuing for an module running in a container, you also interrupt queuing for any external clients, input adapters, and output adapters that were communicating with that module. The following table explains how various combinations are affected:

StreamBase provides a number of ways to monitor container information, as described in Connecting to System Streams.

The StreamBase Client libraries for Java, C++, .NET, and Python support containers. You can write your own modules to connect to and interact with EventFlow engines and the containers therein.

See API Guide for more information.

The following StreamBase features are not supported with containers: