StreamBase Deployment File XML Reference

This topic describes the XML syntax of StreamBase deployment files.

The root element of a deployment file is <deploy>, which contains all XML elements that describe a runnable StreamBase deployment. The <deploy> element supports one instance of the <runtime> element.

The syntax of the <runtime> element of deployment files is comparable to, but not identical to, the deprecated <runtime> element of server configuration files. See Server Configuration File Overview for a discussion of the differences between old and new <runtime> elements.

Edit deployment files in Studio with the Deployment File Editor, which provides typechecking of your deployment file as you compose it, as well as color coding, autocompletion, and context-aware tag proposal of valid elements and attributes.

The root element of deployment files is <deploy>, which has one first-level child element:

<runtime>

This first-level element in turn has the following child elements:

<application>
<container-connection>

<runtime>

Use this element to specify one or more containers (one per application) that will be hosted by StreamBase Server. You can have one or more <application> child elements. The <runtime> element has the following child elements:

The following synthetic example shows all deployment file elements used at least once. In practice, it is unlikely that you will need to specify all elements for the same deployment case.

<?xml version="1.0" encoding="UTF-8"?>
<deploy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/sbdeploy/">
  <runtime>
    <application container="default" module="app1.sbapp"/>
    <application container="holder2" module="app2.sbapp">
      <extension-point-contents>
        <extension-point target-id="extpt.id">
          <extension name="caseA" module="submoduleA.sbapp"/>
          <extension name="caseB" module="submoduleB.sbapp">
             <module-parameters>
               <param name="myVar" value="myValue" enciphered="false"/>
             </module-parameters>
          </extension>
        </extension-point>
      </extension-point-contents>
      <module-parameters>
        <param name="varname" value="varvalue" enciphered="false"/>
      </module-parameters>
      <trace traceFileBase="tracebase" traceCompress="true"/>
    </application>
    <container-connections>
      <container-connection dest="holder2.input1"
          source="default.output3" where="tradeID % 2 == 0"/>
    </container-connections>
  </runtime>
</deploy>

<application>

Use this element to specify an application module to load into a named container. The application file can be an EventFlow or StreamSQL module, or a precompiled application (.sbar) file. The element has the following attributes:

Attribute Required Description
module Yes

The name of an EventFlow, StreamSQL, or precompiled application file, which must exist in the current Studio project's module search path. You can use Ctrl+Space in the Deployment File Editor to pop up a list of the available modules in the module search path.

If you selected a module name before starting the New Deployment File wizard, then the module and container attributes are filled in for you.

container Yes The name you assign to the container to hold the specified application. For running or debugging in Studio, the top-level module must be in a container named default.
enqueue No One of ENABLED, DISABLED, or DROP_TUPLES to specify the startup state of enqueuing for this container. ENABLED is the default setting. If you specify DISABLED, then enqueue attempts are actively refused and exceptions are thrown. If you specify DROP_TUPLES, then tuples are silently dropped.
dequeue No One of ENABLED, DISABLED, or DROP_TUPLES, as described above.
suspend No Use suspend=true to specify that the application in this container should start up suspended. Specify false, the default, to have the application start running when the container is added. When starting the server with sbd --suspend, you can use this suspend="false" attribute to override the suspension. You can start or restart a suspended container with the sbadmin resume command.
datadir No Specify the absolute path (or a path relative to the running location of the sbd server) to a directory to contain the files that implement all disk-based Query Tables for this container (if your license enables such tables). If unspecified, the container uses the --datadir location if specified on the sbd command line, or the default temporary location if not.

<application> has the following child elements:

<module-parameters>

This element can be a sub-element of both <application> and <extension>. Use it to specify the value of one or more parameters to be passed to the top-level application module in the current container. There are several ways in StreamBase to pass parameters to modules, but using this element in a deployment file or server configuration file is the only method that allows parameter values to be enciphered. See Using Module Parameters for details of passing module parameter values.

<module-parameters> supports one or more of the <parameter> child element.

<parameter>

Use this element to specify the name and value of a parameter to be passed to the top-level module in the specified container. You can specify <param> as an alias for <parameter>.

Attribute Required Description
name yes

Parameter label that can be used in an expression.

enciphered no Set to "true" to specify that the contents of the current value attribute were enciphered with the sbcipher command. This allows you to specify private values such as passwords and user names, yet not have the values appear as clear text in the configuration file. For further information, see Enciphering Passwords and Parameter Values.
value yes

Value to which the parameter is to be resolved.

See String Values in Parameters for TIBCO' recommended policy on quoting string parameters.

<extension-point-contents>

The <extension-point-contents> element contains zero or more <extension-point> child elements.

<extension-point>

Each <extension-point> has one attribute, target-id:

Attribute Required Description
target-id yes

The Extension Point ID for an Extension Point operator in a module loaded in the container for this application, as specified in the Extension Point ID field in the Modules tab of the Properties view of an Extension Point operator whose module instances are defined externally. The target-id must exactly match such an Extension Point ID. Extension Point IDs are container-scoped and must be unique among all Extension Point operators in all modules loaded in the same container.

You can use Ctrl+Space in the Deployment File Editor to pop up a list of the available Extension Point IDs in modules in the module search path.

The target-id specifies an extension child element, which must be present in the file.

The <extension-point> element contains zero or more <extension> child elements.

<extension>

Use the <extension> element to specify modules that implement the interface in an Extension Point operator for this application module. This element has the following attributes:

Attribute Required Description
name yes

The module ID assigned to this module. The module ID is used in your application's logic as a handle to pass to an Extension Point component's input stream for dispatch using the Name dispatch style.

module yes The name of an EventFlow or StreamSQL module in the current module search path. Specify the module name only. You can use Ctrl+Space in the Deployment File Editor to pop up a list of the available modules in the module search path.

See Using the Extension Point Operator and Using Interfaces with Extension Points for further information.

Each <extension> may have a <module-parameters> element that implements the extension point's interface. The <module-parameters> element of <extension> can contain the same kinds of elements as the <module-parameters> element of <application> does.

<trace>

Use this element to configure runtime tracing. Remember that these settings do not enable tracing, they only configure tracing when it is set up and enabled. Tracing does not occur unless you set up StreamBase Server for it and tracing is enabled. To set up for tracing, set the system property streambase.codegen.trace-tuples or environment variable STREAMBASE_CODEGEN_TRACE_TUPLES to true, as described in Runtime Tracing and Creating Trace Files.

If the setup conditions are met, then tracing is enabled by default when the application starts. You can disable tracing at runtime with sbadmin modifyContainer containerName trace false. In that case, re-enable tracing with sbadmin modifyContainer containerName trace true. As soon as you stop tracing, all trace files are closed.

The element has the following attributes:

Attribute Required Default Description
traceStreamPattern No none

Specify a regular expression pattern in the format of java.util.regex.Pattern. The pattern limits tracing to the operators and streams whose name matches the pattern. If not specified, tracing is active for all operators and streams in the application.

traceFileBase No none

By default, trace output is written to StreamBase Server's console. To redirect trace output to a file, specify traceFileBase with a basename argument.

There is one trace file generated per parallel module. Specify a string to serve as the basename for trace files. Trace file names are generated as basename+containername.sbtrace. For modules running with parallel execution enabled, the module's path becomes part of the trace file name: basename+containername.modulepath.sbtrace.

Tracing also creates a second file with extension .sbtrace.meta. This file, in XML format, contains the equivalent of the output of sbc describe. This file is automatically used by the Trace Debugger perspective when reading and displaying .sbtrace files.

traceOverwrite No false Either true or false. Set to true to cause tracing to overwrite all trace files on Server restart. By default, new trace information is appended to existing trace files for each traced container.
traceCompress No false Either true or false. Set to true to specify that the generated trace file is to be compressed with gzip. If true, the trace file's extension becomes .sbtrace.gz. Compressed trace files are readable by Studio's Trace Browser perspective.
traceBuffered No true Either true or false. When set to false, the output trace file is flushed on every trace line. This slows down performance considerably, but makes it easier to use tracing as part of debugging a live application. When set to true, the default, tracing output is buffered before the trace file is written, to minimize tracing's drag on performance.

Example:

...
<application container="default" module="BestBidsAsks.sbapp">
  <trace traceStreamPattern="Bids" traceFileBase="trace_" 
     traceOverwrite="true" traceCompress="true" />
</application>
...

<container-connections>

Use this element to specify a set of one or more container connections. See Container Connections to understand the types and uses of connections between containers.

The <container-connections> element (plural) supports one or more <container-connection> elements (singular).

See the deployment file example above. You can establish container connections in several other ways, as described in Specifying Container Connections.

<container-connection>

Use this element to specify a single connection between containers. The <container-connection> element has the following attributes:

Attribute Required Description
dest Yes

The entity (usually an input stream) in one named container that will consume the output of the connected source container.

For both dest and source attributes, you usually specify a StreamBase component path in the form container-name.module-name.stream-name. If required by your application, you can also specify a full StreamBase URI to a container in remote server, including remote connection parameters.

source Yes The entity in another named container (usually an output stream) that will send the data to the destination container.
synchronicity No Either "ASYNCHRONOUS" (default) or "SYNCHRONOUS". See Synchronous Container Connections.
where No Specifies a predicate expression filter to limit the tuples that cross to the destination container. 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.

Back to top ^