Deployment File Overview

Contents

Introduction
Naming Convention and Namespace Declarations
Deployment Files Are Runnable
Advantages of Deployment Files
Deployment Files and Extension Points
Deployment File Examples

Introduction

StreamBase deployment files are XML configuration files used for two primary purposes:

  • To specify which application modules will run in which containers, along with any container connections, module parameters, or trace instructions to configure at application start time.

  • To specify a set of externally defined modules to which tuples can be dispatched by an Extension Point operator in your application.

The primary advantage of deployment files is the ability to configure separate deployment files for different deployment scenarios. For example, you can create one deployment file to run your application in a test and QA environment, and another to run in a production environment.

Edit deployment files in Studio with the validating and syntax-aware Deployment File Editor, as described in Deployment File Editor. The XML syntax of deployment files is described in StreamBase Deployment File XML Reference.

Deployment files support most aspects of the <runtime> element used in server configuration files in StreamBase releases before 7.0, and also support the <extension-point-contents> element discussed below.

You can encipher password values in deployment files, just as in server configuration files.

Naming Convention and Namespace Declarations

Deployment files should be named with the .sbdeploy extension, which allows Studio to assign the correct editor. Using this extension is enforced when creating a new deployment file in Studio.

Deployment files use a schema-defined XML syntax. Studio validates each deployment file against its schema and decorates deployment file icons with a red X in the Package Explorer view if it detects any unrecognized or unbalanced elements in the file:

The top-level element of a deployment file is <deploy>, which includes two namespace declarations, as seen in this fragment: 

<?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/">
...

These declare the xsi namespace for the XML Schema standard, and the unnamed default namespace for the deployment file schema. These namespace declarations are what allow Studio's Deployment File Editor to provide syntax color coding, autocompletion, and content assistance prompts.

Deployment Files Are Runnable

You can run a StreamBase deployment file just as you would run an EventFlow or StreamSQL file. Of course, what StreamBase actually runs is the application module that the deployment file specifies to run. You can launch a deployment file for debugging or trace debugging as well.

Run Deployment Files in Studio

Run deployment files in Studio in the following ways:

  • Select the name of a deployment file in the Package Explorer view, right-click, and from the context menu, select Run As → StreamBase Application. (You can also select Debug As → StreamBase Application.)

  • With the Deployment File Editor open, active, and showing a typechecked and valid deployment file, click the Run button or press Ctrl+F11.

  • After you have run a deployment file once, Studio creates a launch configuration named for the deployment file. You can edit, re-run, debug, or trace debug that launch configuration.

    Note

    When you specify a deployment file in the Main tab of a launch configuration dialog, the Containers tab becomes a read-only view of any containers, container connections, and module parameters specified in that deployment file. In this case, to change one of these settings, you must edit the deployment file.

Run Deployment Files at the Command Prompt

Run deployment files at the command prompt with the sbd command: 

sbd fxtrading.sbdeploy

Deployment files can be used in conjunction with a server configuration file: 

sbd -f sbd.sbconf fxtrading.sbdeploy

Running a Server Configuration File with a Deployment File

The <application> child element of the <runtime> element is deprecated in server configuration files in favor of the same functionality in deployment files. However, these elements are still supported for backward compatibility in existing server configuration files.

For command-line sbd, If you specify both server configuration and deployment files in the same command, and both files define application modules and containers, the server reports an error and exits.

In Studio, <application> elements in the sbd.sbconf file are always ignored.

TIBCO recommends migrating your existing <application> settings from server configuration files to deployment files.

Bundling Deployment Files

You can bundle deployment files. That is, you can specify a deployment file as the primary target of the Studio bundler or the sbbundle command. See Application Bundling.

You can generate a precompiled archive file from a deployment file with the sbargen command described in Precompiled Application Archives.

Advantages of Deployment Files

The syntax of the deployment file's <application> child element of the <runtime> element is similar to, but not the same as the deprecated <application> element in server configuration files. For this reason, if you copy the <application> element from a server configuration file and copy it into a deployment file, you must edit it to restore validity in the new file.

Module versus Path Attributes

In the deprecated server configuration file's <application> element of StreamBase releases before 7.0, you specified a path attribute with a file system path to a module. In deployment files, the path attribute is replaced with the module attribute, where you specify only the name of the module to run, without a path. The module must be locatable on the module search path for the current Studio project.

Using the module attribute in the deployment file allows StreamBase to specify the modules to run without hard-coding file system paths or operating system dependencies.

When you create a runnable StreamBase bundle in Studio from a deployment file, the bundle stores an encapsulation of the project's module search path in addition to the module names, and no longer contains any machine-specific file system paths. Such a bundle can be run identically on different StreamBase Server host machines without requiring machine-specific server configuration files.

The sbbundle command can emulate the behavior of the Studio bundler by means of the -p or -P options. These allow the command line bundler to determine the module search path of the current project and encapsulate that into the bundle file.

No Container Connection Start Order Issues

Multi-container applications can have connections between containers, as described in Container Connections. When starting such an application without a deployment file, you must pay attention to the start order of containers, so that a container with the receiving end of a container connection is already started when the connection attempt is made.

However, when using a deployment file to start such a multi-container application, start order complications do not exist for the purpose of making container connections. This is because the deployment file starts all containers first, and only then attempts to make the first container connection.

It is possible that you still need to control module and container start order, such as to connect to a vendor's data feed from an adapter in one module before the primary module starts. In this case, you can control container start order by the order of the <application> elements in the deployment file.

Deployment Files and Extension Points

The second purpose of deployment files is to implement externally defined modules for an application's Extension Point operators. In the Modules tab of the Properties view for an Extension Point operator, you can specify Defined: Locally or Defined: Externally as the source for the list of modules that implement the operator's interface. When you specify Defined: Externally, you must provide the name of an Extension Point ID. Extension point IDs are container-scoped and must be unique among all Extension Point components used in all modules in the same container. Choose a complex ID that is not likely to be mistaken for an ID in another module.

You then provide a deployment file with an <extension-point-contents> element and at least one <extension-point> child element. The target-id attribute of the <extension-point> element must match the Extension Point ID field in the operator's Properties view: 

...
  <application container="default" module="ExtPtDeployment.sbapp">
    <extension-point-contents>
      <extension-point target-id="extpt.deployment.multiplier">
...

Next, add one or more <extension> elements that specify the names of modules that implement the interface, and specify a module identifier with the name attribute: 

...
  <application container="default" module="ExtPtDeployment.sbapp">
    <extension-point-contents>
      <extension-point target-id="extpt.deployment.multiplier">
        <extension name="double" module="Doubler.sbapp" />
        <extension name="triple" module="Tripler.sbapp" />
      </extension-point>
    </extension-point-contents>
  </application>
...

This feature provides support for team development of large StreamBase applications, where different teams are assigned the task of creating different modules that each implement the same StreamBase interface. Instead of hard-coding the name of an implementing module into an extension point operator, you can complete the containing application without access to the subordinate implementing modules.

This feature also allows you to run different deployment files that specify different sets of implementing modules for an interface. For example, you could create test and production deployment files that specify test and production sets of implementing modules, respectively.

Deployment File Examples

StreamBase includes a sample that illustrates using deployment files to run the same application in two different ways, depending on which deployment file is run. The following is one of the two deployment files included with that sample. See Deployment File Sample for further information. 

<?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="Main.sbapp"/>
    <application container="largetraderwatcher" 
      module="LargeTradesLogHandler.sbapp"/>
    <container-connections>
      <container-connection dest="largetraderwatcher.LargeTrades" 
        source="default.LargeTrades"/>
    </container-connections>
  </runtime>
</deploy>

The operator group of samples includes a sample that illustrates the use of deployment files with externally defined Extension Point modules to run an application that dispatches tuples to one of two sub-modules based on information in the input tuple. The following deployment file is one of the two from the operator group. See Extension Point Deployment Sample for details. 

<?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="ExtPtDeployment.sbapp">
    <extension-point-contents>
      <extension-point target-id="extpt.deployment.multiplier">
        <extension name="double" module="Doubler.sbapp" />
        <extension name="triple" module="Tripler.sbapp" />
      </extension-point>
    </extension-point-contents>
  </application>
</runtime>
</deploy>

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>