Server Configuration File Overview

Server configuration files are XML files used to provide runtime directives to StreamBase Server. The use of a configuration file is not required when running simple StreamBase applications, but is required to enable certain features such as support for authentication or automatic HA. In the absence of a configuration file, the server uses internally-defined default settings.

Under the following circumstances, server configuration files are recognized and used by StreamBase Studio when running applications:

Configuration files with other names or in other locations are not used by Studio when running applications. The presence of an sbd.sbconf file at the project root overrides most Studio default settings. Studio uses most, but not all, settings in the sbd.sbconf file, as described on How StreamBase Studio Uses Server Configuration Files.

When running StreamBase Server from the command line, specify a server configuration file with the -f option. For example:

sbd -f sbd.sbconf fxtrading.sbdeploy
sbd -f qasettings.sbconf hedge.sbapp

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.

The XML syntax for configuration files is described in StreamBase Server Configuration File XML Reference. You can break a complex server configuration file into component pieces, and then include smaller portions into a top-level 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.

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

The standard name sbd.sbconf is required by Studio, and that name is recommended for all uses. However, when using multiple or alternate configuration files with the sbd command at the command prompt, you can assign any basename that your project requires. For example, you may need to specify different JDBC connection strings for test and production databases, which you might keep in separate configuration files for use in test and production environments. (But see below for an alternate way to handle different JDBC connection strings.)

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

The top-level element of a server configuration file is <streambase-configuration>, which includes three namespace declarations, as seen in this fragment:

<?xml version="1.0" encoding="UTF-8"?>
<streambase-configuration xmlns:xi="http://www.w3.org/2001/XInclude"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.streambase.com/schemas/sbconf/">
...

These declare the xi namespace for the XInclude standard, the xsi namespace for the XML Schema standard, and the unnamed default namespace for the server configuration schema. The last two namespace declarations are what allow Studio's Configuration File Editor to provide syntax color coding, autocompletion, and Ctrl+Space prompts of context-aware tag suggestions.

If you are reusing a configuration file from an earlier StreamBase release, add the namespace declarations as shown above to enable these features in the Editor.

Server configuration files are usually, but not always, reusable between StreamBase releases. In major releases, the configuration file schema may deprecate certain elements, change the syntax of elements, or remove elements deprecated in previous releases.

TIBCO recommends upgrading your project's configuration files when migrating to a new release. Follow these steps:

New server configuration files created with sbd -s always include a template of commented default settings. When creating a new server configuration file in Studio, you can optionally include the default settings template.

The comments in the template can help you determine which settings to use, along with the documentation in StreamBase Server Configuration File XML Reference. Certain settings are provided wrapped in XML comment characters. You can enable these suggestions by removing the initial <-- comment characters, and matching end --> comment characters. Be sure to edit the suggested settings to provide values appropriate for your application.

For UNIX, environment variable expansion in the server configuration file works for all environment variables in the shell that started the sbd process. For Windows, environment variable expansion works for all variables in the System and User environments for the currently logged in Windows user that is running StreamBase Server.

Thus, the use of environment variables in configuration files is not limited to the STREAMBASE_* variables shown in StreamBase Environment Variables. Certain variables, such as STREAMBASE_HOME, are guaranteed to be set by StreamBase Server, but all other variables are also passed in from the environment that started StreamBase Server.

You can take advantage of this feature to pass data fields that you do not want to hard-code in the configuration file, such as the username and password for a JDBC connection. For example:

<uri value="jdbc:mysql://mysql.example.com:3306/qa?user=${MYDB_USER}&amp;password=${MYDB_PWD}"/>

Use the ${ENV_VAR} syntax to specify the contents of the variable ENV_VAR. Uppercase is traditional for environment variable names, but is not required. If you reference a variable that is found to be empty or unset at sbd launch time, you receive a configuration file parsing error, and sbd fails to start.

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. For example:

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

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 the next section.

You can specify a default value for an environment variable using := (colon-equals). For example, ${AUTH:=false} means the following:

The default value cannot be another environment variable, but can be the literal string null. A default value of null means that if the specified variable is found to be unset, set it, but with no value; this allows StreamBase Server continue loading if a required environment variable is not present.

Using the last example from the previous section, you might specify a local variable Host to the value of the environment variable $STREAMBASE_SERVER if found, or to sb://sbhost:9900 otherwise:

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

When using the <java-vm> element of the configuration file, it helps to understand how the StreamBase Server process, sbd, attempts to find a JDK when it starts. The tests are performed in the following order and cease when a JDK is located:

Back to top ^