com.caplin.streamlink

Interface StreamLink

public interface StreamLink

Defines the StreamLink interface.

You can obtain an instance of this interface by calling one of the create() methods on the StreamLinkFactory object.

Method Summary

Methods

Modifier and Type	Method and Description
void	addConnectionListener(ConnectionListener listener) Adds a connection listener with this StreamLink instance.
void	connect() Instructs this StreamLink instance to attempt to connect to the Liberator.
Channel	createChannel(java.lang.String subject, ChannelListener listener, CommandParameters parameters) Creates a Channel for the specified subject on the Liberator.
CommandParameters	createCommandParameters() Creates a set of CommandParameters which can be used to set a command to be persistent.
ContainerSubscriptionParameters	createContainerSubscriptionParameters() Creates a parameters object for a container subscription.
FreeFormSubscriptionParameters	createFreeFormSubscriptionParameters() Creates a parameters object for subscriptions.
RecordSubscriptionParameters	createRecordSubscriptionParameters() Creates a parameters object for a record subscription.
void	createSubject(java.lang.String subject, SubjectType subjectType, CommandListener commandListener) Creates a subject on the Liberator.
CommandSubscription	createSubject(java.lang.String subject, SubjectType subjectType, CommandListener commandListener, CommandParameters commandParameters) Creates a subject on the Liberator.
WebRequestParameters	createWebRequestParameters(java.lang.String moduleName, java.util.Map<java.lang.String,java.lang.String> options) Creates a WebRequestParameters object for the specified Liberator web module.
void	deleteSubject(java.lang.String subject, CommandListener commandListener) Deletes a subject on the Liberator.
void	disconnect() Instructs this StreamLink instance to disconnect from the Liberator.
java.util.List<LogInfo>	getLastLog() Returns a List containing the last "log_buffer_size" log lines written by the current StreamLink instance.
Logger	getLogger() Returns the StreamLink logger object.
java.lang.String	getVersion() Gets the version of StreamLink.
void	networkAvailable() Informs StreamLink the network is available.
void	networkUnavailable() Informs StreamLink the network is unavailable.
void	pause() Pauses StreamLink so it does not receive new updates from the Liberator.
void	publishToSubject(java.lang.String subject, java.util.Map<java.lang.String,java.lang.String> fieldData, CommandListener commandListener) Publishes data to a subject.
CommandSubscription	publishToSubject(java.lang.String subject, java.util.Map<java.lang.String,java.lang.String> fieldData, CommandListener commandListener, CommandParameters commandParameters) Publishes data to a subject.
void	removeConnectionListener(ConnectionListener listener) Removes a previously added ConnectionListener from this StreamLink instance.
void	resume() Re-establishes the connection to the Liberator to receive updates.
void	snapshot(java.lang.String subject, SubscriptionListener subscriptionListener) Requests a single update from a subject.
void	snapshot(java.lang.String subject, SubscriptionListener subscriptionListener, SubscriptionParameters subscriptionParameters) Requests a single update from a subject.
Subscription	subscribe(java.lang.String subject, SubscriptionListener subscriptionListener) Subscribes to a subject to receive updates.
Subscription	subscribe(java.lang.String subject, SubscriptionListener subscriptionListener, SubscriptionParameters subscriptionParameters) Subscribes to a subject to receive updates.
void	throttleEverything(ThrottleCommand command, CommandListener commandListener) Throttles all the currently subscribed subjects, reducing the number of updates that are sent every second.
CommandSubscription	throttleEverything(ThrottleCommand command, CommandListener commandListener, CommandParameters commandParameters) Throttles all the currently subscribed subjects, reducing the number of updates that are sent every second.
void	throttleSubject(java.lang.String subject, ThrottleCommand command, CommandListener commandListener) Throttles the specified subject, reducing the number of updates that are sent every second.
CommandSubscription	throttleSubject(java.lang.String subject, ThrottleCommand command, CommandListener commandListener, CommandParameters commandParameters) Throttles the specified subject, reducing the number of updates that are sent every second.

Method Detail

connect

void connect()

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

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

disconnect

void disconnect()

Instructs this StreamLink instance to disconnect from the Liberator.

addConnectionListener

void addConnectionListener(ConnectionListener listener)

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

Parameters:

connectionListener - - The ConnectionListener to be added.

removeConnectionListener

void removeConnectionListener(ConnectionListener listener)

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

Parameters:

connectionListener - - The ConnectionListener to remove.

createRecordSubscriptionParameters

RecordSubscriptionParameters createRecordSubscriptionParameters()

Creates a parameters object for a record subscription.

A RecordSubscriptionParameters allows a subscription to a record subject to be restricted to a specified set of fields. It can also filter updates so that they are only received when the specified condition has been met.

Returns:

A new set of RecordSubscriptionParameters.

createContainerSubscriptionParameters

ContainerSubscriptionParameters createContainerSubscriptionParameters()

Creates a parameters object for a container subscription.

A ContainerSubscriptionParameters allows the container window to be set, restricting the number of elements that are subscribed to.

Returns:

A new set of ContainerSubscriptionParameters

createFreeFormSubscriptionParameters

FreeFormSubscriptionParameters createFreeFormSubscriptionParameters()

Creates a parameters object for subscriptions.

Most of the SubjectTypes supported by the Liberator can be subscribed to with parameters. A set of FreeFormSubscriptionParameters can be used to pass parameters to subscription requests for SubjectTypes that do not have a dedicated subscription parameters implementation. At present, these would be used for News headline subject. For details on the format please consult the news filtering subsection of the StreamLink Overview document.

Returns:

A new set of FreeFormSubscriptionParameters.

createCommandParameters

CommandParameters createCommandParameters()

Creates a set of CommandParameters which can be used to set a command to be persistent.

Returns:

A new set of CommandParameters.

subscribe

Subscription subscribe(java.lang.String subject,
                     SubscriptionListener subscriptionListener,
                     SubscriptionParameters subscriptionParameters)

Subscribes to a subject to receive updates.

Parameters:

subject - The subject to subscribe to.

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.

subscriptionParameters - A set of parameters for this subscription.

Returns:

Information about the subscription. You can unsubscribe (stop receiving updates) from a subscription using the unsubscribe() method on the returned Subscription object.

A SubscriptionParameters object can be obtained by calling one of the following methods:

• com.caplin.streamlink.StreamLink.createRecordSubscriptionParameters()
- that returns a RecordSubscriptionParameters object that is used to create parameters for record subjects.
• com.caplin.streamlink.StreamLink.createContainerSubscriptionParameters()
- that returns a ContainerSubscriptionParameters object that is used to create parameters for container subjects.
• com.caplin.streamlink.StreamLink.createFreeFormSubscriptionParameters()
- that returns a FreeFormSubscriptionParameters object that is used to create parameters for other subject types.

subscribe

Subscription subscribe(java.lang.String subject,
                     SubscriptionListener subscriptionListener)

Subscribes to a subject to receive updates.

Parameters:

subject - The subject to subscribe to.

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.

Returns:

Information about the subscription. You can unsubscribe (stop receiving updates) from a subscription using the unsubscribe() method on the returned Subscription object.

snapshot

void snapshot(java.lang.String subject,
            SubscriptionListener subscriptionListener,
            SubscriptionParameters subscriptionParameters)

Requests a single update from a subject.

Parameters:

subject - The subject to subscribe to.

subscriptionListener - A listener that is called to provide information about the result of the subscription request, the subscribed data.

subscriptionParameters - A set of parameters for this subscription.

A SubscriptionParameters object can be obtained by calling one of the following methods:

• com.caplin.streamlink.StreamLink.createRecordSubscriptionParameters()
- that returns a RecordSubscriptionParameters object that is used to create parameters for record subjects.
• com.caplin.streamlink.StreamLink.createContainerSubscriptionParameters()
- that returns a ContainerSubscriptionParameters object that is used to create parameters for container subjects.
• com.caplin.streamlink.StreamLink.createFreeFormSubscriptionParameters()
- that returns a FreeFormSubscriptionParameters object that is used to create parameters for other subject types.

snapshot

void snapshot(java.lang.String subject,
            SubscriptionListener subscriptionListener)

Requests a single update from a subject.

Parameters:

subject - The subject to subscribe to.

subscriptionListener - A listener that is called to provide information about the result of the subscription request, the subscribed data.

createSubject

CommandSubscription createSubject(java.lang.String subject,
                                SubjectType subjectType,
                                CommandListener commandListener,
                                CommandParameters commandParameters)

Creates a subject on the Liberator.

Parameters:

subject - The name of the subject to create.

subjectType - The type of subject to create.

commandListener - A listener that is called to provide information about the result of the "create subject" command.

commandParameters - Additional parameters for the command (for example to make the command persistent).

Returns:

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.

createSubject

void createSubject(java.lang.String subject,
                 SubjectType subjectType,
                 CommandListener commandListener)

Creates a subject on the Liberator.

Parameters:

subject - The name of the subject to create.

subjectType - The type of subject to create.

commandListener - A listener that is called to provide information about the result of the "create subject" command.

deleteSubject

void deleteSubject(java.lang.String subject,
                 CommandListener commandListener)

Deletes a subject on the Liberator.

Parameters:

subject - The name of the subject to delete.

commandListener - A listener that is called to provide information about the result of the "delete subject" command.

publishToSubject

CommandSubscription publishToSubject(java.lang.String subject,
                                   java.util.Map<java.lang.String,java.lang.String> fieldData,
                                   CommandListener commandListener,
                                   CommandParameters commandParameters)

Publishes data to a subject.

Parameters:

subject - The subject to publish to.

fieldData - The data, as key-value pairs, to be published to the subject.

commandListener - A listener that receives notification of the publish command's success or failure.

commandParameters - Additional parameters for the command (for example to make the command persistent).

Returns:

Information about the 'publish' command. If the parameters made the command persistent, you can subsequently cancel this by calling the CommandSubscription's unPersist() method.

publishToSubject

void publishToSubject(java.lang.String subject,
                    java.util.Map<java.lang.String,java.lang.String> fieldData,
                    CommandListener commandListener)

Publishes data to a subject.

Parameters:

subject - The subject to publish to.

fieldData - The data, as key-value pairs, to be published to the subject.

commandListener - A listener that receives notification of the publish command's success or failure.

throttleSubject

CommandSubscription throttleSubject(java.lang.String subject,
                                  ThrottleCommand command,
                                  CommandListener commandListener,
                                  CommandParameters 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.

Parameters:

subject - The subject for which received data updates are to be throttled.

command - The Throttle command to apply.

commandListener - A listener that is called to provide information about the result of the throttle command.

commandParameters - Additional parameters for the command (for example to make the command persistent).

Returns:

Information about the 'throttle' command. If the parameters made the command persistent, you can subsequently cancel this by calling the CommandSubscription's unPersist() method.

throttleSubject

void throttleSubject(java.lang.String subject,
                   ThrottleCommand command,
                   CommandListener commandListener)

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.

Parameters:

subject - The subject for which received data updates are to be throttled.

command - The Throttle command to apply.

commandListener - A listener that is called to provide information about the result of the throttle command.

throttleEverything

CommandSubscription throttleEverything(ThrottleCommand command,
                                     CommandListener commandListener,
                                     CommandParameters 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:

command - The throttle command to apply.

commandListener - A listener that is called to provide information about the result of the throttle command.

commandParameters - Additional parameters for the command (for example to make the command persistent).

Returns:

Information about the 'throttle' command. If the parameters made the command persistent, you can subsequently cancel this by calling the CommandSubscription's unPersist() method.

throttleEverything

void throttleEverything(ThrottleCommand command,
                      CommandListener commandListener)

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:

command - The throttle command to apply.

listener - A listener that is called to provide information about the result of the throttle command.

networkAvailable

void networkAvailable()

Informs StreamLink the network is available.

networkUnavailable

void networkUnavailable()

Informs StreamLink the network is unavailable. If StreamLink is connected to the Liberator, it will disconnect.

pause

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 application's lifecycle to conserve battery life and reduce data usage by not receiving data when your application is in the background.

resume

void resume()

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

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

getLogger

Logger getLogger()

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

Returns:

The StreamLink logger.

getVersion

java.lang.String getVersion()

Gets the version of StreamLink.

Returns:

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

createWebRequestParameters

WebRequestParameters createWebRequestParameters(java.lang.String moduleName,
                                              java.util.Map<java.lang.String,java.lang.String> 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.

The following example shows how the WebRequestParameters can be used to obtain the response text from a web module.

                Map options = new HashMap();
                options.put("export", "/container");
                options.put("fields", "FIELD1,FIELD2");
                options.put("filename", "export.csv");
                
                WebRequestParameters wrp = streamLink.createWebRequestParameters("blotterexport", options);
                
                URL server = new URL(wrp.getUrl());
                HttpURLConnection connection = (HttpURLConnection)server.openConnection();
                connection.setDoInput(true);
                connection.setDoOutput(true);
                connection.setRequestMethod("POST");
                connection.setRequestProperty("Content-Type", "text/plain");
                
                connection.connect();
                OutputStreamWriter writer = new OutputStreamWriter(connection.getOutputStream(), "UTF-8");
                writer.write(wrp.getPostBody());
                writer.close();

                // Response
                BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream(), "UTF-8"));
                StringBuilder sb = new StringBuilder();
                String line = in.readLine();
                while (line != null)
                {
                        sb.append(line + "\n");
                        line = in.readLine();
                }
                
                connection.getInputStream().close();
                connection.disconnect();
                
                System.out.println(sb.toString());
 

Parameters:

moduleName - the name of the Liberator web module.

options - a map of named options that the web module accepts.

Returns:

an object of type WebRequestParameters or null if the module is not available or the options are invalid.

getLastLog

java.util.List<LogInfo> getLastLog()

Returns a List containing the last "log_buffer_size" log lines written by the current 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:

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

createChannel

Channel createChannel(java.lang.String subject,
                    ChannelListener listener,
                    CommandParameters parameters)

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.

Parameters:

subject - the Liberator subject that will be used for this channel.

channelListener - to receive data, status and error messages from the channel.

commandParameters - command parameters object that will be used on all sends to the channel, can be null.

Returns:

channel object that can be used to send and receive data as maps of name/value pairs.