transaction.rb in stomper-1.0.0

- old
+ new

@@ -59,11 +59,11 @@
 
     # Creates a new Transaction instance.  The +client+ parameter
     # is an instance of Stomper::Client and is required so that the Transaction
     # instance has somewhere to forward +begin+, +ack+ and +abort+ methods
     # to.  If the +trans_id+ parameter is not specified, an id is automatically
-    # generated of the form "tx-{Time.now.to_f}".  This name can be accessed
+    # generated of the form +tx-<Time.now.to_f>+.  This name can be accessed
     # through the +id+ attribute and is used in naming the transaction to
     # the stomp broker.  If +block+ is given, the Transaction instance immediately
     # calls its perform method with the supplied +block+.
     def initialize(client, trans_id=nil, &block)
       @client = client
@@ -92,10 +92,13 @@
     # If you are using Transaction objects directly, and not relying on their
     # generation through Stomper::Client#transaction, be warned that this method
     # will raise a TransactionAborted exception if the +block+ evaluation fails.
     # This behavior allows for nesting transactions and ensuring that if a nested
     # transaction fails, so do all of its ancestors.
+    #
+    # @param [Proc] block A block of code that is evaluated as part of the transaction.
+    # @raise [TransactionAborted] raises an exception if the given block raises an exception
     def perform(&block) #:yields: transaction
       begin
         @client.begin(@id)
         if block.arity == 1
           yield self
@@ -122,11 +125,11 @@
     end
 
     # Similar to Stomper::Client#transaction, this method creates a new
     # Transaction object, nested inside of this one.  To prevent name
     # collisions, this method automatically generates a transaction id,
-    # if one is not specified, of the form "#{parent_transaction_id}-#{Time.now.to_f}.
+    # if one is not specified, of the form +<parent_transaction_id>-<Time.now.to_f>+.
     def transaction(transaction_id=nil,&block)
       # To get a transaction name guaranteed to not collide with this one
       # we will supply an explicit id to the constructor unless an id was
       # provided
       transaction_id ||= "#{@id}-#{Time.now.to_f}"
@@ -135,33 +138,35 @@
 
     # Wraps the Stomper::Client#send method, injecting a "transaction" header
     # into the +headers+ hash, thus informing the stomp broker that the message
     # generated here is part of this transaction.
     def send(destination, body, headers={})
-      headers['transaction'] = @id
-      @client.send(destination, body, headers)
+      @client.send(destination, body, headers.merge({:transaction => @id }))
     end
 
     # Wraps the Stomper::Client#ack method, injecting a "transaction" header
     # into the +headers+ hash, thus informing the stomp broker that the message
     # acknowledgement is part of this transaction.
     def ack(message_or_id, headers={})
-      headers['transaction'] = @id
-      @client.ack(message_or_id, headers)
+      @client.ack(message_or_id, headers.merge({ :transaction => @id }))
     end
 
     # Aborts this transaction if it has not already been committed or aborted.
     # Note that it does so by raising a TransactionAborted exception, allowing
     # the +abort+ call to force any ancestral transactions to also fail.
     #
-    # See also: commit, committed?, aborted?
+    # @see Transaction#commit
+    # @see Transaction#committed?
+    # @see Transaction#aborted?
     def abort
       raise TransactionAborted, "transaction '#{@id}' aborted explicitly" if _abort
     end
 
     # Commits this transaction unless it has already been committed or aborted.
     #
-    # See also: abort, committed?, aborted?
+    # @see Transaction#abort
+    # @see Transaction#committed?
+    # @see Transaction#aborted?
     def commit
       # Guard against sending multiple commit messages to the server for a
       # single transaction.
       @client.commit(@id) unless committed? || aborted?
       @committed = true