onstomp 1.0.0pre1

data/lib/onstomp/interfaces/connection_events.rb

@@ -0,0 +1,62 @@
+# -*- encoding: utf-8 -*-
+
+# Mixin for connection events
+module OnStomp::Interfaces::ConnectionEvents
+  include OnStomp::Interfaces::EventManager
+  
+  # @group Connection State Events
+
+  # Binds a callback to be invoked when a connection has been fully
+  # established between broker and client.
+  # @yield [client, connection] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Client] client
+  # @yieldparam [OnStomp::Connections::Base] connection that triggered
+  #   the event (in general the same as +client.connection+)
+  create_event_methods :established, :on
+  # Binds a callback to be invoked when a connection has been died due to
+  # insufficient data transfer.
+  # @note Only applies to STOMP 1.1 connections with heartbeating enabled.
+  # @yield [client, connection] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Client] client
+  # @yieldparam [OnStomp::Connections::Base] connection that triggered
+  #   the event (in general the same as +client.connection+)
+  create_event_methods :died, :on
+  # Binds a callback to be invoked when a connection has been terminated
+  # (eg: closed unexpectedly due to an exception)
+  # @yield [client, connection] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Client] client
+  # @yieldparam [OnStomp::Connections::Base] connection that triggered
+  #   the event (in general the same as +client.connection+)
+  create_event_methods :terminated, :on
+  # Binds a callback to be invoked when a connection has been closed, either
+  # through a graceful disconnect or unexpectedly.
+  # @note If connection is closed unexpectedly, {#on_died} is triggered first,
+  # followed by this event.
+  # @yield [client, connection] callback invoked when event is triggered
+  # @yieldparam [OnStomp::Client] client
+  # @yieldparam [OnStomp::Connections::Base] connection that triggered
+  #   the event (in general the same as +client.connection+)
+  create_event_methods :closed, :on
+  
+  # @endgroup
+
+  # Triggers a connection specific event.
+  # @param [Symbol] event name
+  def trigger_connection_event event
+    trigger_event :"on_#{event}", self.client, self
+  end
+  
+  # Takes a hash of event bindings a {OnStomp::Client client} has stored
+  # and binds them to this connection, then triggers +on_established+.
+  # This allows users to add callbacks for
+  # connection events before the connection exist and have said callbacks
+  # installed once the connection is created.
+  # @param [{Symbol => Array<Proc>}] callbacks to install, keyed by event name
+  # @see OnStomp::Interfaces::ClientEvents#pending_connection_events
+  def install_bindings_from_client ev_hash
+    ev_hash.each do |ev, cbs|
+      cbs.each { |cb| bind_event(ev, cb) }
+    end
+    trigger_connection_event :established
+  end
+end

data/lib/onstomp/interfaces/event_manager.rb

@@ -0,0 +1,69 @@
+# -*- encoding: utf-8 -*-
+
+# Mixin for event management.
+module OnStomp::Interfaces::EventManager
+  # Extends base with {OnStomp::Interfaces::EventManager::ClassMethods}
+  def self.included(base)
+    base.extend ClassMethods
+  end
+  
+  # Binds a +Proc+ to be invoked when the given +event_name+ is triggered.
+  # @param [Symbol] event_name
+  # @param [Proc] cb_proc
+  # @return [self]
+  def bind_event(event_name, cb_proc)
+    event_callbacks[event_name] << cb_proc
+    self
+  end
+  
+  # Returns a hash of event names mapped to arrays of proc callbacks.
+  # @return [{Symbol => Array<Proc>}]
+  def event_callbacks
+    @event_callbacks ||= Hash.new { |h, k| h[k] = [] }
+  end
+  
+  # Triggers an event by the given name, passing along any additional
+  # +args+ as parameters to the callback
+  # @param [Symbol] event_name event to trigger
+  # @param [Object, Object, ...] args
+  def trigger_event(event_name, *args)
+    event_callbacks[event_name].each { |cb| cb.call(*args) }
+  end
+  
+  # Mixin to allow includers to define custom event methods
+  module ClassMethods
+    # Creates a convenience method for binding callbacks to the given
+    # event name.
+    # @param [Symbol] name
+    # @example
+    #   class ExampleClass
+    #     include OnStomp::Interfaces::EventManager
+    #
+    #     create_event_method :do_event
+    #   end
+    #
+    #   example_obj.do_event { |arg1, arg2| ... }
+    def create_event_method name
+      module_eval "def #{name}(&block); bind_event(:#{name}, block); end"
+    end
+
+    # Creates convenience methods for binding callbacks to the given
+    # event name with a set of prefixes.
+    # @param [Symbol] name
+    # @param [Symbol, Symbol, ...] prefixes (eg: :on, :before, :after)
+    # @example
+    #   class ExampleClass
+    #     include OnStomp::Interfaces::EventManager
+    #
+    #     create_event_methods :some_event, :before, :during, :after
+    #   end
+    #
+    #   example_obj.before_some_event { |arg| ... }
+    #   example_obj.after_some_event { |arg| ... }
+    #   example_obj.during_some_event { |arg| ... }
+    def create_event_methods name, *prefixes
+      prefixes << :on if prefixes.empty?
+      prefixes.each { |pre| create_event_method :"#{pre}_#{name}" }
+    end
+  end
+end

data/lib/onstomp/interfaces/frame_methods.rb

@@ -0,0 +1,190 @@
+# -*- encoding: utf-8 -*-
+
+# Mixin for {OnStomp::Client clients} to provide methods that create
+# and transmit STOMP {OnStomp::Components::Frame frames}.
+module OnStomp::Interfaces::FrameMethods
+  # Transmits a SEND frame generated by the client's connection
+  # @param [String] dest destination for the frame
+  # @param [String] body body of the frame
+  # @param [{#to_sym => #to_s}] headers additional headers to include in
+  #   the frame
+  # @return [OnStomp::Components::Frame] SEND frame
+  # @yield [receipt] block to invoke when a RECEIPT frame is received for the
+  #   transmitted SEND frame
+  # @yieldparam [OnStomp::Components::Frame] receipt RECEIPT for the frame
+  # @raise OnStomp::UnsupportedCommandError if the connection does not support
+  #   SEND frames
+  def send dest, body, headers={}, &cb
+    transmit connection.send_frame(dest, body, headers), :receipt => cb
+  end
+  alias :puts :send
+
+  # Transmits a SUBSCRIBE frame generated by the client's connection. Depending
+  # upon the connection, a subscription can be set to various MESSAGE
+  # acknowledgement modes by setting the +:ack+ header.
+  # STOMP 1.0 and STOMP 1.1 connections support:
+  # * :ack => 'auto'
+  #   The broker assumes that MESSAGE frames received through the
+  #   subscription have been properly received, the client should NOT attempt
+  #   to ACK (or NACK) any of the messages.
+  # * :ack => 'client'
+  #   The broker assumes that MESSAGE frames should be acknowledged by the
+  #   client through the use of ACK frames.
+  # STOMP 1.1 connections support:
+  # * :ack => 'client-individual'
+  #   Upon receiving an ACK frame for a MESSAGE frame, some brokers will
+  #   mark the MESSAGE frame and all those sent to the client before it
+  #   as acknowledged. This mode indicates that each MESSAGE frame must
+  #   be acknowledged by its own ACK frame for the broker can assume the
+  #   MESSAGE frame has been received by the client.
+  # @param [String] dest destination for the frame
+  # @param [{#to_sym => #to_s}] headers additional headers to include in
+  #   the frame
+  # @return [OnStomp::Components::Frame] SUBSCRIBE frame
+  # @yield [message] block to invoke for every MESSAGE frame received on the
+  #   subscription
+  # @yieldparam [OnStomp::Components::Frame] message MESSAGE frame received on
+  #  the subscription
+  # @raise OnStomp::UnsupportedCommandError if the connection does not support
+  #   SUBSCRIBE frames
+  # @see #unsubscribe
+  # @see #ack
+  # @see #nack
+  def subscribe dest, headers={}, &cb
+    transmit connection.subscribe_frame(dest, headers), :subscribe => cb
+  end
+  
+  # Transmits an UNSUBSCRIBE frame generated by the client's connection.
+  # @overload unsubscribe(subscribe_frame, headers={})
+  #   Generates an UNSUBSCRIBE frame to match the given SUBSCRIBE frame
+  #   @param [OnStomp::Components::Frame] subscribe_frame
+  #   @param [{#to_sym => #to_s}] headers optional headers to include in
+  #     the UNSUBSCRIBE frame
+  # @overload unsubscribe(id, headers={})
+  #   Generates an UNSUBSCRIBE frame with the given id
+  #   @param [String] id
+  #   @param [{#to_sym => #to_s}] headers optional headers to include in
+  #     the UNSUBSCRIBE frame
+  # @return [OnStomp::Components::Frame] UNSUBSCRIBE frame
+  # @raise OnStomp::UnsupportedCommandError if the connection does not support
+  #   UNSUBSCRIBE frames
+  # @see #subscribe
+  def unsubscribe frame_or_id, headers={}
+    transmit connection.unsubscribe_frame(frame_or_id, headers)
+  end
+  
+  # Transmits a BEGIN frame generated by the client's connection to start
+  # a transaction.
+  # @param [String] tx_id identifier for the transaction
+  # @param [{#to_sym => #to_s}] headers additional headers to include in
+  #   the frame
+  # @return [OnStomp::Components::Frame] BEGIN frame
+  # @raise OnStomp::UnsupportedCommandError if the connection does not support
+  #   BEGIN frames
+  # @see #abort
+  # @see #commit
+  def begin tx_id, headers={}
+    transmit connection.begin_frame(tx_id, headers)
+  end
+  
+  # Transmits an ABORT frame generated by the client's connection to rollback
+  # a transaction.
+  # @param [String] tx_id identifier for the transaction
+  # @param [{#to_sym => #to_s}] headers additional headers to include in
+  #   the frame
+  # @return [OnStomp::Components::Frame] ABORT frame
+  # @raise OnStomp::UnsupportedCommandError if the connection does not support
+  #   ABORT frames
+  # @see #begin
+  # @see #commit
+  def abort tx_id, headers={}
+    transmit connection.abort_frame(tx_id, headers)
+  end
+  
+  # Transmits a COMMIT frame generated by the client's connection to complete
+  # a transaction.
+  # @param [String] tx_id identifier for the transaction
+  # @param [{#to_sym => #to_s}] headers additional headers to include in
+  #   the frame
+  # @return [OnStomp::Components::Frame] COMMIT frame
+  # @raise OnStomp::UnsupportedCommandError if the connection does not support
+  #   COMMIT frames
+  # @see #abort
+  # @see #begin
+  def commit tx_id, headers={}
+    transmit connection.commit_frame(tx_id, headers)
+  end
+
+  # Transmits a DISCONNECT frame generated by the client's connection to end
+  # the STOMP session.
+  # @param [{#to_sym => #to_s}] headers additional headers to include in
+  #   the frame
+  # @return [OnStomp::Components::Frame] DISCONNECT frame
+  # @raise OnStomp::UnsupportedCommandError if the connection does not support
+  #   DISCONNECT frames
+  def disconnect headers={}
+    transmit connection.disconnect_frame headers
+  end
+
+  # Transmits an ACK frame generated by the client's connection.
+  # @overload ack(message_frame, headers={})
+  #   @note Users should use this form whenever possible as it will work
+  #     with STOMP 1.0 and 1.1 connections.
+  #   @param [OnStomp::Components::Frame] message_frame the MESSAGE frame to
+  #     acknowledge.
+  #   @param [{#to_sym => #to_s}] headers additional headers to include in
+  #     the frame
+  # @overload ack(message_id, headers={})
+  #   @note This form will raise an +ArgumentError+ with STOMP 1.1 connections
+  #     as a subscription ID is also required to ACK a received MESSAGE.
+  #   @param [String] message_id +message-id+ header of MESSAGE frame to
+  #     acknowledge.
+  #   @param [{#to_sym => #to_s}] headers additional headers to include in
+  #     the frame
+  # @overload ack(message_id, subscription_id, heders={})
+  #   @note This form should be used with STOMP 1.1 connections when it is
+  #     not possible to provide the actual MESSAGE frame.
+  #   @param [String] message_id +message-id+ header of MESSAGE frame to
+  #     acknowledge.
+  #   @param [String] subscription_id +subscription+ header of MESSAGE frame to
+  #     acknowledge.
+  #   @param [{#to_sym => #to_s}] headers additional headers to include in
+  #     the frame
+  # @return [OnStomp::Components::Frame] ACK frame
+  # @raise OnStomp::UnsupportedCommandError if the connection does not support
+  #   ACK frames
+  # @see #nack
+  def ack *args
+    transmit connection.ack_frame(*args)
+  end
+
+  # Transmits a NACK frame generated by the client's connection.
+  # @overload nack(message_frame, headers={})
+  #   Generates a NACK frame for the given MESSAGE frame.
+  #   @param [OnStomp::Components::Frame] message_frame the MESSAGE frame to
+  #     un-acknowledge.
+  #   @param [{#to_sym => #to_s}] headers additional headers to include in
+  #     the frame
+  # @overload nack(message_id, subscription_id, heders={})
+  #   @param [String] message_id +message-id+ header of MESSAGE frame to
+  #     un-acknowledge.
+  #   @param [String] subscription_id +subscription+ header of MESSAGE frame to
+  #     un-acknowledge.
+  #   @param [{#to_sym => #to_s}] headers additional headers to include in
+  #     the frame
+  # @return [OnStomp::Components::Frame] NACK frame
+  # @raise OnStomp::UnsupportedCommandError if the connection does not support
+  #   NACK frames
+  # @see #ack
+  def nack *args
+    transmit connection.nack_frame(*args)
+  end
+  
+  # Transmits a client heartbeat frame generated by the client's connection.
+  # @return [OnStomp::Components::Frame] heartbeat frame
+  # @raise OnStomp::UnsupportedCommandError if the connection does not support
+  #   heartbeat frames
+  def beat
+    transmit connection.heartbeat_frame
+  end
+end

data/lib/onstomp/interfaces/receipt_manager.rb

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+
+# Mixin for {OnStomp::Client clients} to provide receipt management
+module OnStomp::Interfaces::ReceiptManager
+  private
+  def configure_receipt_management
+    @receipt_monitor = Monitor.new
+    @receipt_backs = {}
+    before_disconnect do |d, con|
+      @receipt_to_close = d[:receipt] if d[:receipt]
+    end
+    on_receipt do |r, con|
+      dispatch_receipt r
+      close if r[:'receipt-id'] == @receipt_to_close
+    end
+  end
+
+  def add_receipt f, cb
+    f[:receipt] = OnStomp.next_serial unless f.header?(:receipt)
+    @receipt_monitor.synchronize { @receipt_backs[f[:receipt]] = cb }
+    self
+  end
+  
+  def clear_receipts
+    @receipt_monitor.synchronize { @receipt_backs.clear }
+  end
+  
+  def dispatch_receipt receipt
+    cb = @receipt_monitor.synchronize { @receipt_backs.delete(receipt[:'receipt-id']) }
+    cb && cb.call(receipt)
+    self
+  end
+end

data/lib/onstomp/interfaces/subscription_manager.rb

@@ -0,0 +1,48 @@
+# -*- encoding: utf-8 -*-
+
+# Mixin for {OnStomp::Client clients} to provide receipt management
+module OnStomp::Interfaces::SubscriptionManager
+  # Returns an array of {OnStomp::Components::Subscription} objects for all
+  # currently active subscriptions.
+  # @return [Array<OnStomp::Components::Subscription>]
+  def subscriptions
+    @subcription_mon.synchronize { @subscriptions.values }
+  end
+  
+  private
+  def configure_subscription_management
+    @subcription_mon = Monitor.new
+    @subscriptions = {}
+    on_message { |m, c| dispatch_subscription m }
+    on_unsubscribe { |u, c| remove_subscription u[:id] }
+  end
+  
+  def add_subscription f, cb
+    s_id = f[:id]
+    dest = f[:destination]
+    @subcription_mon.synchronize do
+      @subscriptions[s_id] = OnStomp::Components::Subscription.new(f, cb)
+    end
+  end
+
+  def remove_subscription sub_id
+    @subcription_mon.synchronize do
+      @subscriptions.delete sub_id
+    end
+  end
+  
+  def clear_subscriptions
+    @subcription_mon.synchronize { @subscriptions.clear }
+  end
+  
+  def dispatch_subscription m
+    if m.header? :subscription
+      sub = @subcription_mon.synchronize { @subscriptions[m[:subscription]] }
+      sub && sub.call(m)
+    else
+      @subcription_mon.synchronize do
+        @subscriptions.values.select { |sub| sub.include? m }
+      end.each { |sub| sub.call m }
+    end
+  end
+end

data/lib/onstomp/interfaces/uri_configurable.rb

@@ -0,0 +1,106 @@
+# -*- encoding: utf-8 -*-
+
+# Module for configurable attributes
+module OnStomp::Interfaces::UriConfigurable
+  # Extends +base+ with {OnStomp::Interfaces::UriConfigurable::ClassMethods}
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  private  
+  def configure_configurable hash_opts
+    config = OnStomp.keys_to_sym(CGI.parse(uri.query || '')).
+      merge(OnStomp.keys_to_sym(hash_opts))
+    self.class.config_attributes.each do |attr_name, attr_conf|
+      attr_val = config.key?(attr_name) ? config[attr_name] :
+        attr_conf.key?(:uri_attr) && uri.__send__(attr_conf[:uri_attr]) ||
+        attr_conf[:default]
+      __send__(:"#{attr_name}=", attr_val)
+    end
+  end
+
+  # Provides attribute methods that can be configured by URI attributes
+  # or query parameters.
+  module ClassMethods
+    # Creates a group readable and writeable attributes that can be set
+    # by a URI query parameter sharing the same name, a property of a URI or
+    # a default value. The value of this attribute will be transformed by
+    # invoking the given block, if one has been provided.
+    def attr_configurable *args, &block
+      opts = args.last.is_a?(Hash) ? args.pop : {}
+      args.each do |attr_name|
+        __init_config_attribute__ attr_name, opts
+        attr_reader attr_name
+        define_method :"#{attr_name}=" do |v|
+          instance_variable_set(:"@#{attr_name}", (block ? block.call(v) : v))
+        end
+      end
+    end
+    
+    # Creates a group readable and writeable attributes that can be set
+    # by a URI query parameter sharing the same name, a property of a URI or
+    # a default value. The value of this attribute will be transformed by
+    # invoking the given block, if one has been provided. If the attributes
+    # created by this method are assigned an +Array+, only the first element
+    # will be used as their value.
+    def attr_configurable_single *args, &block
+      trans = __attr_configurable_wrap__ lambda { |v| v.is_a?(Array) ? v.first : v }, block
+      attr_configurable(*args, &trans)
+    end
+    
+    # Creates a group readable and writeable attributes that can be set
+    # by a URI query parameter sharing the same name, a property of a URI or
+    # a default value. The value of this attribute will be transformed by
+    # invoking the given block, if one has been provided. The attributes
+    # created by this method will be treated as though they were created
+    # with {#attr_configurable_single} and will also be converted into Strings.
+    def attr_configurable_str *args, &block
+      trans = __attr_configurable_wrap__ lambda { |v| v.to_s }, block
+      attr_configurable_single(*args, &trans)
+    end
+    
+    # Creates a group readable and writeable attributes that can be set
+    # by a URI query parameter sharing the same name, a property of a URI or
+    # a default value. The value of this attribute will be transformed by
+    # invoking the given block, if one has been provided. If the attributes
+    # created by this method are assigned a value that is not an +Array+, the
+    # value will be wrapped in an array.
+    def attr_configurable_arr *args, &block
+      trans = __attr_configurable_wrap__ lambda { |v| Array(v) }, block
+      attr_configurable(*args, &trans)
+    end
+    
+    # Creates a group readable and writeable attributes that can be set
+    # by a URI query parameter sharing the same name, a property of a URI or
+    # a default value. The value of this attribute will be transformed by
+    # invoking the given block, if one has been provided. The attributes
+    # created by this method will be treated as though they were created
+    # with {#attr_configurable_single} and will also be converted into Class
+    # or Module objects.
+    def attr_configurable_class *args, &block
+      trans = __attr_configurable_wrap__ lambda { |v| OnStomp.constantize(v) }, block
+      attr_configurable_single(*args, &trans)
+    end
+    
+    private
+    def __attr_configurable_wrap__(trans, block)
+      if block
+        lambda { |v| block.call(trans.call(v)) }
+      else
+        trans
+      end
+    end
+    
+    def __init_config_attribute__(name, opts)
+      unless respond_to?(:config_attributes)
+        class << self
+          def config_attributes
+            @config_attributes ||= {}
+          end
+        end
+      end
+      config_attributes[name] ||= {}
+      config_attributes[name].merge!(opts)
+    end
+  end
+end

data/lib/onstomp/interfaces.rb

@@ -0,0 +1,14 @@
+# -*- encoding: utf-8 -*-
+
+# Namespace for interface mixins
+module OnStomp::Interfaces
+end
+
+require 'onstomp/interfaces/uri_configurable'
+require 'onstomp/interfaces/client_configurable'
+require 'onstomp/interfaces/frame_methods'
+require 'onstomp/interfaces/event_manager'
+require 'onstomp/interfaces/connection_events'
+require 'onstomp/interfaces/client_events'
+require 'onstomp/interfaces/receipt_manager'
+require 'onstomp/interfaces/subscription_manager'

data/lib/onstomp/version.rb

@@ -0,0 +1,13 @@
+# -*- encoding: utf-8 -*-
+
+# Primary namespace for the +onstomp+ gem
+module OnStomp
+  # Major / API version
+  MAJOR = 1
+  # Minor / feature version
+  MINOR = 0
+  # Patch version
+  PATCH = 0
+  # Complete version
+  VERSION = "#{MAJOR}.#{MINOR}.#{PATCH}pre1"
+end

data/lib/onstomp.rb

@@ -0,0 +1,147 @@
+# -*- encoding: utf-8 -*-
+
+# Copyright 2011 Ian D. Eccles
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+# http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# For extensions to URI.parse for Stomp schemes.
+require 'uri'
+# Primarily for CGI.parse
+require 'cgi'
+# Sockets are fairly important in all of this.
+require 'socket'
+# As is openssl
+require 'openssl'
+# For IO#ready?
+require 'io/wait'
+# The socket helpers use this to delegate to the real sockets
+require 'delegate'
+# Threading and Mutex support
+require 'thread'
+# Monitor support (prevent recursive dead locking)
+require 'monitor'
+
+# Primary namespace for the +onstomp+ gem
+module OnStomp
+  # A common base class for errors raised by the OnStomp gem
+  # @abstract
+  class OnStompError < StandardError; end
+  
+  # Low level error raised when the broker transmits data that violates
+  # the Stomp protocol specification.
+  # @abstract
+  class FatalProtocolError < OnStompError; end
+  
+  # Raised when an invalid character is encountered in a header
+  class InvalidHeaderCharacterError < FatalProtocolError; end
+  
+  # Raised when an invalid escape sequence is encountered in a header name or value
+  class InvalidHeaderEscapeSequenceError < FatalProtocolError; end
+  
+  # Raised when a malformed header is encountered. For example, if a header
+  # line does not contain ':'
+  class MalformedHeaderError < FatalProtocolError; end
+  
+  # Raised when a malformed frame is encountered on the stream. For example,
+  # if a frame is not properly terminated with the {OnStomp::FrameIO::FRAME_TERMINATOR}
+  # character.
+  class MalformedFrameError < FatalProtocolError; end
+  
+  # An error that is raised as a result of a misconfiguration of the client
+  # connection
+  # @abstract
+  class FatalConnectionError < OnStompError; end
+  
+  # Raised when a connection has been configured with an unsupported protocol
+  # version. This can be due to end user misconfiguration, or due to improper
+  # protocol negotiation with the message broker.
+  class UnsupportedProtocolVersionError < FatalConnectionError; end
+  
+  # Raised when an attempt to connect to the broker results in an unexpected
+  # exchange.
+  class ConnectFailedError < FatalConnectionError; end
+  
+  # Raised if the command issued is not supported by the protocol version
+  # negotiated between the client and broker.
+  class UnsupportedCommandError < OnStompError; end
+  
+  # An error that is raised as a result frames being generated on
+  # a transaction while it is in an invalid state.
+  # @abstract
+  class TransactionError < OnStompError; end
+
+  # Raised by ThreadedReceiver to stop the receiving thread.
+  class StopReceiver < StandardError; end
+  
+  class << self
+    # Creates a new connection and immediately connects it to the broker.
+    # @see #initialize
+    def connect(uri, options={})
+      conx = OnStomp::Client.new(uri, options)
+      conx.connect
+      conx
+    end
+    alias :open :connect
+    
+    # Duplicates an existing hash while transforming its keys to symbols.
+    # The keys must implement the +to_sym+ method, otherwise an exception will
+    # be raised. This method is used internally to convert hashes keyed with
+    # Strings.
+    #
+    # @param [{Object => Object}] hsh The hash to convert. It's keys must respond to +to_sym+.
+    # @return [{Symbol => Object}]
+    # @example
+    #   hash = { '10' => nil, 'key2' => [3, 5, 8, 13, 21], :other => :value }
+    #   OnStomp.keys_to_sym(hash) #=> { :'10' => nil, :key2 => [3, 5, 8, 13, 21], :other => :value }
+    #   hash #=> { '10' => nil, 'key2' => [3, 5, 8, 13, 21], :other => :value }
+    def keys_to_sym(hsh)
+      hsh.inject({}) do |new_hash, (k,v)|
+        new_hash[k.to_sym] = v
+        new_hash
+      end
+    end
+    
+    # Generates the next serial number in a thread-safe manner. This method
+    # merely initializes an instance variable to 0 if it has not been set,
+    # then increments this value and returns its string representation.
+    def next_serial(prefix=nil)
+      Thread.exclusive do
+        @next_serial_sequence ||= 0
+        @next_serial_sequence += 1
+        @next_serial_sequence.to_s
+      end
+    end
+
+    # Converts a string to the Ruby constant it names. If the +klass+ parameter
+    # is a kind of +Module+, this method will return +klass+ directly.
+    # @param [String,Module] klass
+    # @return [Module]
+    # @example
+    #   OnStomp.constantize('OnStomp::Frame') #=> OnStomp::Frame
+    #   OnStomp.constantize('This::Constant::DoesNotExist) #=> raises NameError
+    #   OnStomp.constantize(Symbol) #=> Symbol 
+    def constantize(klass)
+      return klass if klass.is_a?(Module) || klass.nil? || klass.respond_to?(:new)
+      klass.to_s.split('::').inject(Object) do |const, named|
+        next const if named.empty?
+        const.const_defined?(named) ? const.const_get(named) :
+          const.const_missing(named)
+      end
+    end
+  end
+end
+require 'onstomp/version'
+require 'onstomp/interfaces'
+require 'onstomp/components'
+require 'onstomp/connections'
+require 'onstomp/client'