lightstreamer 0.4 → 0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 863ad0ba9936b00dca802004782358a03cf5cd36
-  data.tar.gz: a13adc3e4b6b9945580bc02927826d61742dba1d
+  metadata.gz: 3c64dd0d680841a38eb530d0a17fa0700985426a
+  data.tar.gz: 5a66944aff7e81aeef70c8cb5551703c1389c281
 SHA512:
-  metadata.gz: 7f9dd91cc66467027ddd209d0c964559db461e8b9a05c1cb9aa583ae42d1997516c0196ea2be18c0fbc5d317db97fcef10ce81e32cefe677390dd4c8f339ebfc
-  data.tar.gz: 4863842643a0d7a876f6efa2b41270044f7ada1479c0154e452e02f7e1d6b2e75c39f6f24d79029b633dd7402c3cd6a5d24a41e5c3dba057013a0ddc403b9dbc
+  metadata.gz: dca8fbcb4375c44451946467847f764b072e86b45d7f7c6d50b4240e9c8a4ae3d3eac5cbb3ee2019365e2436bdcadbeb21bda2dd9eb2a9bdd89bed5bd6657bcd
+  data.tar.gz: 1cd6cc4234ddcf107194d59d4443a69e3ffa4f6ce2bfed5671f5e5ac72c33bc9a64ccfda4086fca1901489133e7f43f32ef787bf32fc1b3a57304dd2fec43c78

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Lightstreamer Changelog
 
+### 0.5 — July 26, 2016
+
+- Improved handling of `:distinct` subscriptions
+- Subscriptions can now request an unfiltered stream and handle any overflow messages from the server using
+  `Lightstreamer::Subscription#on_callback`
+- Added a connection timeout to all requests
+- Unhandled exceptions in subscription data callbacks are no longer automatically rescued
+- Improved API documentation
+- Renamed `Lightstreamer::Subscription#add_data_callback` to `Lightstreamer::Subscription#on_data`
+- Replaced `Lightstreamer::Subscription#remove_data_callback` with `Lightstreamer::Subscription#clear_callbacks`
+- Renamed `Lightstreamer::Error` class to `Lightstreamer::LightstreamerError`
+- Renamed `Lightstreamer::Subscription#retrieve_item_data` to `Lightstreamer::Subscription#item_data`
+- Removed `Lightstreamer::Subscription#clear_data_for_item`
+
 ### 0.4 — July 25, 2016
 
 - Added support for specifying a subscription's selector and maximum update frequency

data/README.md

@@ -53,7 +53,7 @@ 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.add_data_callback do |subscription, item_name, item_data, new_values|
+subscription.on_data do |subscription, item_name, item_data, new_values|
   queue.push item_data
 end
 

data/lib/lightstreamer.rb

@@ -2,19 +2,19 @@ require 'thor'
 require 'typhoeus'
 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/overflow_message'
+require 'lightstreamer/messages/update_message'
 require 'lightstreamer/session'
 require 'lightstreamer/stream_connection'
 require 'lightstreamer/stream_connection_header'
 require 'lightstreamer/subscription'
-require 'lightstreamer/utf16'
 require 'lightstreamer/version'
 
-require 'lightstreamer/cli/main'
-require 'lightstreamer/cli/commands/stream_command'
-
 # This module contains all the code for the Lightstreamer gem. See `README.md` to get started with using this gem.
 module Lightstreamer
 end

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

@@ -13,7 +13,7 @@ module Lightstreamer
       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'
+      option :maximum_update_frequency, desc: 'The maximum number of updates per second for each item'
 
       def stream
         session = create_session
@@ -24,7 +24,9 @@ module Lightstreamer
         session.subscribe create_subscription
 
         loop do
-          puts @queue.pop
+          puts @queue.pop unless @queue.empty?
+
+          raise session.error if session.error
         end
       end
 
@@ -40,7 +42,8 @@ module Lightstreamer
       def create_subscription
         subscription = Lightstreamer::Subscription.new subscription_options
 
-        subscription.add_data_callback(&method(:subscription_data_callback))
+        subscription.on_data(&method(:on_data))
+        subscription.on_overflow(&method(:on_overflow))
 
         subscription
       end
@@ -52,9 +55,13 @@ module Lightstreamer
         }
       end
 
-      def subscription_data_callback(_subscription, item_name, _item_data, new_values)
+      def on_data(_subscription, item_name, _item_data, new_values)
         @queue.push "#{item_name} - #{new_values.map { |key, value| "#{key}: #{value}" }.join ', '}"
       end
+
+      def on_overflow(_subscription, item_name, overflow_size)
+        @queue.push "Overflow of size #{overflow_size} on item #{item_name}"
+      end
     end
   end
 end

data/lib/lightstreamer/control_connection.rb

@@ -1,5 +1,7 @@
 module Lightstreamer
-  # This is an internal class used by {Session} and is responsible for sending Lightstreamer control requests.
+  # 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.
@@ -12,30 +14,22 @@ module Lightstreamer
     end
 
     # 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.
+    # 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 Error.build(result[2], result[1]) if result.first != 'OK'
+      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 an {Error} subclass will be raised.
+    # 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.
-    # @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`.
-    # @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 [: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
 
@@ -64,7 +58,7 @@ module Lightstreamer
     # 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)
-      response = Typhoeus.post @control_url, body: payload
+      response = Typhoeus.post @control_url, body: payload, timeout: 15
 
       raise RequestError.new(response.return_message, response.response_code) unless response.success?
 

data/lib/lightstreamer/errors.rb

@@ -1,114 +1,120 @@
 module Lightstreamer
-  # Base class for all errors raised by this gem.
-  class Error < StandardError
+  class LightstreamerError < StandardError
   end
 
   # This error is raised when the session username and password check fails.
-  class AuthenticationError < Error
+  class AuthenticationError < LightstreamerError
   end
 
   # This error is raised when the requested adapter set is unknown.
-  class UnknownAdapterSetError < Error
+  class UnknownAdapterSetError < LightstreamerError
   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
+  class IncompatibleSessionError < LightstreamerError
   end
 
   # This error is raised when the licensed maximum number of sessions is reached.
-  class LicensedMaximumSessionsReachedError < Error
+  class LicensedMaximumSessionsReachedError < LightstreamerError
   end
 
   # This error is raised when the configured maximum number of sessions is reached.
-  class ConfiguredMaximumSessionsReachedError < Error
+  class ConfiguredMaximumSessionsReachedError < LightstreamerError
   end
 
   # This error is raised when the configured maximum server load is reached.
-  class ConfiguredMaximumServerLoadReachedError < Error
+  class ConfiguredMaximumServerLoadReachedError < LightstreamerError
   end
 
   # This error is raised when the creation of new sessions has been temporarily blocked.
-  class NewSessionsTemporarilyBlockedError < Error
+  class NewSessionsTemporarilyBlockedError < LightstreamerError
   end
 
   # This error is raised when streaming is not available because of the current license terms.
-  class StreamingNotAvailableError < Error
+  class StreamingNotAvailableError < LightstreamerError
   end
 
   # This error is raised when the specified table can't be modified because it is configured for unfiltered dispatching.
-  class TableModificationNotAllowedError < Error
+  class TableModificationNotAllowedError < LightstreamerError
   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
+  class InvalidDataAdapterError < LightstreamerError
   end
 
   # This error occurs when the specified table is not found.
-  class UnknownTableError < Error
+  class UnknownTableError < LightstreamerError
   end
 
   # This error is raised when an invalid item name is specified.
-  class InvalidItemError < Error
+  class InvalidItemError < LightstreamerError
   end
 
   # This error is raised when an invalid item name for the given fields is specified.
-  class InvalidItemForFieldsError < Error
+  class InvalidItemForFieldsError < LightstreamerError
   end
 
   # This error is raised when an invalid field name is specified.
-  class InvalidFieldError < Error
+  class InvalidFieldError < LightstreamerError
   end
 
   # This error is raised when the specified subscription mode is not supported by one of the items.
-  class UnsupportedModeForItemError < Error
+  class UnsupportedModeForItemError < LightstreamerError
   end
 
   # This error is raised when an invalid selector is specified.
-  class InvalidSelectorError < Error
+  class InvalidSelectorError < LightstreamerError
   end
 
   # This error is raised when unfiltered dispatching is requested on an item that does not allow it.
-  class UnfilteredDispatchingNotAllowedForItemError < Error
+  class UnfilteredDispatchingNotAllowedForItemError < LightstreamerError
   end
 
   # This error is raised when unfiltered dispatching is requested on an item that does not support it.
-  class UnfilteredDispatchingNotSupportedForItemError < Error
+  class UnfilteredDispatchingNotSupportedForItemError < LightstreamerError
   end
 
   # This error is raised when unfiltered dispatching is requested but is not allowed by the current license terms.
-  class UnfilteredDispatchingNotAllowedByLicenseError < Error
+  class UnfilteredDispatchingNotAllowedByLicenseError < LightstreamerError
   end
 
   # This error is raised when `RAW` mode was requested but is not allowed by the current license terms.
-  class RawModeNotAllowedByLicenseError < Error
+  class RawModeNotAllowedByLicenseError < LightstreamerError
   end
 
   # This error is raised when subscriptions are not allowed by the current license terms.
-  class SubscriptionsNotAllowedByLicenseError < Error
+  class SubscriptionsNotAllowedByLicenseError < LightstreamerError
   end
 
   # This error is raised when the specified progressive sequence number for the custom message was invalid.
-  class InvalidProgressiveNumberError < Error
+  class InvalidProgressiveNumberError < LightstreamerError
   end
 
   # This error is raised when the client version requested is not supported by the server.
-  class ClientVersionNotSupportedError < Error
+  class ClientVersionNotSupportedError < LightstreamerError
   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.
+  class MetadataAdapterError < LightstreamerError
+    # The error message from the metadata adapter.
+    #
+    # @return [String]
     attr_reader :adapter_error_message
 
-    # @return [Fixnum] The error code from the metadata adapter.
+    # The error code from the metadata adapter.
+    #
+    # @return [Fixnum]
     attr_reader :adapter_error_code
 
     # Initializes this metadata adapter error with the specified error message and error code.
+    #
+    # @param [String] message The error message.
+    # @param [Fixnum] code The error code.
     def initialize(message, code)
       @adapter_error_message = message
-      @adapter_error_code = code.to_i
+      @adapter_error_code = code
 
       super message
     end
@@ -116,52 +122,77 @@ module Lightstreamer
 
   # 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
+  class SyncError < LightstreamerError
   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.
+  # This error is raised when the session was explicitly closed on the server side. The reason for this is specified by
+  # {#cause_code}.
+  class SessionEndError < LightstreamerError
+    # The cause code specifying why the session was terminated by the server, or `nil` if unknown.
+    #
+    # The following codes are defined, but other values are allowed and signal an unexpected cause.
+    #
+    # - `<=0` - The session was closed through a `destroy` request and this custom code was specified.
+    # - `31` - The session was closed through a `destroy` request.
+    # - `32` - The session was closed by an administrator through JMX.
+    # - `33`, `34` - An unexpected error occurred on the server.
+    # - `35` - Another session was opened on the metadata adapter and the metadata adpater only supports one session.
+    # - `40` - A manual rebind to the session was done by another client.
+    # - `48` - The maximum session duration configured on the server has been reached. This is meant as a way to refresh
+    #          the session and the client should recover by opening a new session immediately.
+    #
+    # @return [Fixnum, nil]
     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
+    # @param [Session?] cause_code See {#cause_code} for details.
+    def initialize(cause_code)
+      @cause_code = 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.
+  class RequestError < LightstreamerError
+    # The description of the request error that occurred.
+    #
+    # @return [String]
     attr_reader :request_error_message
 
-    # @return [Fixnum] The HTTP code that was returned, or zero if unknown.
+    # The HTTP code that was returned, or zero if unknown.
+    #
+    # @return [Fixnum]
     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.
+    # @param [Fixnum] code The HTTP code for the request failure, or zero if unknown.
     def initialize(message, code)
       @request_error_message = message
-      @request_error_code = code.to_i
+      @request_error_code = code
 
-      super "Request error #{code}: #{message}"
+      if code != 0
+        super "#{code}: #{message}"
+      else
+        super message
+      end
     end
   end
 
   # Base class for all errors raised by this gem.
-  class Error
+  class LightstreamerError
     # 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.
+    # @param [Fixnum] code The numeric error code that is used to determine which {LightstreamerError} subclass to
+    #        instantiate.
     #
     # @return [Error]
+    #
+    # @private
     def self.build(message, code)
       code = code.to_i
 
@@ -170,7 +201,7 @@ module Lightstreamer
       elsif code <= 0
         MetadataAdapterError.new message, code
       else
-        new message
+        new "#{code}: #{message}"
       end
     end
 

data/lib/lightstreamer/line_buffer.rb

@@ -1,13 +1,18 @@
 module Lightstreamer
-  # Helper class that takes an incoming stream of ASCII data and yields back individual lines as they become complete.
+  # Helper class used by {StreamConnection} that takes an incoming stream of ASCII data and yields back individual lines
+  # as they become complete.
+  #
+  # @private
   class LineBuffer
     def initialize
       @buffer = ''
     end
 
-    # Appends a new piece of ASCII data to this buffer. Any lines that are now complete will be yielded back.
+    # Appends a new piece of ASCII data to this buffer and yields back any lines that are now complete.
     #
     # @param [String] data The new piece of ASCII data.
+    #
+    # @yieldparam [String] line The new line that is now complete.
     def process(data)
       @buffer << data
 

data/lib/lightstreamer/messages/overflow_message.rb

@@ -0,0 +1,40 @@
+module Lightstreamer
+  # Helper class used by {Subscription} in order to parse incoming overflow messages.
+  #
+  # @private
+  class OverflowMessage
+    # The index of the item this overflow message applies to.
+    #
+    # @return [Fixnum]
+    attr_accessor :item_index
+
+    # The size of the overflow that occurred.
+    #
+    # @return [Fixnum]
+    attr_accessor :overflow_size
+
+    class << self
+      # 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.item_index = match.captures[0].to_i - 1
+        return unless message.item_index < items.size
+
+        message.overflow_size = match.captures[1].to_i
+
+        message
+      end
+
+      private
+
+      def table_regexp(table_id)
+        Regexp.new "^#{table_id},(\\d+),OV(\\d+)$"
+      end
+    end
+  end
+end

data/lib/lightstreamer/messages/update_message.rb

@@ -0,0 +1,86 @@
+module Lightstreamer
+  # Helper class used by {Subscription} in order to parse incoming update messages.
+  #
+  # @private
+  class UpdateMessage
+    # The index of the item this update message applies to.
+    #
+    # @return [Fixnum]
+    attr_accessor :item_index
+
+    # The field values specified by this update message.
+    #
+    # @return [Array]
+    attr_accessor :values
+
+    class << self
+      # 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.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
+      end
+
+      private
+
+      def table_regexp(table_id, fields)
+        Regexp.new "^#{table_id},(\\d+)#{'\|(.*)' * fields.size}$"
+      end
+
+      def parse_values(values, fields)
+        hash = {}
+
+        values.each_with_index do |value, index|
+          next if value == ''
+
+          hash[fields[index]] = parse_raw_field_value value
+        end
+
+        hash
+      end
+
+      def parse_raw_field_value(value)
+        return '' if value == '$'
+        return nil if value == '#'
+
+        value = value[1..-1] if value =~ /^(\$|#)/
+
+        decode_escape_sequences value
+      end
+
+      # Decodes any UTF-16 escape sequences in the form '\uXXXX' in the passed string. Invalid escape sequences are
+      # removed.
+      def decode_escape_sequences(string)
+        string = decode_surrogate_pair_escape_sequences string
+
+        string.gsub(/\\u[A-F\d]{4}/i) do |escape_sequence|
+          codepoint = escape_sequence[2..-1].hex
+
+          # Codepoints greater than 0xD7FF are invalid and so are removed
+          codepoint < 0xD800 ? [codepoint].pack('U') : ''
+        end
+      end
+
+      # Decodes any UTF-16 surrogate pair escape sequences in the form '\uXXXX\uYYYY' in the passed string.
+      def decode_surrogate_pair_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
+          low_surrogate = escape_sequence[8...12].hex
+
+          codepoint = 0x10000 + ((high_surrogate - 0xD800) << 10) + (low_surrogate - 0xDC00)
+
+          [codepoint].pack 'U'
+        end
+      end
+    end
+  end
+end

data/lib/lightstreamer/session.rb

@@ -2,30 +2,40 @@ 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.
   class Session
-    # @return [String] The URL of the Lightstreamer server to connect to. Set by {#initialize}.
+    # The URL of the Lightstreamer server to connect to. Set by {#initialize}.
+    #
+    # @return [String]
     attr_reader :server_url
 
-    # @return [String] The username to connect to the Lightstreamer server with. Set by {#initialize}.
+    # The username to connect to the Lightstreamer server with. Set by {#initialize}.
+    #
+    # @return [String, nil]
     attr_reader :username
 
-    # @return [String] The password to connect to the Lightstreamer server with. Set by {#initialize}.
+    # The password to connect to the Lightstreamer server with. Set by {#initialize}.
+    #
+    # @return [String, nil]
     attr_reader :password
 
-    # @return [String] The name of the adapter set to request from the Lightstreamer server. Set by {#initialize}.
+    # The name of the adapter set to request from the Lightstreamer server. Set by {#initialize}.
+    #
+    # @return [String, nil]
     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}.
+    # 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}.
+    #
+    # @return [Error, nil]
     attr_reader :error
 
     # Initializes this new Lightstreamer session with the passed options.
     #
     # @param [Hash] options The options to create the session with.
     # @option options [String] :server_url The URL of the Lightstreamer server. Required.
-    # @option options [String] :username The username to connect to the server with. Optional.
-    # @option options [String] :password The password to connect to the server with. Optional.
-    # @option options [String] :adapter_set The name of the adapter set to request from the server. Optional.
+    # @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.
     def initialize(options = {})
       @subscriptions = []
       @subscriptions_mutex = Mutex.new
@@ -37,7 +47,7 @@ module Lightstreamer
     end
 
     # Creates a new Lightstreamer session using the details passed to {#initialize}. If an error occurs then
-    # an {Error} subclass will be raised.
+    # a {LightstreamerError} subclass will be raised.
     def connect
       return if @stream_connection
 
@@ -74,15 +84,15 @@ 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 an {Error} subclass will be raised.
+    # requested explicitly by the client. If an error occurs then a {LightstreamerError} 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.
+    # Subscribes this Lightstreamer session to the specified subscription. If an error occurs then a
+    # {LightstreamerError} subclass will be raised.
     #
     # @param [Subscription] subscription The new subscription to subscribe to.
     def subscribe(subscription)

data/lib/lightstreamer/stream_connection.rb

@@ -1,18 +1,23 @@
 module Lightstreamer
-  # Manages a long-running Lightstreamer connection that handles incoming streaming data on a separate thread and
-  # makes it available for consumption via the {#read_line} method.
+  # Internal class used by {Session} that manages a long-running Lightstreamer connection and handles incoming streaming
+  # data on a separate thread and makes it available for consumption through {#read_line}.
+  #
+  # @private
   class StreamConnection
-    # @return [Thread] The thread used to process incoming streaming data.
-    attr_reader :thread
-
-    # @return [String] The session ID returned from the server when this stream connection was initiated.
+    # The session ID returned from the server when this stream connection was initiated.
+    #
+    # @return [String, nil]
     attr_reader :session_id
 
-    # @return [String] The control address returned from the server when this stream connection was initiated.
+    # The control address returned from the server when this stream connection was initiated.
+    #
+    # @return [String, nil]
     attr_reader :control_address
 
-    # @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.
+    # If an error occurs on the stream thread that causes the stream to disconnect then the error will be stored in this
+    # attribute.
+    #
+    # @return [Error, nil]
     attr_reader :error
 
     # Establishes a new stream connection using the authentication details from the passed session.
@@ -24,22 +29,26 @@ module Lightstreamer
 
       @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
 
     # Establishes a new stream connection using the authentication details from the session that was passed to
-    # {#initialize}. Raises an {Error} subclass on failure.
+    # {#initialize}. Raises a {LightstreamerError} subclass on failure.
     def connect
       return if @thread
-      @session_id = @error = nil
       @queue.clear
 
-      create_stream_thread
-
-      # Wait until the connection result is known
-      until @session_id || @error
+      @connect_result_mutex.synchronize do
+        create_stream_thread
+        @connect_result_condition_variable.wait @connect_result_mutex
       end
 
-      raise @error if @error
+      return unless @error
+
+      @thread = nil
+      raise @error
     end
 
     # Returns whether or not this stream connection is connected.
@@ -51,12 +60,12 @@ module Lightstreamer
 
     # Disconnects this stream connection by shutting down the streaming thread.
     def disconnect
-      if @thread
-        @thread.exit
-        @thread.join
-      end
+      return unless @thread
+
+      @thread.exit
+      @thread.join
 
-      @session_id = @control_address = @error = @thread = nil
+      @thread = nil
     end
 
     # Reads the next line of streaming data. If the streaming thread is alive then this method blocks the calling thread
@@ -94,11 +103,11 @@ module Lightstreamer
 
       params[:LS_adapter_set] = @session.adapter_set if @session.adapter_set
 
-      Typhoeus::Request.new @stream_create_url, method: :post, params: params
+      Typhoeus::Request.new @stream_create_url, method: :post, connecttimeout: 15, params: params
     end
 
     def stream_bind_post_request
-      Typhoeus::Request.new @stream_bind_url, method: :post, params: { LS_session: @session_id }
+      Typhoeus::Request.new @stream_bind_url, method: :post, connecttimeout: 15, params: { LS_session: @session_id }
     end
 
     def connect_stream_and_process_data(request)
@@ -109,12 +118,19 @@ module Lightstreamer
         buffer.process data, &method(:process_stream_line)
       end
 
-      request.on_complete do |response|
-        @error = @header.error if @header
-        @error = RequestError.new(response.return_message, response.response_code) unless response.success?
-      end
-
+      request.on_complete(&method(:on_request_complete))
       request.run
+
+      signal_connect_result_ready
+    end
+
+    def on_request_complete(response)
+      @error = @header.error if @header
+      @error = RequestError.new(response.return_message, response.response_code) unless response.success?
+    end
+
+    def signal_connect_result_ready
+      @connect_result_mutex.synchronize { @connect_result_condition_variable.signal }
     end
 
     def process_stream_line(line)
@@ -128,24 +144,23 @@ module Lightstreamer
     def process_header_line(line)
       return if @header.process_header_line line
 
-      @control_address = @header['ControlAddress']
       @session_id = @header['SessionId']
+      @control_address = @header['ControlAddress']
+      @error = @header.error
+
+      signal_connect_result_ready
 
       @header = nil
     end
 
     def process_body_line(line)
-      if line == 'LOOP'
+      if line =~ /^LOOP/
         @loop = true
       elsif line =~ /^END/
         @error = SessionEndError.new line[4..-1]
-      elsif !ignore_line?(line)
+      elsif line !~ /^(PROBE|Preamble:.*)$/
         @queue.push line
       end
     end
-
-    def ignore_line?(line)
-      line =~ /^(PROBE|Preamble:.*)$/
-    end
   end
 end

data/lib/lightstreamer/stream_connection_header.rb

@@ -1,9 +1,13 @@
 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.
+  # Internal class used by {StreamConnection} 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.
+  #
+  # @private
   class StreamConnectionHeader
-    # @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.
+    # 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, nil]
     attr_reader :error
 
     def initialize
@@ -49,7 +53,7 @@ module Lightstreamer
     end
 
     def process_error
-      @error = Error.build @lines[2], @lines[1]
+      @error = LightstreamerError.build @lines[2], @lines[1]
       true
     end
 
@@ -64,7 +68,7 @@ module Lightstreamer
     end
 
     def process_unrecognized
-      @error = Error.new @lines.join(' ')
+      @error = LightstreamerError.new @lines.join(' ')
       true
     end
   end

data/lib/lightstreamer/subscription.rb

@@ -1,45 +1,61 @@
 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 {#add_data_callback}, or by polling {#retrieve_item_data}. Subscriptions start receiving data only
-  # once they are attached to a session using {Session#subscribe}.
+  # callback using {#on_data} or by polling using {#item_data}. Subscriptions start receiving data 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.
+    # The unique identification number of this subscription.
+    #
+    # @return [Fixnum]
     attr_reader :id
 
-    # @return [Array] The names of the items to subscribe to.
+    # The names of the items to subscribe to.
+    #
+    # @return [Array]
     attr_reader :items
 
-    # @return [Array] The names of the fields to subscribe to on the items.
+    # The names of the fields to subscribe to on the items.
+    #
+    # @return [Array]
     attr_reader :fields
 
-    # @return [:distinct, :merge] The operation mode of this subscription.
+    # The operation mode of this subscription.
+    #
+    # @return [:distinct, :merge]
     attr_reader :mode
 
-    # @return [String] 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.
+    # 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.
+    #
+    # @return [String, nil]
     attr_reader :adapter
 
-    # @return [String] The selector for table items. Optional.
+    # The selector for table items.
+    #
+    # @return [String, nil]
     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.
+    # 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}).
+    #
+    # @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.
-    # @option options [Array] :fields The names of the fields to subscribe to on the items.
-    # @option options [:distinct, :merge] :mode The operation mode of this subscription.
+    # @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] :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.
+    # @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
 
@@ -51,62 +67,55 @@ module Lightstreamer
       @maximum_update_frequency = options[:maximum_update_frequency] || 0.0
 
       @data_mutex = Mutex.new
-      clear_data
 
-      @data_callbacks = []
+      clear_data
+      clear_callbacks
     end
 
     # Clears all current data stored for this subscription. New data will continue to be processed as it becomes
     # available.
     def clear_data
-      @data_mutex.synchronize do
-        @data = (0...items.size).map { { distinct: [], merge: {} }.fetch(mode) }
-      end
+      @data = (0...items.size).map { {} }
     end
 
-    # Clears the current data stored for the specified item. This is important to do when {#mode} is `:distinct` as
-    # otherwise the incoming data will build up indefinitely.
+    # 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.
     #
-    # @param [String] item_name The name of the item to clear the current data for.
-    def clear_data_for_item(item_name)
-      index = @items.index item_name
-      raise ArgumentError, 'Unrecognized item name' unless index
-
+    # @param [Proc] callback The callback that is to be run when new data arrives.
+    def on_data(&callback)
       @data_mutex.synchronize do
-        @data[index] = { distinct: [], merge: {} }.fetch(mode)
+        @callbacks[:on_data] << callback
       end
     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|`.
-    #
-    # @param [Proc] block The callback block that is to be run when new data arrives.
+    # 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|`.
     #
-    # @return [Proc] The same `Proc` object that was passed to this method. This can be used to remove this data
-    #         callback at a later stage using {#remove_data_callback}.
-    def add_data_callback(&block)
-      @data_mutex.synchronize { @data_callbacks << block }
-
-      block
+    # @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
     end
 
-    # Removes a data callback that was added by {#add_data_callback}.
-    #
-    # @param [Proc] block The data callback block to remove.
-    def remove_data_callback(block)
-      @data_mutex.synchronize { @data_callbacks.delete block }
+    # 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
     end
 
-    # Returns the current data of one of this subscription's items.
+    # 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, Array] The item data. Will be a `Hash` if {#mode} is `:merge`, and an `Array` if {#mode} is
-    #         `:distinct`.
-    def retrieve_item_data(item_name)
+    # @return [Hash] A copy of the item data.
+    def item_data(item_name)
       index = @items.index item_name
-      raise ArgumentError, 'Unrecognized item name' unless index
+      raise ArgumentError, 'Unknown item' unless index
 
       @data_mutex.synchronize do
         @data[index].dup
@@ -120,25 +129,17 @@ module Lightstreamer
     #
     # @return [Boolean] Whether the passed line of stream data was relevant to this subscription and was successfully
     #         processed by it.
+    #
+    # @private
     def process_stream_data(line)
-      item_index, new_values = parse_stream_data line
-      return false unless item_index
-
-      @data_mutex.synchronize do
-        data = @data[item_index]
-
-        data << new_values if mode == :distinct
-        data.merge!(new_values) if mode == :merge
-
-        call_data_callbacks @items[item_index], data, new_values
-      end
-
-      true
+      process_update_message(line) || process_overflow_message(line)
     end
 
-    # Returns the next unique ID to use for a new subscription.
+    # Returns the next unique subscription ID.
     #
     # @return [Fixnum]
+    #
+    # @private
     def self.next_id
       @next_id ||= 0
       @next_id += 1
@@ -146,57 +147,40 @@ module Lightstreamer
 
     private
 
-    # Attempts to parse a line of stream data. If parsing is successful then the first return value is the item index,
-    # and the second is a hash of the values contained in the stream data.
-    def parse_stream_data(line)
-      match = line.match stream_data_regex
-      return unless match
-
-      item_index = match.captures[0].to_i - 1
-      return unless item_index < @items.size
+    def process_update_message(line)
+      update_message = UpdateMessage.parse line, id, items, fields
+      return unless update_message
 
-      [item_index, parse_values(match.captures[1..-1])]
-    end
+      @data_mutex.synchronize do
+        process_new_values update_message.item_index, update_message.values
+      end
 
-    # Returns the regular expression that will match a single line of data in the incoming stream that is relevant to
-    # this subscription. The ID at the beginning must match, as well as the number of fields.
-    def stream_data_regex
-      Regexp.new "^#{id},(\\d+)#{'\|(.*)' * fields.size}"
+      true
     end
 
-    # Parses an array of values from an incoming line of stream data into a hash where the keys are the field names
-    # defined for this subscription.
-    def parse_values(values)
-      hash = {}
+    def process_new_values(item_index, new_values)
+      data = @data[item_index]
 
-      values.each_with_index do |value, index|
-        next if value == ''
+      data.replace(new_values) if mode == :distinct
+      data.merge!(new_values) if mode == :merge
 
-        hash[fields[index]] = parse_raw_field_value value
-      end
-
-      hash
+      run_callbacks :on_data, @items[item_index], data, new_values
     end
 
-    # Parses a raw field value according to to the Lightstreamer specification.
-    def parse_raw_field_value(value)
-      return '' if value == '$'
-      return nil if value == '#'
+    def process_overflow_message(line)
+      overflow_message = OverflowMessage.parse line, id, items
+      return unless overflow_message
 
-      value = value[1..-1] if value =~ /^(\$|#)/
+      @data_mutex.synchronize do
+        run_callbacks :on_overflow, @items[overflow_message.item_index], overflow_message.overflow_size
+      end
 
-      UTF16.decode_escape_sequences value
+      true
     end
 
-    # Invokes all of this subscription's data callbacks with the specified arguments. Any exceptions that occur in a
-    # data callback are reported on `stderr` but are otherwise ignored.
-    def call_data_callbacks(item_name, item_data, new_values)
-      @data_callbacks.each do |callback|
-        begin
-          callback.call self, item_name, item_data, new_values
-        rescue StandardError => error
-          warn "Lightstreamer: exception occurred in a subscription data callback: #{error}"
-        end
+    def run_callbacks(callback_type, *arguments)
+      @callbacks.fetch(callback_type).each do |callback|
+        callback.call self, *arguments
       end
     end
   end

data/lib/lightstreamer/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lightstreamer
 version: !ruby/object:Gem::Version
-  version: '0.4'
+  version: '0.5'
 platform: ruby
 authors:
 - Richard Viney
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-25 00:00:00.000000000 Z
+date: 2016-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -181,11 +181,12 @@ files:
 - lib/lightstreamer/control_connection.rb
 - lib/lightstreamer/errors.rb
 - lib/lightstreamer/line_buffer.rb
+- lib/lightstreamer/messages/overflow_message.rb
+- lib/lightstreamer/messages/update_message.rb
 - lib/lightstreamer/session.rb
 - lib/lightstreamer/stream_connection.rb
 - lib/lightstreamer/stream_connection_header.rb
 - lib/lightstreamer/subscription.rb
-- lib/lightstreamer/utf16.rb
 - lib/lightstreamer/version.rb
 homepage: https://github.com/rviney/lightstreamer
 licenses:

data/lib/lightstreamer/utf16.rb

@@ -1,40 +0,0 @@
-module Lightstreamer
-  # This module supports the decoding of UTF-16 escape sequences
-  module UTF16
-    module_function
-
-    # 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 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 are ignored
-        codepoint < 0xD800 ? [codepoint].pack('U') : ''
-      end
-    end
-
-    # 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
-        low_surrogate = escape_sequence[8...12].hex
-
-        codepoint = 0x10000 + ((high_surrogate - 0xD800) << 10) + (low_surrogate - 0xDC00)
-
-        [codepoint].pack 'U'
-      end
-    end
-  end
-end