onstomp 1.0.0 → 1.0.1

data/lib/onstomp.rb

@@ -31,7 +31,7 @@ require 'thread'
 # Monitor support (prevent recursive dead locking)
 require 'monitor'
 
-# Primary namespace for the +onstomp+ gem
+# Primary namespace for the `onstomp` gem
 module OnStomp
   # Class to use for creating enumerator objects, which depends upon the
   # version of Ruby being used.
@@ -98,11 +98,11 @@ module OnStomp
     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
+    # 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+.
+    # @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 }
@@ -126,8 +126,8 @@ module OnStomp
       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.
+    # 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

data/lib/onstomp/client.rb

@@ -10,7 +10,7 @@ class OnStomp::Client
   include OnStomp::Interfaces::SubscriptionManager
   include OnStomp::Components::Scopes
   
-  # The +URI+ reference to the STOMP broker
+  # The `URI` reference to the STOMP broker
   # @return [String]
   attr_reader :uri
   # SSL options for the connection
@@ -47,6 +47,7 @@ class OnStomp::Client
   # @return [Class]
   attr_configurable_processor :processor
   
+  # @api gem:1 STOMP:1.0,1.1
   # Creates a new client for the specified uri and optional hash of options.
   # @param [String,URI] uri
   # @param [{Symbol => Object}] options
@@ -61,6 +62,7 @@ class OnStomp::Client
     end
   end
   
+  # @api gem:1 STOMP:1.0,1.1
   # Connects to the STOMP broker referenced by {#uri}. Includes optional
   # headers in the CONNECT frame, if specified.
   # @param [{#to_sym => #to_s}] headers
@@ -75,6 +77,7 @@ class OnStomp::Client
   end
   alias :open :connect
   
+  # @api gem:1 STOMP:1.0,1.1
   # Sends a DISCONNECT frame to the broker and blocks until the connection
   # has been closed. This method ensures that all frames not yet sent to
   # the broker will get processed barring any IO exceptions.
@@ -89,12 +92,14 @@ class OnStomp::Client
   alias :disconnect_without_flush :disconnect
   alias :disconnect :disconnect_with_flush
   
+  # @api gem:1 STOMP:1.0,1.1
   # Returns true if a connection to the broker exists and itself is connected.
   # @return [true,false]
   def connected?
     connection && connection.connected?
   end
   
+  # @api gem:1 STOMP:1.0,1.1
   # Forces the connection between broker and client closed.
   # @note Use of this method may result in frames never being sent to the
   #   broker. This method should only be used if {#disconnect} is not an

data/lib/onstomp/components/frame.rb

@@ -13,8 +13,8 @@ class OnStomp::Components::Frame
   attr_reader :headers
   
   # Creates a new frame. The frame will be initialized with the optional
-  # +command+ name, a {OnStomp::Components::FrameHeaders headers} collection initialized
-  # with the optional +headers+ hash, and an optional body.
+  # `command` name, a {OnStomp::Components::FrameHeaders headers} collection initialized
+  # with the optional `headers` hash, and an optional body.
   def initialize(command=nil, headers={}, body=nil)
     @command = command
     @headers = OnStomp::Components::FrameHeaders.new(headers)
@@ -26,7 +26,7 @@ class OnStomp::Components::Frame
   #
   # @param [Object] name the header name associated with the desired value
   # @return [String] the value associated with the requested header name
-  # @see OnStomp::Headers#[]
+  # @see OnStomp::Components::FrameHeaders#[]
   # @example
   #   frame['content-type'] #=> 'text/plain'
   def [](name); @headers[name]; end
@@ -37,7 +37,7 @@ class OnStomp::Components::Frame
   # @param [Object] name the header name to associate with the supplied value
   # @param [Object] val the value to associate with the supplied header name
   # @return [String] the supplied value as a string, or `nil` if `nil` was supplied as the value.
-  # @see OnStomp::Headers#[]=
+  # @see OnStomp::Components::FrameHeaders#[]=
   # @example
   #   frame['content-type'] = 'text/plain' #=> 'text/plain'
   #   frame['other header'] = 42 #=> '42'
@@ -52,9 +52,9 @@ class OnStomp::Components::Frame
   
   # If a +content-type+ header is set, splits it into three parts: type,
   # subtype and charset. If any component of the +content-type+ is missing,
-  # its value will be +nil+ in the returned triple. If the +content-type+
+  # its value will be `nil` in the returned triple. If the +content-type+
   # header is not set or does not match {OnStomp::Components::Frame::CONTENT_TYPE_REG}
-  # all values in the triple will be +nil+.
+  # all values in the triple will be `nil`.
   # @return [Array<String,nil>]
   def content_type
     @headers[:'content-type'] =~ CONTENT_TYPE_REG ? [$1, $2, $3] : [nil, nil, nil]

data/lib/onstomp/components/frame_headers.rb

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
 
 # A specialized container for storing header name / value pairs for a
-# {OnStomp::Components::Frame frame}.  This container behaves much like a +Hash+, but
+# {OnStomp::Components::Frame frame}.  This container behaves much like a `Hash`, but
 # is specialized for the Stomp protocol.  Header names are always converted
-# into +String+s through the use of +to_s+ and may have more than one value
+# into `String`s through the use of `to_s` and may have more than one value
 # associated with them.
 class OnStomp::Components::FrameHeaders
   include Enumerable
@@ -19,7 +19,7 @@ class OnStomp::Components::FrameHeaders
   end
   
   # Merges a hash into this collection of headers. All of the keys used
-  # in the hash must be convertable to Symbols through +to_sym+.
+  # in the hash must be convertable to Symbols through `to_sym`.
   # @note With Ruby 1.8.7, the order of hash keys may not be preserved
   # @param [Hash] hash
   def merge!(hash)
@@ -29,7 +29,7 @@ class OnStomp::Components::FrameHeaders
   # Reverse merges a hash into this collection of headers. The hash keys and
   # values are included only if the headers collection does not already have
   # a matching key. All of the keys used
-  # in the hash must be convertable to Symbols through +to_sym+.
+  # in the hash must be convertable to Symbols through `to_sym`.
   # @note With Ruby 1.8.7, the order of hash keys may not be preserved
   # @param [Hash] hash
   def reverse_merge!(hash)
@@ -48,7 +48,7 @@ class OnStomp::Components::FrameHeaders
   end
   
   # Returns true if a header value has been set for the supplied header, and
-  # the value is neither +nil+ nor an empty string.
+  # the value is neither `nil` nor an empty string.
   # @param [#to_sym] name the header name to test
   # @return [Boolean]
   # @example
@@ -68,7 +68,7 @@ class OnStomp::Components::FrameHeaders
   # element of the array will be the principle value of the supplied
   # header name.
   #
-  # @param [#to_sym] name the header name associated with the desired values (will be converted using +to_sym+)
+  # @param [#to_sym] name the header name associated with the desired values (will be converted using `to_sym`)
   # @return [Array] the array of values associated with the header name.
   # @example
   #   headers.all_values('content-type') #=> [ 'text/plain' ]
@@ -83,8 +83,8 @@ class OnStomp::Components::FrameHeaders
   # principle value.  This method is used internally when constructing
   # frames sent by the broker to capture repeated header names.
   #
-  # @param [#to_sym] name the header name to associate with the supplied value (will be converted using +to_s+)
-  # @param [#to_s] val the header value to associate with the supplied name (will be converted using +to_s+)
+  # @param [#to_sym] name the header name to associate with the supplied value (will be converted using `to_s`)
+  # @param [#to_s] val the header value to associate with the supplied name (will be converted using `to_s`)
   # @return [String] the supplied value as a string.
   # @example
   #   headers.append(:'new header', 'first value') #=> 'first value'
@@ -104,11 +104,11 @@ class OnStomp::Components::FrameHeaders
   end
   
   # Deletes all of the header values associated with the header name and
-  # removes the header name itself.  This is analogous to the +delete+
+  # removes the header name itself.  This is analogous to the `delete`
   # method found in Hash objects.
   #
-  # @param [#to_sym] name the header name to remove from this collection (will be converted using +to_sym+)
-  # @return [Array] the array of values associated with the deleted header, or +nil+ if the header name did not exist
+  # @param [#to_sym] name the header name to remove from this collection (will be converted using `to_sym`)
+  # @return [Array] the array of values associated with the deleted header, or `nil` if the header name did not exist
   # @example
   #   headers.delete(:'content-type') #=> [ 'text/html' ]
   #   headers.delete('no such header') #=> nil
@@ -121,11 +121,11 @@ class OnStomp::Components::FrameHeaders
   end
   
   # Gets the principle header value paired with the supplied header name. The name will
-  # be converted to a Symbol, so must respond to the +to_sym+ method.  The
+  # be converted to a Symbol, so must respond to the `to_sym` method.  The
   # Stomp 1.1 protocol specifies that in the event of a repeated header name,
   # the first value encountered serves as the principle value.
   #
-  # @param [#to_sym] name the header name paired with the desired value (will be converted using +to_sym+)
+  # @param [#to_sym] name the header name paired with the desired value (will be converted using `to_sym`)
   # @return [String] the value associated with the requested header name
   # @return [nil] if no value has been set for the associated header name
   # @example
@@ -136,12 +136,12 @@ class OnStomp::Components::FrameHeaders
   end
   
   # Sets the header value paired with the supplied header name.  The name 
-  # will be converted to a Symbol and must respond to +to_sym+; meanwhile,
-  # the value will be converted to a String so must respond to +to_s+.
+  # will be converted to a Symbol and must respond to `to_sym`; meanwhile,
+  # the value will be converted to a String so must respond to `to_s`.
   # Setting a header value in this fashion will overwrite any repeated header values.
   #
-  # @param [#to_sym] name the header name to associate with the supplied value (will be converted using +to_sym+)
-  # @param [#to_s] val the value to pair with the supplied name (will be converted using +to_s+)
+  # @param [#to_sym] name the header name to associate with the supplied value (will be converted using `to_sym`)
+  # @param [#to_s] val the value to pair with the supplied name (will be converted using `to_s`)
   # @return [String] the supplied value as a string.
   # @example
   #   headers['content-type'] = 'image/png' #=> 'image/png'
@@ -155,7 +155,7 @@ class OnStomp::Components::FrameHeaders
     val
   end
   
-  # Returns a new +Hash+ object associating symbolized header names and their
+  # Returns a new `Hash` object associating symbolized header names and their
   # principle values.
   # @return [Hash]
   def to_hash

data/lib/onstomp/components/scopes/transaction_scope.rb

@@ -8,7 +8,7 @@
 class OnStomp::Components::Scopes::TransactionScope
   include OnStomp::Interfaces::FrameMethods
   
-  # The id of the current transaction. This may be +nil+ if the transaction
+  # The id of the current transaction. This may be `nil` if the transaction
   # has not been started with {#begin} or if the transaction has been completed
   # by a call to either {#abort} or {#commit}.
   # @return [String,nil]
@@ -18,7 +18,7 @@ class OnStomp::Components::Scopes::TransactionScope
   # @return [OnStomp::Client]
   attr_reader :client
   
-  # A reference to +self+ to trick {OnStomp::Interfaces::FrameMethods} into
+  # A reference to `self` to trick {OnStomp::Interfaces::FrameMethods} into
   # creating frames on this object instead of the client's actual
   # {OnStomp::Client#connection connection}.
   # @return [self]
@@ -89,9 +89,9 @@ class OnStomp::Components::Scopes::TransactionScope
   
   # Overrides the {OnStomp::Connections::Stomp_1#send_frame send_frame} method
   # of the {OnStomp::Client#connection client's connection}, setting a
-  # +transaction+ header to match the current transaction if it has been
+  # `transaction` header to match the current transaction if it has been
   # started.
-  # @param [arg1, arg2, ...] args arguments to connection's +send_frame+ method
+  # @param [arg1, arg2, ...] args arguments to connection's `send_frame` method
   # @return [OnStomp::Components::Frame] SEND frame
   def send_frame *args, &blk
     client.connection.send_frame(*args,&blk).tap do |f|
@@ -101,9 +101,9 @@ class OnStomp::Components::Scopes::TransactionScope
   
   # Overrides the {OnStomp::Connections::Stomp_1_0#ack_frame ack_frame} method
   # of the client's {OnStomp::Client#connection connection}, setting a
-  # +transaction+ header to match the current transaction if it has been
+  # `transaction` header to match the current transaction if it has been
   # started.
-  # @param [arg1, arg2, ...] args arguments to connection's +ack_frame+ method
+  # @param [arg1, arg2, ...] args arguments to connection's `ack_frame` method
   # @return [OnStomp::Components::Frame] ACK frame
   def ack_frame *args
     client.connection.ack_frame(*args).tap do |f|
@@ -113,9 +113,9 @@ class OnStomp::Components::Scopes::TransactionScope
   
   # Overrides the {OnStomp::Connections::Stomp_1_1#nack_frame nack_frame} method
   # of the {OnStomp::Client#connection client's connection}, setting a
-  # +transaction+ header to match the current transaction if it has been
+  # `transaction` header to match the current transaction if it has been
   # started.
-  # @param [arg1, arg2, ...] args arguments to connection's +nack_frame+ method
+  # @param [arg1, arg2, ...] args arguments to connection's `nack_frame` method
   # @return [OnStomp::Components::Frame] NACK frame
   def nack_frame *args
     client.connection.ack_frame(*args).tap do |f|
@@ -123,13 +123,13 @@ class OnStomp::Components::Scopes::TransactionScope
     end
   end
   
-  # If the name of the missing method ends with +_frame+, the method is passed
+  # If the name of the missing method ends with `_frame`, the method is passed
   # along to the client's {OnStomp::Client#connection connection} so that it
   # might build the appropriate (non-transactional) frame.
   # @return [OnStomp::Components::Frame]
   # @raise [OnStomp::UnsupportedCommandError] if the connection does not
   #   support the requested frame command.
-  # @raise [NoMethodError] if the method name does not end in +_frame+
+  # @raise [NoMethodError] if the method name does not end in `_frame`
   def method_missing meth, *args, &block
     if meth.to_s =~ /^(.*)_frame$/
       client.connection.__send__(meth, *args, &block)
@@ -154,7 +154,7 @@ class OnStomp::Components::Scopes::TransactionScope
   # @return [self]
   # @raise [Exception] if supplied block raises an exception
   # @yield [t] block of frames to transmit transactionally
-  # @yieldparam [OnStomp::Components::Scopes::TransactionScope] t +self+
+  # @yieldparam [OnStomp::Components::Scopes::TransactionScope] t `self`
   def perform
     begin
       self.begin unless @started

data/lib/onstomp/components/subscription.rb

@@ -12,10 +12,10 @@ class OnStomp::Components::Subscription
     @frame = fr
     @callback = cb
   end
-  # Returns the +id+ header of the associated SUBSCRIBE frame
+  # Returns the `id` header of the associated SUBSCRIBE frame
   # @return [String]
   def id; frame[:id]; end
-  # Returns the +destination+ header of the associated SUBSCRIBE frame
+  # Returns the `destination` header of the associated SUBSCRIBE frame
   # @return [String]
   def destination; frame[:destination]; end
   # Invokes the {#callback}, passing along the supplied MESSAGE frame

data/lib/onstomp/components/threaded_processor.rb

@@ -47,7 +47,7 @@ class OnStomp::Components::ThreadedProcessor
     end
   end
   
-  # Causes the thread this method was invoked in to +pass+ until the
+  # Causes the thread this method was invoked in to `pass` until the
   # processor is no longer {#running? running}.
   # @return [self]
   def join

data/lib/onstomp/components/uri.rb

@@ -23,7 +23,7 @@ module OnStomp::Components::URI
   end
 end
 
-# Add the new URI classes to +URI+'s set of known schemes.
+# Add the new URI classes to `URI`'s set of known schemes.
 module ::URI
   @@schemes['STOMP'] = OnStomp::Components::URI::STOMP
   @@schemes['STOMP+SSL'] = OnStomp::Components::URI::STOMP_SSL

data/lib/onstomp/connections/base.rb

@@ -13,9 +13,9 @@ class OnStomp::Connections::Base
   MAX_BYTES_PER_READ = 1024 * 4
   
   # Creates a new connection using the given {#socket} object and
-  # {OnStomp::Client client}. The {#socket} object will generally be a +TCPSocket+
-  # or an +OpenSSL::SSL::SSLSocket+ and must support the methods +read_nonblock+
-  # +write_nonblock+, and +close+.
+  # {OnStomp::Client client}. The {#socket} object will generally be a `TCPSocket`
+  # or an +OpenSSL::SSL::SSLSocket+ and must support the methods `read_nonblock`
+  # `write_nonblock`, and `close`.
   # @param [TCPSocket,OpenSSL::SSL::SSLSocket] socket
   # @param [OnStomp::Client] client
   def initialize socket, client
@@ -29,7 +29,7 @@ class OnStomp::Connections::Base
   end
   
   # Performs any necessary configuration of the connection from the CONNECTED
-  # frame sent by the broker and a +Hash+ of pending callbacks. This method
+  # frame sent by the broker and a `Hash` of pending callbacks. This method
   # is called after the protocol negotiation has taken place between client
   # and broker, and the connection that receives it will be the connection
   # used by the client for the duration of the session.
@@ -46,7 +46,7 @@ class OnStomp::Connections::Base
     !socket.closed?
   end
   
-  # Closes the {#socket}. If +blocking+ is true, the socket will be closed
+  # Closes the {#socket}. If `blocking` is true, the socket will be closed
   # immediately, otherwies the socket will remain open until {#io_process_write}
   # has finished writing all of its buffered data. Once this method has been
   # invoked, {#write_frame_nonblock} will not enqueue any additional frames

data/lib/onstomp/connections/heartbeating.rb

@@ -53,14 +53,14 @@ module OnStomp::Connections::Heartbeating
   end
   
   # Number of milliseconds since data was last transmitted to the broker or
-  # +nil+ if no data has been transmitted when the method is called.
+  # `nil` if no data has been transmitted when the method is called.
   # @return [Fixnum, nil]
   def duration_since_transmitted
     last_transmitted_at && ((Time.now - last_transmitted_at)*1000).to_i
   end
   
   # Number of milliseconds since data was last received from the broker or
-  # +nil+ if no data has been received when the method is called.
+  # `nil` if no data has been received when the method is called.
   # @return [Fixnum, nil]
   def duration_since_received
     last_received_at && ((Time.now - last_received_at)*1000).to_i

data/lib/onstomp/connections/serializers/stomp_1.rb

@@ -1,7 +1,7 @@
 # -*- encoding: utf-8 -*-
 
-# Classes that mix this in must define +split_header+ and +prepare_parsed_frame+
-# The method +frame_to_string_base+ is provided as a factoring out of the
+# Classes that mix this in must define `split_header` and `prepare_parsed_frame`
+# The method `frame_to_string_base` is provided as a factoring out of the
 # common tasks of serializing a frame for STOMP 1.0 and STOMP 1.1.
 module OnStomp::Connections::Serializers::Stomp_1
   # Resets the parser that converts byte strings to {OnStomp::Components::Frame frames}
@@ -72,7 +72,7 @@ module OnStomp::Connections::Serializers::Stomp_1
   end
   
   # Adds the substring +data[0...idx]+ to the parser's accumulator,
-  # unshifts the remaining data back onto the buffer, and calls +meth+
+  # unshifts the remaining data back onto the buffer, and calls `meth`
   # with the parser's accumulated string.
   # @param [Array<String>] buffer
   # @param [String] data
@@ -117,7 +117,7 @@ module OnStomp::Connections::Serializers::Stomp_1
   
   # Called when a frame's body has been fully read from the buffer. This
   # method will set the frame's {OnStomp::Components::Frame#body body}
-  # attribute, call +prepare_parsed_frame+ with the "current frame",
+  # attribute, call `prepare_parsed_frame` with the "current frame",
   # and tell the parser to move on to the next state.
   # @param [String] body
   def finish_body body
@@ -150,14 +150,14 @@ module OnStomp::Connections::Serializers::Stomp_1
   end
   
   if RUBY_VERSION >= "1.9"
-    # Takes the result of +frame_to_string+ and forces it to use a binary
+    # Takes the result of `frame_to_string` and forces it to use a binary
     # encoding
     # @return [String] string serialization of frame with 'ASCII-8BIT' encoding
     def frame_to_bytes frame
       frame_to_string(frame).tap { |s| s.force_encoding('ASCII-8BIT') }
     end
   else
-    # Takes the result of +frame_to_string+ and passes it along. Ruby 1.8.7
+    # Takes the result of `frame_to_string` and passes it along. Ruby 1.8.7
     # treats strings as a collection of bytes, so we don't need to do any
     # further work.
     # @return [String]

data/lib/onstomp/connections/serializers/stomp_1_1.rb

@@ -94,7 +94,7 @@ class OnStomp::Connections::Serializers::Stomp_1_1
       f.body.force_encoding(charset)
       f
     end
-    # Set an appropriate +content-type+ header with +charset+ parameter for
+    # Set an appropriate +content-type+ header with `charset` parameter for
     # frames with a text body
     # @note No-op for Ruby 1.8.x
     # @param [OnStomp::Components::Frame] f
@@ -124,7 +124,7 @@ class OnStomp::Connections::Serializers::Stomp_1_1
     # @param [OnStomp::Components::Frame] f
     # @return [OnStomp::Components::Frame]
     def force_body_encoding(f); f; end
-    # Set an appropriate +content-type+ header with +charset+ parameter for
+    # Set an appropriate +content-type+ header with `charset` parameter for
     # frames with a text body
     # @note No-op for Ruby 1.8.x
     # @param [OnStomp::Components::Frame] f