lightstreamer 0.7 → 0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 67492665643def7bc43ea5ab072416c91d7e494d
-  data.tar.gz: 3f47646a1ff2d3c939c65588304e57234f893490
+  metadata.gz: 2fbedc6ddd408cf66740c82acb37a83fb1954b13
+  data.tar.gz: e259733aa9ab2bd100a1cee9a58ea120de44614c
 SHA512:
-  metadata.gz: 7510f00c805e9f83758e91b82c8682f22472d9c367a5a348faa4e46c8422e479c530bd96210c5eced1d7f56537ad39df14b6cf30dbf9d1a4787e1ea16695e6e5
-  data.tar.gz: 184073f14a2e2d34b9f208201526d6357a991d2a4bb113f40da21f80b112a0487f1177c12a24bd715a0e0c5b81d59997d9b6d64b603cff9c7ef89069e0455e02
+  metadata.gz: a47999d9791bf4eb11671fadf6ed949ff3bed475d7856ce2ae1a9f99dceba78608b52ac630ba58a5425a1154c6807ab9aa7e2937119f3e8136051a81be82be84
+  data.tar.gz: 689b06550c0ff39e08ec1042a80e6aa99ab47ddeaa92c0acd6f064eef6bcb6e9be202b90a19627c878157e3d41c795e1b131245ed0538364faf2e15d9dfff5cf

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Lightstreamer Changelog
 
+### 0.8 — August 2, 2016
+
+- Added support for Lightstreamer's `COMMAND` and `RAW` subscription modes
+- Added support for Lightstreamer's polling mode and switching an active session between streaming and polling
+- `Lightstreamer::Subscription#item_data` now return `nil` if the requested item has never had any data set
+- Renamed `Lightstreamer::Subscription#adapter` to `Lightstreamer::Subscription#data_adapter` and the `--adapter`
+  command-line option to `--data-adapter`
+- The `--mode` command-line option is now required because the default value of `merge` has been removed
+
 ### 0.7 — July 31, 2016
 
 - Refactored subscription handling to be more object-oriented, subscriptions are now created using

data/README.md

@@ -8,9 +8,22 @@
 [![Documentation][documentation-badge]][documentation-link]
 [![License][license-badge]][license-link]
 
-Easily interface with a Lightstreamer service from Ruby. Written against the
+Easily interface with a Lightstreamer service from Ruby with this gem, either directly through code or by using the
+provided command-line client. Written against the
 [official API specification](http://www.lightstreamer.com/docs/client_generic_base/Network%20Protocol%20Tutorial.pdf).
 
+Includes support for:
+
+- Streaming and polling connections
+- The four Lightstreamer subscription modes: `command`, `distinct`, `merge` and `raw`
+- Automatic management of table content when in `command` mode
+- Silent subscriptions
+- Item snapshots
+- Unfiltered subscriptions and asynchronous overflow handling
+- Bulk subscription creation
+- Synchronous and asynchronous message sending
+- Detailed error reporting and error handling callbacks
+
 ## License
 
 Licensed under the MIT license. You must read and agree to its terms to use this software.
@@ -30,8 +43,8 @@ The two primary classes that make up the public API are:
 - [`Lightstreamer::Session`](http://www.rubydoc.info/github/rviney/lightstreamer/Lightstreamer/Session)
 - [`Lightstreamer::Subscription`](http://www.rubydoc.info/github/rviney/lightstreamer/Lightstreamer/Subscription)
 
-The following code snippet demonstrates how to setup a Lightstreamer session, a subscription, then print streaming
-output as it comes in.
+The following code snippet demonstrates how to create a Lightstreamer session, build a subscription, then print
+streaming output as it arrives.
 
 ```ruby
 require 'lightstreamer'
@@ -46,19 +59,19 @@ session.connect
 # Create a new subscription that subscribes to thirty items and to four fields on each item
 subscription = session.build_subscription items: (1..30).map { |i| "item#{i}" },
                                           fields: [:ask, :bid, :stock_name, :time],
-                                          mode: :merge, adapter: 'QUOTE_ADAPTER'
+                                          mode: :merge, data_adapter: 'QUOTE_ADAPTER'
 
 # Create a thread-safe queue
 queue = Queue.new
 
 # When new data becomes available for the subscription it will be put on the queue. This callback
 # will be run on a worker thread.
-subscription.on_data do |subscription, item_name, item_data, new_values|
+subscription.on_data do |subscription, item_name, item_data, new_data|
   queue.push item_data
 end
 
-# Start streaming data for the subscription
-subscription.start
+# Start streaming data for the subscription and request an initial snapshot
+subscription.start snapshot: true
 
 # Loop printing out new data as soon as it becomes available on the queue
 loop do
@@ -75,11 +88,12 @@ subscription, then print streaming output from the server as it becomes availabl
 To print streaming data from the demo server run the following command:
 
 ```
-lightstreamer --server-url http://push.lightstreamer.com --adapter-set DEMO --adapter QUOTE_ADAPTER \
-              --items item1 item2 item3 item4 item5 --fields ask bid stock_name time
+lightstreamer --server-url http://push.lightstreamer.com --adapter-set DEMO \
+              --data-adapter QUOTE_ADAPTER --mode merge --snapshot \
+              --items item1 item2 item3 item4 item5 --fields ask bid stock_name
 ```
 
-To see a full list of available options for the command-line client run the following command:
+To see the full list of available options for the command-line client run the following command:
 
 ```
 lightstreamer help stream

data/lib/lightstreamer.rb

@@ -15,6 +15,7 @@ require 'lightstreamer/stream_buffer'
 require 'lightstreamer/stream_connection'
 require 'lightstreamer/stream_connection_header'
 require 'lightstreamer/subscription'
+require 'lightstreamer/subscription_item_data'
 require 'lightstreamer/version'
 
 # This module contains all the code for the Lightstreamer gem. See `README.md` to get started with using this gem.

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

@@ -8,11 +8,13 @@ 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 :polling_enabled, type: :boolean, desc: 'Whether to poll instead of using long-running stream connections'
       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 :data_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 :mode, enum: %w(command distinct merge raw), 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'
@@ -52,17 +54,18 @@ module Lightstreamer
 
       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] }
+          adapter_set: options[:adapter_set], requested_maximum_bandwidth: options[:requested_maximum_bandwidth],
+          polling_enabled: options[:polling_enabled] }
       end
 
       def subscription_options
-        { items: options[:items], fields: options[:fields], mode: options[:mode], adapter: options[:adapter],
+        { items: options[:items], fields: options[:fields], mode: options[:mode], data_adapter: options[:data_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)
-        @queue.push "#{item_name} - #{new_values.map { |key, value| "#{key}: #{value}" }.join ', '}"
+      def on_data(_subscription, item_name, _item_data, new_data)
+        @queue.push "#{item_name} - #{new_data.map { |key, value| "#{key}: #{value}" }.join ', '}"
       end
 
       def on_overflow(_subscription, item_name, overflow_size)

data/lib/lightstreamer/errors.rb

@@ -161,7 +161,7 @@ module Lightstreamer
 
       # Initializes this session end error with the specified cause code.
       #
-      # @param [Session?] cause_code See {#cause_code} for details.
+      # @param [String, Fixnum, nil] cause_code See {#cause_code} for details.
       def initialize(cause_code)
         @cause_code = cause_code && cause_code.to_i
         super()

data/lib/lightstreamer/messages/send_message_outcome_message.rb

@@ -9,8 +9,8 @@ module Lightstreamer
     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.
+    # the case where {#error} is a {Errors::MessagesSkippedByTimeoutError} in which case there may be more than one
+    # entry if multiple messages were skipped.
     #
     # @return [Array<Fixnum>]
     attr_accessor :numbers

data/lib/lightstreamer/messages/update_message.rb

@@ -8,10 +8,10 @@ module Lightstreamer
     # @return [Fixnum]
     attr_accessor :item_index
 
-    # The field values specified by this update message.
+    # The field data specified by this update message.
     #
     # @return [Array]
-    attr_accessor :values
+    attr_accessor :data
 
     class << self
       # Attempts to parses the specified line as an update message for the given table, items, and fields, and returns
@@ -25,7 +25,7 @@ module Lightstreamer
         message.item_index = match.captures[0].to_i - 1
         return unless message.item_index < items.size
 
-        message.values = parse_values match.captures[1..-1], fields
+        message.data = parse_field_values match.captures[1..-1], fields
 
         message
       end
@@ -36,13 +36,13 @@ module Lightstreamer
         Regexp.new "^#{table_id},(\\d+)#{'\|(.*)' * fields.size}$"
       end
 
-      def parse_values(values, fields)
+      def parse_field_values(field_values, fields)
         hash = {}
 
-        values.each_with_index do |value, index|
-          next if value == ''
+        field_values.each_with_index do |field_value, index|
+          next if field_value == ''
 
-          hash[fields[index]] = parse_raw_field_value value
+          hash[fields[index]] = parse_raw_field_value field_value
         end
 
         hash

data/lib/lightstreamer/session.rb

@@ -1,6 +1,9 @@
 module Lightstreamer
   # This class is responsible for managing a Lightstreamer session, and along with the {Subscription} class forms the
-  # primary API for working with Lightstreamer.
+  # primary API for working with Lightstreamer. Start by calling {#initialize} with the desired server URL and other
+  # options, then call {#connect} to initiate the session. Once connected create subscriptions using
+  # {#build_subscription} and then start streaming data by calling {Subscription#start} or {#bulk_subscription_start}.
+  # See the {Subscription} class for details on how to consume the streaming data as it arrives.
   class Session
     # The URL of the Lightstreamer server to connect to. Set by {#initialize}.
     #
@@ -34,6 +37,15 @@ module Lightstreamer
     # @return [Float]
     attr_reader :requested_maximum_bandwidth
 
+    # Whether polling mode is enabled. By default long-running HTTP connections will be used to stream incoming data,
+    # but if polling is enabled then repeated short polling requests will be used instead. Polling may work better if
+    # there is intermediate buffering on the network that affects timely delivery of data on long-running streaming
+    # connections. The polling mode for a connected session can be changed by setting {#polling_enabled} and then
+    # calling {#force_rebind}.
+    #
+    # @return [Boolean]
+    attr_accessor :polling_enabled
+
     # Initializes this new Lightstreamer session with the passed options.
     #
     # @param [Hash] options The options to create the session with.
@@ -43,6 +55,8 @@ module Lightstreamer
     # @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.
+    # @option options [Boolean] :polling_enabled Whether polling mode is enabled. See {#polling_enabled} for details.
+    #                 Defaults to `false`.
     def initialize(options = {})
       @subscriptions = []
       @subscriptions_mutex = Mutex.new
@@ -52,6 +66,7 @@ module Lightstreamer
       @password = options[:password]
       @adapter_set = options[:adapter_set]
       @requested_maximum_bandwidth = options[:requested_maximum_bandwidth].to_f
+      @polling_enabled = options[:polling_enabled]
 
       @on_message_result_callbacks = []
     end
@@ -105,7 +120,9 @@ module Lightstreamer
     # Requests that the Lightstreamer server terminate the currently active stream connection and require that a new
     # stream connection be initiated by the client. The Lightstreamer server requires closure and re-establishment of
     # the stream connection periodically during normal operation, this method just allows such a reconnection to be
-    # requested explicitly by the client. If an error occurs then a {LightstreamerError} subclass will be raised.
+    # requested explicitly by the client. This is particularly useful after {#polling_enabled} has been changed because
+    # it forces the stream connection to rebind using the new setting. If an error occurs then a {LightstreamerError}
+    # subclass will be raised.
     def force_rebind
       return unless @stream_connection
 
@@ -119,9 +136,9 @@ module Lightstreamer
     # @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 [:command, :distinct, :merge, :raw] :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.
+    #                 used. If this is not set or is set to `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.
@@ -140,6 +157,8 @@ module Lightstreamer
     # 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.
+    #
+    # @param [Subscription] subscription The subscription to stop and remove from this session.
     def remove_subscription(subscription)
       subscription.stop
 
@@ -147,10 +166,11 @@ module Lightstreamer
     end
 
     # 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.
+    # each subscription individually would also work but requires a separate POST request to be sent for every
+    # subscription, whereas 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.
     #
     # @param [Array<Subscription>] subscriptions The subscriptions to start.
     #
@@ -181,15 +201,16 @@ module Lightstreamer
     # 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}.
+    # that have been registered via {#on_message_result}. If `:async` is set to `true` then the `:sequence` and
+    # `:number` options must also be specified.
     #
     # @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.
+    #                 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
@@ -205,16 +226,17 @@ module Lightstreamer
       PostRequest.execute url, query
     end
 
-    # 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|`.
+    # Adds the passed block to the list of callbacks that will be run when the outcome of one or more asynchronous
+    # message sends arrive. 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
 
-    # Sends a request to the control connection. If an error occurs then a {LightstreamerError} subclass will be raised.
+    # Sends a request to this session's 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.
@@ -244,8 +266,7 @@ module Lightstreamer
       end
     end
 
-    # 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.
+    # Processes a single line of incoming stream data. This method is always run on the processing thread.
     def process_stream_line(line)
       return if @subscriptions.any? { |subscription| subscription.process_stream_data line }
       return if process_send_message_outcome line
@@ -253,8 +274,7 @@ module Lightstreamer
       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.
+    # Attempts to process the passed line as a send message outcome message.
     def process_send_message_outcome(line)
       outcome = SendMessageOutcomeMessage.parse line
       return unless outcome

data/lib/lightstreamer/stream_connection.rb

@@ -66,8 +66,8 @@ module Lightstreamer
     end
 
     # Reads the next line of streaming data. If the streaming thread is alive then this method blocks the calling thread
-    # until a line of data is available. If the streaming thread is not active then any unconsumed lines will be
-    # returned and after that the return value will be `nil`.
+    # until a line of data is available or the streaming thread terminates for any reason. If the streaming thread is
+    # not active then any unconsumed lines will be returned and after that the return value will be `nil`.
     #
     # @return [String, nil]
     def read_line
@@ -95,8 +95,8 @@ module Lightstreamer
     end
 
     def create_new_stream
-      params = { LS_op2: 'create', LS_cid: 'mgQkwtwdysogQz2BJ4Ji kOj2Bg', LS_user: @session.username,
-                 LS_password: @session.password, LS_requested_max_bandwidth: @session.requested_maximum_bandwidth }
+      params = build_params LS_op2: 'create', LS_cid: 'mgQkwtwdysogQz2BJ4Ji kOj2Bg', LS_user: @session.username,
+                            LS_password: @session.password
 
       params[:LS_adapter_set] = @session.adapter_set if @session.adapter_set
 
@@ -107,12 +107,23 @@ module Lightstreamer
     end
 
     def bind_to_existing_stream
-      params = { LS_session: @session_id, LS_requested_max_bandwidth: @session.requested_maximum_bandwidth }
+      params = build_params LS_session: @session_id
 
       url = URI.join(control_address, '/lightstreamer/bind_session.txt').to_s
       execute_stream_post_request url, connect_timeout: 15, query: params
     end
 
+    def build_params(params)
+      params[:LS_requested_max_bandwidth] = @session.requested_maximum_bandwidth
+
+      if @session.polling_enabled
+        params[:LS_polling] = true
+        params[:LS_polling_millis] = 15_000
+      end
+
+      params
+    end
+
     def execute_stream_post_request(url, options)
       @header = StreamConnectionHeader.new
 
@@ -130,6 +141,8 @@ module Lightstreamer
     end
 
     def process_stream_line(line)
+      return if line =~ /^(PROBE|Preamble:.*)$/
+
       if @header
         process_header_line line
       else
@@ -151,18 +164,17 @@ module Lightstreamer
       @error = @header.error
 
       return if header_incomplete
+      @header = nil
 
       signal_connect_result_ready
-
-      @header = nil
     end
 
     def process_body_line(line)
-      if line =~ /^LOOP/
+      if line =~ /^LOOP( \d+|)$/
         @loop = true
-      elsif line =~ /^END/
+      elsif line =~ /^END( \d+|)/
         @error = Errors::SessionEndError.new line[4..-1]
-      elsif line !~ /^(PROBE|Preamble:.*)$/
+      elsif !line.empty?
         @queue.push line
       end
     end

data/lib/lightstreamer/subscription.rb

@@ -19,16 +19,17 @@ module Lightstreamer
     # @return [Array]
     attr_reader :fields
 
-    # The operation mode of this subscription.
+    # The operation mode of this subscription. The four supported operation modes are: `:command`, `:distinct`, `:merge`
+    # and `:raw`. See the Lightstreamer documentation for details on the different modes.
     #
-    # @return [:distinct, :merge]
+    # @return [:command, :distinct, :merge, :raw]
     attr_reader :mode
 
-    # The name of the data adapter from the Lightstreamer session's adapter set that should be used, or `nil` to use the
-    # default data adapter.
+    # The name of the data adapter from the Lightstreamer session's adapter set to use, or `nil` to use the default
+    # data adapter.
     #
     # @return [String, nil]
-    attr_reader :adapter
+    attr_reader :data_adapter
 
     # The selector for table items.
     #
@@ -37,7 +38,8 @@ module Lightstreamer
 
     # The maximum number of updates this subscription should receive per second. If this is set to zero, which is the
     # default, then 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}).
+    # used for this subscription and it is possible for overflows to occur (see {#on_overflow}). If {#mode} is `:raw`
+    # then the maximum update frequency is treated as `:unfiltered` regardless of its actual value.
     #
     # @return [Float, :unfiltered]
     attr_reader :maximum_update_frequency
@@ -59,7 +61,7 @@ module Lightstreamer
       @items = options.fetch(:items)
       @fields = options.fetch(:fields)
       @mode = options.fetch(:mode).to_sym
-      @adapter = options[:adapter]
+      @data_adapter = options[:data_adapter]
       @selector = options[:selector]
       @maximum_update_frequency = sanitize_frequency options[:maximum_update_frequency]
 
@@ -86,18 +88,21 @@ module Lightstreamer
     #                 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.
+    #                 subscription's items. The default value is `false` which means then the server will not send
+    #                 snapshot information. If set to `true` then the server will send snapshot information if it is
+    #                 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, or {#mode} is `:command`, then any callbacks registered with {#on_end_of_snapshot}
+    #                 will be called once the snapshot for each item is complete. This option is ignored when {#mode} is
+    #                 `:raw`.
     def start(options = {})
-      session.control_request(*start_control_request_args(options)) unless @active
+      return if @active
+
+      session.control_request(*start_control_request_args(options))
       @active = true
     end
 
-    # Returns the arguments to pass to to {Session#control_request} in order ot start this subscription with the given
+    # Returns the arguments to pass to to {Session#control_request} in order to start this subscription with the given
     # options.
     #
     # @param [Hash] options The options to start the subscription with.
@@ -106,15 +111,15 @@ module Lightstreamer
     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,
+      options = { LS_table: id, LS_mode: mode.to_s.upcase, LS_id: items, LS_schema: fields, LS_selector: selector,
+                  LS_data_adapter: data_adapter, LS_requested_max_frequency: maximum_update_frequency,
                   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
+    # 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
@@ -129,7 +134,8 @@ module Lightstreamer
 
     # 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.
+    # and unfiltered dispatching, and {TableModificationNotAllowedError} will be raised if this is attempted. If {#mode}
+    # is `:raw` then the maximum update frequency is treated as `:unfiltered` regardless of its actual value.
     #
     # @param [Float, :unfiltered] new_frequency The new maximum update frequency. See {#maximum_update_frequency} for
     #        details.
@@ -142,13 +148,42 @@ module Lightstreamer
     # Clears all current data stored for this subscription. New data will continue to be processed as it becomes
     # available.
     def clear_data
-      @data = (0...items.size).map { {} }
+      @data_mutex.synchronize { @data = (0...items.size).map { SubscriptionItemData.new } }
+    end
+
+    # Returns a copy of the current data of one of this subscription's items. If {#mode} is `:merge` then the returned
+    # object will be a hash of the item's state, if it is `:command` then an array of row data for the item will be
+    # returned, and if it is `:distinct` or `:raw` then just the most recent update received for the item will be
+    # returned. The return value will be `nil` if no data for the item has been set or been received.
+    #
+    # @param [String] item_name The name of the item to return the current data for.
+    #
+    # @return [Hash, Array, nil] A copy of the item data.
+    def item_data(item_name)
+      index = @items.index item_name
+      raise ArgumentError, 'Unknown item' unless index
+
+      @data_mutex.synchronize { @data[index].data && @data[index].data.dup }
+    end
+
+    # Sets the current data for the item with the specified name. This is only allowed when {mode} is `:command` or
+    # `:merge`. Raises an exception if the specified item name or item data is invalid.
+    #
+    # @param [String] item_name The name of the item to set the data for.
+    # @param [Hash, Array<Hash>] item_data The new data for the item. If {#mode} is `:merge` this must be a hash. If
+    #        {#mode} is `:command` then this must be an `Array<Hash>` and each hash entry must have a unique `:key`
+    #        value.
+    def set_item_data(item_name, item_data)
+      index = @items.index item_name
+      raise ArgumentError, 'Unknown item' unless index
+
+      @data_mutex.synchronize { @data[index].set_data item_data, mode }
     end
 
     # Adds the passed block to the list of callbacks that will be run when new data for this subscription 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 `|subscription, item_name, item_data, new_values|`. If {#mode} is `:distinct`
-    # then the values of `item_data` and `new_values` will be the same.
+    # arguments passed to the block are `|subscription, item_name, item_data, new_data|`. If {#mode} is `:distinct`
+    # or `:raw` then `item_data` and `new_data` will be the same.
     #
     # @param [Proc] callback The callback that is to be run when new data arrives.
     def on_data(&callback)
@@ -156,8 +191,10 @@ module Lightstreamer
     end
 
     # Adds the passed block to the list of callbacks that will be run when the server reports an overflow 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, overflow_size|`.
+    # subscription. This is only relevant when this subscription's {#mode} is `:command` or `:raw`, or if
+    # {#maximum_update_frequency} is `:unfiltered`. 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,
+    # overflow_size|`.
     #
     # @param [Proc] callback The callback that is to be run when an overflow is reported for this subscription.
     def on_overflow(&callback)
@@ -165,51 +202,27 @@ module Lightstreamer
     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|`.
+    # notification for this subscription. End-of-snapshot notifications are only sent when {#mode} is `:command` or
+    # `:distinct` and `snapshot: true` was passed to {#start}. 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.
+    # Removes all {#on_data}, {#on_overflow} and {#on_end_of_snapshot} callbacks present on this subscription.
     def clear_callbacks
       @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.
-    #
-    # @param [String] item_name The name of the item to return the current data for.
-    #
-    # @return [Hash] A copy of the item data.
-    def item_data(item_name)
-      index = @items.index item_name
-      raise ArgumentError, 'Unknown item' unless index
-
-      @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
     # to be called by the session's processing thread.
     #
     # @param [String] line The line of stream data to process.
     #
-    # @return [Boolean] Whether the passed line of stream data was relevant to this subscription and was successfully
-    #         processed by it.
+    # @return [Boolean] Whether the passed line of stream data was processed by this subscription.
     #
     # @private
     def process_stream_data(line)
@@ -229,16 +242,10 @@ module Lightstreamer
     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)
-      data = @data[item_index]
-
-      data.replace(new_values) if mode == :distinct
-      data.merge!(new_values) if mode == :merge
-
-      run_callbacks :on_data, @items[item_index], data, new_values
+      @data_mutex.synchronize do
+        @data[message.item_index].send "process_new_#{mode}_data", message.data.dup
+        run_callbacks :on_data, @items[message.item_index], @data[message.item_index].data, message.data
+      end
     end
 
     def process_overflow_message(message)

data/lib/lightstreamer/subscription_item_data.rb

@@ -0,0 +1,93 @@
+module Lightstreamer
+  # Helper class used by {Subscription} to process incoming item data according to the four different subscription
+  # modes.
+  #
+  # @private
+  class SubscriptionItemData
+    # The current item data. Item data is a hash for all subscription modes except `:command` when it is an array.
+    #
+    # @return [Hash, Array, nil]
+    attr_accessor :data
+
+    # Explicitly sets this item data. See {Subscription#set_item_data} for details.
+    #
+    # @param [Array, Hash] new_data The new data for the item.
+    # @param [:command, :merge] mode The subscription mode.
+    def set_data(new_data, mode)
+      raise ArgumentError, "Data can't be set unless mode is :command or :merge" unless [:command, :merge].include? mode
+      raise ArgumentError, 'Data must be a hash when in merge mode' if mode == :merge && !new_data.is_a?(Hash)
+
+      validate_rows new_data if mode == :command
+
+      @data = new_data.dup
+    end
+
+    # Processes new data for the `:command` subscription mode.
+    #
+    # @param [Hash] new_data The new data.
+    def process_new_command_data(new_data)
+      @data ||= []
+
+      key = row_key new_data
+      command = new_data.delete(:command) || new_data.delete('command')
+
+      send "process_#{command.to_s.downcase}_command", key, new_data
+    end
+
+    # Processes new data for the `:distinct` subscription mode.
+    #
+    # @param [Hash] new_data The new data.
+    def process_new_distinct_data(new_data)
+      @data = new_data
+    end
+
+    # Processes new data for the `:merge` subscription mode.
+    #
+    # @param [Hash] new_data The new data.
+    def process_new_merge_data(new_data)
+      @data ||= {}
+      @data.merge! new_data
+    end
+
+    # Processes new data for the `:raw` subscription mode.
+    #
+    # @param [Hash] new_data The new data.
+    def process_new_raw_data(new_data)
+      @data = new_data
+    end
+
+    private
+
+    def validate_rows(rows)
+      raise ArgumentError, 'Data must be an array when in command mode' unless rows.is_a? Array
+
+      keys = rows.map { |row| row_key row }
+      raise ArgumentError, 'Each row must have a unique key' if keys.uniq.size != rows.size
+    end
+
+    def row_key(row)
+      return row[:key] if row.key? :key
+      return row['key'] if row.key? 'key'
+
+      raise ArgumentError, 'Row does not have a key'
+    end
+
+    def process_add_command(key, new_data)
+      process_update_command key, new_data
+    end
+
+    def process_update_command(key, new_data)
+      row_to_update = @data.detect { |row| row_key(row) == key }
+
+      if row_to_update
+        row_to_update.merge! new_data
+      else
+        data << new_data
+      end
+    end
+
+    def process_delete_command(key, _new_data)
+      @data.delete_if { |row| row_key(row) == key }
+    end
+  end
+end

data/lib/lightstreamer/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lightstreamer
 version: !ruby/object:Gem::Version
-  version: '0.7'
+  version: '0.8'
 platform: ruby
 authors:
 - Richard Viney
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-31 00:00:00.000000000 Z
+date: 2016-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: excon
@@ -189,6 +189,7 @@ files:
 - lib/lightstreamer/stream_connection.rb
 - lib/lightstreamer/stream_connection_header.rb
 - lib/lightstreamer/subscription.rb
+- lib/lightstreamer/subscription_item_data.rb
 - lib/lightstreamer/version.rb
 homepage: https://github.com/rviney/lightstreamer
 licenses: