onstomp 1.0.0 → 1.0.1

data/lib/onstomp/interfaces/connection_events.rb

@@ -6,6 +6,7 @@ module OnStomp::Interfaces::ConnectionEvents
   
   # @group Connection State Events
 
+  # @api gem:1 STOMP:1.0,1.1
   # 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
@@ -13,6 +14,7 @@ module OnStomp::Interfaces::ConnectionEvents
   # @yieldparam [OnStomp::Connections::Base] connection that triggered
   #   the event (in general the same as +client.connection+)
   create_event_methods :established, :on
+  # @api gem:1 STOMP:1.1
   # 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.
@@ -21,6 +23,7 @@ module OnStomp::Interfaces::ConnectionEvents
   # @yieldparam [OnStomp::Connections::Base] connection that triggered
   #   the event (in general the same as +client.connection+)
   create_event_methods :died, :on
+  # @api gem:1 STOMP:1.0,1.1
   # 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
@@ -28,6 +31,7 @@ module OnStomp::Interfaces::ConnectionEvents
   # @yieldparam [OnStomp::Connections::Base] connection that triggered
   #   the event (in general the same as +client.connection+)
   create_event_methods :terminated, :on
+  # @api gem:1 STOMP:1.0,1.1
   # 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,
@@ -47,7 +51,7 @@ module OnStomp::Interfaces::ConnectionEvents
   end
   
   # Takes a hash of event bindings a {OnStomp::Client client} has stored
-  # and binds them to this connection, then triggers +on_established+.
+  # 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.

data/lib/onstomp/interfaces/event_manager.rb

@@ -7,7 +7,7 @@ module OnStomp::Interfaces::EventManager
     base.extend ClassMethods
   end
   
-  # Binds a +Proc+ to be invoked when the given +event_name+ is triggered.
+  # Binds a `Proc` to be invoked when the given `event_name` is triggered.
   # @param [Symbol] event_name
   # @param [Proc] cb_proc
   # @return [self]
@@ -23,7 +23,7 @@ module OnStomp::Interfaces::EventManager
   end
   
   # Triggers an event by the given name, passing along any additional
-  # +args+ as parameters to the callback
+  # `args` as parameters to the callback
   # @param [Symbol] event_name event to trigger
   # @param [Object, Object, ...] args
   def trigger_event(event_name, *args)

data/lib/onstomp/interfaces/frame_methods.rb

@@ -3,6 +3,22 @@
 # Mixin for {OnStomp::Client clients} to provide methods that create
 # and transmit STOMP {OnStomp::Components::Frame frames}.
 module OnStomp::Interfaces::FrameMethods
+  # I'm using @api tags in here to provide a bit of data, here's the format:
+  # gem:<major version>[,<major version>,...] STOMP:<version>[,<version>,...]
+  # The first chunk indicates the MAJOR versions of the OnStomp gem that support
+  # the method. The second chunk indicates the STOMP protocol versions that
+  # support the frame generated by this method. A single '*' after the STOMP
+  # versions indicates that there are minor changes between protocols
+  # (eg: new acceptable values for an optional header.) A single '!' after
+  # the STOMP versions indicates that there are major changes between protocols
+  # (eg: a new header is required, as with ACK) indicating that some ways of
+  # calling the method may produce errors with newer versions of the STOMP
+  # protocol. All other text after the severity markers is for my own reference
+  # to remind me of the changes. These API tags will be queried and put into
+  # a document to provide a quick reference of changes between protocols or
+  # major gem versions for end users.
+  
+  # @api gem:1 STOMP:1.0,1.1
   # Transmits a SEND frame generated by the client's connection
   # @param [String] dest destination for the frame
   # @param [String] body body of the frame
@@ -14,11 +30,38 @@ module OnStomp::Interfaces::FrameMethods
   # @yieldparam [OnStomp::Components::Frame] receipt RECEIPT for the frame
   # @raise OnStomp::UnsupportedCommandError if the connection does not support
   #   SEND frames
+  # @option headers [String] :'content-type' The content type of the SEND
+  #   frame's body. If the body is text (ie: has a non-binary `encoding`)
+  #   `onstomp` will set the :'content-type' header to 'text/plain' if it
+  #   has not been set. See {file:docs/Encodings.md Encodings} for more
+  #   details.
+  # @option headers [String] :receipt A receipt ID for the frame, this
+  #   will be matched by the :'receipt-id' header in the broker's RECEIPT
+  #   response.
+  # @option headers [String] :transaction The ID of an existing transaction
+  #   to add this frame to.
+  # @option headers [String] :'content-length' If you set this header, it
+  #   will be overwritten, so save your fingers from a few keystrokes by not
+  #   setting it.  All SEND frames generated by `onstomp` will have a
+  #   :'content-length' header.
+  # @example
+  #   # Transmit a simple SEND frame to the broker
+  #   client.send '/queue/example', 'Hello STOMP'
+  #   
+  #   # Everything's better with umlauts.
+  #   client.send '/topic/example', "Hëllo Wörld",
+  #     :'content-type' => 'text/plain;charset=UTF-8'
+  #
+  #   # Get a receipt for the SEND frame
+  #   client.send '/queue/example', "Did you get that thing I sent you?" do |r|
+  #     puts "The broker received our SEND frame"
+  #   end
   def send dest, body, headers={}, &cb
     transmit connection.send_frame(dest, body, headers), :receipt => cb
   end
   alias :puts :send
 
+  # @api gem:1 STOMP:1.0,1.1* [+ack:client-individual]
   # 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.
@@ -50,29 +93,65 @@ module OnStomp::Interfaces::FrameMethods
   # @see #unsubscribe
   # @see #ack
   # @see #nack
+  # @option headers [String] :id A unique ID for the subscription. If you
+  #   do not set this header, an subscription ID will be automatically
+  #   generated ensuring that all `onstomp` SUBSCRIBE frames have an ID.
+  # @option headers [String] :ack ('auto') The ack mode to use with this
+  #   subscription. A value of 'auto' means MESSAGE frames are assumed
+  #   received and no ACK frame is necessary. A value of 'client' or
+  #   'client-individual' means all MESSAGE frames should be acknowledged
+  #   with an ACK (or un-acknowledged with a NACK.)
+  # @option headers [String] :selector A SQL style filter to use against
+  #   MESSAGE frames (the form and availability of this will vary by
+  #   broker.)
+  # @option headers [String] :receipt A receipt ID for the frame, this
+  #   will be matched by the :'receipt-id' header in the broker's RECEIPT
+  #   response.
+  # @example
+  #   # A basic subscription
+  #   client.subscribe '/queue/example' do |m|
+  #     puts "Got a MESSAGE: #{m.body}"
+  #   end
+  #   
+  #   # ACK our MESSAGE frames
+  #   client.subscribe '/queue/example', :ack => 'client' do |m|
+  #     client.ack m
+  #     puts "Got (and ACK'd) a MESSAGE: #{m.body}"
+  #   end
   def subscribe dest, headers={}, &cb
     transmit connection.subscribe_frame(dest, headers), :subscribe => cb
   end
   
+  # @api gem:1 STOMP:1.0,1.1
   # 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
+  #   @example
+  #     sub = client.subscribe('/queue/test') { |m| ... }
+  #     client.unsubscribe sub
   # @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
+  #   @example
+  #     client.subscribe('/queue/test', :id => 's-1234') { |m| ... }
+  #     client.unsubscribe 's-1234'
   # @return [OnStomp::Components::Frame] UNSUBSCRIBE frame
   # @raise OnStomp::UnsupportedCommandError if the connection does not support
   #   UNSUBSCRIBE frames
   # @see #subscribe
+  # @option headers [String] :receipt A receipt ID for the frame, this
+  #   will be matched by the :'receipt-id' header in the broker's RECEIPT
+  #   response.
   def unsubscribe frame_or_id, headers={}
     transmit connection.unsubscribe_frame(frame_or_id, headers)
   end
-  
+
+  # @api gem:1 STOMP:1.0,1.1
   # Transmits a BEGIN frame generated by the client's connection to start
   # a transaction.
   # @param [String] tx_id identifier for the transaction
@@ -83,10 +162,18 @@ module OnStomp::Interfaces::FrameMethods
   #   BEGIN frames
   # @see #abort
   # @see #commit
+  # @option headers [String] :receipt A receipt ID for the frame, this
+  #   will be matched by the :'receipt-id' header in the broker's RECEIPT
+  #   response.
+  # @example
+  #   client.begin 't-1234'
+  #   client.send '/queue/test', 'hello transaction!', :transaction => 't-1234'
+  #   client.commit 't-1234'
   def begin tx_id, headers={}
     transmit connection.begin_frame(tx_id, headers)
   end
-  
+
+  # @api gem:1 STOMP:1.0,1.1
   # Transmits an ABORT frame generated by the client's connection to rollback
   # a transaction.
   # @param [String] tx_id identifier for the transaction
@@ -97,10 +184,18 @@ module OnStomp::Interfaces::FrameMethods
   #   ABORT frames
   # @see #begin
   # @see #commit
+  # @option headers [String] :receipt A receipt ID for the frame, this
+  #   will be matched by the :'receipt-id' header in the broker's RECEIPT
+  #   response.
+  # @example
+  #   client.begin 't-1234'
+  #   client.send '/queue/test', 'hello transaction!', :transaction => 't-1234'
+  #   client.abort 't-1234'
   def abort tx_id, headers={}
     transmit connection.abort_frame(tx_id, headers)
   end
-  
+
+  # @api gem:1 STOMP:1.0,1.1
   # Transmits a COMMIT frame generated by the client's connection to complete
   # a transaction.
   # @param [String] tx_id identifier for the transaction
@@ -111,10 +206,18 @@ module OnStomp::Interfaces::FrameMethods
   #   COMMIT frames
   # @see #abort
   # @see #begin
+  # @option headers [String] :receipt A receipt ID for the frame, this
+  #   will be matched by the :'receipt-id' header in the broker's RECEIPT
+  #   response.
+  # @example
+  #   client.begin 't-1234'
+  #   client.send '/queue/test', 'hello transaction!', :transaction => 't-1234'
+  #   client.commit 't-1234'
   def commit tx_id, headers={}
     transmit connection.commit_frame(tx_id, headers)
   end
 
+  # @api gem:1 STOMP:1.0,1.1* [DISCONNECTs are now always RECEIPTable]
   # 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
@@ -122,42 +225,77 @@ module OnStomp::Interfaces::FrameMethods
   # @return [OnStomp::Components::Frame] DISCONNECT frame
   # @raise OnStomp::UnsupportedCommandError if the connection does not support
   #   DISCONNECT frames
+  # @option headers [String] :receipt A receipt ID for the frame, this
+  #   will be matched by the :'receipt-id' header in the broker's RECEIPT
+  #   response.
+  # @example
+  #   client.connect
+  #   client.send '/queue/test', 'a quick message'
+  #   client.disconnect
   def disconnect headers={}
     transmit connection.disconnect_frame headers
   end
 
+  # @api gem:1 STOMP:1.0,1.1! [+subscription:id]
   # Transmits an ACK frame generated by the client's connection.
   # @overload ack(message_frame, headers={})
+  #   @api gem:1 STOMP:1.0,1.1
   #   @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
+  #   @example
+  #     client.subscribe '/queue/test', :ack => 'client' do |m|
+  #       if m[:'x-of-interest-to-me'] == 'hells yes'
+  #         client.ack m
+  #       end
+  #     end
   # @overload ack(message_id, headers={})
-  #   @note This form will raise an +ArgumentError+ with STOMP 1.1 connections
+  #   @api gem:1 STOMP:1.0
+  #   @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={})
+  #   @example
+  #     client.subscribe '/queue/test', :ack => 'client' do |m|
+  #       if m[:'x-of-interest-to-me'] == 'hells yes'
+  #         client.ack m[:'message-id']
+  #       end
+  #     end
+  # @overload ack(message_id, subscription_id, headers={})
+  #   @api gem:1 STOMP:1.0,1.1
   #   @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
+  #   @param [String] subscription_id `subscription` header of MESSAGE frame to
   #     acknowledge.
   #   @param [{#to_sym => #to_s}] headers additional headers to include in
   #     the frame
+  #   @example
+  #     client.subscribe '/queue/test', :ack => 'client' do |m|
+  #       if m[:'x-of-interest-to-me'] == 'hells yes'
+  #         client.ack m[:'message-id'], m[:subscription]
+  #       end
+  #     end
   # @return [OnStomp::Components::Frame] ACK frame
   # @raise OnStomp::UnsupportedCommandError if the connection does not support
   #   ACK frames
   # @see #nack
+  # @option headers [String] :receipt A receipt ID for the frame, this
+  #   will be matched by the :'receipt-id' header in the broker's RECEIPT
+  #   response.
+  # @option headers [String] :transaction The ID of an existing transaction
+  #   to add this frame to.
   def ack *args
     transmit connection.ack_frame(*args)
   end
 
+  # @api gem:1 STOMP:1.1
   # Transmits a NACK frame generated by the client's connection.
   # @overload nack(message_frame, headers={})
   #   Generates a NACK frame for the given MESSAGE frame.
@@ -165,25 +303,48 @@ module OnStomp::Interfaces::FrameMethods
   #     un-acknowledge.
   #   @param [{#to_sym => #to_s}] headers additional headers to include in
   #     the frame
+  #   @example
+  #     client.subscribe '/queue/test', :ack => 'client' do |m|
+  #       if m[:'x-of-interest-to-me'] == 'hells no!'
+  #         client.nack m
+  #       end
+  #     end
   # @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
+  #   @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
+  #   @example
+  #     client.subscribe '/queue/test', :ack => 'client' do |m|
+  #       if m[:'x-of-interest-to-me'] == 'hells no!'
+  #         client.nack m[:'message-id'], m[:subscription]
+  #       end
+  #     end
   # @return [OnStomp::Components::Frame] NACK frame
   # @raise OnStomp::UnsupportedCommandError if the connection does not support
   #   NACK frames
   # @see #ack
+  # @option headers [String] :receipt A receipt ID for the frame, this
+  #   will be matched by the :'receipt-id' header in the broker's RECEIPT
+  #   response.
+  # @option headers [String] :transaction The ID of an existing transaction
+  #   to add this frame to.
   def nack *args
     transmit connection.nack_frame(*args)
   end
-  
+
+  # @api gem:1 STOMP:1.1
   # 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
+  # @example
+  #   # If it's been a while since you've sent any data to the broker:
+  #   client.beat
+  #   # Now the broker knows you're still listening, nay hanging on its every
+  #   # every word.
   def beat
     transmit connection.heartbeat_frame
   end

data/lib/onstomp/interfaces/uri_configurable.rb

@@ -2,7 +2,7 @@
 
 # Module for configurable attributes
 module OnStomp::Interfaces::UriConfigurable
-  # Extends +base+ with {OnStomp::Interfaces::UriConfigurable::ClassMethods}
+  # Extends `base` with {OnStomp::Interfaces::UriConfigurable::ClassMethods}
   def self.included(base)
     base.extend ClassMethods
   end
@@ -41,7 +41,7 @@ module OnStomp::Interfaces::UriConfigurable
     # 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
+    # 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
@@ -63,7 +63,7 @@ module OnStomp::Interfaces::UriConfigurable
     # 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
+    # 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

data/lib/onstomp/open-uri/client_extensions.rb

@@ -5,7 +5,7 @@
 module OnStomp::OpenURI::ClientExtensions
   attr_reader :auto_destination, :openuri_message_queue
   
-  # Aliases {#send_with_openuri} as +send+
+  # Aliases {#send_with_openuri} as `send`
   def self.extended inst
     inst.instance_eval do
       alias :send_without_openuri :send
@@ -43,8 +43,8 @@ module OnStomp::OpenURI::ClientExtensions
     end
   end
 
-  # Returns +n+ frames read from the subscription. If +n+ is ommited,
-  # the next frame is returned, otherwise an array of the next +n+ frames
+  # Returns `n` frames read from the subscription. If `n` is ommited,
+  # the next frame is returned, otherwise an array of the next `n` frames
   # is returned.
   # @see #each
   # @param [Fixnum,nil] n
@@ -62,7 +62,7 @@ module OnStomp::OpenURI::ClientExtensions
   alias :gets :first
   
   # Assigns the auto destination. When a stomp:// URI is opened, this
-  # will initially be set to the +path+ of the URI.
+  # will initially be set to the `path` of the URI.
   # @param [String] dest
   # @return [String,nil]
   def auto_destination= dest

data/lib/onstomp/version.rb

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

data/onstomp.gemspec

@@ -25,5 +25,4 @@ Gem::Specification.new do |s|
   s.add_development_dependency('simplecov', '>= 0.3.0')
   s.add_development_dependency('yard', '>= 0.6.0')
   s.add_development_dependency('rake')
-  s.add_development_dependency('bluecloth')
 end