StreamBase Documentation

StreamBase Server Configuration XML

Current Location: Home > StreamBase Reference Guide > XML Reference > StreamBase Server Configuration XML

This topic provides reference information about the StreamBase Server configuration (sbd.sbconf) XML elements. To view its default (or "skeleton") configuration, enter this command at a terminal window:

sbd -s

To write the default configuration to a file, which you could then customize, enter a command such as the following:

sbd -s > /home/myaccount/myapps/mysbd.sbconf

streambase-configuration is the root element that contains all XML code describing a StreamBase Server configuration. It has one or more of the following child elements:

Zero or one of: global
Zero or one of: server
Zero or one of: page-pool
Zero or one of: runtime
Zero or one of: custom-functions
Zero or one of: sbmonitor
Zero or one of: authentication
Zero or one of: high-availability
Zero or one of: java-vm
Zero or one of: data-sources
Zero or one of: operator-parameters
Zero or one of: error-handler

`global`

Identifies the locations of any custom function plugins or modules that should be loaded when the StreamBase Server runs your application.

Note: It is usually not necessary to declare these elements during development in StreamBase Studio, because you must import plugins and modules into your project before running the application in StreamBase Studio).

However, when you deploy an application, plugins and modules may be stored in a shared libraries separate from the application. At that time, you will need to specify the locations of these resources.

global has the following child elements:

One or more of: plugin
Zero or one of:module-search

Example

<global>
    <plugin directory="/usr/share/sbplugins"/> 
    <module-search directory="/usr/share/sbapps"/>
</global>

`plugin`

Identifies a custom function plugin (simple and/or aggregate) to be loaded when the application runs. You can have as many plugin elements as you need, each identifying a different library.

Note that for C++ custom functions, each function name must also be declared in a custom-functions.

Attributes

Attribute	Required	Description
directory	Either this attribute or filename	A directory containing one or more custom function plugins (simple and/or aggregate) to be loaded. The StreamBase Server scans each specified directory and loads all the files it finds there.
filename	Either this attribute or directory	A list of one or more paths to individual plugin files for custom functions (simple and/or aggregate) that you want to load when your application runs. Unlike the `plugin directory` option, this option causes only the specified files to be loaded. You can omit the file extension: StreamBase will load the platform-appropriate .so file on UNIX, or .dll file on Windows.

Note

When running StreamBase in daemon mode (with the -b flag), make sure you use fully qualified paths.

`module-search`

Identifies the location application modules (.sbapp or .ssql files) to be used at run time. Application modules can be referenced in other applications, either by a module reference (in an .sbapp application) or by an APPLY statement (in an .ssql application). When sbd runs the application, the application's current directory is first scanned for each referenced module (.sbapp or .ssql file); if not found there, it scans the directory designated by this element.

For more information, see Deploying Application Modules in the Authoring Guide.

Attributes

Attribute Required Description

Attribute	Required	Description
directory	Yes	Directory where application modules (`.sbapp` or `.ssql` files) are stored at run time. The directory must be local (or shared) to the runtime system, and StreamBase recommends using only full pathnames. In a clustered environment, the directory must exist on the StreamBase Cluster Manager node, `sbclusterd`. The following UNIX example assumes that you have given a value to the `STREAMBASE_HOME` environment variable: <global> <module-search directory="${STREAMBASE_HOME}/modules"/> </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). server 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	Directory to be used for persistent data from any Query Tables in your StreamBase application. Note that the datadir value could come from other sources. The precedence order is: If present on the sbd command line `--datadir` value. The `STREAMBASE_DATA` environment variable's value. The value in this server section of the sbd configuration file. Finally, if not specified, or the special value `"+TEMP+"` is used, a temporary directory is created on server startup and deleted on shutdown. The default temporary locations are shown below: On UNIX: `/tmp/sbdata-six-random- characters/querytable/ table-name` On Windows: `C:\Documents and Settings\username\Local Settings \Temp\sbdata-six-random- characters\querytable\ table-name`
disk-querytable-cache	Amount of main memory that will be allocated to 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 during the execution of the StreamBase application or other applications. As with any resource setting, you should establish baseline performance metrics and then test the effect 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 has nothing to do with 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 and means use the OS-dependent default value.
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 will transactionally commit every single table update to persistent store. Mode 0 disables transactional support. Please see the next parameter for a related setting.
disk-querytable-logsize	If you are using disk-based Query Tables in 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 10MB.
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 fame. Setting the disk-querytable-flush-interval-ms parameter will force disk commits at the interval specified in milliseconds. Also a flush interval is needed in 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.
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).

Example

<server>
    <param name="tcp-port" value="101000"/>
    <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>

`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	The size in bytes per page. The StreamBase Server (sbd) defaults to the proper minimum value for the machine's architecture. If you change the page-size value, it must be a multiple of the system page size: 4096 bytes for x86, or 8192 bytes for SPARC. The StreamBase page size determines the maximum size of a tuple, so you will need to increase this value if you have large tuples. A related parameter is: `param name="schema-max-size" .../` in the `runtime` In environments where High Availability (HA) is enabled, the page-size value is part of a calculation to determine the total memory allocation for the StreamBase HA application: page-size * pages-per-chunk * max-chunks In non-HA environments, the initial memory allocation is determined by the JVM heap size for the hosted StreamBase application. If needed for StreamBase applications with large memory demands, you can set a higher initial allocation of heap by specifying `-Xms` and `-Xmx` JVM arguments, as described later in this configuration topic.
max-pooled-pages	Sets the maximum number of pages that will be retained in the application-wide dequeuing client buffer pool. When sbd starts, this pool is empty. As client activity begins, it is dynamically sized to accommodate the sum of max-client-pages from all clients. If client demand subsequently recedes, a certain number of pages is retained in the pool. The default is 1024 pages.
max-client-pages	Sets the maximum number of pages that a dequeue client connection can allocate. The sbd process will disconnect clients that try to allocate more. This parameter is designed to protect sbd from a slow or hung dequeue client. Therefore to understand the resulting number of bytes allowed, multiply the `max-client-pages` value by the `page-size` value. A `max-client-pages` value of 2048 pages results in about 8 megabytes. If you want to enable a dequeue client connection that would allocate unlimited memory use, change the `max-client-pages` value to "0".
pages-per-chunk	Sets the number of pages to allocate at a time in the page pool. Defaults to 1024, or 4MB at a time (with 4K page size).
max-chunks	Sets the maximum number of chunks to allocate. Defaults to 128 chunks, or 512MB total (4MB * 128).

Example

In the following configuration example, the administrator decided to increase the page-size and the Java Heap for the StreamBase Server that will host the application:

<page-pool>
    <param name="page-size" value="8192"/>    
</page-pool>

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

`runtime`

Use this element to specify one or more containers (one per application) that will be hosted by the StreamBase Server process, and other aspects of the server's runtime behavior. This includes selecting the now() function's implementation. You can have one or more application elements in the runtime section. The runtime section has the following child elements:

One or more of: application
One or more of: param with any of these name-value attribute pairs:

name Attribute	value Attribute
application	New as of StreamBase 3.7. Lets you optionally specify which application to load into a container on startup, with optional container connections.
application-file	Deprecated as of StreamBase 3.7. Use the `application` element instead.
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 machine(s) 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.
cpp-string-field-size	A default number of characters for strings that are returned between the runtime and C++ custom functions. Default: `32768`. If the C++ custom function developer used the setReturntype method to set the string size, the default size is set at runtime by this parameter. If the custom function used the setReturnString method to hard-code a string size, that value is used at run time, and this attribute is ignored.
now-implementation	StreamBase 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 will use Java's `System.currentTimeMillis()`. This is the default. The `thread` value means that the `now()` function will use a background thread that checks the time approximately every millisecond. This option will result in decreased accuracy, but may be more efficient than "system" if you call `now()` more frequently than 1000 times per second.

Example

<runtime>
  <application file="myapp.ssql" container="A"/>
  <application file="app.ssql" container="B">
    <container-connection dest="B.InputStream1" source="A.OutputStream1"/>
    <container-connection dest="B.InputStream2" source="A.InputStream2"/>
  </application>
  <param name="application" file="buyorsell.sbapp" container="BuySell"/>
  <param name="cpp-string-field-size" value="65536"/>
  <param name="now-implementation" value="system"/>  
</runtime>

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

`application`

Use this element to specify the .sbapp or .ssql application to load into a named container.

Attributes

Attribute	Required	Description
file	Yes	An .sbapp or .ssql file.
container	Yes	The name you assign to the container.

application has the following child elements:

One or more of: container-connection

Example

<application file="myapp.ssql" container="A"/>
<application file="app.ssql" container="B">
  <container-connection dest="B.InputStream1" source="A.OutputStream1"/>
  <container-connection dest="B.InputStream2" source="A.InputStream2"/>
</application>

`container-connection`

Use this element to identify a container for this server. In the case of multiple containers, the dest and source attributes can define connections between the containers.

Attributes

Attribute	Required	Description
dest	Yes	The entity (such as an Input Stream) in one named container that will consume the output of the connected source container.
source	Yes	The entity in one named container (such as an Output Stream) that will send the data to the destination container.

Example

See the application example.

`custom-functions`

Element for all the declarations for a custom function. Has the following child elements:

One or more of: custom-function

Example

In this example, a custom simple function named func1 takes a string and an int argument and returns a string of size 16:

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

`custom-function`

Each C++ simple or aggregate plugin function must be declared in a custom-function element. Each function must also be imported into a directory specified in the global plugin element.

Attributes

Attribute	Required	Description
name	Yes	Must match the name used in the application expression that calls the function.
type	Yes	Enumeration: { simple \| aggregate }

Child Elements

One of: args
Zero or more of: return

`args`

Container element for all the argument declarations for a function. Has the following child elements:

One or more of: arg

`arg`

Defines an argument used in a function.

Attributes

Name	Required	Description
type	Yes	The data type for each argument that the function expects to be passed from the StreamBase application.

`return`

Defines the data returned by a function.

Attributes

Name	Required	Description
type	Yes	The data type to be returned from the function to the StreamBase application.
size	A string requires a size attribute; other data types have implicit sizes	The size to be returned, in bytes.

`sbmonitor`

Use this element to define characteristics of the statistics that will be generated for use by the sbmonitor. sbmonitor 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 enable statistics collection, or false to disable it. If it is set to false, sbmonitor will not be usable with the daemon. The default is true.
period-ms	Specifies the period, in milliseconds, over which statistics are aggregated. The default is 1000 ms (every second).

Example

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

`authentication`

Use this element to define the authentication parameters that will be used to protect the StreamBase application from unauthorized access. Note that this element must not be present if the node is part of a cluster. For clusters, authentication parameters are specified in the cluster manager's configuration (sbclusterd.sbconf) rather than individual server configurations.

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 sbpasswd file containing user names and passwords. Required if authentication is enabled. The default is `passwd` in the `etc` subdirectory of your StreamBase installation.

Example

<authentication>
    <param name="enabled" value="true"/>
    <param name="type" value="sb-password-file"/>
    <param name="filepath" value="/opt/streambase/etc/passwd"/>
</authentication>

`high-availability`

Use this element to define the high-availability parameters for your StreamBase application. For details about using these features, see Using the High Availability Features in the Administration Guide.

high-availability has the following child elements:

One of: param containing each of these name-value attribute pairs:

name Attribute	value Attribute
primary-server	The hostname or IP address of the primary server. Its value can be any string. Examples: <param name = "primary-server" value = "mymachine.mydomain.com"/> Or: <param name = "primary-server" value = "10.0.0.10"/>
ha-primary-port	The primary server's port number that will be used to communicate with the secondary machine. This value should be a non-privileged port, greater than 1000. It must not be the same port number that sbd uses to enqueue/dequeue tuples (that is, it must not be the default of 10000, or the number set by the optional `-p` parameter of the sbd command.
secondary-server	Set the value to the hostname or IP address of the secondary server. Its value can be any string. Examples: <param name = "secondary-server" value = "myothermachine.mydomain.com"/> Or: <param name = "primary-server" value = "10.0.0.11"/>
ha-secondary-port	The secondary server's port number that will be used to communicate with the primary machine. During a failover operation, the secondary server becomes the primary server and listens for secondary servers on this port. It must not be the same port number that sbd uses to enqueue/dequeue tuples (that is, it must not be the default of 10000, or the number set by the optional `-p` parameter of the sbd command.
checkpoint-interval	The interval at which checkpoints are sent from the primary server to the secondary server. Set the value in milliseconds. When the secondary server connects to the primary server a checkpoint is immediately sent. Then from that point, every interval-in-milliseconds, a checkpoint is sent from the primary server to the secondary server.
heartbeat-interval	The interval at which heartbeat messages are sent from the primary server to the secondary server. Set the value in milliseconds. In general, the heartbeat-interval should be less than the checkpoint-interval. And the heartbeat-interval should be greater than the heartbeat-timeout value.
heartbeat-timeout	The timeout in milliseconds when an automatic failover should occur. Often the connection between the primary and secondary server may be dropped if the primary server fails. In this case, the secondary server will immediately determine that the primary server has failed. In other circumstances, the connection between the primary and secondary servers will remain, but the primary server will be unresponsive. In this case, the heartbeat-timeout parameter determines when automatic failover occurs. If the secondary sever does not receive any messages from the primary server in heartbeat-interval + heartbeat-timeout milliseconds, an automatic failover will occur.
checkpoint-directory	The directory path that will be used for temporarily saving checkpoint information. It should be a legal directory path for the local filesystem. Both primary and secondary servers use this directory, so if both servers are running on the same filesystem, you should specify a different checkpoint directory in each server's .sbconf configuration file. You may use an absolute path or a relative path (relative to the current working directory when sbd is started). If the checkpoint directory already exists, a warning message will be displayed and the server will delete the directory and its contents. Otherwise, the server will create the directory. In the .sbconf for use with the primary StreamBase Server, the checkpoint-dir value while you are in development mode might be: <param name = "checkpoint-dir" value = "/home/myaccount/ha/primary-checkpoint"/> <param name = "ha-mode" value = "primary"/> Also in development mode, in the .sbconf for use with the secondary StreamBase Server, you might specify: <param name = "checkpoint-dir" value = "/home/myaccount/ha/ secondary-checkpoint"/> <param name = "ha-mode" value="secondary"/> When you deploy the StreamBase application to your staging or production machines, you would change the checkpoint-dir value to the directories where you and your IT team agree to place this type of critical failover data.
ha-mode	The high-availability mode of the StreamBase Server. Enumerated values: { off \| primary \| secondary } The value `"off"` indicates that the server is running in standalone mode; this is the value supplied by default in the .sbconf skeleton file. Set the value to `primary` or `secondary` in a high-availability environment. Remember to set this value appropriately as you define the separate .sbconf configuration files for use on the primary and secondary machines.
read-timeout	How long the primary and secondary should wait for the response to a read operation. The value is in milliseconds, and the default is 5000. Used to modify the behavior of the primary and secondary server communication. This parameter does not effect client/server communication.
write-timeout	How long the primary and secondary should wait for the response to a write operation. The value is in milliseconds, and the default is 5000. Used to modify the behavior of the primary and secondary server communication. This parameter does not effect client/server communication.
write-retry	How many times the primary and secondary should retry a write operation. This is a count (not milliseconds), and the default is 3 retries. Used to modify the behavior of the primary and secondary server communication. This parameter does not effect client/server communication.
wait-for-checkpoint- ack-timeout"	How long the primary should wait for the secondary to consume the checkpoint. The value is in milliseconds, and the default is 10000. Used to modify the behavior of the primary and secondary server communication. This parameter does not effect client/server communication.
primary-wait	How long the secondary should wait to retry a connect operation to the primary. The value is in milliseconds, and the default is 5000. Used to modify the behavior of the primary and secondary server communication. This parameter does not effect client/server communication.

Example

<high-availability>
 
    <param name="primary-server" value="10.0.0.10"/>
    <param name="ha-primary-port" value="port-number-for-comm-with-secondary"/>
 
    <param name="secondary-server" value="10.0.0.11"/>
    <param name="ha-secondary-port" value="10001"/>

    <param name="checkpoint-interval" value="10000"/> 
    <param name="heartbeat-interval" value="8000"/> 
    <param name="heartbeat-timeout" value="6000"/>

    <param name="checkpoint-dir" value="/home/user/ha/primary-checkpoint"/>
    <param name="ha-mode" value="primary"/>

    <param name="read-timeout" value="10000"/>
    <param name="write-timeout" value="10000"/>
    <param name="write-retry" value="6"/>
    <param name="wait-for-checkpoint-ack-timeout" value="20000"/>
    <param name="primary-wait" value="10000"/>        
 
</high-availability>

`java-vm`

Use this element to set initial min and max values for the JVM memory allocation pool. It's important that you examine, test, and modify these values (as needed) for all StreamBase applications. See the table below for caveats.

In addition, the java-vm element is required when:

When your application uses Java operators.
To load any jars and shared libraries needed by database drivers declared in the data-source element. Use the jar and library child elements for this purpose.

For Java operators you must specify, at a minimum, the jar file that contains the Java operator classes. For details about this feature, see Using the Java Operator API in the API Guide.

Note: If you use this section to override the JDK version, remember that you must be using at least the Sun JDK version 1.4.2_07 or later for the 1.4.2_xx versions, or 1.5.0_06 or later for the 1.5.0_xx versions. For the latest information, see the Supported Configurations topic in the Installation Guide. java-vm has the following child elements:

Optionally one or more of: jar
Optionally one or more of: dir
Zero or one of: library
Zero or one of: param for each of these name-value attribute pairs:

name Attribute value Attribute

java-home

name Attribute	value Attribute
java-home	The path to the installed location of the full JDK on your machine. For example: <param name="java-home" value="/usr/java/j2sdk1.5.0_06" /> Or: <param name="java-home" value="C:\Program Files\Java\jdk1.5.0_06" /> Note: Refer to the Supported Configurations topic in the Installation Guide for details about the required minimum JDK versions.
jvm-args	Arguments to send to the JVM. You can set the initial min and max values for the memory allocation pool, Java properties, or other JVM options. Do not set the classpath here. Also do not specify `'-server'` or `'-client'` because the server JVM is always loaded. Important Although this setting is not required, it is is strongly recommended that you check the heap size arguments As you probably read elsewhere in the documentation, you must have the full Sun JDK installed to run a StreamBase application. This requirement exists on development, staging, and production environments. At runtime, your application is compiled into one or more Java classes. To ensure that your application performs well, it's critical that you use this java-vm section to set the Java Virtual Machine's `-Xms` (min) and `-Xmx` (max) heap-size arguments The default maximum for the JVM is 256 MB. For example: <param name="jvm-args" value="-Xms64m -Xmx256m"/> At runtime, this default may be insufficient for your StreamBase application. We recommend that you experiment with the JVM arguments for memory use and, as needed, increase the values. For example: <java-vm> <param name="java-home" value="C:\Program Files\Java\jdk1.5.0_06" /> <param name="jvm-args" value="-Xms512m -Xmx1024m" /> </java-vm> Additional Caveats If you need to view information about the Java Just-In-Time (JIT) compiler (HotSpot), try adding this JVM argument in the configuration file: -XX:+PrintCompilation If the JVM is using an excessive amount of memory, or spending too much time performing garbage collection, try adding this argument to get more specific information: -verbose:gc With this argument, the JVM will periodically generate output telling you how large the Java heap size is and how much time is being spent in garbage collection. If you notice that a large amount of time is being spent in garbage collection (especially "Full GC" phases), please contact your StreamBase representative. If the generated code for StreamBase operator execution is not optimal, try adding `-Xprof` to the set of JVM arguments. Run your application again, and then send the generated information to your StreamBase representative. You may find more information about JVM arguments by going to the Sun JDK Tools and Utilities Web page, and navigating to the Java application launcher topic for your platform.

The path to the installed location of the full JDK on your machine. For example:

<param name="java-home" 
    value="/usr/java/j2sdk1.5.0_06" />

Or:

<param name="java-home" 
    value="C:\Program Files\Java\jdk1.5.0_06" />

Note: Refer to the Supported Configurations topic in the Installation Guide for details about the required minimum JDK versions.

jvm-args

Arguments to send to the JVM. You can set the initial min and max values for the memory allocation pool, Java properties, or other JVM options.

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

Important

Although this setting is not required, it is is strongly recommended that you check the heap size arguments
As you probably read elsewhere in the documentation, you must have the full Sun JDK installed to run a StreamBase application. This requirement exists on development, staging, and production environments. At runtime, your application is compiled into one or more Java classes. To ensure that your application performs well, it's critical that you use this java-vm section to set the Java Virtual Machine's -Xms (min) and -Xmx (max) heap-size arguments

The default maximum for the JVM is 256 MB. For example:

<param name="jvm-args" 
    value="-Xms64m -Xmx256m"/>

At runtime, this default may be insufficient for your StreamBase application. We recommend that you experiment with the JVM arguments for memory use and, as needed, increase the values. For example:

<java-vm>
    <param name="java-home" 
    value="C:\Program Files\Java\jdk1.5.0_06" />
    <param name="jvm-args" 
    value="-Xms512m -Xmx1024m" />
</java-vm>

Additional Caveats

If you need to view information about the Java Just-In-Time (JIT) compiler (HotSpot), try adding this JVM argument in the configuration file:
```
-XX:+PrintCompilation
```
If the JVM is using an excessive amount of memory, or spending too much time performing garbage collection, try adding this argument to get more specific information:
```
-verbose:gc
```
With this argument, the JVM will periodically generate output telling you how large the Java heap size is and how much time is being spent in garbage collection. If you notice that a large amount of time is being spent in garbage collection (especially "Full GC" phases), please contact your StreamBase representative.
If the generated code for StreamBase operator execution is not optimal, try adding -Xprof to the set of JVM arguments. Run your application again, and then send the generated information to your StreamBase representative.

You may find more information about JVM arguments by going to the Sun JDK Tools and Utilities Web page, and navigating to the Java application launcher topic for your platform.

How sbd searches for JVM

In using the java-vm element, it helps to understand how the StreamBase Server instance (sbd) that hosts and processes your application attempts to find a JDK. If any of the following ordered tests succeeds, no further tests are performed:

Uses the java-home attribute in the sbd.sbconf configuration file, if it is defined (it is undefined at install time).
Uses the internal JDK if present and if the STREAMBASE_USE_INTERNAL_JDK environment variable has not been set to FALSE (it is TRUE by default).
Uses the JAVA_HOME environment variable, if defined on your system.
Searches through your PATH environment variable to find a suitable JDK.
Attempts to find a JDK on your system.
If all of the preceding steps fail, sbd will not start.

Example

    <java-vm>
      <param name="java-home" value="/usr/java/j2sdk1.5.0_06" />
      <param name="jvm-args" value="-Xms512m -Xmx1024m"/>
      <jar file="olive.jar"/>
      <jar file="othercalcs.jar"/>
      <dir path="/opt/apache/classes""/>
      <dir path="/usr/share/maths/classes""/>
      <library file="native-lib"/>
    </java-vm>

`jar`

Specifies a the jar to be loaded at run time, used by a Java Operator or by a JDBC datasource 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.

Attributes

Attribute	Required	Description
file	Yes	Path to the jar file.

`dir`

Use the dir element to add a directory to the classpath. You can use multiple dir elements, as shown in the java-vm example.

Attributes

Attribute	Required	Description
path	Yes	Directory specification to add to the classpath.

`library`

Use the dir element to load native libraries used by your Java code, or libraries used by drivers for JDBC datasources, as shown in the java-vm example.

Attributes

Attribute	Required	Description
file	Yes	Path to the library.

`data-sources`

Container element for data-source declarations, which identify all external database drivers accessed by StreamBase applications using the server. You can define as many datasources as you need, each pointing to a single server. JDBC databases are currently supported. data-sources has the following child elements:

One or more of: data-source

Example

<data-sources>
  <data-source name="myDB" type="jdbc">
    <uri value="jdbc:derby://localhost:1527/myDB;user=me;password=mine"/>
    <driver value="org.apache.derby.jdbc.ClientDriver"/>
    <param name="jdbc-timeout" value="60000"/>
    <param name="jdbc-max-column-size" value="4096"/>
    <param name="jdbc-retry-sqlstate" value="08S01"/>
    <param name="jdbc-retry-sqlstate" value="40001"/>
    <param name="user" value="administrator"/>
    <param name="password" value="jiminycricket"/>
  </data-source>
</data-sources>

`data-source`

This element identifies a server to be used with a datasource, and accessed in an EventFlow or StreamSQL application. Sets parameters for JDBC operations, and loads the drivers required by the server.

Note

For a JDBC data source, you must also edit the java-vm element, adding jar and library child elements for the jars and shared libraries needed by the database driver.

Attributes

Attribute	Required	Description
name	Yes	A unique identifier for the server.
type	Yes	value: jdbc

data-source has the following child elements:

One of: uri
One of: driver
Zero or more of: param with jdbc-retry-sqlstate attribute.
Zero or one of: param with any of the other name-value attribute pairs.

Each param within the data-source element specifies one of the following name-value attribute pairs:

name Attribute	value Attribute
jdbc-fetch-size	This param can be used to control the size of the buffer used by the JDBC driver when fetching rows. Consider limiting fetch size when your StreamBase application experiences memory problems related to large result sets that are returned from queries to the JDBC datasource. Consider increasing fetch size 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 an SQLException. positive integer (for non-MySQL databases): 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. StreamBase Studio communicates with the datasource server in order to typecheck an application that has a JDBC datasource connection. If the datasource server does not respond during this interval, the typecheck fails. The default value of 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, this setting increases the interval to 25 seconds: <param name="jdbc-timeout" value="25000"/>
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, also consider 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 may return an exception due to transaction deadlocks in the database. When a deadlock occurs the database returns a specific exception sqlstate indicating deadlock/timeout, and the expected behavior is to roll back the operation or transaction and retry. You can use multiple params to test for multiple sqlstates.
user	Username to log in to the datasource server.
password	Password to log in to the datasource server.

`uri`

Use the uri element to specify the location of the server used to access the datasource, as shown in the data-sources example.

Attributes

Attribute Required Description

value

Yes

Attribute	Required	Description
value	Yes	A URI for the server. The following example identifies a JDBC server : <uri value="jdbc:derby://localhost:1527/myDB"/> Note that if the URI value contains ampersands, replace them with `&`; otherwise you will get an error about an "Unterminated entity reference".

A URI for the server. The following example identifies a JDBC server :

  <uri value="jdbc:derby://localhost:1527/myDB"/>

Note that if the URI value contains ampersands, replace them with &; otherwise you will get an error about an "Unterminated entity reference".

`driver`

Identifies the database driver, as shown in the data-sources example.

Attributes

Attribute	Required	Description
driver	Yes	The class of the database driver.

`operator-parameters`

This element is a container for operator-parameter declarations that you want to use as expression parameters in operators. Declared parameters apply to any application that is run under the configured sbd (for example in StreamBase Studio, any application in the sbd.sbconf file's project).

operator-parameters has the following child elements:

One or more of: operator-parameter

`operator-parameter`

Use this section to declare each operator-parameter and assign its value. Specify the following name-value attribute pair:

Attributes

Attribute	Required	Description
name	yes	Parameter label that can be used in an expression.
value	yes	Value to which the parameter is resolved.

Example

<operator-parameters>
    <operator-parameter name="MyStringParam" value="somestring"/>
    <operator-parameter name="MyIntParam" value="2"/>
</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 is used.

`error-handler`

The optional error-handler element is not listed in the skeleton STREAMBASE_HOME/etc/sbd.sbconf file. However, if desired, you can add it to override the default sbd server action, which is to shut down (in most cases) when errors occur. There are some exceptions to this rule, as noted below.

In other words, the purpose of this optional section is to allow you to ignore or continue running the sbd even if errors occur.

error-handler has the following child elements:

One or more of: error

Example

<error-handler>
<error type='eval-error' action='ignore'/>
</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++ plugins 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 Note The types default to a shutdown action, except for ordering-error, which defaults to continue, as shown in the `error-handler` example.