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.
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
configurationfollowed by an open brace. Theconfigurationobject is a sibling of thename,version, andtypeidentifiers, 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 = { ... ... }
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 finds a random port to listen on.
If the port value is taken (including, however unlikely, a random port), the engine does not start.
If you specify a port on the epadmin command line (or in the Studio Run/Debug Configuration), you get it.
For example:
portNumber = 10020
- 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 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 either disconnects the slow client or blocks. 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 = 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"
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
}
}