lightstreamer 0.6 → 0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8c5dce2a119bf535faac9e10b36a13624cf57038
-  data.tar.gz: 64bd43f2f8e122608e552e23dfa38047a0e3b53f
+  metadata.gz: 67492665643def7bc43ea5ab072416c91d7e494d
+  data.tar.gz: 3f47646a1ff2d3c939c65588304e57234f893490
 SHA512:
-  metadata.gz: 3261d66e3032ff0f0d324b02e7efda9626fd9a207921247307cbc6d0cbb97698131d423185012ae1b1741af1c50e867a886b4ed5fe30d1093bc6e9c7ec85a7b5
-  data.tar.gz: a8ad81e667183f8d867162f0d0f2733ec7c9d15541508f22b94c34638f944d9343b9cea862bf0f7407475a141f487d281c45bff04644eed37c1c02990b8bd75a
+  metadata.gz: 7510f00c805e9f83758e91b82c8682f22472d9c367a5a348faa4e46c8422e479c530bd96210c5eced1d7f56537ad39df14b6cf30dbf9d1a4787e1ea16695e6e5
+  data.tar.gz: 184073f14a2e2d34b9f208201526d6357a991d2a4bb113f40da21f80b112a0487f1177c12a24bd715a0e0c5b81d59997d9b6d64b603cff9c7ef89069e0455e02

data/CHANGELOG.md

@@ -1,6 +1,26 @@
 # Lightstreamer Changelog
 
-### 0.6 — July 26, 2016
+### 0.7 — July 31, 2016
+
+- Refactored subscription handling to be more object-oriented, subscriptions are now created using
+  `Lightstreamer::Session#build_subscription` and there are new `#start`, `#stop` and `#unsilence` methods on
+  `Lightstreamer::Subscription` that control a subscription's current state
+- Added `Lightstreamer::Session#bulk_subscription_start` for efficiently starting a number of subscriptions at once
+- Added support for sending custom messages using `Lightstreamer::Session#send_message`, both synchronous and
+  asynchronous messages are supported, and the results of asynchronous messages can be checked using the new
+  `Lightstreamer::Session#on_message_result` callback
+- Added support for setting initial subscription data
+- Added support for changing a subscription's requested update frequency after it has been started
+- Added support for setting and altering the session's requested maximum bandwidth
+- Added support for requesting snapshots on subscriptions
+- Added `Lightstreamer::Session#session_id` to query the session ID
+- Added `Lightstreamer::Subscription#active` to query whether the subscription is active and streaming data
+- Stream connection bind requests are now sent to the custom control address if one was specified in the stream
+  connection header
+- The command-line client now prints the session ID following successful connection
+- Added —requested-maximum-bandwidth option
+
+### 0.6 — July 27, 2016
 
 - Switched to the `excon` HTTP library
 - Moved all subclasses of `Lightstreamer::LightstreamerError` into the `Lightstreamer::Errors` module

data/README.md

@@ -44,9 +44,9 @@ session = Lightstreamer::Session.new server_url: 'http://push.lightstreamer.com'
 session.connect
 
 # Create a new subscription that subscribes to thirty items and to four fields on each item
-subscription = Lightstreamer::Subscription.new items: (1..30).map { |i| "item#{i}" },
-                                               fields: [:ask, :bid, :stock_name, :time],
-                                               mode: :merge, adapter: 'QUOTE_ADAPTER'
+subscription = session.build_subscription items: (1..30).map { |i| "item#{i}" },
+                                          fields: [:ask, :bid, :stock_name, :time],
+                                          mode: :merge, adapter: 'QUOTE_ADAPTER'
 
 # Create a thread-safe queue
 queue = Queue.new
@@ -57,8 +57,8 @@ subscription.on_data do |subscription, item_name, item_data, new_values|
   queue.push item_data
 end
 
-# Activate the subscription
-session.subscribe subscription
+# Start streaming data for the subscription
+subscription.start
 
 # Loop printing out new data as soon as it becomes available on the queue
 loop do

data/lib/lightstreamer.rb

@@ -4,12 +4,14 @@ require 'uri'
 
 require 'lightstreamer/cli/main'
 require 'lightstreamer/cli/commands/stream_command'
-require 'lightstreamer/control_connection'
 require 'lightstreamer/errors'
-require 'lightstreamer/line_buffer'
+require 'lightstreamer/messages/end_of_snapshot_message'
 require 'lightstreamer/messages/overflow_message'
+require 'lightstreamer/messages/send_message_outcome_message'
 require 'lightstreamer/messages/update_message'
+require 'lightstreamer/post_request'
 require 'lightstreamer/session'
+require 'lightstreamer/stream_buffer'
 require 'lightstreamer/stream_connection'
 require 'lightstreamer/stream_connection_header'
 require 'lightstreamer/subscription'

data/lib/lightstreamer/cli/commands/stream_command.rb

@@ -8,51 +8,57 @@ module Lightstreamer
       option :username, desc: 'The username for the session'
       option :password, desc: 'The password for the session'
       option :adapter_set, desc: 'The name of the adapter set for the session'
+      option :requested_maximum_bandwidth, type: :numeric, desc: 'The requested maximum bandwidth, in kbps'
       option :adapter, desc: 'The name of the data adapter to stream data from'
       option :items, type: :array, required: true, desc: 'The names of the item(s) to stream'
       option :fields, type: :array, required: true, desc: 'The field(s) to stream'
       option :mode, enum: %w(distinct merge), default: :merge, desc: 'The operation mode'
       option :selector, desc: 'The selector for table items'
+      option :snapshot, type: :boolean, desc: 'Whether to send snapshot data for the items'
       option :maximum_update_frequency, desc: 'The maximum number of updates per second for each item'
 
       def stream
-        session = create_session
-        session.connect
-
         @queue = Queue.new
 
-        session.subscribe create_subscription
+        create_session
+        create_subscription
 
         loop do
           puts @queue.pop unless @queue.empty?
 
-          raise session.error if session.error
+          raise @session.error if @session.error
         end
       end
 
       private
 
-      # Creates a new session from the specified options.
       def create_session
-        Lightstreamer::Session.new server_url: options[:server_url], username: options[:username],
-                                   password: options[:password], adapter_set: options[:adapter_set]
+        @session = Lightstreamer::Session.new session_options
+        @session.connect
+        @session.on_message_result(&method(:on_message_result))
+
+        puts "Session ID: #{@session.session_id}"
       end
 
-      # Creates a new subscription from the specified options.
       def create_subscription
-        subscription = Lightstreamer::Subscription.new subscription_options
+        subscription = @session.build_subscription subscription_options
 
         subscription.on_data(&method(:on_data))
         subscription.on_overflow(&method(:on_overflow))
+        subscription.on_end_of_snapshot(&method(:on_end_of_snapshot))
+
+        subscription.start
+      end
 
-        subscription
+      def session_options
+        { server_url: options[:server_url], username: options[:username], password: options[:password],
+          adapter_set: options[:adapter_set], requested_maximum_bandwidth: options[:requested_maximum_bandwidth] }
       end
 
       def subscription_options
-        {
-          items: options[:items], fields: options[:fields], mode: options[:mode], adapter: options[:adapter],
-          maximum_update_frequency: options[:maximum_update_frequency], selector: options[:selector]
-        }
+        { items: options[:items], fields: options[:fields], mode: options[:mode], adapter: options[:adapter],
+          maximum_update_frequency: options[:maximum_update_frequency], selector: options[:selector],
+          snapshot: options[:snapshot] }
       end
 
       def on_data(_subscription, item_name, _item_data, new_values)
@@ -62,6 +68,14 @@ module Lightstreamer
       def on_overflow(_subscription, item_name, overflow_size)
         @queue.push "Overflow of size #{overflow_size} on item #{item_name}"
       end
+
+      def on_message_result(sequence, numbers, error)
+        @queue.push "Message result for #{sequence}#{numbers} = #{error ? error.class : 'Done'}"
+      end
+
+      def on_end_of_snapshot(_subscription, item_name)
+        @queue.push "End of snapshot for item #{item_name}"
+      end
     end
   end
 end

data/lib/lightstreamer/errors.rb

@@ -95,6 +95,18 @@ module Lightstreamer
     class InvalidProgressiveNumberError < LightstreamerError
     end
 
+    # This error occurs when a send message request was refused as illegal by the metadata adapter.
+    class IllegalMessageError < LightstreamerError
+    end
+
+    # This error occurs when the elaboration of a sent message failed unexpectedly.
+    class MessageElaborationFailedError < LightstreamerError
+    end
+
+    # This error occurs when sent message(s) were not processed due to a timeout.
+    class MessagesSkippedByTimeoutError < LightstreamerError
+    end
+
     # This error is raised when the client version requested is not supported by the server.
     class ClientVersionNotSupportedError < LightstreamerError
     end
@@ -209,6 +221,10 @@ module Lightstreamer
       30 => Errors::SubscriptionsNotAllowedByLicenseError,
       32 => Errors::InvalidProgressiveNumberError,
       33 => Errors::InvalidProgressiveNumberError,
+      34 => Errors::IllegalMessageError,
+      35 => Errors::MessageElaborationFailedError,
+      38 => Errors::MessagesSkippedByTimeoutError,
+      39 => Errors::MessagesSkippedByTimeoutError,
       60 => Errors::ClientVersionNotSupportedError
     }.freeze
 

data/lib/lightstreamer/messages/end_of_snapshot_message.rb

@@ -0,0 +1,27 @@
+module Lightstreamer
+  # Helper class used by {Subscription} in order to parse incoming end-of-snapshot messages.
+  #
+  # @private
+  class EndOfSnapshotMessage
+    # The index of the item this end-of-snapshot message applies to.
+    #
+    # @return [Fixnum]
+    attr_accessor :item_index
+
+    class << self
+      # Attempts to parses the specified line as an end-of-snapshot message for the given table and items and returns an
+      # instance of {EndOfSnapshotMessage} on success, or `nil` on failure.
+      def parse(line, table_id, items)
+        message = new
+
+        match = line.match Regexp.new("^#{table_id},(\\d+),EOS$")
+        return unless match
+
+        message.item_index = match.captures[0].to_i - 1
+        return unless message.item_index < items.size
+
+        message
+      end
+    end
+  end
+end

data/lib/lightstreamer/messages/overflow_message.rb

@@ -17,11 +17,11 @@ module Lightstreamer
       # Attempts to parses the specified line as an overflow message for the given table and items and returns an
       # instance of {OverflowMessage} on success, or `nil` on failure.
       def parse(line, table_id, items)
-        message = new
-
         match = line.match table_regexp(table_id)
         return unless match
 
+        message = new
+
         message.item_index = match.captures[0].to_i - 1
         return unless message.item_index < items.size
 

data/lib/lightstreamer/messages/send_message_outcome_message.rb

@@ -0,0 +1,53 @@
+module Lightstreamer
+  # Helper class used by {Session} in order to parse incoming overflow send message outcome messages.
+  #
+  # @private
+  class SendMessageOutcomeMessage
+    # The name of the sequence this message outcome is for.
+    #
+    # @return [String]
+    attr_accessor :sequence
+
+    # The message number(s) this message outcome is for. There will always be exactly one entry in this array except in
+    # the case where {#error} is a {MessagesSkippedByTimeoutError} in which case there may be more than one entry if
+    # multiple messages were skipped.
+    #
+    # @return [Array<Fixnum>]
+    attr_accessor :numbers
+
+    # If an error occurred processing the message then it will be set here.
+    #
+    # @return [LightstreamerError, nil]
+    attr_accessor :error
+
+    class << self
+      # Attempts to parses the specified line as a message outcome message and returns an instance of
+      # {SendMessageOutcomeMessage} on success, or `nil` on failure.
+      def parse(line)
+        match = line.match Regexp.new '^MSG,([A-Za-z0-9_]+),(\d*),(?:DONE|ERR,(\d*),(.*))$'
+        return unless match
+
+        message = new
+
+        message.sequence = match.captures[0]
+        message.numbers = [match.captures[1].to_i]
+        handle_error_outcome message, match.captures if match.captures.compact.size == 4
+
+        message
+      end
+
+      private
+
+      def handle_error_outcome(message, captures)
+        message.error = LightstreamerError.build captures[3], captures[2]
+
+        return unless captures[2].to_i == 39
+
+        last_number = message.numbers[0]
+        first_number = last_number - captures[3].to_i + 1
+
+        message.numbers = Array(first_number..last_number)
+      end
+    end
+  end
+end

data/lib/lightstreamer/messages/update_message.rb

@@ -17,11 +17,11 @@ module Lightstreamer
       # Attempts to parses the specified line as an update message for the given table, items, and fields, and returns
       # an instance of {UpdateMessage} on success, or `nil` on failure.
       def parse(line, table_id, items, fields)
-        message = new
-
         match = line.match table_regexp(table_id, fields)
         return unless match
 
+        message = new
+
         message.item_index = match.captures[0].to_i - 1
         return unless message.item_index < items.size
 

data/lib/lightstreamer/post_request.rb

@@ -0,0 +1,81 @@
+module Lightstreamer
+  # This module contains helper methods for sending single and bulk POST requests to a Lightstreamer server and
+  # handling the possible error responses.
+  #
+  # @private
+  module PostRequest
+    module_function
+
+    # Sends a POST request to the specified Lightstreamer URL with the given query params. If an error occurs then a
+    # {LightstreamerError} subclass will be raised.
+    #
+    # @param [String] url The URL to send the POST request to.
+    # @param [Hash] query The POST request's query params.
+    def execute(url, query)
+      errors = bulk_execute url, [request_body(query)]
+      raise errors.first if errors.first
+    end
+
+    # Sends a POST request to the specified Lightstreamer URL that concatenates multiple individual POST request bodies
+    # into one to avoid sending lots of individual requests. The return value is an array with one entry per body and
+    # indicates the error state returned by the server for that body's request, or `nil` if no error occurred.
+    #
+    # @param [String] url The URL to send the POST request to.
+    # @param [Array<String>] bodies The individual POST request bodies that are to be sent together in one request.
+    #        These should be created with {#request_body}.
+    #
+    # @return [Array<LightstreamerError, nil>] The execution result of each of the passed bodies. If an entry is `nil`
+    #         then no error occurred when executing that body.
+    def bulk_execute(url, bodies)
+      response = Excon.post url, body: bodies.join("\r\n"), expects: 200, connect_timeout: 15
+
+      response_lines = response.body.split("\n").map(&:strip)
+
+      errors = []
+      errors << parse_error(response_lines) until response_lines.empty?
+
+      raise LightstreamerError if errors.size != bodies.size
+
+      errors
+    rescue Excon::Error => error
+      raise Errors::ConnectionError, error.message
+    end
+
+    # Returns the request body to send for a POST request with the given options.
+    #
+    # @param [Hash] query The POST request's query params.
+    #
+    # @return [String] The request body for the given query params.
+    def request_body(query)
+      params = {}
+
+      query.each do |key, value|
+        next if value.nil?
+        value = value.map(&:to_s).join(' ') if value.is_a? Array
+        params[key] = value
+      end
+
+      URI.encode_www_form params
+    end
+
+    # Parses the next error from the given lines that were returned by a POST request. The consumed lines are removed
+    # from the passed array.
+    #
+    # @param [Array<String>] response_lines
+    #
+    # @return [LightstreamerError, nil]
+    def parse_error(response_lines)
+      first_line = response_lines.shift
+
+      return nil if first_line == 'OK'
+      return Errors::SyncError.new if first_line == 'SYNC ERROR'
+
+      if first_line == 'ERROR'
+        error_code = response_lines.shift
+        LightstreamerError.build response_lines.shift, error_code
+      else
+        LightstreamerError.new first_line
+      end
+    end
+  end
+end

data/lib/lightstreamer/session.rb

@@ -1,6 +1,6 @@
 module Lightstreamer
-  # This class is responsible for managing a Lightstreamer session, and along with the {Subscription} class is the
-  # primary interface for working with Lightstreamer.
+  # This class is responsible for managing a Lightstreamer session, and along with the {Subscription} class forms the
+  # primary API for working with Lightstreamer.
   class Session
     # The URL of the Lightstreamer server to connect to. Set by {#initialize}.
     #
@@ -24,11 +24,16 @@ module Lightstreamer
 
     # If an error occurs on the stream connection that causes the session to terminate then details of the error will be
     # stored in this attribute. If the session is terminated as a result of calling {#disconnect} then the error will be
-    # {SessionEndError}.
+    # {Errors::SessionEndError}.
     #
     # @return [LightstreamerError, nil]
     attr_reader :error
 
+    # The server-side bandwidth constraint on data usage, expressed in kbps. If this is zero then no limit is applied.
+    #
+    # @return [Float]
+    attr_reader :requested_maximum_bandwidth
+
     # Initializes this new Lightstreamer session with the passed options.
     #
     # @param [Hash] options The options to create the session with.
@@ -36,6 +41,8 @@ module Lightstreamer
     # @option options [String] :username The username to connect to the server with.
     # @option options [String] :password The password to connect to the server with.
     # @option options [String] :adapter_set The name of the adapter set to request from the server.
+    # @option options [Float] :requested_maximum_bandwidth. The server-side bandwidth constraint on data usage,
+    #                 expressed in kbps. Defaults to zero which means no limit is applied.
     def initialize(options = {})
       @subscriptions = []
       @subscriptions_mutex = Mutex.new
@@ -44,41 +51,55 @@ module Lightstreamer
       @username = options[:username]
       @password = options[:password]
       @adapter_set = options[:adapter_set]
+      @requested_maximum_bandwidth = options[:requested_maximum_bandwidth].to_f
+
+      @on_message_result_callbacks = []
     end
 
-    # Creates a new Lightstreamer session using the details passed to {#initialize}. If an error occurs then
+    # Connects a new Lightstreamer session using the details passed to {#initialize}. If an error occurs then
     # a {LightstreamerError} subclass will be raised.
     def connect
       return if @stream_connection
 
       @error = nil
 
-      create_stream_connection
-      create_control_connection
+      @stream_connection = StreamConnection.new self
+      @stream_connection.connect
+
       create_processing_thread
     rescue
       @stream_connection = nil
       raise
     end
 
-    # Returns whether this session is currently connected and has an active stream connection.
+    # Returns whether this Lightstreamer session is currently connected and has an active stream connection.
     #
     # @return [Boolean]
     def connected?
       !@stream_connection.nil?
     end
 
-    # Disconnects this session and terminates the session on the server. All worker threads are exited.
+    # Returns the ID of the currently active Lightstreamer session, or `nil` if there is no active session.
+    #
+    # @return [String, nil]
+    def session_id
+      @stream_connection && @stream_connection.session_id
+    end
+
+    # Disconnects this Lightstreamer session and terminates the session on the server. All worker threads are exited.
     def disconnect
-      @control_connection.execute :destroy if @control_connection
+      control_request :destroy if @stream_connection
 
       @processing_thread.join 5 if @processing_thread
     ensure
       @stream_connection.disconnect if @stream_connection
       @processing_thread.exit if @processing_thread
 
-      @processing_thread = @control_connection = @stream_connection = nil
-      @subscriptions = []
+      @subscriptions.each do |subscription|
+        subscription.instance_variable_set :@active, false
+      end
+
+      @processing_thread = @stream_connection = nil
     end
 
     # Requests that the Lightstreamer server terminate the currently active stream connection and require that a new
@@ -88,66 +109,123 @@ module Lightstreamer
     def force_rebind
       return unless @stream_connection
 
-      @control_connection.execute :force_rebind
+      control_request :force_rebind
     end
 
-    # Subscribes this Lightstreamer session to the specified subscription. If an error occurs then a
-    # {LightstreamerError} subclass will be raised.
+    # Builds a new subscription for this session with the specified options. Note that ths does not activate the
+    # subscription, {Subscription#start} must be called to actually start streaming the subscription's data. See the
+    # {Subscription} class for more details.
+    #
+    # @param [Hash] options The options to create the subscription with.
+    # @option options [Array] :items The names of the items to subscribe to. Required.
+    # @option options [Array] :fields The names of the fields to subscribe to on the items. Required.
+    # @option options [:distinct, :merge] :mode The operation mode of the subscription. Required.
+    # @option options [String] :adapter The name of the data adapter from this session's adapter set that should be
+    #                 used. If `nil` then the default data adapter will be used.
+    # @option options [String] :selector The selector for table items. Optional.
+    # @option options [Float, :unfiltered] :maximum_update_frequency The maximum number of updates the subscription
+    #                 should receive per second. Defaults to zero which means there is no limit on the update frequency.
+    #                 If set to `:unfiltered` then unfiltered streaming will be used for the subscription and it is
+    #                 possible for overflows to occur (see {Subscription#on_overflow}).
     #
-    # @param [Subscription] subscription The new subscription to subscribe to.
-    def subscribe(subscription)
-      subscription.clear_data
+    # @return [Subscription] The new subscription.
+    def build_subscription(options)
+      subscription = Subscription.new self, options
 
       @subscriptions_mutex.synchronize { @subscriptions << subscription }
 
-      options = { mode: subscription.mode, items: subscription.items, fields: subscription.fields,
-                  adapter: subscription.adapter, maximum_update_frequency: subscription.maximum_update_frequency,
-                  selector: subscription.selector }
+      subscription
+    end
+
+    # Stops the specified subscription and removes it from this session. If an error occurs then a {LightstreamerError}
+    # subclass will be raised. To just stop a subscription with the option of restarting it at a later date call
+    # {Subscription#stop} on the subscription itself.
+    def remove_subscription(subscription)
+      subscription.stop
 
-      @control_connection.subscription_execute :add, subscription.id, options
-    rescue
       @subscriptions_mutex.synchronize { @subscriptions.delete subscription }
-      raise
     end
 
-    # Returns whether the specified subscription is currently active on this session.
-    #
-    # @param [Subscription] subscription The subscription to return the status for.
+    # This method performs a bulk {Subscription#start} on all the passed subscriptions. Calling {Subscription#start} on
+    # each of them individually would also work but requires a separate POST request to be sent for every subscription.
+    # This request starts all of the passed subscriptions in a single POST request which is significantly faster for
+    # a large number of subscriptions. The return value is an array with one entry per subscription and indicates the
+    # error state returned by the server for that subscription's start request, or `nil` if no error occurred.
     #
-    # @return [Boolean] Whether the specified subscription is currently active on this session.
-    def subscribed?(subscription)
-      @subscriptions_mutex.synchronize { @subscriptions.include? subscription }
-    end
-
-    # Unsubscribes this Lightstreamer session from the specified subscription.
+    # @param [Array<Subscription>] subscriptions The subscriptions to start.
     #
-    # @param [Subscription] subscription The existing subscription to unsubscribe from.
-    def unsubscribe(subscription)
-      raise ArgumentError, 'Unknown subscription' unless subscribed? subscription
+    # @return [Array<LightstreamerError, nil>]
+    def bulk_subscription_start(*subscriptions)
+      request_bodies = subscriptions.map do |subscription|
+        PostRequest.request_body session_id, *subscription.start_control_request_args
+      end
 
-      @control_connection.subscription_execute :delete, subscription.id
+      errors = PostRequest.bulk_execute @stream_connection.control_address, request_bodies
 
-      @subscriptions_mutex.synchronize { @subscriptions.delete subscription }
+      # Set @active to true on all subscriptions that did not have an error
+      errors.each_with_index do |error, index|
+        subscriptions[index].instance_variable_set :@active, true if error.nil?
+      end
     end
 
-    private
+    # Sets the server-side bandwidth constraint on data usage for this session, expressed in kbps. A value of zero
+    # means no limit will be applied. If an error occurs then a {LightstreamerError} subclass will be raised.
+    #
+    # @param [Float] bandwidth The new requested maximum bandwidth, expressed in kbps.
+    def requested_maximum_bandwidth=(bandwidth)
+      control_request :constrain, LS_requested_max_bandwidth: bandwidth if connected?
+      @requested_maximum_bandwidth = bandwidth.to_f
+    end
 
-    def create_stream_connection
-      @stream_connection = StreamConnection.new self
-      @stream_connection.connect
+    # Sends a custom message to the Lightstreamer server. Message sending can be done synchronously or asynchronously.
+    # By default the message will be sent synchronously, i.e. the message will be processed by the server and if an
+    # error occurs a {LightstreamerError} subclass will be raised immediately. However, if the `:async` option is true
+    # then the message will be sent asynchronously, and the result of the message send will be reported to all callbacks
+    # that have been registered via {#on_message_result}.
+    #
+    # @param [String] message The message to send to the Lightstreamer server.
+    # @param [Hash] options The options that control messages sent asynchronously.
+    # @option options [Boolean] :async Whether to send the message asynchronously. Defaults to `false`.
+    # @option options [String] :sequence The alphanumeric identifier that identifies a subset of messages that are to
+    #                 be processed in sequence based on the `:number` given to them. If the special `UNORDERED_MESSAGES`
+    #                 sequence is used then the associated messages are processed immediately, possibly concurrently,
+    #                 with no ordering constraint.
+    # @option options [Fixnum] :number The progressive number of this message within its sequence. Should start at 1.
+    # @option options [Float] :max_wait The maximum time the server can wait before processing this message if one or
+    #                 more of the preceding messages in the same sequence have not been received. If not specified then
+    #                 a timeout is assigned by the server.
+    def send_message(message, options = {})
+      url = URI.join(@stream_connection.control_address, '/lightstreamer/send_message.txt').to_s
+
+      query = { LS_session: session_id, LS_message: message }
+      query[:LS_sequence] = options.fetch(:sequence) if options[:async]
+      query[:LS_msg_prog] = options.fetch(:number) if options[:async]
+      query[:LS_max_wait] = options[:max_wait] if options[:max_wait]
+
+      PostRequest.execute url, query
     end
 
-    def create_control_connection
-      control_address = @stream_connection.control_address || server_url
+    # Adds the passed block to the list of callbacks that will be run when the outcome of an asynchronous message send
+    # arrives. The block will be called on a worker thread and so the code that is run by the block must be thread-safe.
+    # The arguments passed to the block are `|sequence, numbers, error|`.
+    #
+    # @param [Proc] callback The callback that is to be run.
+    def on_message_result(&callback)
+      @on_message_result_callbacks << callback
+    end
 
-      # If the control address doesn't have a schema then use the same schema as the server URL
-      unless control_address.start_with? 'http'
-        control_address = "#{URI(server_url).scheme}://#{control_address}"
-      end
+    # Sends a request to the control connection. If an error occurs then a {LightstreamerError} subclass will be raised.
+    #
+    # @param [Symbol] operation The control operation to perform.
+    # @param [Hash] options The options to send with the control request.
+    def control_request(operation, options = {})
+      url = URI.join(@stream_connection.control_address, '/lightstreamer/control.txt').to_s
 
-      @control_connection = ControlConnection.new @stream_connection.session_id, control_address
+      PostRequest.execute url, options.merge(LS_session: session_id, LS_op: operation)
     end
 
+    private
+
     # Starts the processing thread that reads and processes incoming data from the stream connection.
     def create_processing_thread
       @processing_thread = Thread.new do
@@ -155,28 +233,37 @@ module Lightstreamer
 
         loop do
           line = @stream_connection.read_line
-
           break if line.nil?
 
-          process_stream_data line unless line.empty?
+          process_stream_line line
         end
 
         # The stream connection has terminated so the session is assumed to be over
         @error = @stream_connection.error
-        @processing_thread = @control_connection = @stream_connection = nil
+        @processing_thread = @stream_connection = nil
       end
     end
 
-    # Processes a single line of incoming stream data by passing it to all the active subscriptions until one
+    # Processes a single line of incoming stream data by passing it to all the subscriptions until one
     # successfully processes it. This method is always run on the processing thread.
-    def process_stream_data(line)
-      was_processed = @subscriptions_mutex.synchronize do
-        @subscriptions.detect do |subscription|
-          subscription.process_stream_data line
-        end
+    def process_stream_line(line)
+      return if @subscriptions.any? { |subscription| subscription.process_stream_data line }
+      return if process_send_message_outcome line
+
+      warn "Lightstreamer: unprocessed stream data '#{line}'"
+    end
+
+    # Attempts to process the passed line as a send message outcome message, and if is such a message then the
+    # registered callbacks are run.
+    def process_send_message_outcome(line)
+      outcome = SendMessageOutcomeMessage.parse line
+      return unless outcome
+
+      @on_message_result_callbacks.each do |callback|
+        callback.call outcome.sequence, outcome.numbers, outcome.error
       end
 
-      warn "Lightstreamer: unprocessed stream data '#{line}'" unless was_processed
+      true
     end
   end
 end

data/lib/lightstreamer/{line_buffer.rb → stream_buffer.rb}

@@ -3,7 +3,7 @@ module Lightstreamer
   # as they become complete.
   #
   # @private
-  class LineBuffer
+  class StreamBuffer
     def initialize
       @buffer = ''
     end

data/lib/lightstreamer/stream_connection.rb

@@ -9,7 +9,7 @@ module Lightstreamer
     # @return [String, nil]
     attr_reader :session_id
 
-    # The control address returned from the server when this stream connection was initiated.
+    # The control address to use for this stream connection.
     #
     # @return [String, nil]
     attr_reader :control_address
@@ -27,9 +27,6 @@ module Lightstreamer
       @session = session
       @queue = Queue.new
 
-      @stream_create_url = URI.join(session.server_url, '/lightstreamer/create_session.txt').to_s
-      @stream_bind_url = URI.join(session.server_url, '/lightstreamer/bind_session.txt').to_s
-
       @connect_result_mutex = Mutex.new
       @connect_result_condition_variable = ConditionVariable.new
     end
@@ -99,26 +96,29 @@ module Lightstreamer
 
     def create_new_stream
       params = { LS_op2: 'create', LS_cid: 'mgQkwtwdysogQz2BJ4Ji kOj2Bg', LS_user: @session.username,
-                 LS_password: @session.password }
+                 LS_password: @session.password, LS_requested_max_bandwidth: @session.requested_maximum_bandwidth }
 
       params[:LS_adapter_set] = @session.adapter_set if @session.adapter_set
 
-      execute_stream_post_request @stream_create_url, connect_timeout: 15, query: params
+      url = URI.join(@session.server_url, '/lightstreamer/create_session.txt').to_s
+      execute_stream_post_request url, connect_timeout: 15, query: params
 
       signal_connect_result_ready
     end
 
     def bind_to_existing_stream
-      execute_stream_post_request @stream_bind_url, connect_timeout: 15, query: { LS_session: @session_id }
+      params = { LS_session: @session_id, LS_requested_max_bandwidth: @session.requested_maximum_bandwidth }
+
+      url = URI.join(control_address, '/lightstreamer/bind_session.txt').to_s
+      execute_stream_post_request url, connect_timeout: 15, query: params
     end
 
     def execute_stream_post_request(url, options)
       @header = StreamConnectionHeader.new
 
-      buffer = LineBuffer.new
-      options[:response_block] = lambda do |data, _remaining_bytes, _total_bytes|
-        buffer.process data, &method(:process_stream_line)
-      end
+      buffer = StreamBuffer.new
+      options[:response_block] = -> (data, _, _) { buffer.process data, &method(:process_stream_line) }
+      options[:expects] = 200
 
       Excon.post url, options
     rescue Excon::Error => error
@@ -141,7 +141,13 @@ module Lightstreamer
       header_incomplete = @header.process_line line
 
       @session_id = @header['SessionId']
-      @control_address = @header['ControlAddress']
+
+      # Set the control address and ensure it has a schema
+      @control_address = @header['ControlAddress'] || @session.server_url
+      unless @control_address.start_with? 'http'
+        @control_address = "#{URI(@session.server_url).scheme}://#{@control_address}"
+      end
+
       @error = @header.error
 
       return if header_incomplete

data/lib/lightstreamer/subscription.rb

@@ -1,13 +1,13 @@
 module Lightstreamer
-  # Describes a subscription that can be bound to a {Session} in order to consume its streaming data. A subscription is
-  # described by the options passed to {#initialize}. Incoming data can be consumed by registering an asynchronous data
-  # callback using {#on_data} or by polling using {#item_data}. Subscriptions start receiving data once they are
-  # attached to a session using {Session#subscribe}.
+  # This class manages a subscription that can be used to stream data from a {Session}. Subscriptions should always be
+  # created using {Session#build_subscription}. Subscriptions start receiving data after {#start} is called, and
+  # streaming subscription data can be consumed by registering an asynchronous data callback using {#on_data}, or by
+  # polling using {#item_data}.
   class Subscription
-    # The unique identification number of this subscription.
+    # The session that this subscription is associated with.
     #
-    # @return [Fixnum]
-    attr_reader :id
+    # @return [Session]
+    attr_reader :session
 
     # The names of the items to subscribe to.
     #
@@ -42,29 +42,26 @@ module Lightstreamer
     # @return [Float, :unfiltered]
     attr_reader :maximum_update_frequency
 
-    # Initializes a new Lightstreamer subscription with the specified options. This can then be passed to
-    # {Session#subscribe} to activate the subscription on a Lightstreamer session.
-    #
-    # @param [Hash] options The options to create the subscription with.
-    # @option options [Array] :items The names of the items to subscribe to. Required.
-    # @option options [Array] :fields The names of the fields to subscribe to on the items. Required.
-    # @option options [:distinct, :merge] :mode The operation mode of this subscription. Required.
-    # @option options [String] :adapter The name of the data adapter from the Lightstreamer session's adapter set that
-    #                 should be used. If `nil` then the default data adapter will be used.
-    # @option options [String] :selector The selector for table items. Optional.
-    # @option options [Float, :unfiltered] :maximum_update_frequency The maximum number of updates this subscription
-    #                 should receive per second. Defaults to zero which means there is no limit on the update frequency.
-    #                 If set to `:unfiltered` then unfiltered streaming will be used for this subscription and it is
-    #                 possible for overflows to occur (see {#on_overflow}).
-    def initialize(options)
-      @id = self.class.next_id
+    # Whether this subscription is currently started and actively streaming data. See {#start} and {#stop} for details.
+    #
+    # @return [Boolean]
+    attr_reader :active
+
+    # Initializes a new Lightstreamer subscription with the specified options.
+    #
+    # @param [Session] session The session this subscription is associated with.
+    # @param [Hash] options The options to create the subscription with. See {Session#build_subscription}
+    #
+    # @private
+    def initialize(session, options)
+      @session = session
 
       @items = options.fetch(:items)
       @fields = options.fetch(:fields)
       @mode = options.fetch(:mode).to_sym
       @adapter = options[:adapter]
       @selector = options[:selector]
-      @maximum_update_frequency = options[:maximum_update_frequency] || 0.0
+      @maximum_update_frequency = sanitize_frequency options[:maximum_update_frequency]
 
       @data_mutex = Mutex.new
 
@@ -72,6 +69,76 @@ module Lightstreamer
       clear_callbacks
     end
 
+    # Returns this subscription's unique identification number.
+    #
+    # @return [Fixnum]
+    #
+    # @private
+    def id
+      @id ||= ID_GENERATOR.next
+    end
+
+    # Starts streaming data for this Lightstreamer subscription. If an error occurs then a {LightstreamerError} subclass
+    # will be raised.
+    #
+    # @param [Hash] options The options to start the subscription with.
+    # @option options [Boolean] :silent Whether the subscription should be started in silent mode. In silent mode the
+    #                 subscription is initiated on the server and begins buffering incoming data, however this data will
+    #                 not be sent to the client for processing until {#unsilence} is called.
+    # @option options [Boolean, Fixnum] :snapshot Controls whether the server should send a snapshot of this
+    #                 subscription's items. If `false` then the server does not send snapshot information (this is the
+    #                 default). If `true` then the server will send snapshot information if it's available. If this
+    #                 subscription's {#mode} is `:distinct` then `:snapshot` can also be an integer specifying the
+    #                 number of events the server should send as part of the snapshot. If this latter option is used
+    #                 then any callbacks registered with {#on_end_of_snapshot} will be called once the snapshot for each
+    #                 item is complete.
+    def start(options = {})
+      session.control_request(*start_control_request_args(options)) unless @active
+      @active = true
+    end
+
+    # Returns the arguments to pass to to {Session#control_request} in order ot start this subscription with the given
+    # options.
+    #
+    # @param [Hash] options The options to start the subscription with.
+    #
+    # @private
+    def start_control_request_args(options = {})
+      operation = options[:silent] ? :add_silent : :add
+
+      options = { LS_table: id, LS_mode: mode.to_s.upcase, LS_id: items, LS_schema: fields, LS_data_adapter: adapter,
+                  LS_requested_max_frequency: maximum_update_frequency, LS_selector: selector,
+                  LS_snapshot: options.fetch(:snapshot, false) }
+
+      [operation, options]
+    end
+
+    # Unsilences this subscription if it was initially started in silent mode (by passing `silent: true` to {#start}).
+    # If this subscription was not started in silent mode then this method has no effect. If an error occurs then a
+    # {LightstreamerError} subclass will be raised.
+    def unsilence
+      session.control_request :start, LS_table: id
+    end
+
+    # Stops streaming data for this Lightstreamer subscription. If an error occurs then a {LightstreamerError} subclass
+    # will be raised.
+    def stop
+      session.control_request :delete, LS_table: id if @active
+      @active = false
+    end
+
+    # Sets this subscription's maximum update frequency. This can be done while a subscription is streaming data in
+    # order to change its update frequency limit, but an actively streaming subscription cannot switch between filtered
+    # and unfiltered dispatching, and {TableModificationNotAllowedError} will be raised if this is attempted.
+    #
+    # @param [Float, :unfiltered] new_frequency The new maximum update frequency. See {#maximum_update_frequency} for
+    #        details.
+    def maximum_update_frequency=(new_frequency)
+      new_frequency = sanitize_frequency new_frequency
+      session.control_request :reconf, LS_table: id, LS_requested_max_frequency: new_frequency if @active
+      @maximum_update_frequency = new_frequency
+    end
+
     # Clears all current data stored for this subscription. New data will continue to be processed as it becomes
     # available.
     def clear_data
@@ -85,9 +152,7 @@ module Lightstreamer
     #
     # @param [Proc] callback The callback that is to be run when new data arrives.
     def on_data(&callback)
-      @data_mutex.synchronize do
-        @callbacks[:on_data] << callback
-      end
+      @data_mutex.synchronize { @callbacks[:on_data] << callback }
     end
 
     # Adds the passed block to the list of callbacks that will be run when the server reports an overflow for this
@@ -96,16 +161,21 @@ module Lightstreamer
     #
     # @param [Proc] callback The callback that is to be run when an overflow is reported for this subscription.
     def on_overflow(&callback)
-      @data_mutex.synchronize do
-        @callbacks[:on_overflow] << callback
-      end
+      @data_mutex.synchronize { @callbacks[:on_overflow] << callback }
+    end
+
+    # Adds the passed block to the list of callbacks that will be run when the server reports an end-of-snapshot
+    # notification for this subscription. The block will be called on a worker thread and so the code that is run by the
+    # block must be thread-safe. The arguments passed to the block are `|subscription, item_name|`.
+    #
+    # @param [Proc] callback The callback that is to be run when an overflow is reported for this subscription.
+    def on_end_of_snapshot(&callback)
+      @data_mutex.synchronize { @callbacks[:on_end_of_snapshot] << callback }
     end
 
     # Removes all {#on_data} and {#on_overflow} callbacks present on this subscription.
     def clear_callbacks
-      @data_mutex.synchronize do
-        @callbacks = { on_data: [], on_overflow: [] }
-      end
+      @data_mutex.synchronize { @callbacks = { on_data: [], on_overflow: [], on_end_of_snapshot: [] } }
     end
 
     # Returns a copy of the current data of one of this subscription's items.
@@ -117,9 +187,20 @@ module Lightstreamer
       index = @items.index item_name
       raise ArgumentError, 'Unknown item' unless index
 
-      @data_mutex.synchronize do
-        @data[index].dup
-      end
+      @data_mutex.synchronize { @data[index].dup }
+    end
+
+    # Sets the current data for the item with the specified name.
+    #
+    # @param [String] item_name The name of the item to set the data for.
+    # @param [Hash] item_data The new data for the item.
+    def set_item_data(item_name, item_data)
+      index = @items.index item_name
+      raise ArgumentError, 'Unknown item' unless index
+
+      raise ArgumentError, 'Item data must be a hash' unless item_data.is_a? Hash
+
+      @data_mutex.synchronize { @data[index] = item_data.dup }
     end
 
     # Processes a line of stream data if it is relevant to this subscription. This method is thread-safe and is intended
@@ -132,30 +213,23 @@ module Lightstreamer
     #
     # @private
     def process_stream_data(line)
-      process_update_message(line) || process_overflow_message(line)
-    end
-
-    # Returns the next unique subscription ID.
-    #
-    # @return [Fixnum]
-    #
-    # @private
-    def self.next_id
-      @next_id ||= 0
-      @next_id += 1
+      return true if process_update_message UpdateMessage.parse(line, id, items, fields)
+      return true if process_overflow_message OverflowMessage.parse(line, id, items)
+      return true if process_end_of_snapshot_message EndOfSnapshotMessage.parse(line, id, items)
     end
 
     private
 
-    def process_update_message(line)
-      update_message = UpdateMessage.parse line, id, items, fields
-      return unless update_message
+    ID_GENERATOR = (1..Float::INFINITY).each
 
-      @data_mutex.synchronize do
-        process_new_values update_message.item_index, update_message.values
-      end
+    def sanitize_frequency(frequency)
+      frequency.to_s == 'unfiltered' ? :unfiltered : frequency.to_f
+    end
 
-      true
+    def process_update_message(message)
+      return unless message
+
+      @data_mutex.synchronize { process_new_values message.item_index, message.values }
     end
 
     def process_new_values(item_index, new_values)
@@ -167,21 +241,22 @@ module Lightstreamer
       run_callbacks :on_data, @items[item_index], data, new_values
     end
 
-    def process_overflow_message(line)
-      overflow_message = OverflowMessage.parse line, id, items
-      return unless overflow_message
+    def process_overflow_message(message)
+      return unless message
 
-      @data_mutex.synchronize do
-        run_callbacks :on_overflow, @items[overflow_message.item_index], overflow_message.overflow_size
-      end
+      @data_mutex.synchronize { run_callbacks :on_overflow, @items[message.item_index], message.overflow_size }
+    end
 
-      true
+    def process_end_of_snapshot_message(message)
+      return unless message
+
+      @data_mutex.synchronize { run_callbacks :on_end_of_snapshot, @items[message.item_index] }
     end
 
-    def run_callbacks(callback_type, *arguments)
-      @callbacks.fetch(callback_type).each do |callback|
-        callback.call self, *arguments
-      end
+    def run_callbacks(callback_type, *args)
+      @callbacks.fetch(callback_type).each { |callback| callback.call self, *args }
+
+      true
     end
   end
 end

data/lib/lightstreamer/version.rb

@@ -1,4 +1,4 @@
 module Lightstreamer
   # The version of this gem.
-  VERSION = '0.6'.freeze
+  VERSION = '0.7'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lightstreamer
 version: !ruby/object:Gem::Version
-  version: '0.6'
+  version: '0.7'
 platform: ruby
 authors:
 - Richard Viney
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-27 00:00:00.000000000 Z
+date: 2016-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon
@@ -142,14 +142,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.41'
+        version: '0.42'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.41'
+        version: '0.42'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -178,12 +178,14 @@ files:
 - lib/lightstreamer.rb
 - lib/lightstreamer/cli/commands/stream_command.rb
 - lib/lightstreamer/cli/main.rb
-- lib/lightstreamer/control_connection.rb
 - lib/lightstreamer/errors.rb
-- lib/lightstreamer/line_buffer.rb
+- lib/lightstreamer/messages/end_of_snapshot_message.rb
 - lib/lightstreamer/messages/overflow_message.rb
+- lib/lightstreamer/messages/send_message_outcome_message.rb
 - lib/lightstreamer/messages/update_message.rb
+- lib/lightstreamer/post_request.rb
 - lib/lightstreamer/session.rb
+- lib/lightstreamer/stream_buffer.rb
 - lib/lightstreamer/stream_connection.rb
 - lib/lightstreamer/stream_connection_header.rb
 - lib/lightstreamer/subscription.rb

data/lib/lightstreamer/control_connection.rb

@@ -1,106 +0,0 @@
-module Lightstreamer
-  # Helper class used by {Session} and is responsible for sending Lightstreamer control requests.
-  #
-  # @private
-  class ControlConnection
-    # Initializes this class for sending Lightstreamer control requests using the specified session ID and control
-    # address.
-    #
-    # @param [String] session_id The Lightstreamer session ID.
-    # @param [String] control_url The URL of the server to send Lightstreamer control requests to.
-    def initialize(session_id, control_url)
-      @session_id = session_id
-      @control_url = URI.join(control_url, '/lightstreamer/control.txt').to_s
-    end
-
-    # Sends a Lightstreamer control request that executes the specified operation with the specified options. If an
-    # error occurs then a {LightstreamerError} subclass will be raised.
-    #
-    # @param [String] operation The operation to execute.
-    # @param [Hash] options The options to include on the request.
-    def execute(operation, options = {})
-      result = execute_post_request build_payload(operation, options)
-
-      raise Errors::SyncError if result.first == 'SYNC ERROR'
-      raise LightstreamerError.build(result[2], result[1]) if result.first != 'OK'
-    end
-
-    # Sends a Lightstreamer subscription control request with the specified operation, table, and options. If an error
-    # occurs then a {LightstreamerError} subclass will be raised.
-    #
-    # @param [:add, :add_silent, :start, :delete] operation The operation to execute.
-    # @param [Fixnum] table The ID of the table this request pertains to.
-    # @param [Hash] options The subscription control request options.
-    def subscription_execute(operation, table, options = {})
-      options[:table] = table
-
-      validate_subscription_options operation, options
-
-      execute operation, options
-    end
-
-    private
-
-    # Validates the passed subscription control request options.
-    def validate_subscription_options(operation, options)
-      raise ArgumentError, 'Invalid table' unless options[:table].is_a? Fixnum
-      raise ArgumentError, 'Unsupported operation' unless [:add, :add_silent, :start, :delete].include? operation
-
-      validate_add_subscription_options options if [:add, :add_silent].include? operation
-    end
-
-    # Validates options required for subscription control requests that perform `add` operations.
-    def validate_add_subscription_options(options)
-      raise ArgumentError, 'Items not specified' if Array(options[:items]).empty?
-      raise ArgumentError, 'Fields not specified' if Array(options[:fields]).empty?
-      raise ArgumentError, 'Unsupported mode' unless [:distinct, :merge].include? options[:mode]
-    end
-
-    # Executes a POST request to the control address with the specified payload. Raises {ConnectionError} if the HTTP
-    # request fails. Returns the response body split into individual lines.
-    def execute_post_request(payload)
-      response = Excon.post @control_url, body: URI.encode_www_form(payload), connect_timeout: 15
-
-      response.body.split("\n").map(&:strip)
-    rescue Excon::Error => error
-      raise Errors::ConnectionError, error.message
-    end
-
-    # Constructs the payload for a Lightstreamer control request based on the given options hash. See {#execute} for
-    # details on the supported keys.
-    def build_payload(operation, options)
-      params = {}
-
-      build_optional_payload_fields options, params
-
-      params[:LS_session] = @session_id
-      params[:LS_op] = operation
-
-      params
-    end
-
-    OPTION_NAME_TO_API_PARAMETER = {
-      table: :LS_table,
-      adapter: :LS_data_adapter,
-      items: :LS_id,
-      fields: :LS_schema,
-      selector: :LS_selector,
-      maximum_update_frequency: :LS_requested_max_frequency
-    }.freeze
-
-    def build_optional_payload_fields(options, params)
-      params[:LS_mode] = options[:mode].to_s.upcase if options[:mode]
-
-      options.each do |key, value|
-        next if key == :mode
-        next if value.nil?
-
-        value = value.map(&:to_s).join(' ') if value.is_a? Array
-
-        api_parameter = OPTION_NAME_TO_API_PARAMETER.fetch key
-
-        params[api_parameter] = value
-      end
-    end
-  end
-end