- Index

< Previous |  | Next >

# 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. This property is optional and its default value is 10000. As a TCP port number, its range is between 0 and 65535.

      For example:

          portNumber = 9999

  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

## 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
        authenticationRealmName = "my-realm"
        }
        pagePool = {
          pageSize = 6K
          maxPooledBuffers = 2048
          slowDequeueClientWaitMilliseconds = 100
          maxClientPages = 4K
        }
        connectionBacklog = 11
        maxPersistentConnections = 10
        clientHeartbeatIntervalMilliseconds = 10001
        idleEnqueueClientTimeoutMilliseconds = 1000
        idleDequeueClientTimeoutMilliseconds = 2000

        idleClientCheckIntervalMilliseconds = 60001
      }
    }