Defining a StreamBase Server Configuration

Overview

By default, a StreamBase Server process that hosts a StreamBase application uses a set of predetermined configuration properties. As you develop and test your StreamBase application, you may want to modify some of the default properties, such as to change a port number or to identify an external JDBC resource. You can create an XML file with the extension sbconf for this purpose.

Deploying an application may require some configuration that was not required during development. For example, during development you can use custom functions and modules in your project or a referenced project, without modifying the sbd configuration. However, in some situations you will need to modify the configuration file to identify the locations of those resources. This might happen while you're authoring in StreamBase Studio, and it is the norm when you deploy applications.

You can generate a skeleton or template configuration file in StreamBase Studio named sbd.sbconf by default. You can then edit the file's elements. To help you, many of the elements are documented in the form of XML comments. For full documentation, see StreamBase Server Configuration XML in the Reference Guide.

Creating a New Configuration File

We recommend that you let StreamBase Studio generate a configuration file for you. The file is generated from StreamBase Studio's connected sbd server process. It lists the current default settings, and contains comments about most of them. You can use any of these methods:

In StreamBase Studio, right-click the project in the Package Explorer, and choose StreamBase → Add Default Server Configuration File. The last menu command is not available if sbd.sbconf already exists in your project.
Use the New StreamBase Server Configuration File wizard as described in Creating a New Server Configuration File.
In a StreamBase Command Prompt or terminal window, run sbd -s. With this option, the sbd command does not start the server or run an application, it generates a default configuration file. For example, the following command generates a skeleton file in a directory that you specify, and gives it a different filename:

sbd -s > ~/mytestarea/MyAppsConfig.sbconf

After customizing your configuration file, you can use the -f option to start the server and application. For example:

sbd -f ~/mytestarea/MyAppsConfig.sbconf MyApp.sbapp

Using sbd.sbconf in StreamBase Studio

A StreamBase Studio project does not require an sbd configuration file: it uses default settings. However, if you create an sbd.sbconf file in the root folder of a project, the settings there override the default settings for that project.

You can open an sbd.sbconf file in the Eclipse Text editor by double-clicking it in the Package Explorer. Outside of StreamBase Studio, you can use any text editor.

Changes to your sbd.sbconf persist between StreamBase Studio sessions. You can also export your customized sbd.sbconf file when you deploy the application.

Note

Each StreamBase project only uses a single configuration file named sbd.sbconf, which must be at the root of the project folder. You can create additional configuration files with different names or in project subfolders, but they will not be used by StreamBase Server run by Studio. Configuration files used outside of StreamBase Studio can have any name, as long as the extension is sbconf.

What If My Project Already Contains a Server Configuration?

When you generate an sbd.sbconf file, if your project already contains a server configuration file but it does not use the exact filename sbd.sbconf, StreamBase Studio adds the new sbd.sbconf template file in the project's folder.

When the server is started in StreamBase Studio, Studio ignores any customized configurations that are not named sbd.sbconf. If you want StreamBase Studio to use an already customized version in a project, you must rename it to sbd.sbconf, by selecting the (closed) file in the Package Explorer, and using the File → Rename menu command.

To avoid confusion between sbd.sbconf edits in StreamBase Studio versus directly on the file system, we recommend that you use the StreamBase Studio editor. If you make edits on the file system in your StreamBase workspace, remember to close the sbd.sbconf editor in StreamBase Studio and then reopen the file in the external editor to ensure you are viewing or editing the latest version.

Also Note

Be careful when re-using sbd.sbconf files from previous StreamBase releases. Renaming a previously customized server configuration file to sbd.sbconf in the Package Explorer (so that the server will use it when started from StreamBase Studio) does not guarantee that the settings are the latest used by StreamBase. We recommend that you compare the latest template sbd.sbconf file with any configurations you defined using prior StreamBase releases.

Specifiying Different Configuration Settings for Different Applications

In StreamBase Studio, there is one sbd.sbconf file for each StreamBase Studio project. Thus, if you have multiple StreamBase applications in the same project folder, and each one needs a different configuration setting that cannot be accommodated in a single sbd.sbconf, you can move your sbapp files to separate projects. You can drag sbapp files from one project folder to another in the Package Explorer, or right-click and use the Copy and Paste functions.

Editing sbd.sbconf

The editor in StreamBase Studio provides XML syntax validation. The sbd.sbconf file contains a required <streambase-configuration> root element and a matching </streambase-configuration> closing element, also required. When you save an edited sbd.sbconf file, StreamBase Studio overlays a red X on the file's icon in the Package Explorer if it contains any unrecognized or unbalanced elements. For example:

In the template sbd.sbconf file, notice that many parameters are commented out. For example:

<!-- The following optional element is used to load any
     operator/adapter resources required by this application. You can
     have as many <operator-resource-search> elements as you like. Each
     one must have a "directory" attribute, which will be scanned for
     any resources referenced by operators and adapters. -->
<!-- <operator-resource-search directory="${STREAMBASE_HOME}/resources"/> -->

You are not required to provide values for each section, or for all parameters within a section. If you want to change a setting, remove the initial <-- comment characters, and the matching end --> comment characters, then provide values that are appropriate for your application. If you do not specify a parameter in the configuration file, default configuration values are used, as listed in Default Configuration Settings for a StreamBase Server Process.

Details about the sbd.sbconf XML elements are provided in StreamBase Server Configuration XML in the Reference Guide.

Note: Although you are free to modify any section in the configuration file, settings in the high-availability section are ignored when launching StreamBase Server within Studio. This is because the leadership status for machines in HA environments requires coordination outside StreamBase Studio. For more information on HA, see Clustering and High Availability.

On the other hand, as you plan for the eventual deployment of your StreamBase application into a staging environment, it is useful to have a fully defined configuration as part of the deployed project. Thus, editing all sections of your project's sbd.sbconf is a good practice during development, even if some parameters are not exercised until your deploy your application into a staging environment, and eventually in a production environment.

Default Configuration Settings for a StreamBase Server Process

This section lists the StreamBase Server default configuration settings. In other words, if you never provide a customized *.sbconf file when the StreamBase Server (sbd process) is started, these are the values that are in effect.

Defaults:

No custom functions are loaded by the sbd process hosting the StreamBase application. In the configuration file, custom functions are also referred to as "plug-ins."
No modules (other StreamBase applications) are loaded by the sbd process hosting the StreamBase application.
The sbd process will listen for client messages on port 10000.
There can be up to ten backlogged connections from clients to the running StreamBase Server.
No embedded adapters are loaded for this application.
If your application contains Java Operators or Embedded Adapters, or both, the default value used by the operator-state-change-timeout-ms parameter is 10000 milliseconds (ten seconds). This is the amount of time the server will wait before timing out a Java Operator or Embedded Adapter. If a Java Operator or Embedded Adapter is timed out on a state change, the server shuts down the Java Operator or Embedded Adapter, and proceeds with its own server state change.
If the StreamBase application contains one or more disk-based Query Tables (available only in StreamBase Enterprise Edition), a temporary data directory is created during the server startup and deleted on shutdown.

On UNIX:

/tmp/sbdata-<six-random-characters> /querytable/<table-name>

On Windows, disk-based Query Tables go to %TEMP%, which is usually:

C:\Documents and Settings\<username>\Local Settings\Temp\sbdata-<six-random-characters> \querytable\<table-name>

Also, if your application contains disk-based Query Tables, StreamBase uses transactional updates when it writes updates to the on-disk files, but (also by default) the updates do not occur in a predictable time frame. A default flush interval, to write a checkpoint and remove unneeded log files, occurs every 30 seconds by default.
The default memory parameters for the sbd process: page size is the minimum value for the machine's architecture, which are 4096 bytes per page on x86 and x86_64 processors, and 8192 bytes per page on SPARC processors.

The initial minimum and maximum values for the memory allocation pool (Java Heap) are 64 MB (-Xms64m) and 256 MB (-Xmx256m).
The maximum number of pages that a dequeuing client connection can allocate is 2048 pages. With a default page size of 4096 bytes on Windows or Linux, the default max-client-pages value of 2048 will provide 8 megabytes.
There is no hard coded default application name. In other words, you must specify a sbapp or ssql filename if you start sbd on the command line. When you start the server in StreamBase Studio, it launches an sbd process for the currently selected sbapp or ssql file.
A container named default exists for the application as a whole. By default, no additional containers are defined.
If you use the now() function in your application, its default implementation is configured as system, which means that the function will use Java's System.currentTimeMillis().
The default maximum size of a schema is 1,048,576 bytes (1 MB). (Remember that the largest tuple must be less than the StreamBase page-size, which must be a multiple of the system's page size, as noted above.)
Performance statistics will be produced by sbd, at the rate of once per second (1000 milliseconds). A StreamBase Studio Monitor View or sbmonitor command can display the statistics at runtime, or a MonitorListener client can consume the statistics and presumably take some action based on them.
Authentication is disabled, meaning any logged in user can enter any StreamBase sb* administration command to interact with the running sbd process hosting the StreamBase application.
If defined outside of the sbconf file, the JAVA_HOME environment variable's value can be used by sbd to find the JDK. If you use any Java operators in your StreamBase application, the JAR file that contains the Operator classes must reside in the Java Build Path as specified in the project's properties.
For C++ custom functions and aggregates, a default maximum string size of 32K characters is set for data passed between the C++ plug-in and the runtime.
By default, most runtime errors that occur in a running StreamBase Server cause a server shutdown. You can override this behavior by setting the error-handler element in your sbd.sbconf. This optional parameter is not present in the skeleton sbd.sbconf, or in the default configuration file generated by sbd -s. See error-handler for information on this element.

Server Configuration Options

Details about the server configuration options are provided in StreamBase Server Configuration XML in the Reference Guide.

Using Environment Variables in the Server Configuration

You can use environment variables in your customized server configuration file. For example, the skeleton sbd.sbconf shows the STREAMBASE_HOME environment variable used in several elements as in the following example:

<global>
    <module-search directory="${STREAMBASE_HOME}/modules"/>
</global/>

On Windows, starting with release 5.0, the global Windows environment is not augmented with StreamBase variables during installation. Remember to start your sbd process from a StreamBase Command Prompt, not an ordinary Windows command prompt.