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> |
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>
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 |
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:
-
Zero or more of: <extension-point-contents>
-
Zero or more of: <module-parameters>
-
Zero or more of: <trace>
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.
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.
The <extension-point-contents>
element contains zero or more <extension-point>
child elements.
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 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.
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.
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
. In that case, re-enable tracing with containerName
trace falsesbadmin modifyContainer
. As soon as you stop tracing, all trace files are closed.
containerName
trace true
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 There is one trace file generated per parallel module. Specify a string to serve as the Tracing also creates a second file with extension |
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> ...
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.
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 |
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. |