StreamBase Server Configuration File XML Reference

This topic provides a reference for the XML syntax of StreamBase Server configuration files. See Server Configuration File Overview for important information on using configuration files.

Create new server configuration files as described in Creating New Server Configuration Files. Edit configuration files in Studio with the validating and syntax-aware Configuration File Editor, as described in Deployment File Editor.

You can break a complex server configuration file into component pieces, and then include smaller portions into a master configuration file as described in Using Modular Configuration Files. You can encipher password and URI values in server configuration files as described in Enciphering Passwords and Parameter Values. See Using Environment Variables in Configuration Files when defining variables in your configuration file.

Server configuration files use a schema-defined XML syntax. The root element is <streambase-configuration>, which contains all configuration elements. It has one or more of the following child elements:

<global>
<server>
<page-pool>
<runtime>
<custom-functions>
<constants-overwrite>
<adapter-configurations>
<sbmonitor>
<security>
<authentication>
<high-availability>
<java-vm>
<data-sources>
<operator-parameters>
<error-handler>
<jms-connections-defaults>
<time-service-configurations>

Note

If a parameter includes a Microsoft Windows path, for path separators either use forward slashes ('/') or double the backslashes ("\\") to escape them. For example, both of the following syntax examples are valid: 

<operator-parameter name="SCRIPT_ROOT" value="D:/scripts/"/>
<operator-parameter name="SCRIPT_ROOT" value="D:\\scripts\\"/>

<global>

Identifies the locations of resources, such as custom function plug-ins or modules, that should be loaded when the StreamBase Server runs your application.

Normally, it is not necessary to identify such resources when they are stored and managed within StreamBase Studio. However, you do need to edit the <global> element to specify the locations of these resources for running from the sbd command line outside of StreamBase Studio. In addition, you may need to provide references to resources stored outside of StreamBase Studio, such as third-party libraries.

<global> has one or more of the following child elements:

Note

For all elements, when running sbd in background mode with the -b flag, be sure to specify fully qualified paths, or use paths with environment variable components that sbd can resolve at runtime. See Using Environment Variables in Configuration Files.

The current directory of sbd at runtime is generally the directory that contains the primary EventFlow or StreamSQL application loaded, but might be a different directory if you start sbd from another directory or if you start sbd from a cron job or automatically start sbd at system startup as a Windows service or with /etc/init.d on UNIX.

global

The following UNIX example assumes that you have given a value to the STREAMBASE_HOME environment variable: 

<global>
  <plugin directory="/usr/share/sbplugins" />
  <plugin file="/home/sbuser/sbproject/waycooloperator.so" />
  <module-search directory="/usr/share/sbapps" />
  <operator-resource-search directory="${STREAMBASE_HOME}/resourceFiles" />
  <ignore-unbound-captures/>
</global>

Back to top ^

<plugin>

Identifies a native code library in the form of a DLL file for Windows or a .so file for UNIX, that contains the implementation of one or more custom simple or aggregate functions to be loaded when the application runs. You can have as many plug-in elements as you need, each identifying a different library. For custom C++ functions, each function name must also be declared in a <custom-functions>.

Do not confuse the <global/plugin> element with the <java-vm/library> element, which also specifies native code libraries to load. Use <plugin> to specify native libraries that contain C++ functions custom-written for your organization. Use <library> to specify native libraries called by Java functions, adapters, or JDBC drivers, possibly written and provided by third parties.

Attributes

Attribute Required Description
directory Either this attribute or file Specifies the path to a directory containing one or more custom function plug-ins to be loaded. StreamBase Server scans each specified directory and loads all the .so or DLL files it finds there, as appropriate for the platform.
file Either this attribute or directory Specifies the path to an individual DLL or .so file that implements a custom function or custom adapter that you want to load when your application runs. Unlike the directory attribute, this option causes only the specified file to be loaded.

You can omit the file extension: StreamBase loads the platform-appropriate shared object (.so) file on UNIX, or DLL file on Windows.


<module-search>

Identifies a directory containing EventFlow or StreamSQL application modules to be called and used by the top-level module at run time. These external modules then can be referenced using a module reference in an EventFlow application, or an APPLY statement in a StreamSQL application.

StreamBase Studio maintains its own module search path as described in module search path in the Authoring Guide. Studio appends entries specified in <global/module-search> elements in the server configuration file, after reconciling relative paths, as described in How StreamBase Studio Uses Server Configuration Files in the Administration Guide.

TIBCO recommends deploying your StreamBase applications by bundling your Studio project and running the bundle file as an argument to the sbd command. Running a bundle has the advantage of preserving the Studio module search path (supplemented as necessary by <module-search> entries in the configuration file), plus the resource search path and Java build path, all in a runnable format.

To run an application from the sbd command line without the benefit of a bundle, you must specify each module-containing directory with <module-search> elements, even if that means re-specifying the Studio module search path.

See Module Search Path Order of Precedence to understand how StreamBase locates module files.

Attribute Required Description
directory Yes Directory where application modules are stored at runtime.

The directory must be local (or shared) to the runtime system.

<operator-resource-search>

Specifies a directory containing resource files used by Java operator and adapter code at run time. File resources might include text files, SQL files, CSV data files from which to load tables or feed simulations, or other file types.

StreamBase Studio maintains its own resource search path as described in resource search path in the Authoring Guide. Studio appends entries specified in <global/operator-resource-search> elements in the server configuration file, after reconciling relative paths, as described in How StreamBase Studio Uses Server Configuration Files in the Administration Guide.

TIBCO recommends deploying your StreamBase applications by bundling your Studio project and running the bundle file as an argument to the sbd command. Running a bundle has the advantage of preserving the Studio module search path, resource search path, and Java build path in a runnable format.

To run an application from the sbd command line without the benefit of a bundle, you must specify each resource-containing directory with <operator-resource-search> elements, even if that means re-specifying the Studio resource search path.

See Module Search Path Order of Precedence to understand how StreamBase locates resource files. The search path order for modules also applies to locating resources on the resource search path.

Attribute Required Description
directory Yes Directory where Java operator or adapter files are stored at runtime.

The directory must be local (or shared) to the runtime system, and TIBCO recommends using only full pathnames.

<ignore-unbound-captures>

StreamBase's default behavior is to fail typechecking when an unbound capture is detected. An unbound capture occurs when an input stream of a module is implemented with a capture field and that input stream is not connected to an input port of the calling Module Reference in the parent application. This situation results in an error because there is no schema to examine or fields to capture for the unbound capture instance.

This existing behavior is preserved to maintain compatibility with pre-7.6.0 previous releases. However, when you are certain your unbound captures are benign, you can optionally suppress the resulting typecheck errors. To do this, use this option in the StreamBase server configuration file syntax: 

 <global><ignore-unbound-captures/></global>

<server>

Specifies aspects of the StreamBase Server that relate to network I/O. Optionally designates a data directory for disk-based Query Tables (so that data can persist between StreamBase Server sessions). The <server> element has the following child elements :

  • One or more of: <param> with any of these name-value attribute pairs:

name Attribute value Attribute
tcp-port TCP port number to be used for network I/O. Default: 10000.
connection-backlog Number of backlogged connections. Servers with many clients may want to increase the maximum number of backlogged connections to the server. For further details, lookup the manual page for the system call listen. The default is 10.
client-heartbeat-interval The number of milliseconds between heartbeat packets sent to clients. Clients can be configured to require a heartbeat packet from the server at a minimum interval. This is used primarily for network segmentation detection. Setting client-heartbeat-interval to 0 will disable heartbeats from the server. Clients connected to such a server will not have heartbeat protection, regardless of their locally configured minimum heartbeat interval. The default value is 10000.
datadir Path to a directory to be used to store persistent data from any on-disk Query Tables in your StreamBase application. You must specify a closing slash for UNIX paths, or a closing backslash for Windows paths, to designate the path as a directory path.

The value of datadir can be specified in several ways, not only in the server configuration file. The precedence order used is described as part of the STREAMBASE_DATA environment variable.

disk-querytable-cache

Amount of main memory that will be allocated to cache data from any disk-based Query Table operations. The value units are in MB of main memory and must be a power of 2. When unspecified, the default value is 16 MB. If your application uses disk-based Query Tables, you may be able to improve performance by setting a higher value. However, use caution with setting this parameter, as too high a value may consume more memory than needed and could negatively impact other resources that require memory. Memory is allocated for this parameter by the native code portion of the StreamBase Server launcher, and thereby competes with memory available for the Java VM. See Java VM Memory Settings.

As with any resource setting, establish baseline performance metrics and then test the affect of increasing or decreasing values under normal and peak loads.

disk-querytable-pagesize The page size used internally for disk-based Query Table operations. You may be able to improve performance by setting a higher value. This page size setting is not related to the StreamBase page size, nor the operating system (OS) page size. The value units are in KB and must be a power of 2. Valid values are 0, 1, 2, 4, 8, 16, 32 and 64. The default is 0 which specifies using an default value, which varies by operating system.
disk-querytable-transaction_mode Mode of transaction support for disk-based Query Tables.

Enumeration: { 0 | 1 | 2 }

The default mode is 1, where transactions are enabled, but not flushed to persistent store in any predictable time. Mode 2 transactionally commits every single table update to persistent store. Mode 0 disables transactional support. See the next parameter for a related setting.

disk-querytable-logsize If you are using disk-based Query Tables in transaction mode 1 or 2, your Query Table performance may improve if you increase the size of transaction log files. The value units are in MB. The default is 10 MB.
disk-querytable-flush-interval-ms If you are using disk-based Query Tables in transaction mode 1 or 0, writes to tables are not committed to disk in a predictable time frame. Setting the disk-querytable-flush-interval-ms parameter forces disk commits at the interval specified in milliseconds. A flush interval is needed in transaction mode 1 and 2 in order to write a checkpoint and remove unneeded log files. The default interval for mode 0 is no flushing (0) and 30000 (30 seconds) for modes 1 and 2.
idle-enqueue-client-timeout-ms, idle-dequeue-client-timeout-ms Settings for disconnecting idle clients.

An idle enqueue client is a client who has enqueued at least one tuple and has been idle for idle-enqueue-client-timeout-ms. An idle dequeue client is a client who has subscribed to at least one stream (at any point) and has been idle for idle-dequeue-client-timeout-ms.

Clients that have enqueued and subscribed are subject to both settings. The server checks clients every idle-client-check-interval-ms. The actual point that a client is disconnected will be approximate modulo idle-client-check-interval-ms.

Values are in milliseconds. Values greater than zero turn these features on. The default is off.
idle-client-check-interval-ms How often the server should check for idle clients. The value is in milliseconds. The default is 60000 (60 seconds).
max-persistent-connections Maximum number of persistent connections. Each persistent connection uses up server resources. To protect the server from errant client connections a user can specify a maximum number of persistent connections. Any attempted client connections over the limit will be disconnected.

Default value = -1 (no limit).
node-name A string value designating a name for the node in which the current application is loaded. This value is returned by the EventFlow function getNodeName(). Useful in managing asymmetric HA applications when 'LEADER' and 'NON-LEADER' are not specific enough.
operator-state-change-timeout-ms Each Java Operator or Embedded Adapter changes state along with the server process as a whole. The server waits for each Operator or Adapter to change state before it completes its state change. The value of operator-state-change-timeout-ms is the amount of time (in milliseconds) the server will wait before timing out the Operator or Adapter. If an Operator or Adapter is timed out on a state change, the server shuts down the Operator or Adapter, and proceeds with its own server state change. If unspecified in your sbd.sbconf, the default operator-state-change-timeout-ms value is 10000 milliseconds (ten seconds).

server Example 

<server>
    <param name="tcp-port" value="10100"/>
    <param name="connection-backlog" value="12"/>
    <param name="datadir" value="/tmp/112233/querytable/last10stocks"/>    
    <param name="disk-querytable-cache" value="256"/>
    <param name="disk-querytable-transaction_mode" value="1"/>
    <param name="disk-querytable-flush-interval-ms" value="40000"/>  
</server>

Back to top ^

<page-pool>

Defines memory parameters used by the StreamBase Server. <page-pool> has the following child elements:

  • One or more of: <param> with any of these name-value attribute pairs:

name Attribute value Attribute
page-size Use this setting to specify the initial size for output buffers and to calculate the maximum size a client output queue can reach before the client is disconnected. See max-client-pages below for further details. The default value for all supported platforms is 4096 bytes.
max-pooled-buffers Use this setting to specify how many buffers per output stream to maintain in a buffer cache. The default is 1024. To disable the cache, set the value to -1. This parameter does not determine when and whether slow clients are disconnected.
slow-dequeue-client-wait Use this setting to specify the behavior of slowly dequeuing clients. The server either disconnects slow clients (the default) or blocks the server to wait for slow clients to catch up. A value of -1 (the default) causes slow clients to be disconnected. A value greater than -1 causes the server to sleep for that amount of time in milliseconds when it detects that a dequeuing client is running behind. The server continues sleeping until there is available dequeuing space for the client.
max-client-pages Sets the maximum number of pages that a dequeuing client connection can allocate. Depending on the setting of the slow-dequeue-client-wait parameter, the server either disconnects a slow client or blocks. This setting is designed to protect sbd from a slow or hung dequeuing clients.

With the default page-size setting of 4096 bytes, the default max-client-pages value of 2048 will provide 8 megabytes. To allow ALL dequeuing clients to allocate unlimited memory in the server, set the value to zero.

Note that the number of pages that a client allocates will change over time. A client that is consuming tuples as fast as the server produces them will only use one or two pages. The maximum can be reached with a slow or hung client, or if there is a large spike of output data.

page-pool Example

In the following configuration example, the administrator decided to double the max-client-pages value from its 2048 default, resulting in a 16 MB page buffer for all dequeuing client connections: 

<page-pool>
  <param name="page-size" value="4096" />
  <param name="max-client-pages" value="4096" />    
</page-pool>

For related details, see the <java-vm> section below.

Back to top ^

<runtime>

The <application> child element of the <runtime> element is deprecated. TIBCO recommends migrating your <application> settings to a StreamBase deployment file, whose syntax is described in StreamBase Deployment File XML Reference.

Use the <runtime> element to specify certain parameters for running StreamBase Server. The <runtime> element supports the following child elements:

  • One or more <application> child elements (deprecated).

  • One or more of: <param> with either of the following name-value attribute pairs:

name Attribute value Attribute
schema-max-size The maximum size of a stream's schema; that is, the total number of bytes of all fields you expect in the tuple. The default value is 1048576 bytes, which is 1 MB. While there is no theoretical upper limit, in practice there is a maximum based on the available memory on the machines that will host the processing of your application. Be cautious about creating very large schemas, because applications that move smaller amounts of data perform much better than applications that move tuples containing unnecessary fields.
now-implementation The StreamBase expression language provides a now() function to return the current time. With this parameter, you can select one of two now() implementations. Default: system.

  • The system value means that the now() function uses Java's System.currentTimeMillis(). This is the default.

  • The thread value means that the now() function uses a background thread that checks the time approximately every millisecond. This option will result in decreased accuracy, but may be more efficient than the system option if you call now() more frequently than 1000 times per second.

runtime Example 

<runtime>
  <param name="schema-max-size" value="1048576"/>
  <param name="now-implementation" value="system"/>  
</runtime>

Back to top ^

<custom-functions>

Use this element to declare the parameters for a custom function. This element has the following child elements:

Use the <custom-functions> section for several reasons:

  • To make a custom C++ function available for use in a StreamBase application.

  • To register a C++ function's type signatures.

  • To assign aliases to C++ or Java functions so they can be called in the same way as built-in functions.

  • In rare cases, to register a Java function's type signatures.

Back to top ^

C++ Function Overview

To use a custom C++ function in your StreamBase application, you must:

  • Identify the DLL (Windows) or .so (UNIX) file that contains your custom function, using the <plugin directory="path"> or <plugin file="filename"> elements described above in the <global> section.

  • Name the function and provide the signatures of its arguments and return type using a <custom-function> element.

In the following example, a custom C++ function named func1 takes a string and an int argument and returns a string: 

<custom-functions>
    <custom-function name="func1" type="simple" >
      <args>
        <arg type="int" />    
        <arg type="string" /> 
      </args>
      <return type="string" />
    </custom-function>
</custom-functions>

Add the alias attribute to allow the use of a short name or alternate name for a given function. For example, the following allows you to call the func1 function (from the example above) in StreamBase expressions in the form f(myString, myInt): 

<custom-functions>
    <custom-function name="func1" type="simple" alias="f">
      <args>
      ... [same as example above]

The language attribute in the above examples is the default, which is the same as specifying language="cplusplus".

Use the <args> and <return> elements to describe the data types of the function's arguments and return types. For C++ functions, you must register each argument and return type. If the type attribute of an <arg> or <return> element is list or tuple, the element must have a child element that further describes the type. For tuple types, this is a <schema> element. For list types, this is an <element-type> element. For example: 

<args>
  <arg type="tuple">
    <schema>
      <field name="f1" type="int" />
      <field name="f2" type="double" />
    </schema>
  </arg>
  <arg type="list">
    <element-type type="string" />
  </arg>
</args>
<return type="list">
  <element-type type="tuple">
    <schema>
      <field name="g1" type="blob" />
      <field name="g2" type="timestamp" />
    </schema>
  </element-type>
</return>

The example above describes the arguments to a function that takes:

  • A tuple whose fields are an int and a double

  • A list of strings

The example returns:

  • A list of tuples whose fields are a blob and a timestamp

Back to top ^

Java Function Overview

Unlike C++ functions, you do not need to add a <custom-function> element for every Java function. A <custom-function> element is required under two circumstances:

  • You want to assign an alias for a custom function or for a standard library function so that your StreamBase application can call the function directly with the alias name (instead of using calljava()).

  • Your custom function takes arguments or returns values of the list or tuple data types, and you do not want to provide a custom function resolver.

For simple Java functions that you expect to use in limited cases, it may be simpler to call it with calljava() than to define a <custom-function> element.

To use a custom Java function in your StreamBase application, you must:

  • Make sure the JAR or class file that implements the function is available on StreamBase Server's classpath. Use the <jar> or <dir> elements of the <java-vm> element to extend the server's classpath.

  • Call the function in an expression in your application using either:

Java functions that have a <custom-function> definition must have the alias attribute defined. If not defined, StreamBase Server starts but does not load the specified function, instead printing a notification message on the console that the function definition will be ignored. As an alternative, you can call a Java function using calljava(), without first specifying a <custom-functions> definition for that function.

When using <custom-function> to describe a custom Java function:

  • You must specify language="java".

  • You must specify the fully qualified class name with the class attribute.

  • You must specify the alias attribute.

  • For simple functions (that is, when using type="simple" or with no type attribute), you must specify the name attribute.

For Java functions only, as an alternative to explicitly specifying argument and return types, you can specify args="auto" to have StreamBase Server autodetect the argument and return types. If the server autodetects overloaded functions of the same name with different argument types, it adds all detected versions of the specified function.

Java functions typically use the args="auto" attribute. If you do not use args="auto" for a Java function, then you must specify <arg> and <return> elements to describe each argument and return type, using the syntax described above for C++ functions. You might use <arg type=> instead of args="auto" if your function has many overloaded signatures, and you only want to expose a subset of those signatures for use in your StreamBase application.

If your Java function has an argument or return value of type list or tuple, and you use args="auto", then you must provide a custom function resolver as described on Custom Functions with Complex Data Types. If you use explicit <arg type=> elements, you do not need to provide a custom function resolver.

The following example shows a typical definition for a Java function:

<custom-functions>
  <custom-function 
    language="java" 
    class="com.streambase.sb.sample.Hypotenuse" 
    name="calculate" 
    alias="hypotenuse"
    type="simple" 
    args="auto" />
</custom-functions>

You can specify an alias for any Java function in the server's classpath, including standard library functions:

<custom-functions>
  <custom-function 
    language="java" 
    class="java.lang.Math" 
    name="toDegrees" 
    alias="degrees" 
    args="auto" />
</custom-functions>

You can use the same string for name and alias. Using the same string allows you to call a function directly by its original name. For example, the following allows you to call log10() in a StreamBase expression: 

<custom-functions>
  <custom-function 
    language="java" 
    class="java.lang.Math" 
    name="log10" 
    alias="log10" 
    args="auto" />
</custom-functions>

Back to top ^

<custom-function>

Each simple or aggregate C++ function must be declared in a <custom-function> element, as described above in C++ Function Overview. Java functions can be optionally declared in a <custom-function> element, as described in Java Function Overview.

C++ and Java functions can be assigned aliases. You can use the aliased function name as if that function were embedded in your StreamBase application. For example, setting alias="foo" means you can invoke foo(arg) in a StreamBase expression instead of calljava(foo(arg)) or callcpp(foo(arg)).

Attributes

Attribute Required for C++ Functions Required for Java Functions Description
name Yes Yes

The function's name as it appears in its C++ or Java source file. This attribute is required for simple functions (that is, when type="simple"), but can and should be omitted for aggregate functions.

type No No Either simple or aggregate. The default is simple.
alias No Yes A substitute name for this function, to be called directly instead of using calljava() or callcpp(). This attribute is required when language="java", and is optional for C++ functions.
language No Yes Either cplusplus or java. The default is cplusplus.
class No Yes For Java functions only, the fully qualified class name where the specified function is defined.
args Not used. No

For Java functions only, you can set args="auto" to have StreamBase Server autodetect the arguments and return type of the current function. If you elect to use an <args> child element for Java functions, do not use this args= attribute.

For C++ functions, use an <args> child element (not this args= attribute) to describe the data type of each of the function's arguments.

isVarargs Not used. No

For Java functions only, you can set the isVarargs="true" attribute if the last argument is variable length and you want to declare the individual <arg> elements. In this case, do not set args="auto". When you use args="auto", the isVararg attribute is ignored.


The <custom-function> element has the following child elements:

Back to top ^

<args>

For Java functions, you can set the args="auto" attribute of the <custom-function> element to have StreamBase Server autodetect the argument types. In this case, do not use the <args> element. You can optionally use <args> for Java functions as described in Java Function Overview.

For C++ functions, you must use an <args> element with <arg> child elements for each of the function's arguments.

The <args> element has the following child element:

Back to top ^

<return>

Defines the data type returned by a C++ or Java function. For C++ functions, this element is required if the function returns a value.

For Java functions only, setting the args="auto" attribute of the <custom-function> element autodetects the return type as well as the argument types. Thus, when using args="auto", no <return> element is required.

Attributes

Name Required Description
type Yes The data type to be returned from the function to the StreamBase application.

For type="list" and type="tuple" you must also supply the appropriate <element-type> or <schema> child element, respectively.


The <return> element has the following child elements:

Back to top ^

<arg>

Defines the data type of one of a function's arguments. The order of <arg> elements in the configuration file should match the argument order for the function.

Attributes

Name Required Description
type Yes The data type for this argument for this function. Valid values are the names of the StreamBase data types in all lowercase letters.

For type="list" and type="tuple" you must also supply the appropriate <element-type> or <schema> child element, respectively.


The <arg> element has the following child elements:

Back to top ^

<schema>

Defines the schema for a value when type="tuple" for the <arg>, <return>, <element-type>, or <field> elements. The <schema> element has one child element:

<field>

Defines the data type for a single field in a tuple.

Attributes

Name Required Description
name Yes The name of this field in the tuple.
type Yes The data type for this field in the tuple. Valid values are the names of the StreamBase data types in all lowercase letters.

For type="list" and type="tuple" you must also supply the appropriate <element-type> or <schema> child element, respectively.


The <field> element has the following child elements:

Back to top ^

<element-type>

Defines the data type for the elements of a list when type="list" for the <arg>, <return>, <element-type>, or <field> elements.

Attributes

Name Required Description
type Yes The data type for the elements of the current list. Valid values are the names of the StreamBase data types in all lowercase letters.

For type="list" and type="tuple" you must also supply the appropriate <element-type> or <schema> child element, respectively.


The <element-type> element has the following child elements:

Back to top ^

<constants-overwrite>

This is an optional element that can contain one or more <constant-overwrite> child elements. Constants are defined and typechecked at compile time. Use <constant-overwrite> elements to override the values of constants at run time. A <constants-overwrite> element can contain any number of <constant-overwrite> child elements, each of which substitutes a new value for a constant.

Each child element overwrites all constants that have the same name in the StreamBase Server process. <constant-overwrite> names are the simple names of constant entities and are not qualified per container or module reference. The specified overwrites are applied to all containers upon creation throughout the lifetime of the server process.

For example, during development an application might define a CSV file name as a constant. When deploying the application, different CSV files might be required. The configuration file can include a <constant-overwrite> element to substitute a different file name during initialization at run time.

The <constants-overwrite> element has one or more child elements named <constant-overwrite>.

<constant-overwrite>

This element specifies a constant value to be used at runtime in place of an original value. Substitution and typechecking takes place during initialization of the application. The element has two required attributes:

Attributes

Name Required Description
name Yes The name of a constant defined within the module.
value Yes The value of that constant to substitute at run time.

Using the above example, a configuration file could specify a new file name at run time by including:

<streambase-configuration>
    ...
    <constants-overwrite>
        <constant-overwrite name="FileName" value="&quote;deploy.csv&quote;"/>
        <constant-overwrite name="timeoutMs" value="250"/>
    </constants-overwrite>
    ....
</streambase-configuration>

The &quote; sequences are required around string values for proper interpretation.

Back to top ^

<adapter-configurations>

This is an optional element that adapters and Java operators can access. For example, it can provide common defaults for all adapter instances in a project that use the same sbd.sbconf file, and the defaults for all adapters can be changed by changing a single setting on any of them.

This element enables operators and adapters to extract string values from a StreamBase server configuration file. It can contain zero or more (but typically at least two) child elements. The element or its sub-elements contain strings that a Java operator or adapter can access and use in any way the developer chooses.

If present, the <adapter-configurations> child elements can have any names. Each one corresponds to a possible alternative value selectable by the user. In the case of two alternatives, the element could take the following form: 

  <adapter-configurations>
      <choice_1>
         string to retrieve for choice 1
      </choice_1>
      <choice_2>
         string to retrieve for choice 2
      </choice_2>
  </adapter-configurations>

The component's Java code would look for elements specifically named <choice_1> and <choice_2>, corresponding to the user's selection. However, the code could also expect elements having id attributes with those names, leading to XML elements structured as shown below: 

  <adapter-configurations>
      <item id="choice_1">
         string to retrieve for choice 1
      </item>
      <item id="choice_2">
         string to retrieve for choice 2
      </item>
  </adapter-configurations>

In the operator or adapter, choice_1 and choice_2 might be items in a drop-down menu. When the user chooses one, Java code in the custom operator or adapter retrieves the indicated string from the <adapter-configurations> configuration file section, and typically would use that string to add or update a field in a schema or set a property value. The mechanism is quite flexible. By providing appropriate Java code, the developer can use it to trigger a variety of actions. Organizations can codify best practices that direct developers to use <adapter-configurations> in a consistent way.

<adapter-configurations> example

You can add or remove choices from a <adapter-configurations> element and change their content at will. You can also nest alternatives in arbitrarily named sub-elements to partition them as needed. For example, here is the <adapter-configurations> section of the configuration file for the Configuration File Access Sample, which happens to contain a sub-element named <configuration>. That element has two <choice> sub-elements that indirectly select strings provided in <text> elements: 

  <adapter-configurations>
    <configuration type="ConfigBasedOperatorSample">
  <!-- See ConfigBasedOperatorSampleBeanInfo for how Studio displays these two choices to the user -->
      <choice id="choice-1" value="First choice" />
      <choice id="choice-2" value="Second choice" />
  <!-- See ConfigBasedOperatorSample#typecheck for how the operator retrieves one of these -->
      <text id="First choice">
         0
      </text>
      <text id="Second choice">
         1
      </text>
    </configuration>
  </adapter-configurations>

As mentioned above, the names of elements and how they are structured are arbitrary. Here, the <choice> id attributes are the menu items that the widget displays to users. If the menu included a third item, you would insert a new <choice> and a corresponding <text> element. For example: 

<adapter-configurations>
    <configuration type="ConfigBasedOperatorSample">
  <!-- See ConfigBasedOperatorSampleBeanInfo for how Studio displays these two choices to the user -->
      <choice id="choice-1" value="First choice" />
      <choice id="choice-2" value="Second choice" />
      <choice id="choice-3" value="Third choice" />
  <!-- See ConfigBasedOperatorSample#typecheck for how the operator retrieves one of these -->
      <text id="First choice">
         0
      </text>
      <text id="Second choice">
         1
      </text>
      <text id="Third choice">
         2
      </text>
    </configuration>
  </adapter-configurations>

The chooser for this property is typically a pull-down choice menu that lists a set of alternative strings corresponding to the child elements. Choices are SBPropertyDescriptors accessed through a ConfigurationChooserPropertyDescriptor in a SBSimpleBeanInfo class file. ConfigBasedOperatorSampleBeanInfo.java in the sample application creates a choice menu for a property descriptor that is labeled "Choose one": 

package com.tibco.streambase.sample;

import java.beans.IntrospectionException;

import javax.xml.xpath.XPathExpressionException;

import com.streambase.sb.operator.parameter.ConfigurationChooserPropertyDescriptor;
import com.streambase.sb.operator.parameter.SBPropertyDescriptor;
import com.streambase.sb.operator.parameter.SBSimpleBeanInfo;

public class ConfigBasedOperatorSampleBeanInfo extends SBSimpleBeanInfo {

  public SBPropertyDescriptor[] getPropertyDescriptorsChecked()
    throws IntrospectionException {
  
  try {
    ConfigurationChooserPropertyDescriptor ccpd =
      new ConfigurationChooserPropertyDescriptor("configElement",
        "configuration[@type='ConfigBasedOperatorSample']/choice/@id",
        ConfigBasedOperatorSample.class);
    ccpd.displayName("Choose one:");
    SBPropertyDescriptor[] p = { ccpd };
    return p;

    } catch (XPathExpressionException e) {
      throw new RuntimeException(e);
    }
  }
}

At runtime, the adapter or operator Java code retrieves the configuration file elements with getOperatorConfigurationAccessor(), as in the sample's code (unrelated blocks and exception handling code elided) shown below: 

private String configElement;
private String valueFound;
...
NodeList blocks = getOperatorConfigurationAccessor().getConfigurationBlocksAsXML(
MessageFormat.format("configuration[@type=\"ConfigBasedOperatorSample\"]/choice[@id=\"{0}\"]",
  getConfigElement()));
...
NamedNodeMap attributes = blocks.item(0).getAttributes();
...
Node valueAttr = attributes.getNamedItem("value");
...
String selValue = valueAttr.getNodeValue();
NodeList textBlocks = getOperatorConfigurationAccessor().getConfigurationBlocksAsXML(
  MessageFormat.format("configuration[@type=\"ConfigBasedOperatorSample\"]/text[@id=\"{0}\"]",
  selValue));
...
valueFound = textBlocks.item(0).getTextContent();

The retrieved property descriptor is created with an XPath expression that selects XPathConstants.NODESET and is expected to return a list of attribute nodes, whose values are presented to the user to select from. The value selected (or entered) is set to a String property type. Then, in the processTuple method, out.setString() overrides a field value, in this case the first field (0), with the retrieved property value: 

public void processTuple(int inputPort, Tuple tuple)
      throws StreamBaseException {
    assert configElement != null;

    Tuple out = outputSchemas[inputPort].createTuple();

    for (int i = 0; i < out.getSchema().getFieldCount(); ++i) {
      out.setField(i, tuple.getField(i));
    }
  out.setString(0, valueFound.trim());
  sendOutput(0, out);
}

In the sample application, values are prepared at typecheck time, but you can use the getOperatorConfigurationAccessor API at runtime as well.

Note

Because <adapter-configurations> elements are free-form, the StreamBase Studio source code editor does not display tag proposal hints for them.

Back to top ^

<sbmonitor>

Use this element to define characteristics of the statistics that will be generated for use by the sbmonitor utility. <sbmonitor> has the following child elements:

  • One or more of: <param> with any of these name-value attribute pairs:

name Attribute value Attribute
enabled Either true or false.

Set to true to enable statistics collection, or false to disable it. If it is set to false, sbmonitor will not be usable with this instance of StreamBase Server. The default is true.

period-ms Specifies the period, in milliseconds, over which statistics are aggregated. The default is 1000 ms (every second).

sbmonitor Example 

<sbmonitor>
    <param name="enabled" value="true"/>
    <param name="period-ms" value="2000"/>
</sbmonitor>

Back to top ^

<security>

The security section controls security and authentication in the sbproxy and sbd. If there is a security section, the sbd will only listen for connections on localhost, so connections from remote computers cannot be made. If there is a security section in the sbconf file, the sbproxy server will allow only SSL connections from clients.

Note

This section cannot be configured together with the <authentication> section, which provides a different authentication method.

<security> has one or more of the following child elements:

  • One of: <ssl-authentication>

  • One <param> element using this name-value attribute pair:

    name Attribute value Attribute
    perform-authentication
    true

    Restrictions to user actions will be added in this section.

    false

    All users will be able to perform any action. The client connections will still be SSL, but no further authentication will be performed.

  • One of: enabled

  • Zero or one of: <transform-principal>

  • Zero or one of: <client-ssl-connections>

  • Zero or more of: <ldap>

  • Zero or more of: <role>

  • Zero or one of: <user-data>

security Example 

<security>
  <ssl-authentication>
    <param name="keystore" value="../test/proxy/security/signed.keystore"/>
    <param name="keystore-password" value="secret"/>
    <param name="key-password" value="secret1"/>
    <param name="enabled" value="true"/>
  </ssl-authentication>

  <param name="perform-authentication" value="false"/>

  <transform-principal>
    <param name="searchRegexp" value="cn=([^,]*).*"/>
    <param name="replaceRegexp" value="$1"/>
  </transform-principal>

  <client-ssl-connections>
    <param name="require-client-authentication" value="true"/>
    <param name="cipher-suite" value="SSL_RSA_WITH_3DES_EDE_CBC_SHA"/>
  </client-ssl-connections>

  <ldap>
    <!-- a TLS auth server -->
    <server host="parallels" port="838">
      <param name="principal-root" value="ou=Users,dc=example,dc=com"/>
      <param name="principal-search" value="cn={0}"/>
      <param name="keystore" value="ldapuser.keystore"/>
      <param name="keystore-password" value="secret"/>
      <param name="key-password" value="secret1"/>
    </server>
  </ldap>

  <ldap>
    <!-- a basic auth server -->
    <server host="parallels" port="839">
      <param name="principal-root" value="ou=Users,dc=example,dc=com"/>
      <param name="principal-search" value="cn={0}"/>
      <param name="root-dn" value="cn=Manager,dc=example,dc=com"/>
      <param name="password" value="secret"/>
    </server>
  </ldap>

  <role name="StreamBaseSuperuser">
    <param name="action" value="Administrate"/>
  </role>

  <role name="InnocentBystander">
    <param name="action" value="Status"/>
    <param name="action" value="Enqueue default.InputStream1"/>
    <param name="action" value="Dequeue default.OutputStream1"/>
  </role>

  <user-data>
    <user>
      <param name="cn" value="cn=Alice Pleasance Liddell,ou=Users,dc=example,dc=com"/>
      <param name="role" value="InnocentBystander"/>
      <param name="role" value="StreamBaseSuperuser"/>
      <param name="password" value="secret"/>
    </user>
    <user>
      <param name="cn" value="EMAILADDRESS=bobn@streambase.com, CN=Bob Newhart, 
        OU=Users, O=TIBCO StreamBase, L=Waltham, ST=Massachusetts, C=US"/>
      <param name="role" value="InnocentBystander"/>
    </user>
  </user-data>

</security>

Back to top ^

<ssl-authentication>

Specifies the keystore that holds the signed X.509 server certificate that will be used for SSL connections between clients and the sbproxy server.

<ssl-authentication> has the following child elements:

  • Two <param> elements, each using one of these name-value attribute pairs:

    name Attribute value Attribute
    keystore URI of the keystore that identifies a certificate authority (CA). Alternatively, the URI can point to a trust store, which defines multiple CAs that your organization recognizes.
    keystore-password The password to access the keystore.
    key-password The password to access the key within the keystore. If absent, the keystore password is used to access the key.
    Enabled Whether ssl authentication is enabled (true or false). Must be set to true to access keystore.

Back to top ^

<transform-principal>

Defines a search/replace regular expression that will change the name of the principal. The transform in the preceding security example extracts the CN section from the entire principal's name as it appears in a certificate.

<transform-principal> has the following child elements:

  • Two <param> elements, each using one of these name-value attribute pairs:

    name Attribute value Attribute
    searchRegexp Matches on a pattern in a field in an LDAP database.
    replaceRegexp Specifies the replacement pattern.

Back to top ^

<client-ssl-connections>

Defines the type of SSL connection and the external tools used for encryption.

<client-ssl-connections> has the following child elements:

  • One of: <param> with this name-value attribute pair:

    name Attribute value Attribute
    require-client-authentication
    false

    SSL connections will be accepted from clients that do not have a signed user certificate. This is sometimes called one-way SSL, and is the default value. The principal and password attributes (user= and password= attributes) must be specified in the URI, unless the perform-authentication parameter is false (see below)

    true

    Only client connections that have a certificate signed by a known certificate authority will be allowed. This is sometimes called two-way SSL. The principal will be taken from the certificate.

  • Zero or more of: <param> with this name-value attribute pair:

    name Attribute value Attribute
    cipher-suite Comma-separated list of cipher suites that can be used for SSL encryption. If this element is not listed, sbproxy uses all the cipher suites that are installed with the JVM. When this element is present, sbproxy is limited to the suites you list. Use this setting to prevent the use of weak or otherwise unacceptable ciphers during the negotiation between the client and server when establishing an SSL connection. See the Oracle website for typical JDK suites.

Back to top ^

<ldap>

Specifies information for connecting to and searching LDAP servers to manage user authentication. Create a separate <ldap> element for each LDAP server. If more than one LDAP server is defined, the requests will be sent to each LDAP server in turn, in a round-robin manner. You can configure one or more LDAP servers.

<ldap> has the following child elements:

Back to top ^

<server>

Identifies an LDAP server that you want to connect to, and specifies the type of authentication to be used.

Attributes

Attribute Required Description
host Yes The address presented to clients.
port Yes The port number used by the LDAP server.

<server> has the following child elements:

  • Two of: <param> elements, each with one of these name-attribute pairs:

    name Attribute value Attribute
    principal-root The Distinguished Name pattern that describes the directory information tree on the LDAP server, from the required entry to the directory root. Principal names will be applied to the pattern during authentication.
    principal-search The field name and index within the LDAP to use when looking up principals.
    root-dn The StreamBase connection to the LDAP server needs the credentials of any LDAP user to validate the connection. This does not need to be a user with any particular privileges and can be a username you add to the LDAP database only for StreamBase authentication, such as sbuser. <param name="root-dn" value="cn=sbuser,dc=example,dc=com"/>

  • One of the following groups of elements:

    To authenticate in the sbconf file

    Two of: <param>, each with one of these name-attribute pairs

    name Attribute value Attribute
    root-dn The Distinguished Name pattern that identifies a valid user to the LDAP server.
    password The password that must be entered to authenticate a user.
    To authenticate in LDAP (TLS)

    Two of: <param>, each with one of these name-attribute pairs

    name Attribute value Attribute
    keystore URI of the keystore that identifies users for the LDAP server.
    keystore-password The password to access the keystore.
    key-password The password to access the key within the keystore. If absent, the keystore password is used to access the key.

Back to top ^

<role>

Use the role element to define a role and assign its actions. You can define any number of roles and use any role names, each with a different combination of actions. Later (in the user-data element) you can assign users to roles.

When a client attempts to perform an action, such as dequeue OutputStream1, the user is authenticated, then the authentication source (an LDAP server or a user-data in the sbconf file) is asked for all of the roles the user has. If the user has as role which has the dequeue default.OutputStream1 action listed, then the dequeue operation is allowed.

Attributes

Attribute Required Description
name Yes A name for a group of actions. You can assign any name.

<role> has the following child elements:

  • One or more <param> elements with this name-attribute pair:

name Attribute value Attribute
action

By assigning actions, you determine the commands that a user is authorized to use (and, by omission, not use). Specify one of the following:

Administrate

Matches Administer actions in the LDAP server, and enables the following all sbadmin commands.

Status

Matches Status actions in the LDAP server, and enables the following subcommands: status, describe, list.

Enqueue container.stream

Matches Status actions in the LDAP server. Enables the user to enqueue the specified stream.

Dequeue container.stream

Matches Status actions in the LDAP server. Enables the user to dequeue the specified stream.

Back to top ^

<user-data>

Defines the Principal-to-role mapping for each user. This section should not be defined if an <ldap> section is defined.

<user-data> has the following child elements:

  • Zero or more of: <user>

Back to top ^

<user>

A user corresponds to a Principal in an LDAP database. Specifies authentication data and assigns user roles.

<user> has the following child elements:

  • One of: <param> with the following name-attribute pair:

    name Attribute value Attribute
    cn The full Distinguished Name of the Principal.

  • One of: <param> with the following name-attribute pair:

    name Attribute value Attribute
    password The user's password.

  • Zero or more of: <param> with the following name-attribute pair:

    name Attribute value Attribute
    role One of the roles defined in a <role> element.

Back to top ^

<authentication>

Use this element to define the authentication parameters that will be used to protect the StreamBase application from unauthorized access.

Note

The <authentication> element cannot be configured together with the <security> element. You can only use one of these security methods.

<authentication> has the following child elements:

  • One or more of: <param> with any of these name-value attribute pairs:

name Attribute value Attribute
enabled Enumerated: { true | false }. Set to true to require authentication information from clients, or false to allow access from anyone. The default is false, but it should be set to true in production systems.
type Enumerated: sb-password-file. This is the only value allowed. It specifies the type of authentication to use to verify user names and password. Required if authentication is enabled.
filepath The path to the password file containing StreamBase user names and passwords. Required if authentication is enabled. The default is sbpasswd in the etc subdirectory of your StreamBase installation.
adminuser The username for the administrative user in the StreamBase authentication system.
adminpassword The password for the administrative user.

Authentication Example 

<authentication>
    <param name="enabled" value="true"/>
    <param name="type" value="sb-password-file"/>
    <param name="filepath" value="/opt/tibco/sb-cep/n.m/etc/sbpasswd"/>
</authentication>

Back to top ^

<high-availability>

Use this element to enable automatic leadership detection, to enable automatic table replication, and to define the high-availability leadership status for an instance of StreamBase Server. You can also specify other parameters required for a particular high-availability server pair. For more information about using StreamBase for high availability, see Clustering and High Availability in the Administration Guide.

<high-availability> has the following child elements:

  • <param> containing each of the following name-value attribute pairs:

    name Attribute value Attribute
    leadership-status value=LEADER or value=NON_LEADER. Specifies the leadership status of this server.
    enabled value="auto" or value="custom" or value="ha-off". The default is ha-off.

    Specifies whether automatic leadership tracking is enabled. When value="auto" or value="custom", you must either define parameters in the <ha-application> element described below, or specify the name of your customized HA container with the <ha-container> parameter.

    ha-container value="container-name". Used when enabled=custom to specify the name of the HA container, and optionally used with enabled=auto to override the default the name of the HA container used for automatic leadership tracking.

    Without this parameter, automatic leadership tracking uses an HA container named _SB_ha.

    When you use the ha-container parameter, you must not also specify an <ha-application> element.

  • <ha-application>, which has one child element, <param>. Specify one or more of the following name-value attribute pairs with one or more <param> elements:

    name Attribute Required? value Attribute
    HB_OTHER_SERVER required Host name or IP address of the other server in a high-availability pair.
    HB_PORT required Port number for HB_OTHER_SERVER.
    HB_TIMEOUT optional Integer, number of milliseconds. Specified how long the HA Heartbeat should wait before declaring a timeout.
    HB_INTERVAL optional Integer, number of milliseconds. Specifies how often to send a heartbeat message
    HB_RECON_ATTEMPTS optional Integer. Specifies the number of times to attempt to reconnect.
    HB_RECON_SLEEP optional Integer, number of milliseconds. Specifies how long to wait between reconnection attempts.

  • <table-replication>, which has one child element, <param>. Specify one or more of the following name-value attribute pairs with one or more <param> elements:

    name Attribute Required? value Attribute
    HB_OTHER_SERVER required Host name or IP address of the other server participating in table replication.
    REPL_OTHER_SERVER_PORT required The port on HB_OTHER_SERVER.
    REPL_CHECK_INTERVAL optional Integer, number of seconds. Specifies how often to check the replication state of the table.
    REPL_BATCH_SIZE optional Integer, number of tuples. Specifies the size of the batches to be sent from the LEADER to the NON_LEADER.
    REPL_RECONNECT_INTERVAL optional Integer, number of milliseconds. Specifies how often to attempt reconnection between the LEADER and NON_LEADER.

The optional parameters can be used only if you set the enabled parameter of <high-availability> to auto or custom.

The following example shows some sample settings. See also High Availability Sample for an example of this section.

high-availability Example 

<high-availability>
  <param name="leadership-status" value="LEADER"/>
  <param name="enabled" value="auto"/>
  <ha-application>
    <param name="HB_OTHER_SERVER" value="name_of_other_server"/>
    <param name="HB_PORT" value="12345"/>
    <param name="HB_TIMEOUT" value="3000"/>
    <param name="HB_INTERVAL" value="1000"/>
    <param name="HB_RECON_ATTEMPTS" value="10"/>
    <param name="HB_RECON_SLEEP" value="500"/>
  </ha-application>
  <table-replication>
    <param name="HB_OTHER_SERVER" value="name_of_other_server"/>
    <param name="REPL_OTHER_SERVER_PORT" value="6789"/>
    <param name="REPL_CHECK_INTERVAL" value="1"/>
    <param name="REPL_BATCH_SIZE" value="100"/>
    <param name="REPL_RECONNECT_INTERVAL" value="250"/>
  </table-replication>
</high-availability>

Back to top ^

<java-vm>

Use the <java-vm> element to specify settings and properties to pass to the Java virtual machine (JVM) that runs StreamBase Server. The <java-vm> top-level element has the following child elements:

Zero, one, or two of <param>
Zero, one, or more of <jar>
Zero, one, or more of <dir>
Zero, one, or more of <library>
Zero, one, or more of <sysproperty>

See the next section for an example of a <java-vm> element in use.

Back to top ^

<java-vm> Complete Example

The following shows a complete example of the <java-vm> top-level element with all of its child elements in use. 

<java-vm>
  <param name="java-home" value="/usr/lib/java" />
  <param name="jvm-args" value="
    -Xms1024m -Xmx4096m     
    -XX:+UseG1GC
    -XX:MaxGCPauseMillis=500 
    "/>
  <jar file="/usr/lib/calcs/othercalcs.jar" />
  <jar file="./Resources/ojdbc14.jar" />
  <dir path="./java-bin" />
  <dir path="/usr/share/maths/classes" />
  <library path="/usr/lib/vendor/lib/" />
  <sysproperty name="streambase.tuple-charset" 
    value="UTF-8" />
  <sysproperty name="codegen.intermediate-stream-dequeue" 
    value="true" />
</java-vm>

Back to top ^

<param> Child Element

The <java-vm> element accepts zero or one of the <param> child element for each of the name-value pairs in the following table:

name Attribute value Attribute
java-home

Rarely used. StreamBase installs a JDK for internal use by StreamBase Studio and StreamBase Server in streambase-install-dir/jdk. Thus, you only need to set the java-home parameter to override the default JDK. See Using an External JDK for instructions.

If used, set the value of java-home to the full, absolute path to a supported JDK on your machine. For example, on UNIX: 

<java-vm>
  <param name="java-home" 
    value="/usr/lib/java" />
</java-vm>

Or, on Windows:

<java-vm>
  <param name="java-home" 
    value="C:/Program Files/Java/jdk1.8.0_60" />
</java-vm>

See Supported Configurations in the Installation Guide for information on the minimum JDK versions supported. See How StreamBase Server Searches for a JDK for background information when considering a change in the java-home parameter.

jvm-args

Specifies a quoted set of arguments to send to the JVM that runs the server. You can specify minimum and maximum values for the memory allocation pool, and can specify Java properties, or other JVM options.

Do not set the classpath here, and do not specify -server or -client, because the server JVM is always loaded.

Use the guidance in Java VM Memory Settings for assistance when setting the -Xms (minimum) and -Xmx (maximum) Java heap size arguments.

Use the guidance in Garbage Collection Policy Settings when adding or changing settings that affect Java garbage collection algorithms.

You can use the <sysproperty> Child Element element as an alternative to, or in addition to, setting Java properties in the <jvm-args> element.

When you generate a default server configuration file in Studio and you opt to include the default contents, or when you generate a default configuration file with sbd –s, it contains the following settings for the <java-vm> element: 

<java-vm>
  <param name="jvm-args" value="
    -Xms1024m -Xmx4096m     
    -XX:+UseG1GC
    -XX:MaxGCPauseMillis=500 
    "/>
</java-vm>

See Java VM Memory Settings and Garbage Collection Policy Settings for further discussions of these settings.

Back to top ^

<jar> Child Element

Specifies a JAR file to be loaded at runtime, used by a Java Operator or by a JDBC data source server. Required within a parent <java-vm> element when Java operators or JDBC tables are used in the StreamBase application. You can specify multiple JAR files, as shown in the <java-vm> example.

  • JARs that provide JDBC access to a supported JDBC database.

  • JARs that implement a custom Java operator or adapter.

  • JARs provided by third parties that implement code needed by an adapter or operator.

You can specify multiple <jar> elements. One <jar> element specifying the path to a JDBC driver is required when using a JDBC Table data construct.

The <jar> element has the following attribute:

Attribute Required Description
file Yes

Path to the JAR file.

Note on Portability of Paths

For maximum portability of your application for deployment on another server, specify a relative path in the Studio project folder, or deploy your application with a StreamBase bundle so that the bundler can resolve absolute paths at bundle time.

Examples:

<java-vm>
  <jar file="./Resources/ojdbc14.jar" />
  <jar file="/usr/lib/calcs/othercalcs.jar" />
</java-vm>

Back to top ^

<dir> Child Element

Use the <dir> element to add a directory to the classpath of the JVM that runs StreamBase Server. You can use multiple <dir> elements.

The <dir> element has the following attribute:

Attribute Required Description
path Yes

Directory path to add to the JVM's classpath.

See the Note in the <jar> element, which also applies here.

Examples:

<java-vm>
  <dir path="./java-bin" />
  <dir path="/usr/share/maths/classes" />
</java-vm>

Back to top ^

<library> Child Element

Use the <library> element to specify the path to a directory that will be prepended to the JVM's java.library.path to identify the location of native libraries used by your Java code, by an adapter, or called by JDBC drivers. The directory you specify is expected to contain one or more DLL files for Windows or .so files for UNIX. To load multiple library sets, use multiple <library> elements. See <java-vm> for an example.

Do not confuse the <java-vm/library> element with the <global/plugin> element, which also specifies native code libraries to load. Use <plugin> to specify native libraries that contain C++ functions custom-written for your organization. Use <library> to specify native libraries called by Java functions, adapters, or JDBC drivers, possibly written and provided by third parties.

The <library> element has the following attribute:

Attribute Required Description
path Yes

Path to the directory containing native libraries called by Java code.

See the Note in the <jar> element, which also applies here.

Example for UNIX:

<java-vm>
  <library path="/usr/lib/vendor/lib" />
</java-vm>

Example for Windows:

<java-vm>
  <library path="C:/Program Files/vendor/lib" />
</java-vm>

Back to top ^

<sysproperty> Child Element

Use the <sysproperty> element as an alternative to adding system properties with the jvm-args parameter of the <java-vm> element. You can only specify one jvm-args parameter, so in order to add a system property with it, you must append the property setting to the jvm-args parameter. By contrast, you can add as many <sysproperty> elements as you need, each one specifying an individual property.

The <sysproperty> element has the following attributes:

Attribute Required Description
name Yes

The name of the system property, such as streambase.tuple-charset or codegen.intermediate-stream-dequeue. See StreamBase Java Properties.

value Yes

The value to set for the named property, such as UTF-8 or true.

Examples:

<java-vm>
  <sysproperty name="streambase.tuple-charset" 
    value="UTF-8" />
  <sysproperty name="codegen.intermediate-stream-dequeue" 
    value="true" />
</java-vm>

Back to top ^

<data-sources>

Parent element for <data-source> declarations, which identify all external database connections accessed by StreamBase applications. You can define as many data sources as you need, each pointing to a single server.

<data-sources> has the following child elements:

<data-sources> Examples

The following shows three examples of <data-sources> sections of the server configuration file, illustrating three different database connections. First, a connection to a MySQL database: 

<data-sources>
  <data-source name="MYSQL" type="jdbc">
    <driver value="com.mysql.jdbc.Driver"/>
    <uri value="jdbc:mysql://mysql.example.com:3306/qa?user=username&amp;password=secret"/>
    <param name="jdbc-reconnect-regexp" value="Communications link failure"/>
    <param name="jdbc-reconnect-regexp" value="Connection reset"/>
    <param name="jdbc-reconnect-attempts" value="5"/>
    <param name="jdbc-reconnect-sleep" value="250"/>
  </data-source>
</data-sources>

Next, a connection to an Oracle 10g database, using an enciphered connection password: 

<data-sources>
  <data-source name="Oracle_10g" type="jdbc">
    <driver value="oracle.jdbc.driver.OracleDriver"/>
    <uri value="jdbc:oracle:thin:@orasrv.example.com:1521:sb_test"/>
    <param name="user" value="orauser"/>
    <param name="password" enciphered="true"
      value="M5DSWylszg5aA9AK29MOiaDLq7SMqmTor+nW3qURTrT9E9eqJfTPyyUudCK34nhXHE53PXK6pregp4MW8qrueg=="/>
    <param name="jdbc-fetch-size" value="10000"/>
    <param name="jdbc-batch-size" value="20"/>
    <param name="jdbc-max-column-size" value="32768"/>
    </data-source>
</data-sources>

Finally, a JDBC connection to a Vertica database. (StreamBase also supports high-performance loading of a Vertica database using non-JDBC native API connectivity.) 

<data-sources>
  <data-source name="Vertica" type="jdbc">
    <driver value="com.vertica.Driver"/>
    <uri value="jdbc:vertica://MyHost:5433/chron_vertica"/>
    <param name="user" value="vertigo"/>
    <param name="jdbc-share-connection" value="true"/>
    <param name="jdbc-quote-strings" value="true"/>
  </data-source>
</data-sources>

Back to top ^

<data-source>

This element identifies a database server to be used as a data source and accessed from an EventFlow or StreamSQL application. This element specifies the JDBC driver, the JDBC connection string that identifies the server's location, and one or more JDBC connection parameters.

Note

For a JDBC data source, you must also edit the <java-vm> element. Add the <jar> or <library> elements that specify the location of the JAR file that implements the database vendor's JDBC driver. If your JDBC driver requires supplemental files such as configuration files, specify their location in a <library> element.

Attributes

Attribute Required Description
name Yes A unique identifier for the database server. The name you assign to your data source must follow the StreamBase identifier naming rules, as described in Identifier Naming Rules.
type Yes Must be jdbc.

<data-source> has the following child elements:

  • One of: <driver>

  • One of: <uri>

  • Zero or more of: <param> with jdbc-retry-sqlstate, jdbc-reconnect-regexp, and jdbc-dont-reconnect-regexp attributes.

  • Zero or one of <param> with any of the other name-value attribute pairs.

<data-source> Examples

The following shows examples of the <data-source>, <driver>, and <uri> elements for several supported databases, showing examples of the JDBC connection string format for each database vendor. See Supported Configurations for the currently supported databases.

You must obtain the JDBC driver JAR file from your database vendor's web site, or packaged as part of your database distribution. Remember that, in addition to these lines, you must configure a <jar> child element of the <java-vm> element, with a path pointing to the JDBC driver JAR file.

Microsoft SQL Server
<data-source name="MSSQL64" type="jdbc">
  <driver value="com.microsoft.sqlserver.jdbc.SQLServerDriver"/>
  <uri value="jdbc:sqlserver://mssql64.example.com;databasename=mssql_test;user=sa;password=sa"/>
</data-source>
MySQL
<data-source name="MYSQL" type="jdbc">
  <driver value="com.mysql.jdbc.Driver"/>
  <uri value="jdbc:mysql://mysqlsvr.example.com:3306/mysql_test?user=username&amp;password=secret"/>
</data-source>
Oracle
<data-source name="Oracle_10g" type="jdbc">
  <driver value="oracle.jdbc.driver.OracleDriver"/>
  <uri value="jdbc:oracle:thin:@oraserver.example.com:1521:ora_test"/>
</data-source>
Sybase
<data-source name="SybaseASE" type="jdbc">
  <driver value="com.sybase.jdbc3.jdbc.SybDriver"/>
  <uri value="jdbc:sybase:Tds:sybserver.example.com:5001/syb_test"/>
</data-source>
Vertica
<data-source name="vertica" type="jdbc">
  <driver value="com.vertica.Driver"/>
  <uri value="jdbc:vertica://vertserver.example.com:5433/vertica_test"/>
</data-source>
Thomson Reuters Velocity Analytics
<data-source name="myDB" type="jdbc">
  <driver value="org.firebirdsql.jdbc.FBDriver"/>
  <uri value="jdbc:firebirdsql://velocity.example:3050/TRTCE"/>
</data-source>

Back to top ^

<driver>

Identifies the database driver's Java class.

Attributes

Attribute Required Description
value Yes The fully qualified Java class that implements the database vendor's JDBC driver.

See examples of the driver element in <data-source> Examples below.

Back to top ^

<uri>

Use the <uri> element to specify the JDBC connection string appropriate for your database and server location. Each supported database has its own syntax for JDBC connection strings. You must obtain the correct connection string syntax from your database vendor, possibly from a README file distributed with the JAR file that implements the vendor's JDBC support. Use the examples in <data-sources> Examples as general guidelines for constructing your site's JDBC connection string.

Attributes

Attribute Required Description
value Yes

The JDBC connection string appropriate for your database vendor and server location. The correct string to use will be both vendor-specific and site-specific.

The format of JDBC connection strings are vendor-specific, but generally follow a format like the following:

jdbc:vendorname://server-address:port

The connection string for some vendors appends username and password fields, while other vendors require a protocol name in the string.

If the <uri> value contains ampersands, replace them with &amp;. Failing to do so results in an error at connection time stating Unterminated entity reference.

Use the example JDBC connection strings in the next section as guidelines.
enciphered no Set to "true" to specify that the contents of the value attribute were enciphered with the sbcipher command. This allows you to specify a JDBC connection string that contains private values such as passwords and server connection information, but not have the values appear as clear text in the configuration file. For further information, see Enciphering Passwords and Parameter Values.

Back to top ^

<param>

The <param> child element of the <data-source> element has the attributes shown in the following table. See <data-sources> Examples for examples of the <param> element used in the context of several <data-source> elements. These elements only affect Query operator access to a JDBC database through the JDBC Table data construct. They do not affect feed simulations that take input data from JDBC data sources.

Attributes

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

Note

Pay close attention to the parameter options for your data source. In particular, notice that the StreamBase default for the jdbc-reconnect-attempts option is zero, which means failed database connections are not automatically reconnected by default. Be sure to specify a non-zero value for this option if you want to use automatic reconnection.

The following table lists the possible values for the name attribute, with the corresponding values for each:

name attribute settings corresponding value attribute setting
user Username with which to log in to the database server.
password Password with which to log in to the database server. You can encipher the password and store the enciphered string instead of a plain text password. See Enciphering Passwords and Parameter Values.
jdbc-fetch-size This parameter can be used to control the size of the buffer used by the JDBC driver when fetching rows. Consider limiting the fetch size when your StreamBase application experiences memory problems related to large result sets returned from queries to the JDBC data source. Consider increasing fetch size if deadlocks occur because you are performing multiple queries against the same JDBC data source and query result sets are larger than the current database fetch size.

Possible values:

  • 0: Uses the JDBC driver's default value (default).

  • -2147483648 (For MySQL databases only): Normally, MySQL retrieves complete result sets and stores in them in memory. Setting the Integer.MIN_VALUE in this parameter serves as a signal to the MySQL driver to stream result sets row-by-row instead. Caution For other databases, a negative value causes a SQLException.

  • positive integer (for databases other than MySQL): A positive integer serves as a hint to non-MySQL JDBC drivers for the size to allocate for result set buffers. The actual size allocated depends on how a given driver interprets it, which may vary among drivers. A positive integer is ignored by MySQL drivers.

jdbc-timeout The timeout in milliseconds of background JDBC operations in StreamBase Studio and at runtime. This parameter can affect typechecking efficiency.

StreamBase Studio communicates with the data source server in order to typecheck an application that has a JDBC data source connection. If the database server does not respond during this interval, the typecheck fails. The default value of 15000 (15 seconds) is adequate for normal local area network connections. Consider increasing this value if you experience typecheck failures due to a slow network connection. For example, the following example increases the interval to 25 seconds: 

<param name="jdbc-timeout" value="25000"/>
jdbc-query-timeout Specifies an integer number of milliseconds that StreamBase is to wait for JDBC Query operations to execute. The default is 0, which causes the server to wait forever for each query to return. Specify a value such as 15000 (15 seconds) to prevent StreamBase Server from hanging in rare cases where the JDBC server never responds to a query. This setting specifies the default timeout value for all queries to this data source.

You can also specify a timeout value separately for each JDBC Query operator, using the Timeout field on the Query Settings tab of the Properties view.

jdbc-connection-timeout A JDBC connection from a JDBC Query operator to the specified database occurs every time the Query operator is invoked, which executes its SQL command. If this jdbc-connection-timeout parameter is not set (the default), each JDBC connection stays open and does not time out. Use this parameter to specify an integer number of milliseconds that each database connection stays open before timing out.

What happens when the timeout period is reached depends on the setting of the jdbc-reconnect-attempts parameter below. If that parameter is set to 0 (the default), then each connection simply closes on timeout. If that parameter is set to -1, an attempt to reconnect always occurs and continues to occur until reconnected. If that parameter is set to a positive integer, it specifies a number of reconnection attempts to make before finally closing the connection.

The setting for this jdbc-connection-timeout parameter is only used during runtime. That is, even though Studio might try to connect to a configured JDBC server at typecheck time, this parameter does not affect the timeout for that connection.
jdbc-max-column-size The maximum column size expected in a JDBC table. Columns that are larger than this value (2048, by default) will cause a typecheck exception. If you override the default, remember that the resulting output tuple's schema must entirely fit into the pool-size. Therefore, consider also increasing the page pool-size, described in <page-pool>.
jdbc-retry-sqlstate Retry any select, insert, or update JDBC operation that returns the specified SQLSTATE for this database driver. The operation is retried until it succeeds.

A useful example is when you know that the database might return an exception due to transaction deadlocks in the database. When a deadlock occurs, the database returns a specific exception SQLSTATE indicating deadlock or timeout, and the expected behavior is to roll back the operation or transaction and retry.

You can use multiple parameters to test for multiple SQLSTATEs.
jdbc-batch-size Allows a Query operator to perform an insert or update operation in batch mode, and sets the number of statements that will be executed at one time. For example, if jdbc-batch-size is set to 10, then when the first nine tuples arrive at the Query operator, they are held by the JDBC connection instead of being executed immediately. When the tenth tuple arrives and is added to the batch of statements, the entire batch is executed at once.

If an update is interrupted normally (for example, by stopping the sbd server), the Query operator updates the JDBC table using all the accumulated statements, even if there are fewer than the specified number. However, if the application is stopped abnormally, the updates may not occur.

The value must be an integer greater than 1 (a value of 1 is valid, but not meaningful for a batch operation).

Note that your application may require more memory when you perform query updates in batch mode.
jdbc-batch-timeout-ms Specifies as an integer number of milliseconds, the longest time that batched tuples remain buffered and unsent. Like the jdbc-batch-size setting, this setting only affects insert or update operations. Tuples may be written sooner than this number, or more frequently, for any number of reasons. The default setting is 60000 (60 seconds).
jdbc-reconnect-regexp

If a connection is lost between StreamBase Server and the database server, the next attempted JDBC operation returns an error. There are no standard error codes (or SQLSTATE) for communications failures, so to detect these errors, we must parse the text of the database-specific error messages. Use the jdbc-reconnect-regexp parameter to specify a regular expression to be compared to any received error messages.

You can specify more than one jdbc-reconnect-regexp parameter to specify several error message strings to be considered communications failures. Each specified string is compared in order to the received error message text.

If a specified string is matched in the text of any error message, the JDBC operator assumes a communications failure has occurred, and attempts to open a new connection to the database server in order to re-execute the current command. If the error text is not matched in the error strings, and the JDBC operator has an error port, an error tuple is sent to the error port. If there is no error port, a tuple is sent on the error stream.

If you do not specify a jdbc-reconnect-regexp parameter, the pattern .* (period-asterisk) is used as the pattern string, which means any received error causes a reconnection attempt.

jdbc-dont-reconnect-regexp This parameter is similar to jdbc-reconnect-regexp, but is used to specify the database error messages for which you do NOT want to retry communicating with the database server.

You can use this parameter more than once to specify different regex patterns. Each specified string is compared in order to the received error message text.

When a JDBC error occurs, if the error message text matches a pattern specified in one of the jdbc-dont-reconnect-regexp patterns, the current JDBC command is not executed again, and an error tuple is sent to the JDBC operator's error port, if enabled, or to the error stream if not. The next time a tuple is read by the JDBC operator, a new connection is made to the database server.

If no error strings match a pattern in any jdbc-dont-reconnect-regexp parameter, then the error strings are checked against the jdbc-reconnect-regexp patterns, with a fallback to a pattern of .*, as described above.

jdbc-reconnect-attempts

The jdbc-reconnect-attempts parameter controls the number of reconnection attempts each SQL connection to the specified database is to attempt. If the connection to the database server is lost or times out, a value of 5 for this parameter attempts to reestablish a connection to the database server five times. If five connection attempts fail, an error message is printed and StreamBase Server exits with an error status. If a connection is reestablished to the database server, and then the connection is lost some time thereafter, the reconnection count is reset so that five more attempts to reconnect are made again. The retry count is reset for each SQL exception, not for the lifetime of the connection.

A jdbc-reconnect-attempts value of -1 specifies that the server is to continue reconnection attempts without limits. The default value is 0, which disables reconnection attempts. Supplying a nonzero value is therefore strongly recommended.

See also the discussion of this parameter as part of the jdbc-connection-timeout parameter description above.

jdbc-reconnect-sleep

If the jdbc-reconnect-sleep parameter is specified, reconnection attempts are delayed by the specified number of milliseconds. If no jdbc-reconnect-sleep parameter is used, there will be no delay between reconnection attempts.

Just like the initial connection to the database, by default, reconnection attempts use the jdbc-timeout parameter to limit how long StreamBase Server waits to establish a connection. The default value for jdbc-timeout is 15000 milliseconds (15 seconds).

jdbc-share-connection This parameter has no effect if your StreamBase application has only one JDBC operator. The default setting is false, which means that, in an application with two or more JDBC operators, each JDBC operator gets its own connection from StreamBase Server to the specified data source. Set this parameter to true to specify that all JDBC operators in an application are to share a single connection from StreamBase Server to the specified data source.
jdbc-quote-strings Some databases such as Vertica require the strings passed into a JDBC PreparedStatement object to be enclosed in single quotes within double quotes ("'Dallas'"). Set this parameter to true if the database vendor's documentation specifies quoting the strings passed into PreparedStatement.setString().

Back to top ^

<operator-parameters>

This element contains declarations of global parameters that you want to use in expressions in any module or container run by the current StreamBase Server instance. Parameters declared with an <operator-parameter> element are global to the StreamBase Server instance configured herein, and apply to any application or container run under that server instance. See Using Global Parameters for details. See Parameter Overview to understand the difference between this element and the <module-parameter> child element of the <application> element in StreamBase deployment files.

<operator-parameters> has the following child element:

<operator-parameter>

Use this element to declare global operator parameters and assign them a default value. Parameters are defined as name-value attribute pairs, with the name attribute being a simple name such as ParamOne.

Assign a value to ParamOne for two purposes:

  1. To expose a parameter available to StreamBase modules using the ${param} syntax. (The same syntax also resolves to module parameters defined directly in application modules, if present.)

  2. To set the specified value as the parameter value for any Java operator or adapter with a parameter of the specified name.

    In this usage, the parameter's name can also be a dotted path name such as ContainerName.OperatorName.ParamOne to set a particular adapter or operator's parameter, without affecting other operators in the system.

    If the operator is in a submodule, you must include the submodule in the dotted path name; for example, ContainerName.SubModuleName.OperatorName.Param. When a path is used, the parameter value is only set for that named operator. All other parameters with the same name on other operators remain unmodified.

You can set the value of an <operator-parameter> to the value of a system environment variable whose value is resolved at StreamBase Server startup time. However, if the specified system variable is not set or not present, StreamBase Server can fail to start. In this case, you can use the colon-equals syntax described in Environment Variables and the Colon-Equals Syntax.

Specify the following name-value attribute pair:

Attribute Required Description
name yes

Parameter label that can be used in an expression. The label can be a simple parameter name or a qualified name in StreamBase path notation.

When this attribute specifies a simple parameter name such as ParamOne, all operators in the application that have a parameter named ParamOne are set with the specified value.

You can narrow the setting to apply only to a particular operator by specifying the StreamBase path to the operator in the form ContainerName.OperatorName.ParamName. If the operator is in a submodule, you must include the module's name in the path: ContainerName.ModuleName.OperatorName.ParamName. This sets the value of ParamName only for the specified operator. All other operators with a parameter named ParamName remain unset.

enciphered no Set to true to specify that the contents of the value attribute were enciphered with the sbcipher command. This allows you to specify global parameters with private values, including passwords and server connection information, but 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.

Examples:

<operator-parameters>
  <operator-parameter name="MyStringParam" value="somestring"/>
  <operator-parameter name="MyIntParam" value="2"/>
  <operator-parameter name="ContainerName.OperatorName.ParamName"
    value="120" />
</operator-parameters>

Applying this example, the following expressions could be used:

SELECT * FROM SourceTagger_1
    "${MyStringParam}" AS source
    ...
    WHERE myint > ${MyIntParam}

Note

If an <operator-parameter> name conflicts with a declared module parameter name, the module parameter value takes precedence. 

<operator-parameter name="Host" value="${STREAMBASE_SERVER}"/>

Or use the colon-equals syntax to specify a default value for the environment variable: 

<operator-parameter name="Host" value="${STREAMBASE_SERVER:=sb://sbhost:9900}"/>

Back to top ^

<error-handler>

The default handling for runtime errors is to discard the error-producing event and continue processing. You can specify different processing for certain error types. <error-handler> has the following child elements:

error-handler Example 

<error-handler>
    <error type="eval-error" action="shutdown" />
    <error type="eval-plugin-error" action="shutdown" />
</error-handler>

<error>

Defines a single error type for the error handler. Use multiple error elements to define multiple error types, as shown in the <error-handler> example.

Attributes

Attribute Required Description
type Yes

  • eval-error

    This exception is caused by a variety of reasons, including errors that occur when evaluating expressions or when flushing disk-based query table logs, and incorrect timestamp formats. Continuing after such errors is not recommended.

  • eval-plugin-error

    Java and C++ plug-ins can get eval-plugin-error exceptions for a variety of reasons, including TupleExceptions, errors, and when setting parameters. Continuing after such errors is not recommended.

  • ordering-error

    The Gather operator throws this error when an order by field value is null. The Aggregate operator throws it when an order by field value is null or the current value is less then a previous value.

action Yes

  • shutdown: Stop the server

  • continue: Continue and display error

  • ignore: Continue and display no error

Back to top ^

<jms-connections-defaults>

The <jms-connections-defaults> element is used ONLY to specify JMS connection parameters for container connections over JMS. This element is described in Specifying JMS Container Connection Defaults.

Settings made with this element do NOT manage or control the operation of the embedded StreamBase JMS adapters. Those adapters have their own independent configuration file formats described in Legacy JMS Input and Output Adapters.

Back to top ^

<time-service-configurations>

The <time-service-configurations> element is used to allow StreamBase JUnit tests to control time during test runs by means of the com.streambase.sb.TimeService interface in the Java Client API. This element has two child elements:

  • One of <type>.

  • Zero or one of <target-time>

<type>

The <type> element accepts one of two values:

  • Specify <type>CONTROLLABLE</type> to allow the TimeService API to manage time values during StreamBase JUnit tests. With this value set, StreamBase JUnit test code can take advantage of methods provided by the TimeService interface, including advanceBy(), advanceTo(), getFutureTimestamp(), and getTargetTme().

  • Specify <type>WALLCLOCK</type>, the default value, to run StreamBase JUnit tests based on the host's system time.

<target-time>

Use the <target-time> element to specify a timestamp to be used as the starting point reference time of a test to be run as a StreamBase JUnit test. Timestamp values set in this element are ignored if the <type> element specifies WALLCLOCK, or is absent. That is, <target-time> is only recognized when accompanied by <type>CONTROLLABLE</type>.

Specify the timestamp value with format string patterns as used in the format_time() expression language function (which is itself based on the java.lang.SimpleDateFormat class). The <target-time> element is optional; if unspecified when CONTROLLABLE type is specified, the reference start time of the JUnit test is the actual start time of the module.

Back to top ^