Contents
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:
-
Refresh the Studio project after such external edits. That is, select the project in the Package Explorer view, right-click, and select F5).
from the context menu (or select the project and press -
Refresh the project's typecheck environment. That is, select the project in the Package Explorer view, right-click, and select Ctrl+F5).
→ from the context menu (or select the project and press
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:
-
Open your existing configuration file in Studio's Configuration File Editor.
-
If missing, add the namespace declarations to the top
<streambase-configuration>
element, as described above. -
Follow red X problem markers in the Editor to correct any syntax errors detected.
-
When no further problem markers remain, save the file.
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}&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:
-
Use the value of
$AUTH
if set with a non-null value. -
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}"/>
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:
-
Evaluate the
java-home
parameter of the<java-vm>
element in the server configuration file. -
Evaluate the
STREAMBASE_USE_INTERNAL_JDK
environment variable.-
If not set or set to
true
(the default setting), uses the internal JDK installed in
orstreambase-install-dir
/jdk
.streambase-install-dir
/jdk64 -
If set to false, uses the JDK defined in the
JAVA_HOME
environment variable.
-
-
Evaluate the
JAVA_HOME
environment variable. -
Search the directories in the
PATH
environment variable to find a suitable JDK. -
Attempt to find a JDK on your system in standard installation locations.
-
If all of the preceding steps fail, sbd does not start.