StreamBase Client API Listener Configuration

Overview

This article provides a reference for writing a StreamBase Client API Listener configuration file where the HOCON type is com.tibco.ep.streambase.configuration.sbclientapilistener.

The StreamBase client API listener configuration defines port numbers and secure communication indicators. It is separate from the base engine configuration and can therefore be managed separately without having to recreate an application archive and redeploy the application whenever for example a port number changes.

Required Header Lines

Each configuration file must contain the following header lines, typically found at the beginning of each file:

name

Specifies an arbitrary, case-sensitive string to name this configuration, which must be unique among other files with the same type, if any. Configuration files can refer to each other by this name. Select a name that reminds you of this configuration's type and purpose. For example:

name = "myapilistenersettings"
version

Specifies an arbitrary version number that you can use to keep track of file versions for this configuration type in your development project. The maintenance of version numbers is under user control; StreamBase does not compare versions when loading configuration files during the fragment launch process. The version number is a string value, and can contain any combination of characters and numbers. For example:

version = "1.0.0"
type

This essential setting specifies the unique HOCON configuration type described on this page.

type = "com.tibco.ep.streambase.configuration.sbclientapilistener"

The three header lines taken together constitute a unique signature for each HOCON file in a project's configurations folder. Each project's configurations folder can contain only one file with the same signature.

The top-level configuration object defines the configuration envelope the same way for all HOCON file types.

configuration

On a line below the header lines, enter the word configuration followed by an open brace. The configuration object is a sibling of the name, version, and type identifiers, and serves to define the configuration envelope around this type's objects as described on this page. The file must end with the matching close brace.

configuration = {
...
...
}

HOCON Properties Explained

Below shows the configuration's HOCON properties, usage, and syntax example, where applicable.

ClientAPIListener

Root object for StreamBase client API listener configuration.

associatedWithEngines

If you want to restrict this object to be associated with specific engines, do so here. Each entry can be a specific engine name or a regular expression that can applies to more than one engine. This array is optional and has no default value. If not present, the configuration is associated with all engines.

For example:

associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
apiListenerAddress

Listener address configuration for the StreamBase client API. This object is optional.

portNumber

TCP port for the StreamBase client API to listen on. Port range is 0 — 65535 and its default value is 10000.

A zero value means that the StreamBase server will find a random port to listen on.

If the port value (including, however unlikely, a random port) is taken, the engine will not start.

If you specify a port on the deploy command line (or in the Studio Run/Debug Configuration), you get it.

For example:

portNumber = 10000
authenticationRealmName

Authentication realm associated with this listener, indicating that user authentication is to be performed for requests handled by this listener. This property is optional and has no default value.

For example:

authenticationRealmName = "my-realm"
pagePool

Connection page pool configuration. This object is optional, with defaults as described below.

pageSize

Determines the initial size for output buffers. It is also used to calculate the maximum size a client output queue can grow to before the client is disconnected, see maxClientPages below. This property is optional and its default value is 4096 bytes.

You can use HOCON power-of-ten or power-of-two suffixes like KB, MB, K, or M as an abbreviation.

For example:

pageSize = 6K
maxPooledBuffers

Determines how many buffers (per output stream) to maintain in a buffer cache. To disable the cache, set the value to -1. This parameter does not determine when and whether slow clients are disconnected.

You can use HOCON power-of-ten or power-of-two suffixes like KB, MB, K, or M as an abbreviation.

This property is optional and its default value is 1024.

For example:

maxPooledBuffers = 2048
slowDequeueClientWaitMilliseconds

Determines the behavior of slow dequeuing clients. The server will either disconnect slow clients (the default) or BLOCK the server to wait for slow clients to catch up. A value of -1 causes clients to be disconnected. A value greater than -1 causes the server to sleep for the given amount of time in milliseconds when it detects that a client is running behind. The server continues sleeping until there is available dequeuing space for the client.

This property is optional and its default value is -1.

For example:

slowDequeueClientWaitMilliseconds = 100
maxClientPages

Controls the maximum number of pages that a dequeuing client connection can allocate. Depending on the value of slowDequeueClientWait the server will either disconnect the slow client or BLOCK. This setting is to protect the StreamBase server from slow or hung dequeuing clients. With the default page size of 4096 bytes, the default maxClientPages value of 2048 will provide 8 megabytes.

To allow ALL dequeuing clients to allocate unlimited memory in the server, set the value to zero. Note that the number of pages that a client allocates will change over time. A client that is consuming tuples as fast as the server produces them will only use one or two pages. The maximum can be reached with a slow or hung client or if there is a large spike of output data.

You can use HOCON power-of-ten or power-of-two suffixes like kB, MB, K, or M as an abbreviation.

This property is optional.

For example:

maxClientPages = 4K
clientHeartbeatIntervalMilliseconds

Int. The heartbeat interval is the number of milliseconds between heartbeat packets sent to clients. Clients can be configured to require a heartbeat packet from the server at a minimum interval. This is used primarily for network segmentation detection.

Setting this option to zero disables heartbeats from the server. Clients connected to such a server will not have heartbeat protection, regardless of their locally configured minimum heartbeat interval.

This property is optional and its default value is 10000.

For example:

clientHeartbeatIntervalMilliseconds = 10001
connectionBacklog

Int. Number of backlogged connections. Servers with many clients may want to increase the maximum number of backlogged connections to the server. For further details look up the manual page for the system call, listen. This property is optional and its default value is 10.

For example:

connectionBacklog = 11
maxPersistentConnections

Int. Maximum number of persistent connections. Each persistent connection uses up server resources. To protect the server from errant client connections a user can specify a maximum number of persistent connections. Any attempted client connections over the limit will be disconnected. This property is optional and its default value is -1, meaning no limit.

For example:

maxPersistentConnections = 10
idleEnqueueClientTimeoutMilliseconds

Int. Settings for disconnecting idle clients. An idle enqueue client is a client who has enqueued at least 1 tuple and has been idle for idleEnqueueClientTimeoutMilliseconds. An idle dequeue client is a client who has subscribed to at least one stream (at any point) and has been idle for idleDequeueClientTimeoutMilliseconds.

Clients that have enqueued and subscribed are subject to both idleEnqueueClientTimeoutMilliseconds and idleDequeueClientTimeoutMilliseconds. The server checks clients every idleClientCheckIntervalMilliseconds. The actual point that a client is disconnected will be approximate modulo idleClientCheckIntervalMilliseconds.

Values are in milliseconds. Values greater than zero enable this feature.

This property is optional and its default value is -1, which turns off checking.

For example:

idleEnqueueClientTimeoutMilliseconds = 1000
idleDequeueClientTimeoutMilliseconds

Int. Settings for disconnecting idle clients. An idle [enqueue] client is a client who has enqueued at least 1 tuple and has been idle for idleEnqueueClientTimeoutMilliseconds.

Clients that have enqueued and subscribed are subject to both idleEnqueueClientTimeoutMilliseconds and idleDequeueClientTimeoutMilliseconds. An idle dequeue client is a client who has subscribed to at least one stream (at any point) and has been idle for idleDequeueClientTimeoutMilliseconds. Clients that have enqueued and subscribed are subject to both settings. The server checks clients every idleClientCheckIntervalMilliseconds. The actual point that a client is disconnected will be approximate [modulo] idleClientCheckIntervalMilliseconds.

Values are in milliseconds. Values greater than zero enable this feature. This property is optional and its default value is -1, which turns off checking.

For example:

idleDequeueClientTimeoutMilliseconds = 2000
idleClientCheckIntervalMilliseconds

How often should the server check for idle clients. The value is in milliseconds. This property is optional and its default value is 60000.

For example:

idleClientCheckIntervalMilliseconds = 60001
secureCommunicationProfileName

Name of a secure communication server profile to use when configuring secure communication for a listener. This property is optional and has no default value. If not present, the listener will not use secure connections with its clients.

For example:

secureCommunicationProfileName = "my-secure-communication-server-profile"

HOCON Configuration File Sample

The following is an example of the sbclientapilistener type.

name = "myapilistenersettings"
version = "1.0.0"
type = "com.tibco.ep.streambase.configuration.sbclientapilistener"
configuration = {
  ClientAPIListener = {
    associatedWithEngines = [ "javaengine", "otherengine[0-9]" ]
    apiListenerAddress = {
      portNumber = 10000
    authenticationRealmName = "my-realm"
    }
    pagePool = {
      pageSize = 6K
      maxPooledBuffers = 2048
      slowDequeueClientWaitMilliseconds = 100
      maxClientPages = 4K
    }
    connectionBacklog = 11
    maxPersistentConnections = 10
    clientHeartbeatIntervalMilliseconds = 10001
    idleEnqueueClientTimeoutMilliseconds = 1000
    idleDequeueClientTimeoutMilliseconds = 2000
    idleClientCheckIntervalMilliseconds = 60001
  }
}