lightstreamer 0.3 → 0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f96a70c42b710644985ba440779ec2d73f32ad9e
-  data.tar.gz: 4c0181a0612a67870d3333671ecbb20e0af27f8c
+  metadata.gz: 863ad0ba9936b00dca802004782358a03cf5cd36
+  data.tar.gz: a13adc3e4b6b9945580bc02927826d61742dba1d
 SHA512:
-  metadata.gz: 5048265eaf80652222323ffad4f4fa4a39343c4adbc8a52ae5b449d43a8c63e343334cab654a2f6fdc3321955b418581661e0c596e23f1f3ea83f953e9a77f02
-  data.tar.gz: 248b20766df771c73189fd3eb61f218a5b016254a2271f965c4076cfde2bd9391eef4ab6afcc1ea5a5424a3ca86c4f15728aeb12bf415bb2b03721722828bced
+  metadata.gz: 7f9dd91cc66467027ddd209d0c964559db461e8b9a05c1cb9aa583ae42d1997516c0196ea2be18c0fbc5d317db97fcef10ce81e32cefe677390dd4c8f339ebfc
+  data.tar.gz: 4863842643a0d7a876f6efa2b41270044f7ada1479c0154e452e02f7e1d6b2e75c39f6f24d79029b633dd7402c3cd6a5d24a41e5c3dba057013a0ddc403b9dbc

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Lightstreamer Changelog
 
+### 0.4 — July 25, 2016
+
+- Added support for specifying a subscription's selector and maximum update frequency
+- Added `Lightstreamer::Session#force_rebind` which asks the server to send a `LOOP` message so the client has to rebind 
+  using a new stream connection
+- Added validation of the arguments for control connection subscription requests
+- All error classes now inherit from `Lightstreamer::Error` and the different Lightstreamer errors that can occur are
+  separated into a variety of new subclasses
+- Removed `Lightstreamer::ProtocolError`
+- `Lightstreamer::Session#disconnect` now properly terminates the session with the server by sending the relevant
+  control request
+- The reason why a session terminated can now be queried using `Lightstreamer::Session#error`
+- Fixed handling of `nil` subscription adapters
+- Correctly handle when an `END` message is received on the stream connection
+- All valid error responses from session create and bind requests are now handled correctly
+- Unhandled exceptions on the internal worker threads now cause the application to terminate
+
 ### 0.3 — July 24, 2016
 
 - Seamlessly rebind the stream connection when a `LOOP` message is received

data/lib/lightstreamer.rb

@@ -3,9 +3,8 @@ require 'typhoeus'
 require 'uri'
 
 require 'lightstreamer/control_connection'
+require 'lightstreamer/errors'
 require 'lightstreamer/line_buffer'
-require 'lightstreamer/protocol_error'
-require 'lightstreamer/request_error'
 require 'lightstreamer/session'
 require 'lightstreamer/stream_connection'
 require 'lightstreamer/stream_connection_header'

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

@@ -12,6 +12,8 @@ module Lightstreamer
       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 :maximum_update_frequency, type: :numeric, desc: 'The maximum number of updates per second for each item'
 
       def stream
         session = create_session
@@ -36,14 +38,20 @@ module Lightstreamer
 
       # Creates a new subscription from the specified options.
       def create_subscription
-        subscription = Lightstreamer::Subscription.new items: options[:items], fields: options[:fields],
-                                                       mode: options[:mode], adapter: options[:adapter]
+        subscription = Lightstreamer::Subscription.new subscription_options
 
         subscription.add_data_callback(&method(:subscription_data_callback))
 
         subscription
       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]
+        }
+      end
+
       def subscription_data_callback(_subscription, item_name, _item_data, new_values)
         @queue.push "#{item_name} - #{new_values.map { |key, value| "#{key}: #{value}" }.join ', '}"
       end

data/lib/lightstreamer/control_connection.rb

@@ -11,26 +11,56 @@ module Lightstreamer
       @control_url = URI.join(control_url, '/lightstreamer/control.txt').to_s
     end
 
-    # Sends a Lightstreamer control request with the specified options. If an error occurs then {RequestError} or
-    # {ProtocolError} will be raised.
+    # Sends a Lightstreamer control request that executes the specified operation with the specified options. If an
+    # error occurs then an {Error} subclass will be raised.
     #
-    # @param [Hash] options The control request options.
-    # @option options [Fixnum] :table The ID of the table this request pertains to. Required.
-    # @option options [:add, :add_silent, :start, :delete] :operation The operation to perform. Required.
+    # @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 Error.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 an {Error} 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.
     # @option options [String] :adapter The name of the data adapter to use. Optional.
     # @option options [Array<String>] :items The names of the items that this request pertains to. Required if
-    #                 `:operation` is `:add` or `:add_silent`.
+    #                 `operation` is `:add` or `:add_silent`.
     # @option options [Array<String>] :fields The names of the fields that this request pertains to. Required if
-    #                 `:operation` is `:add` or `:add_silent`.
-    # @option options [:raw, :merge, :distinct, :command] :mode The subscription mode.
-    def execute(options)
-      result = execute_post_request build_payload(options)
+    #                 `operation` is `:add` or `:add_silent`.
+    # @option options [:distinct, :merge] :mode The subscription mode. Required if `operation` is `:add` or
+    #                 `:add_silent`.
+    # @option options [String] :selector The selector for table items. Optional.
+    def subscription_execute(operation, table, options = {})
+      options[:table] = table
 
-      raise ProtocolError.new(result[2], result[1]) if result.first == 'ERROR'
+      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 {RequestError} if the HTTP
     # request fails. Returns the response body split into individual lines.
     def execute_post_request(payload)
@@ -43,23 +73,39 @@ module Lightstreamer
 
     # 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(options)
-      params = {
-        LS_session: @session_id,
-        LS_table: options.fetch(:table),
-        LS_op: options.fetch(:operation)
-      }
+    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_data_adapter] = options[:adapter] if options.key? :adapter
-      params[:LS_id] = options[:items].join(' ') if options.key? :items
-      params[:LS_schema] = options[:fields].map(&:to_s).join(' ') if options.key? :fields
-      params[:LS_mode] = options[:mode].to_s.upcase if options.key? :mode
+      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

data/lib/lightstreamer/errors.rb

@@ -0,0 +1,206 @@
+module Lightstreamer
+  # Base class for all errors raised by this gem.
+  class Error < StandardError
+  end
+
+  # This error is raised when the session username and password check fails.
+  class AuthenticationError < Error
+  end
+
+  # This error is raised when the requested adapter set is unknown.
+  class UnknownAdapterSetError < Error
+  end
+
+  # This error is raise when trying to bind to a session that was initialized with a different and incompatible
+  # communication protocol.
+  class IncompatibleSessionError < Error
+  end
+
+  # This error is raised when the licensed maximum number of sessions is reached.
+  class LicensedMaximumSessionsReachedError < Error
+  end
+
+  # This error is raised when the configured maximum number of sessions is reached.
+  class ConfiguredMaximumSessionsReachedError < Error
+  end
+
+  # This error is raised when the configured maximum server load is reached.
+  class ConfiguredMaximumServerLoadReachedError < Error
+  end
+
+  # This error is raised when the creation of new sessions has been temporarily blocked.
+  class NewSessionsTemporarilyBlockedError < Error
+  end
+
+  # This error is raised when streaming is not available because of the current license terms.
+  class StreamingNotAvailableError < Error
+  end
+
+  # This error is raised when the specified table can't be modified because it is configured for unfiltered dispatching.
+  class TableModificationNotAllowedError < Error
+  end
+
+  # This error is raised when the specified data adapter is invalid or the data adapter is not specified and there is
+  # no default data adapter.
+  class InvalidDataAdapterError < Error
+  end
+
+  # This error occurs when the specified table is not found.
+  class UnknownTableError < Error
+  end
+
+  # This error is raised when an invalid item name is specified.
+  class InvalidItemError < Error
+  end
+
+  # This error is raised when an invalid item name for the given fields is specified.
+  class InvalidItemForFieldsError < Error
+  end
+
+  # This error is raised when an invalid field name is specified.
+  class InvalidFieldError < Error
+  end
+
+  # This error is raised when the specified subscription mode is not supported by one of the items.
+  class UnsupportedModeForItemError < Error
+  end
+
+  # This error is raised when an invalid selector is specified.
+  class InvalidSelectorError < Error
+  end
+
+  # This error is raised when unfiltered dispatching is requested on an item that does not allow it.
+  class UnfilteredDispatchingNotAllowedForItemError < Error
+  end
+
+  # This error is raised when unfiltered dispatching is requested on an item that does not support it.
+  class UnfilteredDispatchingNotSupportedForItemError < Error
+  end
+
+  # This error is raised when unfiltered dispatching is requested but is not allowed by the current license terms.
+  class UnfilteredDispatchingNotAllowedByLicenseError < Error
+  end
+
+  # This error is raised when `RAW` mode was requested but is not allowed by the current license terms.
+  class RawModeNotAllowedByLicenseError < Error
+  end
+
+  # This error is raised when subscriptions are not allowed by the current license terms.
+  class SubscriptionsNotAllowedByLicenseError < Error
+  end
+
+  # This error is raised when the specified progressive sequence number for the custom message was invalid.
+  class InvalidProgressiveNumberError < Error
+  end
+
+  # This error is raised when the client version requested is not supported by the server.
+  class ClientVersionNotSupportedError < Error
+  end
+
+  # This error is raised when a error defined by a metadata adapter is raised.
+  class MetadataAdapterError < Error
+    # @return [String] The error message from the metadata adapter.
+    attr_reader :adapter_error_message
+
+    # @return [Fixnum] The error code from the metadata adapter.
+    attr_reader :adapter_error_code
+
+    # Initializes this metadata adapter error with the specified error message and error code.
+    def initialize(message, code)
+      @adapter_error_message = message
+      @adapter_error_code = code.to_i
+
+      super message
+    end
+  end
+
+  # This error is raised when a sync error occurs, which most often means that the session ID provided is invalid and
+  # a new session needs to be created.
+  class SyncError < Error
+  end
+
+  # This error is raised when the specified session ID is for a session that has been terminated.
+  class SessionEndError < Error
+    # @return [Fixnum] The cause code specifying why the session was terminated by the server, or `nil` if unknown.
+    attr_reader :cause_code
+
+    # Initializes this session end error with the specified cause code.
+    #
+    # @param [Fixnum] cause_code
+    def initialize(cause_code = nil)
+      @cause_code = cause_code.to_i
+      super()
+    end
+  end
+
+  # This error is raised when an HTTP request error occurs.
+  class RequestError < Error
+    # @return [String] A description of the request error that occurred.
+    attr_reader :request_error_message
+
+    # @return [Fixnum] The HTTP code that was returned, or zero if unknown.
+    attr_reader :request_error_code
+
+    # Initializes this request error with a message and an HTTP code.
+    #
+    # @param [String] message The error description.
+    # @param [Integer] code The HTTP code for the request failure, if known.
+    def initialize(message, code)
+      @request_error_message = message
+      @request_error_code = code.to_i
+
+      super "Request error #{code}: #{message}"
+    end
+  end
+
+  # Base class for all errors raised by this gem.
+  class Error
+    # Takes a Lightstreamer error message and numeric code and returns an instance of the relevant error class that
+    # should be raised in response to the error.
+    #
+    # @param [String] message The error message.
+    # @param [Fixnum] code The numeric error code that is used to determine which {Error} subclass to instantiate.
+    #
+    # @return [Error]
+    def self.build(message, code)
+      code = code.to_i
+
+      if API_ERROR_CODE_TO_CLASS.key? code
+        API_ERROR_CODE_TO_CLASS[code].new
+      elsif code <= 0
+        MetadataAdapterError.new message, code
+      else
+        new message
+      end
+    end
+
+    API_ERROR_CODE_TO_CLASS = {
+      1 => AuthenticationError,
+      2 => UnknownAdapterSetError,
+      3 => IncompatibleSessionError,
+      7 => LicensedMaximumSessionsReachedError,
+      8 => ConfiguredMaximumSessionsReachedError,
+      9 => ConfiguredMaximumServerLoadReachedError,
+      10 => NewSessionsTemporarilyBlockedError,
+      11 => StreamingNotAvailableError,
+      13 => TableModificationNotAllowedError,
+      17 => InvalidDataAdapterError,
+      19 => UnknownTableError,
+      21 => InvalidItemError,
+      22 => InvalidItemForFieldsError,
+      23 => InvalidFieldError,
+      24 => UnsupportedModeForItemError,
+      25 => InvalidSelectorError,
+      26 => UnfilteredDispatchingNotAllowedForItemError,
+      27 => UnfilteredDispatchingNotSupportedForItemError,
+      28 => UnfilteredDispatchingNotAllowedByLicenseError,
+      29 => RawModeNotAllowedByLicenseError,
+      30 => SubscriptionsNotAllowedByLicenseError,
+      32 => InvalidProgressiveNumberError,
+      33 => InvalidProgressiveNumberError,
+      60 => ClientVersionNotSupportedError
+    }.freeze
+
+    private_constant :API_ERROR_CODE_TO_CLASS
+  end
+end

data/lib/lightstreamer/session.rb

@@ -14,6 +14,11 @@ module Lightstreamer
     # @return [String] The name of the adapter set to request from the Lightstreamer server. Set by {#initialize}.
     attr_reader :adapter_set
 
+    # @return [Error] 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}.
+    attr_reader :error
+
     # Initializes this new Lightstreamer session with the passed options.
     #
     # @param [Hash] options The options to create the session with.
@@ -32,10 +37,12 @@ module Lightstreamer
     end
 
     # Creates a new Lightstreamer session using the details passed to {#initialize}. If an error occurs then
-    # {ProtocolError} will be raised.
+    # an {Error} subclass will be raised.
     def connect
       return if @stream_connection
 
+      @error = nil
+
       create_stream_connection
       create_control_connection
       create_processing_thread
@@ -51,20 +58,31 @@ module Lightstreamer
       !@stream_connection.nil?
     end
 
-    # Disconnects this session and shuts down its stream connection and processing threads.
+    # Disconnects this session and terminates the session on the server. All worker threads are exited.
     def disconnect
-      @stream_connection.disconnect if @stream_connection
+      @control_connection.execute :destroy if @control_connection
 
-      if @processing_thread
-        Thread.kill @processing_thread
-        @processing_thread.join
-      end
+      @processing_thread.join 5 if @processing_thread
+    ensure
+      @stream_connection.disconnect if @stream_connection
+      @processing_thread.exit if @processing_thread
 
-      @processing_thread = @stream_connection = @control_connection = nil
+      @processing_thread = @control_connection = @stream_connection = nil
       @subscriptions = []
     end
 
-    # Subscribes this Lightstreamer session to the specified subscription.
+    # 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 an {Error} subclass will be raised.
+    def force_rebind
+      return unless @stream_connection
+
+      @control_connection.execute :force_rebind
+    end
+
+    # Subscribes this Lightstreamer session to the specified subscription. If an error occurs then an {Error} subclass
+    # will be raised.
     #
     # @param [Subscription] subscription The new subscription to subscribe to.
     def subscribe(subscription)
@@ -72,14 +90,14 @@ module Lightstreamer
 
       @subscriptions_mutex.synchronize { @subscriptions << subscription }
 
-      begin
-        @control_connection.execute table: subscription.id, operation: :add, mode: subscription.mode,
-                                    items: subscription.items, fields: subscription.fields,
-                                    adapter: subscription.adapter
-      rescue
-        @subscriptions_mutex.synchronize { @subscriptions.delete subscription }
-        raise
-      end
+      options = { mode: subscription.mode, items: subscription.items, fields: subscription.fields,
+                  adapter: subscription.adapter, maximum_update_frequency: subscription.maximum_update_frequency,
+                  selector: subscription.selector }
+
+      @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.
@@ -97,7 +115,7 @@ module Lightstreamer
     def unsubscribe(subscription)
       raise ArgumentError, 'Unknown subscription' unless subscribed? subscription
 
-      @control_connection.execute table: subscription.id, operation: :delete
+      @control_connection.subscription_execute :delete, subscription.id
 
       @subscriptions_mutex.synchronize { @subscriptions.delete subscription }
     end
@@ -123,6 +141,8 @@ module Lightstreamer
     # Starts the processing thread that reads and processes incoming data from the stream connection.
     def create_processing_thread
       @processing_thread = Thread.new do
+        Thread.current.abort_on_exception = true
+
         loop do
           line = @stream_connection.read_line
 
@@ -131,9 +151,9 @@ module Lightstreamer
           process_stream_data line unless line.empty?
         end
 
-        # The stream connection has died, so exit the processing thread
-        warn "Lightstreamer: processing thread exiting, error: #{@stream_connection.error}"
-        @processing_thread = @stream_connection = @control_connection = nil
+        # The stream connection has terminated so the session is assumed to be over
+        @error = @stream_connection.error
+        @processing_thread = @control_connection = @stream_connection = nil
       end
     end
 

data/lib/lightstreamer/stream_connection.rb

@@ -11,8 +11,8 @@ module Lightstreamer
     # @return [String] The control address returned from the server when this stream connection was initiated.
     attr_reader :control_address
 
-    # @return [ProtocolError, RequestError, String] If an error occurs on the stream thread that causes this stream
-    #         to disconnect then the exception or error details will be stored in this attribute.
+    # @return [Error] If an error occurs on the stream thread that causes the stream to disconnect then the
+    #         error will be stored in this attribute.
     attr_reader :error
 
     # Establishes a new stream connection using the authentication details from the passed session.
@@ -27,10 +27,11 @@ module Lightstreamer
     end
 
     # Establishes a new stream connection using the authentication details from the session that was passed to
-    # {#initialize}. Raises {ProtocolError} or {RequestError} on failure.
+    # {#initialize}. Raises an {Error} subclass on failure.
     def connect
       return if @thread
       @session_id = @error = nil
+      @queue.clear
 
       create_stream_thread
 
@@ -51,7 +52,7 @@ module Lightstreamer
     # Disconnects this stream connection by shutting down the streaming thread.
     def disconnect
       if @thread
-        Thread.kill @thread
+        @thread.exit
         @thread.join
       end
 
@@ -73,22 +74,17 @@ module Lightstreamer
 
     def create_stream_thread
       @thread = Thread.new do
-        begin
-          stream_thread_main
-        rescue StandardError => error
-          @error = error
-        end
+        Thread.current.abort_on_exception = true
 
-        @thread = nil
-      end
-    end
+        connect_stream_and_process_data stream_create_post_request
 
-    def stream_thread_main
-      connect_stream_and_process_data stream_create_post_request
+        while @loop
+          @loop = false
+          connect_stream_and_process_data stream_bind_post_request
+        end
 
-      while @loop
-        @loop = false
-        connect_stream_and_process_data stream_bind_post_request
+        @thread = nil
+        @queue.push nil
       end
     end
 
@@ -114,6 +110,7 @@ module Lightstreamer
       end
 
       request.on_complete do |response|
+        @error = @header.error if @header
         @error = RequestError.new(response.return_message, response.response_code) unless response.success?
       end
 
@@ -133,7 +130,6 @@ module Lightstreamer
 
       @control_address = @header['ControlAddress']
       @session_id = @header['SessionId']
-      @error = @header.error
 
       @header = nil
     end
@@ -141,6 +137,8 @@ module Lightstreamer
     def process_body_line(line)
       if line == 'LOOP'
         @loop = true
+      elsif line =~ /^END/
+        @error = SessionEndError.new line[4..-1]
       elsif !ignore_line?(line)
         @queue.push line
       end

data/lib/lightstreamer/stream_connection_header.rb

@@ -2,8 +2,8 @@ module Lightstreamer
   # Helper class that processes the contents of the header returned by the server when a new stream connection is
   # created or an existing session is bound to.
   class StreamConnectionHeader
-    # @return [ProtocolError, RequestError] If there was an error in the header then this value will be set to the
-    #         error instance that should be raised in response.
+    # @return [Error] If there was an error in the header then this value will be set to the error instance that should
+    #         be raised in response.
     attr_reader :error
 
     def initialize
@@ -20,21 +20,16 @@ module Lightstreamer
     def process_header_line(line)
       @lines << line
 
-      unless %w(OK ERROR).include? @lines.first
-        @error = RequestError.new line
-        return false
-      end
+      return process_success if @lines.first == 'OK'
+      return process_error if @lines.first == 'ERROR'
+      return process_end if @lines.first == 'END'
+      return process_sync_error if @lines.first == 'SYNC ERROR'
 
-      return true if @lines.first == 'OK' && !line.empty?
-      return true if @lines.first == 'ERROR' && @lines.size < 3
-
-      parse_header
-
-      false
+      process_unrecognized
     end
 
     # Returns the value for the item with the specified name in this header, or `nil` if no item with the specified name
-    # was part of this header
+    # was part of this header.
     #
     # @param [String] item_name The name of the item to return the header value for.
     #
@@ -46,15 +41,31 @@ module Lightstreamer
 
     private
 
-    def parse_header
-      if @lines.first == 'OK'
-        @lines[1..-1].each do |line|
-          match = line.match(/^([^:]*):(.*)$/)
-          @data[match.captures[0]] = match.captures[1] if match
-        end
-      elsif @lines.first == 'ERROR'
-        @error = ProtocolError.new @lines[2], @lines[1]
-      end
+    def process_success
+      match = @lines.last.match(/^([^:]*):(.*)$/)
+      @data[match.captures[0]] = match.captures[1] if match
+
+      !@lines.last.empty?
+    end
+
+    def process_error
+      @error = Error.build @lines[2], @lines[1]
+      true
+    end
+
+    def process_end
+      @error = SessionEndError.new @lines[1]
+      true
+    end
+
+    def process_sync_error
+      @error = SyncError.new
+      false
+    end
+
+    def process_unrecognized
+      @error = Error.new @lines.join(' ')
+      true
     end
   end
 end

data/lib/lightstreamer/subscription.rb

@@ -1,8 +1,8 @@
 module Lightstreamer
-  # Describes a subscription that can be bound to a Lightstreamer session in order to consume its data. A subscription
-  # is described by the options passed to {#initialize}. Incoming data can be consumed by registering an asynchronous
-  # data callback using {#add_data_callback}, or by polling {#retrieve_item_data}. Subscriptions start receiving data
-  # only once they are attached to a Lightstreamer session using {Session#subscribe}.
+  # 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 {#add_data_callback}, or by polling {#retrieve_item_data}. Subscriptions start receiving data only
+  # once they are attached to a session using {Session#subscribe}.
   class Subscription
     # @return [Fixnum] The unique identification number of this subscription. This is used to identify the subscription
     #                  in incoming Lightstreamer data.
@@ -21,6 +21,13 @@ module Lightstreamer
     #                  If `nil` then the default data adapter will be used.
     attr_reader :adapter
 
+    # @return [String] The selector for table items. Optional.
+    attr_reader :selector
+
+    # @return [Float] 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.
+    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.
     #
@@ -30,13 +37,18 @@ module Lightstreamer
     # @option options [:distinct, :merge] :mode The operation mode of this subscription.
     # @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] :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.
     def initialize(options)
       @id = self.class.next_id
 
-      @items = Array(options.fetch(:items))
-      @fields = Array(options.fetch(:fields))
+      @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
 
       @data_mutex = Mutex.new
       clear_data

data/lib/lightstreamer/utf16.rb

@@ -3,20 +3,29 @@ module Lightstreamer
   module UTF16
     module_function
 
-    # Decodes any UTF-16 escape sequences in the form '\uXXXX' into a new string. Invalid escape sequences are removed.
+    # Decodes any UTF-16 escape sequences in the form '\uXXXX' in the passed string. Invalid escape sequences are
+    # removed.
+    #
+    # @param [String] string The string to decode.
+    #
+    # @return [String]
     def decode_escape_sequences(string)
       string = decode_surrogate_pairs_escape_sequences string
 
-      # Match all remaining escape sequences
+      # Match all escape sequences
       string.gsub(/\\u[A-F\d]{4}/i) do |escape_sequence|
         codepoint = escape_sequence[2..-1].hex
 
-        # Codepoints greater than 0xD7FF are invalid
+        # Codepoints greater than 0xD7FF are invalid are ignored
         codepoint < 0xD800 ? [codepoint].pack('U') : ''
       end
     end
 
-    # Converts any UTF-16 surrogate pairs escape sequences in the form '\uXXXX\uYYYY' into UTF-8.
+    # Decodes any UTF-16 surrogate pairs escape sequences in the form '\uXXXX\uYYYY' in the passed string.
+    #
+    # @param [String] string The string to decode.
+    #
+    # @return [String]
     def decode_surrogate_pairs_escape_sequences(string)
       string.gsub(/\\uD[89AB][A-F\d]{2}\\uD[C-F][A-F\d]{2}/i) do |escape_sequence|
         high_surrogate = escape_sequence[2...6].hex

data/lib/lightstreamer/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lightstreamer
 version: !ruby/object:Gem::Version
-  version: '0.3'
+  version: '0.4'
 platform: ruby
 authors:
 - Richard Viney
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-24 00:00:00.000000000 Z
+date: 2016-07-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -179,9 +179,8 @@ files:
 - 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/protocol_error.rb
-- lib/lightstreamer/request_error.rb
 - lib/lightstreamer/session.rb
 - lib/lightstreamer/stream_connection.rb
 - lib/lightstreamer/stream_connection_header.rb

data/lib/lightstreamer/protocol_error.rb

@@ -1,22 +0,0 @@
-module Lightstreamer
-  # This error class is raised by {Session} when a request to the Lightstreamer API fails with a Lightstreamer-specific
-  # error code and error message.
-  class ProtocolError < StandardError
-    # @return [String] A description of the Lightstreamer error that occurred.
-    attr_reader :error
-
-    # @return [Fixnum] The numeric code of the Lightstreamer error.
-    attr_reader :code
-
-    # Initializes this protocol error with the specific message and code.
-    #
-    # @param [String] error The error description.
-    # @param [Integer] code The numeric code for the error.
-    def initialize(error, code)
-      @error = error.to_s
-      @code = code.to_i
-
-      super "Lightstreamer error: #{@error}, code: #{code}"
-    end
-  end
-end

data/lib/lightstreamer/request_error.rb

@@ -1,21 +0,0 @@
-module Lightstreamer
-  # This error class is raised by {Session} when a request to the Lightstreamer API fails.
-  class RequestError < StandardError
-    # @return [String] A description of the error that occurred when the request was attempted.
-    attr_reader :error
-
-    # @return [Fixnum] The HTTP code that was returned, or `nil` if unknown.
-    attr_reader :http_code
-
-    # Initializes this request error with a message and an HTTP code.
-    #
-    # @param [String] error The error description.
-    # @param [Integer] http_code The HTTP code for the request failure, if known.
-    def initialize(error, http_code = nil)
-      @error = error.to_s
-      @http_code = http_code ? http_code.to_i : nil
-
-      super "Request error: #{error}#{http_code ? ", http code: #{http_code}" : ''}"
-    end
-  end
-end