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, listed here alphabetically:
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\\"/>
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:
-
Zero, one, or more of: <plugin>
-
Zero, one, or more of: <module-search>
-
Zero, one, or more of: <operator-resource-search>
-
Zero or one of: <ignore-unbound-captures>
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.
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>
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 ( |
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. |
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. |
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>
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). Remember that you can only use disk-based Query Tables if your license enables it.
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 |
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> <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>
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 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. |
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.
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 .
|
<runtime> <param name="schema-max-size" value="1048576"/> <param name="now-implementation" value="system"/> </runtime>
Use this element to declare the parameters for a custom function. This element has the following child elements:
-
One or more of: <custom-function>
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.
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
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:
-
A function alias
-
calljava() for simple functions
-
calljava() for aggregate functions
-
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 notype
attribute), you must specify thename
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>
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 | 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 For C++ functions, use an |
isVarargs | Not used. | No |
For Java functions only, you can set the |
The <custom-function>
element has the following child elements:
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:
-
One or more of: <arg>
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 |
The <return>
element has the following child elements:
-
Zero or more of: <schema>
-
Zero or more of: <element-type>
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 |
The <arg>
element has the following child elements:
-
Zero or more of: <schema>
-
Zero or more of: <element-type>
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:
-
One or more of: <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 |
The <field>
element has the following child elements:
-
Zero or more of: <schema>
-
Zero or more of: <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 |
The <element-type>
element has the following child elements:
-
Zero or more of: <schema>
-
Zero or more of: <element-type> (in the case of a list of lists)
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>
.
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=""e;deploy.csv"e;"/> <constant-overwrite name="timeoutMs" value="250"/> </constants-overwrite> .... </streambase-configuration>
The "e;
sequences are required around string values for proper interpretation.
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.
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 SBPropertyDescriptor
s 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.
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> <param name="enabled" value="true"/> <param name="period-ms" value="2000"/> </sbmonitor>
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> <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>
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.
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.
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.
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:
-
One of: <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 pairsname 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 pairsname 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.
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:
|
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>
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.
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>
<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>
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 isha-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 whenenabled=custom
to specify the name of the HA container, and optionally used withenabled=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> <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>
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.
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>
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 If used, set the value of <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 |
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 Use the guidance in Java VM Memory Settings for assistance when setting the 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 |
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.
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>
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 |
Examples:
<java-vm> <dir path="./java-bin" /> <dir path="/usr/share/maths/classes" /> </java-vm>
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 |
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>
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 |
value | Yes |
The value to set for the named property, such as |
Examples:
<java-vm> <sysproperty name="streambase.tuple-charset" value="UTF-8" /> <sysproperty name="codegen.intermediate-stream-dequeue" value="true" /> </java-vm>
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:
-
One or more of: <data-source>
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&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>
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:
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&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>
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.
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: The connection string for some vendors appends username and password fields, while other vendors require a protocol name in the string. If the 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.
|
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:
|
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-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 You can specify more than one 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-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 If no error strings match a pattern in any |
jdbc-reconnect-attempts |
The A See also the discussion of this parameter as part of the |
jdbc-reconnect-sleep |
If the Just like the initial connection to the database, by default, reconnection attempts use the |
jdbc-share-connection |
This parameter has no effect if your StreamBase application has only one JDBC operator. The default setting is For Live Datamart applications, if this parameter is set to |
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() .
|
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:
-
One or more of: <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:
-
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.) -
To set the specified
value
as the parameter value for any Java operator or adapter with a parameter of the specifiedname
.In this usage, the parameter's
name
can also be a dotted path name such asContainerName.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 You can narrow the setting to apply only to a particular operator by specifying the StreamBase path to the operator in the
form |
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}"/>
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:
-
One or more of: <error>
<error-handler> <error type="eval-error" action="shutdown" /> <error type="eval-plugin-error" action="shutdown" /> </error-handler>
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 |
|
action | Yes |
|
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.
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>
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, includingadvanceBy()
,advanceTo()
,getFutureTimestamp()
, andgetTargetTme()
. -
Specify
<type>WALLCLOCK</type>
, the default value, to run StreamBase JUnit tests based on the host's system 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.
The <sb-include>
element allows you to include fragment configuration files into a top-level file. See Using Modular Configuration Files for instructions on using this element and a comparison with standard XML Xinclude.
You may see the <security-tagging>
element in the Ctrl+Space content assistance menu in the StreamBase Server Configuration File Editor. This element refers to a deprecated and removed
feature of server configuration, but is still supported in the Editor for compatibility with legacy StreamBase projects migrated
to current releases.