StreamBase Java Properties

The StreamBase Java Client library uses the Java properties described on this page. You can set properties:

  • On the Java command line using -Dproperty-name=value when you start a StreamBase client

  • In the StreamBase Server configuration file with the <sysproperty> element

  • In your Java client code using the System.setProperty() method

The following example shows command line usage:

java -Dstreambase.tuple-connection-timeout=4000 \
     -Dstreambase.reconnect-sleep=7000 MyClient

Or, in your Java client code:

System.setProperty("streambase.tuple-connection-timeout", "4000");

Note

Each system property on this page can also be implemented as an environment variable. If both environment variable and system property are specified for the same setting, the system property prevails. To convert a system property from the table below to an environment variable, uppercase all letters, and substitute an underline for periods and hyphens. For example, convert streambase.tcp-nodelay to STREAMBASE_TCP_NODELAY.

To avoid introducing conflicting settings when configuring StreamBase Server, use either Java properties or environment variables to the extent possible, with a preference for Java properties.

The following table describes the StreamBase Java properties.

Property Name
   Description
streambase.appgen.allow-all-function-input
   Set to true or false (default) in <jvm> element of a .sbconf file. When true, allows input functions to call impure functions, such as timestamp().
streambase.appgen.tupleid
   Use with the sbc readTable command -v option to display unique tuple ids. Set to hash to print hash values for tuple ids. Set to sequential to print sequential values (starting at 0) for tuple ids. If unset, all tuple ids are reported as 0. Hash tuple id values are not guaranteed to be unique. Sequential values will be only be unique per server instance and revert to constant 0 values each time a new sbd is started.
streambase.appgen.error-schema-version
   Set to 2 to emit error tuples, with originalTuple emitted as a JSON object string.
streambase.check-app-environment-variables-changed
   Set to true or false. When true, StreamBase Server runs the precompiled archive file present in a bundled archive file it is asked to run, and does not recompile the EventFlow or StreamSQL source files in the bundle.

Under some circumstances, StreamBase Server can emit warning messages at startup that indicate an environment variable has changed since the application was compiled. In most cases, these warnings have no consequences and can be ignored. However, when the server is loading a bundle file that includes a precompiled archive file, an environment variable warning message has the unintended side effect that the server ignores the bundled archive file and recompiles the application from the bundled source files. The bundled application does run normally, but for very large applications, at the cost of the recompilation time.

streambase.client.max-tuples-in-queue
   Specify an integer maximum number of tuples allowed in the client connection queue, to promote better client behavior. The default value is 10000 tuples. This Java property also affects the queue of incoming tuples when using the StreamBase to StreamBase input adapter.
streambase.client.log-connection-status
  

Set to true or false; the default is false. In the default setting, StreamBase clients log both connection and disconnection events at the DEBUG level. Set to true to have your clients log at the INFO level for connection events and at the WARN level for disconnection events. This property requires your client code to import com.streambase.sb.client.ConnectionStatusCallback.

streambase.codegen.trace-tuples
   Set to true or false. When true, you can use the runtime tracing features of StreamBase Server, as described in Runtime Tracing and Creating Trace Files.
streambase.codegen.generate-bytecodes
streambase.codegen.compileinprocess
streambase.codegen.jarinprocess
   Use these properties together to specify that StreamBase Server is to use an external javac command to compile EventFlow and StreamSQL instructions to byte code, instead of using an internal compilation process (the default). Using an external compiler can increase the memory available for large applications on memory-constrained systems. To specify this option, set both compileinprocess and jarinprocess to false, and set generate-bytecodes to javac. Using these three Java properties is the same as selecting the Compile StreamBase application in separate process option on the Main tab of StreamBase Studio's Launch Configuration dialog.
streambase.codegen.codegen.javac-Xmx
   Specifies the maximum amount of memory used by the compiler (default is at least 256MB).

Use this flag the same way as the java -Xmx command-line option: Specify the maximum size, in bytes, of the memory allocation pool. This value must a multiple of 1024. Append the letter k or K to indicate kilobytes, or m or M to indicate megabytes. Examples: 

-Xmx83886080
-Xmx81920k
-Xmx80m
streambase.codegen.error-for-null-as-primitive
   If the value of a parameter with a primitive type is null at run time, the method that implements the custom function is invoked and returns a null result and a console warning is then issued. You can also cause an error tuple to be emitted on the operator's error port (if any) by setting this property to true. The default is false.
streambase.codegen.digest-type-names
   Set to true or false; the default is true. Some file systems supported by StreamBase restrict the maximum length of file names. To avoid hitting these limits, StreamBase uses a hash to shorten the internal names of code generated by compiling EventFlow XML and StreamSQL code, and to avoid name collisions in that internal code namespace. These shortened names make debugging StreamBase internal code more difficult. Set this property to false to temporarily disable internal code name shortening to improve readability while debugging, at the cost of occasionally encountering a file name collision or length restriction.
streambase.codegen.error-for-null-as-primitive
   If the value of a parameter with a primitive type is null at run time, the method that implements the custom function is invoked and returns a null result and a console warning is then issued. You can also cause an error tuple to be emitted on the operator's error port (if any) by setting this property to true. The default is false.
streambase.codegen.intermediate-stream-dequeue-regex
   Limits the number of output streams the application will expose when running in debug mode, by setting the server's JVM property to include the this property set to a regular expression pattern, using an argument of the form regex=expr

For example, you can set the JVM arguments to include a pattern like the following:

-Dstreambase.codegen.intermediate-stream-dequeue-regex=Map\\d

This allows any intermediate stream that contains the pattern of "a Map followed by a digit" to be exposed as a dequeueable stream. All other intermediate streams normally available in debug mode will not be available.

streambase.decouple.operator.log-level
   Decouples the log level of an operator or adapter from the system log level, so it can be less verbose. Set to true or false (default). If true, then the system log-level will not affect the Java operator/adapter log-level. If false, all operators and adapters use the more verbose setting of the component's or the system log-level property value.
streambase.feedsim.plugin-classpath
   For custom feedsim plug-ins, specifies the path to a package directory or JAR file that contains the custom class. If your development environment or your application requires more than one custom file reader class, specify the paths as a list separated with semicolons (Windows) or colons (UNIX).
streambase.ide.component-exchange-force-auth
   Set to true or false. Use this property in conjunction with the site-specific Component Exchange feature described in StreamBase Studio Panel and Site-Specific Component Exchange. If you supply a URL that begins with HTTPS or FTP, Studio automatically prompts for credentials. If you supply a URL for another protocol, you can force authentication prompting for that protocol by setting this property to true for the VM that runs Studio.
streambase.ide.debugger.remote-call-timeout-ms
   The default value is 10000 (10 seconds). Set this property to change the timeout period that prevents the EventFlow Debugger from hanging in rare cases of hung remote calls.
streambase.jdbc.max-repeat-exceptions
   The default value of 1 tells StreamBase Server that a single instance of a JDBC exception is regarded as an exception. Specify zero to mean that JDBC exceptions can be repeated without limit. Use an integer, n, greater than 1 to specify that JDBC exceptions might occur n times before succeeding.
streambase.log-adapter-async
   Set to true or false. Use this property to set the synchronous state of all Log adapter instances in an application at the same time, without having to edit the Properties view for all Log adapters in the application. Set to true to force all Log adapters to enable the Log Asynchronously option. Set to false to restore the default synchronous state of all Log adapters. See The Log Asynchronously Option.
streambase.log-level
   Specify an integer value, one of -2, -1, 0, 1, 2, or 3. Sets the severity of log messages emitted by the standard StreamBase logging mechanism, Logback. See the table Log Levels for a mapping of integer keys to logging levels. The default is 0, which provides INFO level messages and higher.
streambase.low-latency-mode
   Set to true or false; false is the default. This switch provides a single switch that enables several other properties to direct StreamBase Server to run in low latency configuration. Setting this property to true performs the following subordinate actions:

  • Enables the low latency option on all StreamBase to StreamBase adapters, including those used internally to implement remote container connections.

  • Enables the streambase.tcp-nodelay Java property, which disables the Nagle algorithm on network connections.

  • Sets the Java property streambase.queue-flush-interval to zero, which disables queue flushes for client connections.

  • Sets low latency mode on dequeue output queues.
streambase.operator.parameters.log-level
   Specify an integer corresponding to the StreamBase log level in which you want operator property log entries included. Specify 0=OFF to disable this feature, or specify 1=ERROR, 2=WARN, or 3=INFO.

When set to 1, 2, or 3, StreamBase log messages include entries for each property setting for all operators and adapters that inherit from the Operator class in the StreamBase Client Library. This includes any custom Java operators and most adapters, but does not include global operators such as the Map or Filter operators included with StreamBase.

The messages are sent from the Operator caretaker class, and are in the format of the following example, where this setting was set to 1: 

2010-12-01 12:58:28.030-0500 [Thread-4] ERROR \
c.s.sb.runtime.OperatorCaretakerImpl - \
Operator: OrderInput, Parameter: OrderManagementPort, \
Value: 8889

Values set with variables in the operator or adapter's Properties view are shown with the variable's runtime expansion. For example, the value of the OrderManagementPort property in this example was specified with ${MGMTPORT} but is shown in the log message with its runtime value, 8889.

If an adapter uses an adapter-specific configuration file, the file's name is shown as a property setting. However, the contents of such configuration files are not shown.

streambase.max-queue-size
   Specify an integer number of result sets, the maximum size of the queue that a StreamBase client is to maintain when dequeuing result sets. Each result set entry contains a list of tuples. The default is 500 result sets.
streambase.max-stat-tuples-cache
   Specify an integer number of tuples, the default maximum size of the system.statv2 stream's tuple cache, which grows dynamically as needed by the application. The default value of –1 means the statistics stream cache can grow as large as needed, limited only by available memory.
streambase.queue-flush-interval
   Specify an integer number of milliseconds to wait between queue flushes for client connections. The default is 20. Set this value to a lower number to improve latency. While setting this value to 0 does minimize latency, a zero setting may have an impact on the system load.
streambase.read-buf-size
   Specify an integer number of bytes, the default read buffer size used by the client when dequeuing tuples. Changing this value may have an effect on client dequeue performance. The default value is 32768 (32K or 32*1024).
streambase.reconnect-sleep
   Specify an integer number of milliseconds to set how often a StreamBase client should try to reconnect to the primary or secondary StreamBase Server in a high availability StreamBase environment when the connection to the server is dropped. The default is 5000 (5 seconds).
streambase.runtime.send-zero-stats
   Set to true or false. The default setting is true, which means the statv2 stream of the system container includes tuples with zero values. Set this property to false to exclude zero value tuples from the system.statv2 stream. This excludes zero value tuples from consideration in the statistics shown by StreamBase Monitor and StreamBase Manager.
streambase.runtime.stream-queue-max-buffer
   Specify the number of bytes to which you wish to limit buffer doubling. Default value is 1 GB per buffer. The value must be a power of 2. New buffers are only needed if the consuming region continues to be slower than the producing region. Before a new buffer is allocated, the producing region will pause briefly in an effort to aid the consuming region to catch up.
streambase.runtime.stream-queue-wait-strategy
   Specifies the default wait strategy used by the disruptor that controls parallel stream queueing. Valid values are: BLOCKING, BUSY_SPIN, SLEEPING, and YIELDING. Individual parallel regions can override this property by setting a parameter with the url-encoded path of the parallel region. For example, to cause the parallel module reference TopLevel.ParallelInnerModuleRef1 to enter a busy wait state (spinlock), you can specify: -Dstreambase.runtime.stream-queue-wait-strategy-TopLevel.ParallelInnerModuleRef1=BUSY_SPIN
streambase.sbd.allow-overwrite-constants
   When true (the default), allows <constant-overwrite> elements of an sbd.sbconf file to override module constant values at init time. When false, constant definitions are "baked in" at compile time, as usual. Setting this property has no effect if sbd.sbconf contains no <constant-overwrite> elements naming constants defined in the current environment.
streambase.sbd.max-input-packet-size
   Specify an integer maximum number of bytes per packet, the maximum limit sent to the server in a client enqueue connection. The default value is 67108864 (64 MB, or 64*1024*1024).
streambase.sbd.max-tuples-in-dequeue-packet
   Specify an integer maximum number of packets the server includes in any one dequeue packet. The default value is 10000, which matches the default of the streambase.client.max-tuples-in-queue property described above. Administrators can set both server and client with matching values to make sure client dequeues are not overwhelmed.
streambase.sbd-shrink-after-process
   Set to true or false; the default setting is false. Set to true for servers with dozens of StreamBase client connections. This forces client buffers to shrink after each use instead of remaining a fixed size, which reduces the overall memory footprint of the server, at the expense of higher memory churn and consequent garbage collection.
streambase.tcp-nodelay
   Set to any value, such as 1, to disable the Nagle algorithm for StreamBase Server and for StreamBase clients. The Nagle algorithm is a throughput optimization implemented by default in the TCP/IP network code of the Server and Client Libraries. The algorithm adds about 40 milliseconds of latency on Linux and about 200 milliseconds on Windows. Make this setting independently for Server and clients.
streambase.tuple-connection-quiescent-limit
   Specify an integer number of milliseconds, the timeout value for how long a Java StreamBase dequeuing client tolerates not receiving anything from the StreamBase Server to which it is connected. The default value is 120000, or 120 seconds. By default, StreamBase Servers emit client heartbeats every 10 seconds, so that StreamBase applications have no requirement to send data regularly. StreamBase Servers can be configured to send heartbeats faster, slower, or not at all. The quiescent timer only starts after the first heartbeat is received. Thus, if a server never sends a heartbeat, clients do not have quiescent protection.
streambase.tuple-connection-timeout
   Specify an integer number of milliseconds. In a high availability StreamBase application environment, this property sets a timeout value on reads and writes between the client and server. This timeout is used by the client to recognize failure of the server. The default value is 15000 (15 seconds). A value of 0 disables the timeout (some operations will block forever).

Consider carefully when using this property. A timeout value too long may cause the client to hang for that period before it fails over to the other server. Too short of a value may cause the client to disconnect prematurely from the server if the server is busy.

streambase.unit-test.server-conf
   Path to and name of the StreamBase Server configuration file used for conducting unit tests, which must contain the path to the directory containing your JUnit test class file (usually the java-bin folder of the Studio workspace). Can be specified or overridden using the sbunit command.
streambase.uri
   Overrides the default URI of the StreamBase Server instance to which connections are to be made. The default is sb://localhost:10000. See sburi for the syntax of StreamBase URIs.
streambase.write-buf-size
   Specify an integer number of bytes, the default read buffer size used by the client when enqueuing tuples. Changing this value may have an effect on client enqueue performance. The default value is 32768 (32K or 32*1024).
streambase.xmlrpc-timeout
   Specify an integer number of milliseconds to set a timeout value that clients built with the StreamBase Client Library are to wait for a response from StreamBase Server. This setting applies in the rare case when the server is alive and listening, but not responding. The default value is zero, which specifies no timeout.