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:

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

<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:

Zero, one, or more <application> elements
Zero, one, or more <container-connection> 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 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:

Zero or more of: <extension-point-contents>
Zero or more of: <module-parameters>
Zero or more of: <trace>

<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

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 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.