Reference for StreamBase ClientAPIListener Configuration

Overview

This article provides a reference for writing a StreamBase ClientAPIListener HOCON configuration file.

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 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.

In addition, the configuration top-level element is the same for all HOCON file types.

configuration

On a line below the header element lines, enter the word configuration followed by an open brace. The configuration element is a sibling of the name, version, and type elements, and serves as a wrapper around this type's elements described below. The file must end with the matching close brace.

configuration = {
...
...
}

HOCON Elements Explained

Below shows the configuration's HOCON elements, its name-values, usage, and syntax example, where applicable.

ClientAPIListener

Describes the StreamBase client API listener configuration settings.

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 name-value pair 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 name-value pair is optional.

portNumber

TCP port for the StreamBase client API to listen on. This name-value pair is optional and its default value is 10000. As a TCP port number, its range is between 0 and 65535.

For example:

portNumber = 9999
secure

A secure-transport indicator. If true, use TLS to secure communication to the client; if false do not. Enabling secure communication requires that the engine have a secure communication configuration, or this indicator value is ignored. This name-value pair is optional and its default value is false.

For example:

secure = false
pagePool

Connection page pool configuration. This name-value pair 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 name-value pair 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 name-value pair 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 name-value pair 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 name-value pair is optional.

For example:

maxClientPages = 4K
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 name-value pair 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 name-value pair is optional and its default value is -1, meaning no limit.

For example:

maxPersistentConnections = 10
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 clientHeartbeatIntervalMilliseconds to zero will disable heartbeats from the server. Clients connected to such a server will not have heartbeat protection, regardless of their locally configured minimum heartbeat interval.

This name-value pair is optional and its default value is 10000.

For example:

clientHeartbeatIntervalMilliseconds = 10001
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 name-value pair 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 name-value pair 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 name-value pair is optional and its default value is 60000.

For example:

idleClientCheckIntervalMilliseconds = 60001

HOCON Configuration File Sample

The following is an example of the com.tibco.ep.streambase.configuration.sbclientapilistener type.

name = "myapilistenersettings"
version = "1.0.0"
type = "com.tibco.ep.streambase.configuration.sbclientapilistener"
configuration = 
  ClientAPIListener = {

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

    apiListenerAddress = {

      portNumber = 9999
      secure = false
    }

   pagePool = {

      pageSize = 6K
      maxPooledBuffers = 2048
      slowDequeueClientWaitMilliseconds = 100
 
      maxClientPages = 4K
    }

    connectionBacklog = 11
    maxPersistentConnections = 10
    clientHeartbeatIntervalMilliseconds = 10001
    idleEnqueueClientTimeoutMilliseconds = 1000
    idleDequeueClientTimeoutMilliseconds = 2000

    idleClientCheckIntervalMilliseconds = 60001
  }
}