LiveView Client API Listener Configuration

< Previous		Next >

Overview

This article provides a reference for writing a LiveView Client API Listener configuration file where the HOCON type is com.tibco.ep.ldm.configuration.ldmclientapilistener.

The LiveView client API listener configuration defines port numbers and secure communication indicators. It is separate from the base StreamBase 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 = "my-ldm-api-settings"

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.ldm.configuration.ldmclientapilistener"

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 the LiveView Client API listener configuration settings.

associatedWithEngines

If you want to manually 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 apply to more than one engine. This array is optional and has no default value. If not present, the configuration uses a default engine association based on its location in a fragment or application archive, or in a node deploy configuration.

For example:

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

portNumber

Specifies the TCP port on which the current LiveView 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 LiveView engine to find a random unused port to listen on.

Starting with TIBCO Streaming 10.6.0, the client connection port for LiveView is determined as follows:

Both in Studio and on the command line with epadmin, a port specified in a configuration file with this ClientAPIListener > portNumber property is always honored first.
If there is no configuration definition, the LiveView engine tests port 10080 and uses it, if available.
If that port is busy, the engine tries 10081 and uses it, if available.
If that port is busy, the engine tries 10082 and so on.
For Studio launches, once a port is selected, Studio communicates that port to the Runtime.

If your project has architectural or legacy reasons to specify a particular port, use this ClientAPIListener > portNumber property in a configuration file in the Studio project's /src/main/configurations folder at node installation time.

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 = 10080

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

Note

In previous TIBCO Streaming releases, the default value of 10080 was set for connections to be made with lv:// or http://, and 10443 for connections to be made with lvs:// or https://. Those defaults and the distinction for the connecting protocol are no longer valid.

authenticationRealmName

Authentication realm associated with this listener, indicating that user authentication is to be performed for requests handled by this listener. This realm name is specified in the com.tibco.ep.dtm.configuration.security file.

This optional property has no default value. When you provide one, LiveView server authentication is enabled for the realm.

For example:

authenticationRealmName = "my-realm"

secureCommunicationProfileName

Name of a secure communication server profile to use when configuring secure communication for a listener. The profile must be defined in the secureCommunicationProfileName property in a separate configuration file of type com.tibco.ep.dtm.configuration.security.

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-client-profile"

HOCON Configuration File Sample

The following shows an example of the com.tibco.ep.ldm.configuration.ldmclientapilistener type.

name = "clientApiListener"
version = "1.0.0"
type = "com.tibco.ep.ldm.configuration.ldmclientapilistener"
configuration = {
  ClientAPIListener = {
    portNumber = 10080    
    authenticationRealmName = "authRealm"
    secureCommunicationProfileName = "my-secure-communication-client-profile"    
  }
}