Deployment File Sample

Introduction

StreamBase deployment files are a type of configuration file that specify the names of containers and application modules to be run, plus runtime setup options such as container connections, module parameter definitions, and trace file configuration. See StreamBase Deployment Files for an overview, and see StreamBase Deployment File XML Reference for the XML syntax of deployment files.

This sample illustrates the use of deployment files to run the same multi-container EventFlow application in two different ways without editing EventFlow and without using separate server configuration files.

Note

Do not run this sample's EventFlow file, Main.sbapp. Instead, run one of this sample's StreamBase deployment files, as described in the steps below.

StreamBase deployment files can also be used to specify externally defined modules that implement the interface defined in an Extension Point operator. That feature of deployment files is illustrated in a separate sample in the Operator Sample Group, described in Extension Point Deployment Sample.

This sample's primary application, Main.sbapp, accepts stock trade tuples, then filters trades with volume over 1000 shares to a separate output port. If the LargeTrades output port has a container connection to the input port of modules/LargeTradesLogHandler.sbapp, then notification of large trades is written to the StreamBase log handler. On the other hand, if the LargeTrades output port has a container connection to the input port of modules/LargeTradesErrorStreamHandler.sbapp, then notification of large trades is passed to the StreamBase error stream mechanism. In both cases, announcements of large trades appear in Studio's Console view.

This sample uses separate deployment files to select between the two run scenarios. To see the sample in action, do not run Main.sbapp or either module in the modules folder. Instead, run one of the two StreamBase deployment files provided with the sample. This shows that the primary application can be run with different sub-modules only by running different deployment files.

This Sample's Files

The deployment file sample is composed of following files:

File Purpose
Main.sbapp The top-level application for this sample, with a simple Filter component to filter large trades. To run this sample, DO NOT RUN this EventFlow module. Instead, run one of the two StreamBase deployment files described next.
LargeTradesErrorStream.sbdeploy A StreamBase deployment file that runs both Main.sbapp and LargeTradesErrorStreamHandler.sbapp in separate containers, and connects the LargeTrades output stream of Main.sbapp to the input stream of the second module.
LargeTradeLog.sbdeploy A StreamBase deployment file that runs both Main.sbapp and LargeTradesLogHandler.sbapp in separate containers. This deployment also connects the LargeTrades output stream of Main.sbapp to the input stream of the second module.
sbd.sbconf A server configuration file that adds the modules folder to the module search path. Used only for running the sample at the command prompt.
The following files are located in the modules subfolder of the sample_sbdeploy project folder.
LargeTradesErrorStreamHandler.sbapp An application intended to accept input from the LargeTrades output stream in Main.sbapp. To flag large trades, this module sends an event to the StreamBase error stream.
LargeTradesLogHandler.sbapp Another application intended to accept input from the LargeTrades output stream in Main.sbapp. To flag large trades, this module sends an event to the StreamBase logging facility using the Log adapter.

Running This Sample in StreamBase Studio

  1. In the Package Explorer, open the sample_sbdeploy project folder.

  2. Double-click to open the LargeTradesLogHandler.sbdeploy deployment file. Make sure the Deployment File Editor is the currently active tab in Studio.

  3. Click the Run button. This opens the SB Test/Debug perspective, opens Main.sbapp, and starts the two containers and application modules named in the deployment file.

  4. In the Manual Input view, confirm that the TradesIn input stream is selected.

  5. Enter the following field values:

    Field Enter this value
    symbol IBM
    price 135.00
    volume 200
  6. Click Send Data, and a tuple arrives in the Application Output view. Observe that the tuple only appears on the AllOtherTrades output stream.

  7. Back in the Manual Input view, change only the volume field. Add a zero to change the 200 to 2000.

    Field Enter this value
    volume 2000
  8. Click Send Data, and a tuple arrives in the Application Output view. Observe that this time, the large trade tuple arrived at both the LargeTrades output port of the primary module and the largetradewatcher.out:Log_1 port of the secondary module. An announcement of the trade also appears as a WARN message in the Console view.

  9. Enter more tuples in the Manual Input view as desired.

  10. When done, press F9 or click the Stop Running Application button to stop the first deployment application.

  11. Double-click to open the LargeTradesErrorStream.sbdeploy deployment file, and make sure the Deployment File Editor is the currently active tab in Studio.

  12. Click the Run button to run this second deployment file. As before, this opens Main.sbapp and starts the two containers and application modules named in the second deployment file.

  13. Enter input tuples in the Manual Input view using steps similar to steps 5 through 8. Observe that large trade tuples only arrive on the LargeTrades output port and not from any port in the secondary module. Instead, large trade tuples are announced in the Console view with WARN messages.

  14. Enter more tuples in the Manual Input view as desired.

  15. When done, press F9 or click the Stop Running Application button to stop the second deployment application.

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.

  1. Open two terminal windows on UNIX, or two StreamBase Command Prompts on Windows. In both windows, navigate to your workspace copy of the sample.

  2. In window 1, start StreamBase Server running the first deployment file. You must also specify the provided server configuration file so that the application can locate the module files in the modules subfolder. Enter:

    sbd -f sbd.sbconf LargeTradesLogHandler.sbdeploy
    
  3. In window 2, type:

    sbc enq TradesIn
    

    The sbc command in window 3 now waits for keyboard input. Type:

    IBM, 135.77, 200
    IBM, 135.77, 2000
    
  4. Observe that a WARN message appears in window 1 when the third field is over 1000.

  5. In window 2, type: Ctrl+C to exit the sbc session.

  6. In window 2, type the following command to terminate the server: sbadmin shutdown

  7. Now, back in window 1, run the second deployment file:

    sbd -f sbd.sbconf LargeTradesErrorStream.sbdeploy
    
  8. In window 2, type:

    sbc enq TradesIn
    
  9. In window 2, type:

    IBM, 135.77, 2000
    
  10. Observe that a WARN message appears in window 1, ending with Evaluation exception: large trade

  11. In window 2, type: Ctrl+C to exit the sbc session.

  12. In window 2, type the following command to terminate the server: sbadmin shutdown

Importing This Sample into StreamBase Studio

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

  • From the top menu, select FileLoad StreamBase Sample.

  • Select StreamBase Deployment Files from the Application category.

  • Click OK.

StreamBase Studio creates a project for the sample.

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_sbdeploy

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/sbdeploy

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.