Class
caplin.streamlink

StreamLink

The main StreamLink Class.

To create an instance of this class, use the caplin.streamlink.StreamLinkFactory.

You can obtain an instance of this interface by calling the create() method on the caplin.streamlink.StreamLinkFactory object.

Constructor Summary

Attributes Name and Description
caplin.streamlink.StreamLink()

Method Summary

Attributes Name and Description
void addConnectionListener(caplin.streamlink.ConnectionListener connectionListener)

Adds a connection listener with this StreamLink instance.

void connect()

Instructs this StreamLink instance to attempt to connect to the Liberator.

caplin.streamlink.Channel createChannel(String subject, caplin.streamlink.ChannelListener channelListener, Map commandParameters)

Creates a Channel for the specified subject on the Liberator.

caplin.streamlink.CommandSubscription createSubject(String subject, caplin.streamlink.SubjectType subjectType, caplin.streamlink.CommandListener commandListener, Map commandParameters)

Creates a subject in the Liberator.

caplin.streamlink.WebRequestParameters createWebRequestParameters(String moduleName, Map options)

Creates a WebRequestParameters object for the specified Liberator web module.

void deleteSubject(String subject, caplin.streamlink.CommandListener commandListener)

Deletes a subject in the Liberator.

void disconnect()

Instructs this StreamLink instance to disconnect from the Liberator.

void getLastLog()

Returns an array containing the last "log_buffer_size" log lines written by the current {caplin.streamlink.StreamLink} instance.

caplin.streamlink.Logger getLogger()

Returns the StreamLink logger object.

void getVersion()

Gets the version of StreamLink JavaScript.

void networkAvailable()

Informs StreamLink the network connection is available so can connect.

void networkUnavailable()

Informs StreamLink the network connection is unavailable so it will not try to connect.

void pause()

Pauses StreamLink so it does not receive new updates from the Liberator.

caplin.streamlink.CommandSubscription publishToSubject(String subject, Map fieldData, caplin.streamlink.CommandListener commandListener, Map commandParameters)

Publishes data to a subject.

void removeConnectionListener(caplin.streamlink.ConnectionListener connectionListener)

Removes a previously added caplin.streamlink.ConnectionListener from this StreamLink instance.

void resume()

Re-establishes the connection to the Liberator to receive updates.

void snapshot(String subject, caplin.streamlink.SubscriptionListener subscriptionListener, Map subscriptionParameters)

Requests a single update from a subject.

caplin.streamlink.Subscription subscribe(String subject, caplin.streamlink.SubscriptionListener subscriptionListener, Map subscriptionParameters)

Subscribes to a subject to receive updates.

caplin.streamlink.CommandSubscription throttleEverything(caplin.streamlink.ThrottleCommand throttleCommand, caplin.streamlink.CommandListener commandListener, Map commandParameters)

Throttles all the currently subscribed subjects, reducing the number of updates that are sent every second.

caplin.streamlink.CommandSubscription throttleSubject(String subject, caplin.streamlink.ThrottleCommand throttleCommand, caplin.streamlink.CommandListener commandListener, Map commandParameters)

Throttles the specified subject, reducing the number of updates that are sent every second.

Constructor Detail

caplin.streamlink.StreamLink()

Method Detail

void addConnectionListener(caplin.streamlink.ConnectionListener connectionListener)

Adds a connection listener with this StreamLink instance. This connectionListener is called whenever a connection event occurs.

Parameters
caplin.streamlink.ConnectionListener connectionListener The ConnectionListener to be added.

void connect()

Instructs this StreamLink instance to attempt to connect to the Liberator.

When a caplin.streamlink.ConnectionListener has been registered with this StreamLink instance, the listener's methods are called when the status of the connection changes.

caplin.streamlink.Channel createChannel(String subject, caplin.streamlink.ChannelListener channelListener, Map commandParameters)

Creates a Channel for the specified subject on the Liberator.

Use the returned channel to send and receive data as maps of name/value pairs.

The commandParameters argument takes the following JSON configuration attributes:
Attribute name Type Default Optional Description
persistent boolean false Yes

When true, the latest channel record data sent persists across a failure of the connection to Liberator and subsequent reconnection.

When false, the record data only applies to the current Liberator session and does not persist following a connection failure.

For a fuller explanation, see the 'Persistence' section of the StreamLink Overview document.

cancellable boolean false Yes

Sets the sending of record data associated with this channel to be cancelled in the event that the connection goes down before it is sent.

Parameters
String subject the Liberator subject that will be used for this channel.
caplin.streamlink.ChannelListener channelListener to receive data, status and error messages from the channel.
Map commandParameters Optional JSON configuration attributes.
Returns
{caplin.streamlink.Channel} channel object that can be used to send and receive data as maps of name/value pairs.

caplin.streamlink.CommandSubscription createSubject(String subject, caplin.streamlink.SubjectType subjectType, caplin.streamlink.CommandListener commandListener, Map commandParameters)

Creates a subject in the Liberator.

The commandParameters argument takes the following JSON configuration attributes:
Attribute name Type Default Optional Description
persistent boolean false Yes

Sets the command associated with these parameters to be persistent. This deals with the situation where the connection to the Liberator server has been lost, and on subsequent reconnection StreamLink must create a brand new user session and log in to Liberator again. When this happens, the "persistent" command is automatically re-sent to the Liberator.

cancellable boolean false Yes

Sets the command associated with these parameters to be cancelled in the event that the connection goes down before it is sent.

Parameters
String subject The name of the subject to create.
caplin.streamlink.SubjectType subjectType The type of subject to create.
caplin.streamlink.CommandListener commandListener A listener that is called to provide information about the result of the "create subject" command.
Map commandParameters Optional JSON configuration attributes.
Returns
{caplin.streamlink.CommandSubscription} Information about the 'create subject' command. If the commandParameters made the command persistent, you can subsequently cancel this by calling the CommandSubscription's unPersist() method.

caplin.streamlink.WebRequestParameters createWebRequestParameters(String moduleName, Map options)

Creates a WebRequestParameters object for the specified Liberator web module.

The returned WebRequestParameters object contains the URL and HTTP post body that should be used to access the required web module.

Parameters
String moduleName the name of the Liberator web module.
Map options a map of named options that the web module accepts.
Returns
{caplin.streamlink.WebRequestParameters} an object of type WebRequestParameters or null if the module is not available or the options are invalid.

void deleteSubject(String subject, caplin.streamlink.CommandListener commandListener)

Deletes a subject in the Liberator.

Parameters
String subject The name of the subject to delete.
caplin.streamlink.CommandListener commandListener A listener that is called to provide information about the result of the 'delete subject' command.

void disconnect()

Instructs this StreamLink instance to disconnect from the Liberator.

void getLastLog()

Returns an array containing the last "log_buffer_size" log lines written by the current {caplin.streamlink.StreamLink} instance. If log_buffer_size is not set or <= 0 then the log buffer is disabled and this method will always return an empty array

Returns
An array containing the last "log_buffer_size" log lines written by this instance, or an empty array if "log_buffer_size" is not set

caplin.streamlink.Logger getLogger()

Returns the StreamLink logger object. You can receive StreamLink log messages by adding your own caplin.streamlink.LogListener to this object.

Returns
{caplin.streamlink.Logger} The StreamLink logger.

void getVersion()

Gets the version of StreamLink JavaScript.

Returns
String The version number and build identifier for this version of the StreamLink library.

void networkAvailable()

Informs StreamLink the network connection is available so can connect.

void networkUnavailable()

Informs StreamLink the network connection is unavailable so it will not try to connect.

void pause()

Pauses StreamLink so it does not receive new updates from the Liberator. The KeyMaster session will be kept alive.

This method can be used as part of your applications lifecycle to conserve battery life and reduce data usage by not receiving data when your application is in the background.

caplin.streamlink.CommandSubscription publishToSubject(String subject, Map fieldData, caplin.streamlink.CommandListener commandListener, Map commandParameters)

Publishes data to a subject.

The commandParameters argument takes the following JSON configuration attributes:
Attribute name Type Default Optional Description
persistent boolean false Yes

When true, if the connection to the Liberator fails after publication, the data is resent when StreamLink reconnects.

When false, if the connection to the Liberator fails after publication, the data is not resent when StreamLink reconnects.

cancellable boolean false Yes

Sets the command associated with these parameters to be cancelled in the event that the connection goes down before it is sent.

Parameters
String subject The subject to publish to.
Map fieldData The data, as key-value pairs, to be published to the subject.
caplin.streamlink.CommandListener commandListener A listener that receives notification of the publish command's success or failure.
Map commandParameters Optional JSON configuration attributes.
Returns
{caplin.streamlink.CommandSubscription} Information about the 'publish' command. If the commandParameters made the command persistent, you can subsequently cancel this by calling the CommandSubscription's unPersist() method.

void removeConnectionListener(caplin.streamlink.ConnectionListener connectionListener)

Removes a previously added caplin.streamlink.ConnectionListener from this StreamLink instance. After removal, no further callbacks are received by this ConnectionListener.

Parameters
caplin.streamlink.ConnectionListener connectionListener The ConnectionListener to be removed.

void resume()

Re-establishes the connection to the Liberator to receive updates.

This method can be used as part of your applications lifecycle to conserve battery life and reduce data usage by not receiving data when your application is in the background.

void snapshot(String subject, caplin.streamlink.SubscriptionListener subscriptionListener, Map subscriptionParameters)

Requests a single update from a subject.

The subscriptionParameters argument takes the following JSON configuration attributes:
Attribute name Type Default Optional Description
structureonly boolean false Yes If this value is set, the subscription will not provide field data updates
keepinaccessible boolean false Yes If this value is set, the container will keep elements that are unavailable.
fields [string] All fields are subscribed to. Yes An array of the the fields to subscribe to.

For example: ["field_a","field_b","field_d"]

filter {value: string, image: boolean} No filter is applied. Yes A filter that restricts the number of field updates that will be received.

The value string specifies the filter criteria. For example: (dLast >50) & (dVolumeAcc > 1000)/code>, means that the Liberator sends updates only when the value of the field dLast is greater than 50 and the dVolumeAcc field is greater than 1000.

When the image boolean is true, the filter not applied until after the data within a particular update has been applied to the image of the data item. When image is false, the update filter is applied just to the data within a particular update of the data item.

For more information about filters, see the 'Filtering data' section of the document StreamLink Overview.

window {start: int, size: int} Updates are returned for the whole container (subject to any filter applied). Yes When the subscription is to a container, this attribute defines a window that begins at the element defined by start, and is size elements long. Liberator only returns updates for the elements that are in the window. The first element in a container starts at position 0 (zero).
select {where: string, orderby: string, groupby: string} Updates are returned for the whole container in creation order. Yes When the subscription is to a container and the backend system is running Caplin Refiner, this attribute defines the selection and sorting applied to the container.

Parameters:

where: The where clause, in the form accepted by Caplin Refiner (example bid>123&ask<222). Use the caplin.streamlink.ContainerFilterFactory to help build valid where clauses.

orderby: The sorting order of the returned container in the form: field [ASC|DESC] [NUMBER|TEXT], ... example: bid DESC NUMBER,ask ASC NUMBER

groupby: The group by clause in the form: field example: bid

freeform [string] Free form string parameters. Yes Freeform subscription parameters allows you to pass parameters to subscriptions for subject types that are not records or containers. They can be used to define filter expressions for filtering news headlines. For more information about news headlines, and the syntax and rules for defining news filter expressions, see the "News filtering" section of the StreamLink Overview
json [string] jsonpath filter string parameter. Yes Sets the filter that restricts the the information returned by the subscription. The filtering is performed by the Liberator, rather than the client, so that bandwidth and client side processing are reduced.

For more details on the format of the filter string, please see https://goessner.net/articles/JsonPath/.

Parameters
String subject The subject to subscribe to.
caplin.streamlink.SubscriptionListener subscriptionListener A listener that is called to provide information about the result of the subscription request, the subscribed data, and subsequent updates to that data.
Map subscriptionParameters Optional JSON configuration attributes.

caplin.streamlink.Subscription subscribe(String subject, caplin.streamlink.SubscriptionListener subscriptionListener, Map subscriptionParameters)

Subscribes to a subject to receive updates.

The subscriptionParameters argument takes the following JSON configuration attributes:
Attribute name Type Default Optional Description
fields [string] All fields are subscribed to. Yes An array of the the fields to subscribe to.

For example: ["field_a","field_b","field_d"]

filter {value: string, image: boolean} No filter is applied. Yes A filter that restricts the number of field updates that will be received.

The value string specifies the filter criteria. For example: (dLast >50) & (dVolumeAcc > 1000)/code>, means that the Liberator sends updates only when the value of the field dLast is greater than 50 and the dVolumeAcc field is greater than 1000.

When the image boolean is true, the filter not applied until after the data within a particular update has been applied to the image of the data item. When image is false, the update filter is applied just to the data within a particular update of the data item.

For more information about filters, see the 'Filtering data' section of the document StreamLink Overview.

window {start: int, size: int} Updates are returned for the whole container (subject to any filter applied). Yes When the subscription is to a container, this attribute defines a window that begins at the element defined by start, and is size elements long. Liberator only returns updates for the elements that are in the window. The first element in a container starts at position 0 (zero).
freeform [string] Free form string parameters. Yes Freeform subscription parameters allows you to pass parameters to subscriptions for subject types that are not records or containers. They can be used to define filter expressions for filtering news headlines. For more information about news headlines, and the syntax and rules for defining news filter expressions, see the "News filtering" section of the StreamLink Overview
json [string] jsonpath filter string parameter. Yes Sets the filter that restricts the the information returned by the subscription. The filtering is performed by the Liberator, rather than the client, so that bandwidth and client side processing are reduced.

For more details on the format of the filter string, please see https://goessner.net/articles/JsonPath/.

select {where: string, orderby: string, groupby: string} Updates are returned for the whole container in creation order. Yes When the subscription is to a container and the backend system is running Caplin Refiner, this attribute defines the selection and sorting applied to the container.

Parameters:

where: The where clause, in the form accepted by Caplin Refiner (example bid>123&ask<222).
Use the caplin.streamlink.ContainerFilterFactory to build valid where clauses (see example below).

orderby: The sorting order of the returned container in the form: field [ASC|DESC] [NUMBER|TEXT], ... example: bid DESC NUMBER,ask ASC NUMBER

groupby: The group by clause in the form: field [,field] example: bid,ask

Container filtering example using the ContainerFilterFactory to build the where clause:


 // Build an expression for FIELD1 > 0.1 AND FIELD3 = "a a"
 var exp1 = caplin.streamlink.ContainerFilterFactory
   .create("FIELD1", caplin.streamlink.FilterExpressionOperator.GREATER_THAN, "0.1");
 var exp2 = caplin.streamlink.ContainerFilterFactory
   .create("FIELD3", caplin.streamlink.FilterExpressionOperator.EQUAL, "a a");
 var exp1Andexp2 = caplin.streamlink.ContainerFilterFactory
   .createLogical(caplin.streamlink.FilterExpressionLogicalOperator.AND, exp1, exp2);

 var subscription = streamLink.subscribe("/container", subscriptionListener,
                  {"select":
                         {
                             "where": exp1Andexp2.toFilterString(),
                             "orderby": "FIELD1"
                         }
                     });
 

Note: if you subscribe to a container multiple times, then include one or both of the configuration attributes window and select in each subscription to the container. The presence of either of these attributes indicates to StreamLink that the subject is a container, and causes StreamLink to add a sequential container-instance identifier to the subscription request. Liberator uses this identifier to support multiple subscriptions to the same container; without this identifier, only the first subscription to a container will have a container instance and receive updates. If you don't want to window or filter a container, then specify a window with a large size, for example window:{start:0, size:999999999}.

Parameters
String subject The subject to subscribe to.
caplin.streamlink.SubscriptionListener subscriptionListener A listener that is called to provide information about the result of the subscription request, the subscribed data, and subsequent updates to that data.
Map subscriptionParameters Optional JSON configuration attributes.
Returns
{caplin.streamlink.Subscription} Information about the subscription. You can unsubscribe (stop receiving updates) from a subscription using the unsubscribe() method on the returned Subscription object.

caplin.streamlink.CommandSubscription throttleEverything(caplin.streamlink.ThrottleCommand throttleCommand, caplin.streamlink.CommandListener commandListener, Map commandParameters)

Throttles all the currently subscribed subjects, reducing the number of updates that are sent every second.

For a fuller explanation of throttling, refer to the 'Throttling' section of the document StreamLink Overview.

Parameters
caplin.streamlink.ThrottleCommand throttleCommand The throttle command to apply.
caplin.streamlink.CommandListener commandListener A listener that is called to provide information about the result of the throttle command.
Map commandParameters Optional JSON configuration attributes; for details, see the commandParameters parameter of throttleSubject().
Returns
{caplin.streamlink.CommandSubscription} Information about the 'throttle' command. If the commandParameters made the command persistent, you can subsequently cancel this by calling the CommandSubscription's unPersist() method.

caplin.streamlink.CommandSubscription throttleSubject(String subject, caplin.streamlink.ThrottleCommand throttleCommand, caplin.streamlink.CommandListener commandListener, Map commandParameters)

Throttles the specified subject, reducing the number of updates that are sent every second.

For a fuller explanation of throttling, refer to the 'Throttling' section of the document StreamLink Overview.

The commandParameters argument takes the following JSON configuration attributes:
Attribute name Type Default Optional Description
persistent boolean false Yes

When true, the throttle setting for this command persists across a failure of the connection to Liberator and subsequent reconnection.

When false, the throttle setting only applies to the current Liberator session and does not persist following a connection failure.

For a fuller explanation, see the 'Persistence' section of the StreamLink Overview document.

cancellable boolean false Yes

Sets the command associated with these parameters to be cancelled in the event that the connection goes down before it is sent.

Parameters
String subject The subject for which received data updates are to be throttled.
caplin.streamlink.ThrottleCommand throttleCommand The Throttle command to apply.
caplin.streamlink.CommandListener commandListener A listener that is called to provide information about the result of the throttle command.
Map commandParameters Optional JSON configuration attributes.
Returns
{caplin.streamlink.CommandSubscription} Information about the 'throttle' command. If the commandParameters made the command persistent, you can subsequently cancel this by calling the CommandSubscription's unPersist() method.