StreamBase Client API Listener Configuration

Contents

Overview
Required Header Lines
HOCON Properties Explained
HOCON Configuration File Sample

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

Specifies the TCP port on which the current EventFlow engine is to listen for client connections. This property is optional and has no default value. The port range is 1025 – 65535, inclusive. A zero value directs the EventFlow engine to find a random, unused port to listen on.

Starting with TIBCO Streaming 10.6.0, the client connection port for EventFlow engines is determined at engine startup to use a random, unused port. This means the default value for portNumber is effectively zero.

It is a best practice using the cluster- and node-aware epadmin administration tool, which allows administrators to avoid knowing or using an EventFlow engine's listening port. However, if your project has architectural or legacy reasons to specify a particular port, use this ClientAPIListener > apiListenerAddress > portNumber property in a configuration file in the Studio project's /src/main/configurations folder at node installation time. You can also set a port number in a Studio run configuration, potentially overriding a port defined in a configuration file.

For a running node, you can upload but cannot activate a configuration that specifies a portNumber. The engine that has affinity with the configuration must be stopped to activate such a configuration.

For example: 

portNumber = 10020

Note that the Client API listener port for LiveView fragments is determined with a different algorithm, as described on this page.

Note

In previous releases, the default value of 10000 for portNumber was assumed. Most legacy administration tools such as sbc and sbadmin still presume that default. However, starting with release 10.6.0, there is no longer a default value for the StreamBase client API listener port.

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 = "ldaprealm"
pagePool

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

Note that the product of pageSize * maxClientPages must be a number smaller than or equal to 2^31 - 1 (2147483647).

pageSize

Use this property to determine the initial size for output buffers; pageSize is also used to calculate the maximum size a client output queue can grow to before the client is disconnected. Refer to maxClientPages property for related information. The pageSize property is optional, its default value is 4096 bytes, and its maximum value is 16384.

The pageSize value specifies the memory allocation granularity and should stay small, on the order of 4K to 8K. To provide additional queue space for your connecting clients, increase only the maxClientPages value.

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

For example: 

pageSize = 4K
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

This property controls the maximum number of pages that a dequeuing client connection can allocate. Depending on the value of slowDequeueClientWaitMilliseconds the engine will either disconnect the slow client or BLOCK. This property is used to protect the StreamBase engine from slow or hung dequeuing clients. With the default page size of4096 bytes, the default maxClientPages value of 2048 provides 8 megabytes.

To allow all dequeuing clients to allocate unlimited memory in the StreamBase engine, set the value to 0. Note that the number of pages that a client allocates will change over time. A client that is consuming tuples as quickly as the engine produces them will only use 1 or 2 pages. The max can be reached with a slow or hung client or if there is a large spike of output data. This property is optional and its default value is 4096.

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

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 = 60000
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 = 20
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 that has enqueued at least one tuple and has been idle for idleEnqueueClientTimeoutMilliseconds.

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 = 10000
idleDequeueClientTimeoutMilliseconds

Int. Settings for disconnecting idle clients. An idle dequeue client is a client that 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 at which a client is disconnected is approximate, taking into account the idleClientCheckIntervalMilliseconds period.

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 = 5000
idleClientCheckIntervalMilliseconds

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

For example: 

idleClientCheckIntervalMilliseconds = 120000
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 = "tlsprofile"

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 = "ldaprealm"
    }
    pagePool = {
      pageSize = 6K
      maxPooledBuffers = 2048
      slowDequeueClientWaitMilliseconds = 100
      maxClientPages = 4K
    }
    connectionBacklog = 20
    maxPersistentConnections = 10
    clientHeartbeatIntervalMilliseconds = 60000
    idleEnqueueClientTimeoutMilliseconds = 10000
    idleDequeueClientTimeoutMilliseconds = 5000
    idleClientCheckIntervalMilliseconds = 120000
  }
}