frame_methods.rb in onstomp-1.0.1

- old
+ new

@@ -1,10 +1,26 @@
 # -*- encoding: utf-8 -*-
 
 # 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
   # @param [{#to_sym => #to_s}] headers additional headers to include in
   #   the frame
@@ -12,15 +28,42 @@
   # @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
+  # @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.
   # STOMP 1.0 and STOMP 1.1 connections support:
   # * :ack => 'auto'
@@ -48,143 +91,261 @@
   # @raise OnStomp::UnsupportedCommandError if the connection does not support
   #   SUBSCRIBE frames
   # @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
   # @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
+  # @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
   # @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
+  # @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
   # @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
+  # @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
   #   the frame
   # @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.
   #   @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
+  #   @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
 end