qpid_messaging 0.20.2 → 0.22.0

data/lib/qpid_messaging/encoding.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Licensed to the Apache Software Foundation (ASF) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -15,19 +15,19 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
 module Qpid
 
   module Messaging
 
     # Encodes the supplied content into the given message.
-    def self.encode content, message, encoding = nil
+    def self.encode content, message, encoding = nil # :nodoc:
       Cqpid::encode content, message.message_impl, encoding
     end
 
     # Decodes and returns the message's content.
-    def self.decode(message, content_type = nil)
+    def self.decode(message, content_type = nil) # :nodoc:
       content_type = message.content_type if content_type.nil?
 
       case content_type
@@ -42,7 +42,7 @@ module Qpid
 
     # Takes as input any type and converts anything that's a symbol
     # into a string.
-    def self.stringify(value)
+    def self.stringify(value) # :nodoc:
       # set the default value
       result = value
 

data/lib/qpid_messaging/message.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Licensed to the Apache Software Foundation (ASF) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -15,27 +15,26 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
 module Qpid
 
   module Messaging
 
     # A +Message+ represents an routable piece of information.
-    #
-    # The content for a message is automatically encoded and decoded.
-    #
     class Message
 
-      # Creates a new instance of +Message+.
+      # Creates a +Message+.
       #
       # ==== Options
       #
-      # * :content - The content.
+      # * +:content+ - the content
       #
       # ==== Examples
       #
+      #   # create a simple message and sends it
       #   message = Qpid::Messaging::Message.new :content => "This is a message."
+      #   sender.send message
       #
       def initialize(args = {})
         @message_impl = (args[:impl] if args[:impl]) || nil
@@ -49,15 +48,20 @@ module Qpid
         @message_impl
       end
 
-      # Sets the address to which replies should be sent for the +Message+.
+      # Sets the reply-to address.
+      #
+      # The address can either be an instance of Address or else and
+      # address string.
       #
       # ==== Options
       #
-      # * address - an instance of +Address+, or an address string
+      # * +address+ - the address
       #
       # ==== Examples
       #
+      #   # set replies using an Address
       #   msg.reply_to = Qpid:Messaging::Address.new "my-responses"
+      #   # set replies using an address string
       #   msg.reply_to = "my-feed/responses"
       #
       def reply_to=(address)
@@ -67,7 +71,6 @@ module Qpid
       end
 
       # Returns the reply to address for the +Message+.
-      #
       def reply_to
         address_impl = @message_impl.getReplyTo
         # only return an address if a reply to was specified
@@ -78,25 +81,15 @@ module Qpid
       #
       # ==== Options
       #
-      # * subject - the subject
-      #
-      # ==== Examples
-      #
-      #   msg.subject = "mysubject"
-      #
+      # * +subject+ - the subject
       def subject=(subject); @message_impl.setSubject subject; end
 
       # Returns the subject of the +Message+.
-      #
-      # ==== Options
-      #
-      #   puts "The subject is #{msg.subject}"
-      #
       def subject; @message_impl.getSubject; end
 
       # Sets the content type for the +Message+.
       #
-      # This should be set by the sending applicaton and indicates to
+      # This should be set by the sending application and indicates to the
       # recipients of the message how to interpret or decode the content.
       #
       # By default, only dictionaries and maps are automatically given a content
@@ -105,23 +98,17 @@ module Qpid
       #
       # ==== Options
       #
-      # * content_type - the content type.
-      #
-      def content_type=(content_type); @message_impl.setContentType content_type; end
-
-      # Returns the content type for the +Message+.
+      # * +content_type+ - the content type
       #
       # ==== Examples
       #
-      #   case msg.content_type
-      #     when "myapp/image"
-      #       ctl.handle_image msg
-      #       end
-      #     when "myapp/audio"
-      #       ctl.handle_audio msg
-      #       end
-      #   end
+      #   # send base64 encoded data in a mesage
+      #   msg = Qpid::Messaging::Message.new :content = "UXBpZCBSdWxlcyEK"
+      #   msg.content_type = "application/base64"
       #
+      def content_type=(content_type); @message_impl.setContentType content_type; end
+
+      # Returns the content type for the +Message+.
       def content_type; @message_impl.getContentType; end
 
       # Sets the message id.
@@ -131,16 +118,17 @@ module Qpid
       #
       # ==== Options
       #
-      # * id - the id
+      # * +id+ - the id
       #
       # ==== Examples
       #
+      #   # this example only works in Ruby >= 1.9, for 1.8 use a UUID library
+      #   require 'SecureRandom'
+      #   msg.message_id = SecureRandom.uuid
       #
       def message_id=(message_id); @message_impl.setMessageId message_id.to_s; end
 
       # Returns the message id.
-      #
-      # See +message_id=+ for details.
       def message_id; @message_impl.getMessageId; end
 
       # Sets the user id for the +Message+.
@@ -149,44 +137,38 @@ module Qpid
       # the connection itself, as the messaging infrastructure will verify
       # this.
       #
-      # See +Qpid::Messaging::Connection.authenticated_username+
+      # See Qpid::Messaging::Connection.authenticated_username
       #
       # *NOTE:* If the id is not a +String+ then the id is set using
       # the object's string representation.
       #
       # ==== Options
       #
-      # * id - the id
+      # * +id+ - the id
       #
       def user_id=(user_id); @message_impl.setUserId user_id; end
 
       # Returns the user id for the +Message+.
-      #
-      # See +user_id=+ for details.
-      #
       def user_id; @message_impl.getUserId; end
 
       # Sets the correlation id of the +Message+.
       #
       # The correlation id can be used as part of a protocol for message
-      # exchange patterns; e.g., a requestion-response pattern might require
+      # exchange patterns; e.g., a request-response pattern might require
       # the correlation id of the request and the response to match, or it
       # might use the message id of the request as the correlation id on
-      # the response
+      # the response.
       #
       # *NOTE:* If the id is not a +String+ then the id is setup using
       # the object's string representation.
       #
       # ==== Options
       #
-      # * id - the id
+      # * +id+ - the id
       #
       def correlation_id=(correlation_id); @message_impl.setCorrelationId correlation_id; end
 
       # Returns the correlation id of the +Message+.
-      #
-      # *NOTE:* See +correlation_id=+ for details.
-      #
       def correlation_id; @message_impl.getCorrelationId; end
 
       # Sets the priority of the +Message+.
@@ -200,19 +182,21 @@ module Qpid
       #
       # ==== Options
       #
-      # * priority - the priority
+      # * +priority+ - the priority
       #
       def priority=(priority); @message_impl.setPriority priority; end
 
       # Returns the priority for the +Message+.
-      #
       def priority; @message_impl.getPriority; end
 
       # Sets the time-to-live in milliseconds.
       #
+      # This can be used by the messaging infrastructure to discard messages
+      # that are no longer of relevance.
+      #
       # ==== Options
       #
-      # * duration - the number of milliseconds
+      # * +duration+ - the number of milliseconds
       #
       def ttl=(duration)
         if duration.is_a? Qpid::Messaging::Duration
@@ -229,16 +213,15 @@ module Qpid
       #
       # This is a hint to the messaging infrastructure that the message
       # should be persisted or otherwise stored. This helps to ensure
-      # that th emessage is not lost during to failures or a shutdown.
+      # that the message is not lost due to failures or a shutdown.
       #
       # ==== Options
       #
-      # * durable - the durability flag (def. false)
+      # * +durable+ - the durability flag (def. false)
       #
       def durable=(durable); @message_impl.setDurable durable; end
 
       # Returns the durability for the +Message+.
-      #
       def durable; @message_impl.getDurable; end
 
       # This is a hint to the messaging infrastructure that if de-duplication
@@ -247,17 +230,16 @@ module Qpid
       #
       # ==== Options
       #
-      # * redelivered - sets the redelivered state (def. false)
+      # * +redelivered+ - sets the redelivered state (def. false)
       #
       # ==== Examples
       #
-      #   # processed is an array of processed message ids
+      #   # processed is a collection of messages already received
       #   msg.redelivered = true if processed.include? msg.message_id
       #
       def redelivered=(redelivered); @message_impl.setRedelivered redelivered; end
 
       # Returns whether the +Message+ has been marked as redelivered.
-      #
       def redelivered; @message_impl.getRedelivered; end
 
       # Returns all named properties.
@@ -265,14 +247,13 @@ module Qpid
       # *NOTE:* It is recommended to use the []= method for
       # retrieving and setting properties. Using this method may
       # result in non-deterministic behavior.
-      #
       def properties; @message_impl.getProperties; end
 
       # Returns the value for the named property.
       #
       # ==== Options
       #
-      # * name - the property name
+      # * +name+ - the property name
       #
       # ==== Examples
       #
@@ -283,10 +264,21 @@ module Qpid
 
       # Assigns a value to the named property.
       #
+      # A property's name or value, if a symbol, will be converted to a string
+      # representation. However, you will still be able to access them using
+      # a symbol for the name.
+      #
       # ==== Options
       #
-      # * name - the property name
-      # * value - the property value
+      # * +name+ - the property name
+      # * +value+ - the property value
+      #
+      # ==== Examples
+      #
+      #   # set the signed attribute on a message and then retrieve it
+      #   msg[:signed] = true # sets "signed" => true
+      #   puts "It's signed" if msg["signed"] # outputs "It's signed"
+      #
       def []=(key, value)
         @message_impl.setProperty(key.to_s,
                                   Qpid::Messaging.stringify(value))
@@ -295,17 +287,19 @@ module Qpid
       # Sets the content for the +Message+.
       #
       # Content is automatically encoded for Array and Hash types. Other types
-      # need to set their own content types (via +content_type+) in order to
+      # need to set their own content types (via content_type) in order to
       # specify how recipients should process the content.
       #
       # ==== Options
       #
-      # * content - the content
+      # * +content+ - the content
       #
       # ==== Examples
       #
-      #   msg.content = "This is a simple message." # a simple message
-      #   msg.content = {:foo => :bar} # content is automatically encoded
+      #   # set a simple content for a message
+      #   msg.content = "This is a simple message."
+      #   # sets content that is automatically encoded
+      #   msg.content = {:foo => :bar}
       #
       def content=(content)
         content_type = nil
@@ -348,8 +342,7 @@ module Qpid
         @content
       end
 
-      # Returns the content's size.
-      #
+      # Returns the content's size in bytes.
       def content_size; @message_impl.getContentSize; end
 
     end

data/lib/qpid_messaging/receiver.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Licensed to the Apache Software Foundation (ASF) under one
 # or more contributor license agreements.  See the NOTICE file
 # distributed with this work for additional information
@@ -15,23 +15,32 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
 module Qpid
 
   module Messaging
 
-    # Receiver is the entity through which messages are received.
+    # +Receiver+ is the entity through which messages are received.
     #
-    # An instance of Receiver can only be created using an active (not
-    # previously closed) Session.
+    # An instance of +Receiver+ can only be created using an active (i.e., not
+    # previously closed) Session. See Qpid::Messaging::Session.create_receiver
+    # for more details.
     #
     # ==== Example
     #
+    #   # create a connection and a session
     #   conn     = Qpid::Messaging::Connection.new :url => "mybroker:5762"
     #   conn.open
     #   session  = conn.create_session
-    #   receiver = session.create_receiver "my-sender-queue"
+    #
+    #   # create a receiver that listens on the "updates" topic of "alerts"
+    #   receiver = session.create_receiver "alerts/updates"
+    #
+    #   # wait for an incoming message and process it
+    #   incoming = receiver.get Qpid::Messaging::Duration::FOREVER
+    #   process(incoming)
+    #
     class Receiver
 
       def initialize(session, receiver_impl) # :nodoc:
@@ -46,27 +55,24 @@ module Qpid
       # Retrieves a message from the local queue, or waits for up to
       # the duration specified for one to become available.
       #
-      # If a block is given, then it will be invaked after the next message
-      # is received or the call times out, passing in the message or nil
-      # respectively.
+      # If no message is received within the specified time then a
+      # MessagingException is raised.
       #
       # ==== Options
-      # * duration - the timeout to wait (def. Duration::FOREVER)
-      #
-      # ==== Examples
       #
-      #   msg = rcvr.get # Uses the default timeout of forever
+      # * duration - the timeout to wait
       #
-      #   msg = rcvr.get Qpid::Messaging::Duration::IMMEDIATE # returns a message or exits immediately
+      # ==== Examples
       #
-      #   # passes in a block to handle the received message
-      #   rcvr.get Qpid::Messaging::Duration::SECOND do |message|
-      #     if message.nil?
-      #       puts "No message was received."
-      #     else
-      #       puts "Received this message: #{message.content}"
-      #     end
+      #   # retrieves a message, also handles exceptions raised on no messages
+      #   begin
+      #     # checks for a message, returning immediately
+      #     msg = recv.get Qpid::Messaging::Duration::IMMEDIATE
+      #     puts "Received this message: #{message.content}"
+      #   rescue
+      #     puts "No messages available.
       #   end
+      #
       def get(duration = Qpid::Messaging::Duration::FOREVER)
         message_impl = @receiver_impl.get duration.duration_impl
         create_message_wrapper message_impl unless message_impl.nil?
@@ -75,33 +81,35 @@ module Qpid
       # Retrieves a message from the receiver's subscription, or waits
       # for up to the duration specified for one to become available.
       #
-      # If a block is given, then it will be invaked after the next message
-      # is received or the call times out, passing in the message or nil
-      # respectively.
+      # If no message is fetched within the specified time then a
+      # MessagingException is raised.
       #
       # ==== Options
+      #
       # * duration - the timeout to wait (def. Duration::FOREVER)
       #
       # ==== Examples
       #
-      #   msg = rcvr.fetch # Uses the default timeout of forever
-      #
-      #   msg = rcvr.fetch Qpid::Messaging::Duration::IMMEDIATE # returns a message or exits immediately
-      #
-      #   # passes in a block to handle the received message
-      #   rcvr.fetch Qpid::Messaging::Duration::SECOND do |message|
-      #     if message.nil?
-      #       puts "No message was received."
-      #     else
-      #       puts "Received this message: #{message.content}"
-      #     end
+      #   # retrieves a message, also handles exceptions raised on no messages
+      #   begin
+      #     # checks for a message, times out after one second
+      #     msg = recv.fetch Qpid::Messaging::Duration::SECOND
+      #     puts "Fetched this message: #{message.content}"
+      #   rescue
+      #     puts "No messages available.
       #   end
+      #
       def fetch(duration = Qpid::Messaging::Duration::FOREVER)
         message_impl = @receiver_impl.fetch duration.duration_impl
         create_message_wrapper message_impl unless message_impl.nil?
       end
 
-      # Sets the capacity for this +Receiver+.
+      # Sets the capacity.
+      #
+      # The capacity of a +Receiver+ is the number of Messages that can be
+      # pre-fetched from the broker and held locally. If capacity is 0 then
+      # messages will never be pre-fetched and all messages must instead be
+      # retrieved using #fetch.
       #
       # ==== Options
       #
@@ -109,63 +117,50 @@ module Qpid
       #
       # ==== Examples
       #
-      #   receiver.capacity = 50 # sets the incoming capacity to 50 messages
+      #   # create a receiver and give it a capacity of 50
+      #   recv = session.create_receiver "alerts/minor"
+      #   recv.capacity = 50
       #
       def capacity=(capacity); @receiver_impl.setCapacity capacity; end
 
       # Returns the capacity.
-      #
-      #
-      # The capacity is the numnber of incoming messages that can be held
-      # locally before being fetched.
-      #
-      # ==== Examples
-      #
-      #   puts "The receiver can hold #{rcv.capacity} messages."
-      #
       def capacity; @receiver_impl.getCapacity; end
 
-      # Returns the number of slots for receiving messages.
+      # Returns the number of messages locally held.
+      #
+      # The available is always 0 <= available <= capacity.
       #
-      # This differs from +capacity+ in that it is the available slots in
-      # the capacity for holding incoming messages, where available <= capacity.
+      # If the #capacity is set to 0 then available will always be 0.
       #
       # ==== Examples
       #
-      #   puts "You can receive #{rcv.available} messages before blocking."
+      #   # output the number of messages waiting while processing
+      #   loop do
+      #     puts "There are #{recv.available} messages pending..."
+      #     # wait forever (the default) for the next message
+      #     msg = recv.get
+      #     # process the message
+      #     dispatch_message msg
+      #   end
       #
       def available; @receiver_impl.getAvailable; end
 
       # Returns the number of messages that have been received and acknowledged
       # but whose acknowledgements have not been confirmed by the sender.
-      #
-      # ==== Examples
-      #
-      #   puts "You have #{rcv.unsettled} messages to be confirmed."
-      #
       def unsettled; @receiver_impl.getUnsettled; end
 
       # Closes this +Receiver+.
       #
-      # This does not affect the +Session+.
+      # This does not affect the owning Session or Connection.
       def close; @receiver_impl.close; end
 
-      # Returns whether the receiver is closed.
-      #
-      # ==== Examples
-      #
-      #   recv.close unless recv.closed?
-      #
+      # Returns whether the +Receiver+ is closed.
       def closed?; @receiver_impl.isClosed; end
 
       # Returns the name of this +Receiver+.
-      #
-      # ==== Examples
-      #
-      #   puts "Receiver: #{recv.name}"
       def name; @receiver_impl.getName; end
 
-      # Returns the Session for this +Receiver+.
+      # Returns the owning Session for this +Receiver+.
       def session; @session; end
 
       private