Server Configuration File Overview

Introduction

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:

  • The file is named sbd.sbconf.

  • The file is at the root of the Studio project.

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.

Note

TIBCO discourages editing a project's server configuration file, or one of its component fragment files, in another editor outside of Studio while Studio is running. Nevertheless, if you do so, you must perform the following steps in this order:

  1. Refresh the Studio project after such external edits. That is, select the project in the Package Explorer view, right-click, and select Refresh from the context menu (or select the project and press F5).

  2. Refresh the project's typecheck environment. That is, select the project in the Package Explorer view, right-click, and select StreamBaseRefresh Project Typecheck Environment from the context menu (or select the project and press Ctrl+F5).

Naming Convention and Namespace Declarations

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.

Upgrading Configuration Files

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:

  1. Open your existing configuration file in Studio's Configuration File Editor.

  2. If missing, add the namespace declarations to the top <streambase-configuration> element, as described above.

  3. Follow red X problem markers in the Editor to correct any syntax errors detected.

  4. When no further problem markers remain, save the file.

Template Configuration with Comments

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.

Using Environment Variables in Configuration Files

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.

Environment Variables and the Colon-Equals Syntax

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

  1. Use the value of $AUTH if set with a non-null value.

  2. Use false otherwise.

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}"/>

How StreamBase Server Searches for a JDK

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:

  1. Evaluate the java-home parameter of the <java-vm> element in the server configuration file.

  2. Evaluate the STREAMBASE_USE_INTERNAL_JDK environment variable.

    1. If not set or set to true (the default setting), uses the internal JDK installed in streambase-install-dir/jdk or streambase-install-dir/jdk64.

    2. If set to false, uses the JDK defined in the JAVA_HOME environment variable.

  3. Evaluate the JAVA_HOME environment variable.

  4. Search the directories in the PATH environment variable to find a suitable JDK.

  5. Attempt to find a JDK on your system in standard installation locations.

  6. If all of the preceding steps fail, sbd does not start.

Back to top ^