Package 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 Details

    • 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.

    • createJsonSubscriptionParameters

      JsonSubscriptionParameters createJsonSubscriptionParameters()

      Creates a parameters object for a Json subscription.

      A JsonSubscriptionParameters allows a subscription to filter updates so that they are only received when the specified condition has been met.

      Returns:
      A new set of JsonSubscriptionParameters.

    • 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(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:

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

    • subscribe

      Subscription subscribe(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(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:

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

    • snapshot

      void snapshot(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(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(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(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(String subject, Map<String,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.

    • publishToJsonSubject

      CommandSubscription publishToJsonSubject(String subject, Object obj, CommandListener commandListener, CommandParameters commandParameters)

      Publishes JSON data to a subject.

      Parameters:
      subject - The subject to publish to.
      obj - The java object to serialize to json (using the installed JsonHandler) and send.
      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(String subject, Map<String,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.

    • publishToSubject

      CommandSubscription publishToSubject(String subject, List<STuple> fieldData, CommandListener commandListener, CommandParameters commandParameters)

      Publishes data to a subject.

      Parameters:
      subject - The subject to publish to.
      fieldData - The data, as a list of tuples, 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(String subject, List<STuple> fieldData, CommandListener commandListener)

      Publishes data to a subject.

      Parameters:
      subject - The subject to publish to.
      fieldData - The data, as a list of tuples, to be published to the subject.
      commandListener - A listener that receives notification of the publish command's success or failure.

    • create

      CommandSubscription create(String subject, CommandParameters parameters, CommandResultListener listener)

      Creates a subject.

      This method can be used to send a POST message to a configured REST endpoint.

      Parameters:
      subject - The name of the subject to create.
      parameters - command parameters.
      listener - A listener that is called to provide information about the result of the "create" command.

    • delete

      CommandSubscription delete(String subject, CommandParameters parameters, CommandResultListener listener)

      Deletes a subject.

      This method can be used to send a DELETE message to a configured REST endpoint.

      Parameters:
      subject - The name of the subject to delete.
      parameters - command parameters.
      listener - A listener that is called to provide information about the result of the "delete" command.

    • publish

      CommandSubscription publish(String subject, CommandParameters parameters, CommandResultListener listener)

      Publishes data to a subject.

      This method can be used to send a PUT message to a configured REST endpoint.

      Parameters:
      subject - The subject to publish to.
      parameters - command parameters.
      listener - A listener that receives notification of the publish command's success or failure.

    • throttleSubject

      CommandSubscription throttleSubject(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(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.
      commandListener - 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

      String getVersion()

      Gets the version of StreamLink.

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

    • createWebRequestParameters

      WebRequestParameters createWebRequestParameters(String moduleName, Map<String,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<String, String> options = new HashMap<String, String>();
                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

      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(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.
      listener - to receive data, status and error messages from the channel.
      parameters - 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.

    • createJsonChannel

      JsonChannel createJsonChannel(String subject, JsonChannelListener listener, CommandParameters parameters)

      Creates a JsonChannel for the specified subject on the Liberator.

      Use the returned channel to send and receive Json serialized Java objects.

      Parameters:
      subject - the Liberator subject that will be used for this channel.
      listener - to receive data, status and error messages from the channel.
      parameters - 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 Json serialized Java objects.

    • getCustomAttributes

      Map<String,String> getCustomAttributes()

    • getConnectionCurrentState

      ConnectionCurrentState getConnectionCurrentState()

      Returns information about the state of the current connection.

      Returns:
      {ConnectionCurrentState} object containing the current state of the connection, fields available are the latest values reported by the addConnectionListener callbacks.

    • registerRecordProvider

      RecordProviderHandle registerRecordProvider(String pattern, RecordProvider provider, CommandListener commandListener)

      Registers a provider of data for the given subject pattern

      Parameters:
      pattern - the subject glob pattern
      provider - the provider that will be called when requests for subjects matching the given pattern are received.
      commandListener - A listener that is called to provide information about the result of the registration.
      Returns:
      a ProviderHandle object.

    • registerJsonProvider

      JsonProviderHandle registerJsonProvider(String pattern, JsonProvider provider, CommandListener commandListener)

      Registers a provider of data for the given subject pattern

      Parameters:
      pattern - the subject glob pattern
      provider - the provider that will be called when requests for subjects matching the given pattern are received.
      commandListener - A listener that is called to provide information about the result of the registration.
      Returns:
      a ProviderHandle object.