lightstreamer 0.1 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bf90908d8a97af1417f8391f16e2c26a10baf73d
-  data.tar.gz: 6e89354b80f3712ca9c4278f09342123d3844878
+  metadata.gz: 7dd1721bffbb480dfa570531e520c727084a58d9
+  data.tar.gz: 67ee866151859546536fca838dabfe05e84a1d2d
 SHA512:
-  metadata.gz: a17d1e9276c986f6c436e3aad883f4f068b319e9e88e30b7e7eb844b1af33ca18c35dab74a76e2e25763263199c7f251acf45d999a07afeb749b424d6ea58985
-  data.tar.gz: d359e20a661d5dc953f5ba02d3984f4db0206886b38ebdc1ab555c20c5b367eab9aa8499071eef6ba6f074da116925cf2774742c043e314bdd21f419126535a9
+  metadata.gz: 0e52c034fa5c273733b97373038f1ccb9ac18959b9ab8c47b47c515ce64a954f3b397966cb02d5e924183364ec47d0402454faf117e4dbef3d3451fb5cfdaafa
+  data.tar.gz: 8a79799ea6def575bd5aed0bbbe9d514512d4db4bd32b5dd6417a320d8b929739931714403f4312b3316f326280dc049c15ca883c5af929be9ba92c62687451a

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Lightstreamer Changelog
 
-### 0.1 — July 23, 2016
+### 0.2 — July 23, 2016
+
+- Added complete test suite
+- Added `Lightstreamer::Session#subscribed?` and `Lightstreamer::Session#disconnect`
+- Fixed `Lightstreamer::ProtocolError#code` not being set
+- Renamed the command-line client's `--address` option to `--server-url`
+
+### 0.1 — July 22, 2016
 
 - Initial release

data/README.md

@@ -75,7 +75,7 @@ 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 --address http://push.lightstreamer.com --adapter-set DEMO --adapter QUOTE_ADAPTER \
+lightstreamer --server-url http://push.lightstreamer.com --adapter-set DEMO --adapter QUOTE_ADAPTER \
               --items item1 item2 item3 item4 item5 --fields time stock_name bid ask bid
 ```
 

data/lib/lightstreamer.rb

@@ -11,7 +11,7 @@ require 'lightstreamer/subscription'
 require 'lightstreamer/version'
 
 require 'lightstreamer/cli/main'
-require 'lightstreamer/cli/stream_command'
+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

data/lib/lightstreamer/cli/{stream_command.rb → commands/stream_command.rb}

@@ -4,7 +4,7 @@ module Lightstreamer
     class Main < Thor
       desc 'stream', 'Streams a set of items and fields from a Lightstreamer server and prints the live output'
 
-      option :address, required: true, desc: 'The address of the Lightstreamer server'
+      option :server_url, required: true, desc: 'The URL of the Lightstreamer server'
       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'
@@ -30,7 +30,7 @@ module Lightstreamer
 
       # Creates a new session from the specified options.
       def create_session
-        Lightstreamer::Session.new server_url: options[:address], username: options[:username],
+        Lightstreamer::Session.new server_url: options[:server_url], username: options[:username],
                                    password: options[:password], adapter_set: options[:adapter_set]
       end
 
@@ -39,12 +39,14 @@ module Lightstreamer
         subscription = Lightstreamer::Subscription.new items: options[:items], fields: options[:fields],
                                                        mode: options[:mode], adapter: options[:adapter]
 
-        subscription.add_data_callback do |_subscription, item_name, _item_data, new_values|
-          @queue.push "#{item_name} - #{new_values.map { |key, value| "#{key}: #{value}" }.join ', '}"
-        end
+        subscription.add_data_callback(&method(:subscription_data_callback))
 
         subscription
       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
     end
   end
 end

data/lib/lightstreamer/control_connection.rb

@@ -26,10 +26,7 @@ module Lightstreamer
     def execute(options)
       result = execute_post_request build_payload(options)
 
-      return if result.first == 'OK'
-      raise ProtocolError, result[2], result[1] if result.first == 'ERROR'
-
-      warn "Lightstreamer: unexpected response from server: #{result}"
+      raise ProtocolError.new(result[2], result[1]) if result.first == 'ERROR'
     end
 
     private

data/lib/lightstreamer/protocol_error.rb

@@ -14,7 +14,7 @@ module Lightstreamer
     # @param [Integer] code The numeric code for the error.
     def initialize(error, code)
       @error = error.to_s
-      @http_code = code.to_i
+      @code = code.to_i
 
       super "Lightstreamer error: #{@error}, code: #{code}"
     end

data/lib/lightstreamer/session.rb

@@ -34,8 +34,9 @@ module Lightstreamer
     # Creates a new Lightstreamer session using the details passed to {#initialize}. If an error occurs then
     # {ProtocolError} will be raised.
     def connect
+      return if @stream_connection
+
       @stream_connection = StreamConnection.new self
-      @subscriptions = []
 
       first_line = @stream_connection.read_line
 
@@ -48,6 +49,19 @@ module Lightstreamer
       end
     end
 
+    # Disconnects this session and shuts down its stream and processing threads.
+    def disconnect
+      @stream_connection.disconnect if @stream_connection
+
+      if @processing_thread
+        Thread.kill @processing_thread
+        @processing_thread.join
+      end
+
+      @processing_thread = @stream_connection = @control_connection = nil
+      @subscriptions = []
+    end
+
     # Subscribes this Lightstreamer session to the specified subscription.
     #
     # @param [Subscription] subscription The new subscription to subscribe to.
@@ -66,13 +80,20 @@ module Lightstreamer
       end
     end
 
+    # Returns whether the specified subscription is currently active on this session.
+    #
+    # @param [Subscription] subscription The subscription to return the status for.
+    #
+    # @return [Boolean] Whether the specified subscription is currently active on this session.
+    def subscribed?(subscription)
+      @subscriptions_mutex.synchronize { @subscriptions.include? subscription }
+    end
+
     # Unsubscribes this Lightstreamer session from the specified subscription.
     #
     # @param [Subscription] subscription The existing subscription to unsubscribe from.
     def unsubscribe(subscription)
-      @subscriptions_mutex.synchronize do
-        raise ArgumentError, 'Unknown subscription' unless @subscriptions.detect subscription
-      end
+      raise ArgumentError, 'Unknown subscription' unless subscribed? subscription
 
       @control_connection.execute table: subscription.id, operation: :delete
 
@@ -105,13 +126,10 @@ 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
-        begin
-          loop do
-            process_stream_data @stream_connection.read_line
-          end
-        rescue StandardError => error
-          warn "Lightstreamer: exception in processing thread: #{error}"
-          exit 1
+        loop do
+          line = @stream_connection.read_line
+
+          process_stream_data line unless line.empty?
         end
       end
     end
@@ -137,7 +155,7 @@ module Lightstreamer
       @stream_connection = nil
       @control_connection = nil
 
-      raise ProtocolError, error_message, error_code
+      raise ProtocolError.new(error_message, error_code)
     end
   end
 end

data/lib/lightstreamer/stream_connection.rb

@@ -2,6 +2,9 @@ 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.
   class StreamConnection
+    # @return [Thread] The thread used to process incoming streaming data.
+    attr_reader :thread
+
     # Establishes a new stream connection using the authentication details from the passed session.
     #
     # @param [Session] session The session to create a stream connection for.
@@ -13,6 +16,14 @@ module Lightstreamer
       create_stream_thread
     end
 
+    # Disconnects this stream connection by shutting down the streaming thread.
+    def disconnect
+      return unless @thread
+
+      Thread.kill @thread
+      @thread.join
+    end
+
     # Reads the next line of streaming data. This method blocks the calling thread until a line of data is available.
     def read_line
       @queue.pop
@@ -29,8 +40,6 @@ module Lightstreamer
       @thread = Thread.new do
         begin
           connect_stream_and_queue_data
-
-          warn 'Lightstreamer: stream connection closed'
         rescue StandardError => error
           warn "Lightstreamer: exception in stream thread: #{error}"
           exit 1

data/lib/lightstreamer/subscription.rb

@@ -8,10 +8,10 @@ module Lightstreamer
     #                  in incoming Lightstreamer data.
     attr_reader :id
 
-    # @return [Array<String>] The names of the items to subscribe to.
+    # @return [Array] The names of the items to subscribe to.
     attr_reader :items
 
-    # @return [Array<String>] The names of the fields to subscribe to on the items.
+    # @return [Array] The names of the fields to subscribe to on the items.
     attr_reader :fields
 
     # @return [:distinct, :merge] The operation mode of this subscription.
@@ -25,8 +25,8 @@ module Lightstreamer
     # {Session#subscribe} to activate the subscription on a Lightstreamer session.
     #
     # @param [Hash] options The options to create the subscription with.
-    # @option options [Array<String>] :items The names of the items to subscribe to.
-    # @option options [Array<String>] :fields The names of the fields to subscribe to on the items.
+    # @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 [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.
@@ -55,7 +55,7 @@ module Lightstreamer
     # 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.
     #
-    # @param [String] item_name The name of the item to clear the current data of.
+    # @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
@@ -74,8 +74,6 @@ module Lightstreamer
     # @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)
-      raise ArgumentError, 'Data callbacks must take four arguments' unless block.arity == 4
-
       @data_mutex.synchronize { @data_callbacks << block }
 
       block
@@ -111,16 +109,16 @@ module Lightstreamer
     # @return [Boolean] Whether the passed line of stream data was relevant to this subscription and was successfully
     #         processed by it.
     def process_stream_data(line)
-      item_index, values = parse_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 << values if mode == :distinct
-        data.merge!(values) if mode == :merge
+        data << new_values if mode == :distinct
+        data.merge!(new_values) if mode == :merge
 
-        @data_callbacks.each { |callback| callback.call self, @items[item_index], data, values }
+        call_data_callbacks @items[item_index], data, new_values
       end
 
       true
@@ -172,23 +170,35 @@ module Lightstreamer
       values.each_with_index do |value, index|
         next if value == ''
 
-        # These conversions are specified in the Lightstreamer specification
-        value = '' if value == '$'
-        value = nil if value == '#'
-        value = value[1..-1] if value =~ /^($|#)/
-
-        hash[fields[index]] = convert_utf16_characters value
+        hash[fields[index]] = parse_raw_field_value value
       end
 
       hash
     end
 
-    # Non-ASCII characters are transmitted as UTF-16 escape sequences in the form '\uXXXX' or '\uXXXX\uYYYY'. This
-    # method is respnsible for converting such escape sequences into native Unicode characters.
-    #
-    # @todo Implement this method.
-    def convert_utf16_characters(value)
+    # Parses a raw field value according to to the Lightstreamer specification.
+    def parse_raw_field_value(value)
+      return '' if value == '$'
+      return nil if value == '#'
+
+      value = value[1..-1] if value =~ /^(\$|#)/
+
+      # TODO: parse any non-ASCII characters which are specified as UTF-16 escape sequences in the form '\uXXXX' or
+      # '\uXXXX\uYYYY'. They need to be transformed into native Unicode characters.
+
       value
     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
+      end
+    end
   end
 end

data/lib/lightstreamer/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lightstreamer
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
 platform: ruby
 authors:
 - Richard Viney
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-07-22 00:00:00.000000000 Z
+date: 2016-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -176,8 +176,8 @@ files:
 - README.md
 - bin/lightstreamer
 - lib/lightstreamer.rb
+- lib/lightstreamer/cli/commands/stream_command.rb
 - lib/lightstreamer/cli/main.rb
-- lib/lightstreamer/cli/stream_command.rb
 - lib/lightstreamer/control_connection.rb
 - lib/lightstreamer/line_buffer.rb
 - lib/lightstreamer/protocol_error.rb
@@ -209,5 +209,5 @@ rubyforge_project:
 rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
-summary: Ruby client for accessing a Lightstreamer server.
+summary: Library and command-line client for accessing a Lightstreamer server.
 test_files: []