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 engine configuration file with the systemProperties object.

  • 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). 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 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 Interpreting Trace Files.
streambase.codegen.allow-refactoring
streambase.codegen.n-stmts-limit
streambase.codegen.broken-method-names
   There are cases when generated Java code exceeds Java limits and module compilation will fail with an exception. The typical cause of this failure is a very large schema definition. When this error occurs, use the following system properties together to force the generated code to be refactored to work around the Java limits:

streambase.codegen.n-stmts-limit: applied to all generated methods, not just the ones that exceed the Java constraints. Specific methods can be refactored using streambase.codegen.broken-method-names. streambase.codegen.broken-method-names is recommended for resolving compilation failures.

streambase.codegen.allow-refactoring: Set to true to enable refactoring, false to disable. Default value is false.

streambase.codegen.n-stmts-limit: Positive integer, greater than 1. Default value is 300. Maximum number of statements in a block. Also, streambase.codegen.allow-refactoring must be true.

streambase.codegen.broken-method-names: Comma-separated list of fully-qualified-method-name:refactor-value or simple-method-name:refactor-value values. The refactor-value must be less than the value of streambase.codegen.n-stmts-limit. Maximum number of statements in a block for a specific method. Also, streambase.codegen.allow-refactoring must be true.

Refactoring blocks into fewer statements generates more entries in the JVM constant pool because more methods are generated. When a compilation failure of generated source occurs because of a Java constraint violation, take these steps in order, recompiling after each change.

To enable streambase.codegen.allow-refactoring: 

-Dstreambase.codegen.allow-refactoring=true

Optionally fine-tune the statement block size used for refactoring specific methods using streambase.codegen.broken-method-names and these steps:

  • Enable streambase.codegen.broken-method-names for the specific failed method. For example: 

    -Dstreambase.codegen.broken-method-names=com.streambase.
cache.translationUtils.fieldMethod0:10

  • Add additional methods to streambase.codegen.broken-method-names for additional failed methods. For example: 

    -Dstreambase.codegen.broken-method-names=com.streambase.
cache.translationUtils.fieldMethod0:10,fieldMethod1:10

  • Continue adding methods until all compilation failures are resolved.

Optionally change the default value of streambase.codegen.n-stmts-limit to change the refactoring block size of all methods. Reducing this value from the default value may avoid exceeding Java constraints. For example: 

-Dstreambase.codegen.n-stmts-limit=150

For individual method refactor values:

The refactor-value set in streambase.codegen.broken-method-names is calculated as the value of streambase.codegen.n-stmts-limit divided by the specified refactor-value. For example, if streambase.codegen.n-stmts-limit is set to 100 and the refactor-value is set to 10, the method is refactored into blocks with a maximum of 10 (100/10) statements.

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 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.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 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.java-operator.stacktrace-on-warn
   Set to true or false. Set to true to turn on displaying stack traces on exceptions thrown from Java operators.
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 Logback 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 Manager.
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.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(5) 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.