QPID-3727 - Applied patch from Darryl Pierce

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk/qpid@1227786 13f79535-47bb-0310-9956-ffa450edef68

5 files changed, 359 insertions, 88 deletions

diff --git a/cpp/bindings/qpid/ruby/lib/qpid/address.rb b/cpp/bindings/qpid/ruby/lib/qpid/address.rb
index 73b61bb1c7..266d8668d6 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid/address.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid/address.rb
@@ -38,75 +38,137 @@ module Qpid
     # Or they can be lists of values, where they are contained within square
     # brackets but still comma delimited, such as:
     #
-    # [value1,value2,value3]
+    #   [value1,value2,value3]
     #
     # The following are the list of supported options:
     #
-    # create:: Indicates if the address should be created; values are *always*,
-    #          *never*, *sender* or *reciever*.
+    # [:create]
+    #   Indicates if the address should be created; values are *always*,
+    #   *never*, *sender* or *reciever*.
     #
-    # assert:: Indicates whether or not to assert any specified node properties;
-    #          values are *always*, *never*, *sender* or *receiver*.
+    # [:assert]
+    #   Indicates whether or not to assert any specified node properties;
+    #   values are *always*, *never*, *sender* or *receiver*.
     #
-    # delete:: Indicates whether or not to delete the addressed node when a
-    #          sender or receiver is cancelled; values are *always*, *never*,
-    #          *sender* or *receiver*.
+    # [:delete]
+    #   Indicates whether or not to delete the addressed node when a sender
+    #   or receiver is cancelled; values are *always*, *never*, *sender* or
+    #   *receiver*.
     #
-    # node:: A nested map describing properties for the addressed node.
-    #        Properties are *type* (*topic* or *queue*), *durable* (a boolean),
-    #        *x-declare* (a nested map of amqp 0.10-specific options) and
-    #        *x-bindings*. (nested list which specifies a queue, exchange or
-    #        a binding key and arguments.
+    # [:node]
+    #   A nested map describing properties for the addressed node. Properties
+    #   are *type* (*topic* or *queue*), *durable* (a boolean), *x-declare*
+    #   (a nested map of amqp 0.10-specific options) and *x-bindings*. (nested
+    #   list which specifies a queue, exchange or a binding key and arguments.
     #
-    # link:: A nested map through which properties of the link can be specified;
-    #        properties are *durable*, *reliability*, *x-declare*, *x-subscribe*
-    #        and *x-bindings*.
+    # [:link]
+    #   A nested map through which properties of the link can be specified;
+    #   properties are *durable*, *reliability*, *x-declare*, *x-subscribe*
+    #   and *x-bindings*.
+    #
+    # [:mode]
+    #   (*For receivers only*) indicates whether the receiver should consume
+    #   or browse messages; values are *consume* (the default) and *browse*.
     #
-    # mode:: (*For receivers only*) indicates whether the receiver should consume
-    #        or browse messages; values are *consume* (the default) and *browse*.
     class Address
 
+      # Creates a new +Address+ object.
+      #
+      # ==== Options
+      #
+      # * name - The name for the +Address+.
+      # * subject - The subject for the +Address+
+      # * :create - See the class documentation.
+      # * :assert - See the class documentation.
+      # * :delete - See the class documentation.
+      # * :node   - See the class documentation.
+      # * :link   - See the class documentation.
+      # * :mode   - See the class documentation.
+      #
+      # ==== Examples
+      #
+      #   addr = Qpid::Messaging::Address.new "my-queue"
+      #   addr = Qpid::Messaging::Address.new "my-queue", "testing", :create => :always
+      #
       def initialize(name, subject, options = {}, _type = "", address_impl = nil)
         @address_impl = address_impl || Cqpid::Address.new(name, subject, convert_options(options), _type)
       end
 
-       def address_impl # :nodoc:
-         @address_impl
-       end
+      def address_impl # :nodoc:
+        @address_impl
+      end
 
-       # Returns the name.
+      # Returns the name for the +Address+.
+      #
+      # ==== Examples
+      #
+      #   puts "The address name is #{addr.name}."
+      #
       def name; @address_impl.getName; end
 
-      # Sets the name.
+      # Sets the name for the +Address+.
+      #
+      # ==== Examples
+      #
+      #   addr.name = "my-new-queue"
+      #
       def name=(name); @address_impl.setName name; end
 
-      # Returns the subject.
+      # Returns the subject for the +Address+.
+      #
+      # ==== Examples
+      #
+      #   puts "The subject is #{addr.subject}."
+      #
       def subject; @address_impl.getSubject; end
 
-      # Sets the subject.
+      # Sets the subject for the +Address+.
+      #
+      # ==== Examples
+      #
+      #   addr.subject = "testing"
+      #
       def subject=(subject); @address_impl.setSubject(subject); end
 
-      # Returns the type.
+      # Returns the type for the +Address+.
+      #
+      # ==== Examples
+      #
+      #   puts "The address is a #{address.address_type}."
+      #
       #---
       # We cannot use "type" since that clashes with the Ruby object.type
       # identifier.
-      def _type; @address_impl.getType; end
+      def address_type; @address_impl.getType; end
 
-      # Sets the type.
+      # Sets the type for the +Address+.
       #
-      # The type of the address determines how Sender and Receiver objects
+      # The type of the address determines how +Sender+ and +Receiver+ objects
       # are constructed for it. If no type is specified then it will be
       # determined by querying the broker.
-      def _type=(_type); @address_impl.setType(_type); end
+      #
+      # ===== Options
+      #
+      # * type - the address type
+      #
+      def address_type=(type); @address_impl.setType(type); end
 
       # Returns the options.
       def options; @address_impl.getOptions; end
 
       # Sets the options for the address.
-      # Any symbols are converted to strings.
-      def options=(options); @address_impl.setOptions(convert_options(options)); end
+      #
+      # *NOTE:* See the class documentation for more details on options.
+      #
+      # ==== Examples
+      #
+      #   addr.options = :create => :always
+      #
+      def options=(options = {}); @address_impl.setOptions(convert_options(options)); end
 
-      def to_s; @address_impl.str; end
+      def to_s # :nodoc:
+        @address_impl.str
+      end
 
       private
 
diff --git a/cpp/bindings/qpid/ruby/lib/qpid/connection.rb b/cpp/bindings/qpid/ruby/lib/qpid/connection.rb
index 37086c95ba..12669bc947 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid/connection.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid/connection.rb
@@ -26,6 +26,8 @@ module Qpid
     # Establishes a connection to a remote endpoint.
     class Connection
 
+      attr_reader :options # :nodoc:
+
       # Creates a connection object, but does not actually connect to
       # the specified location.
       #
@@ -64,8 +66,8 @@ module Qpid
       #
       def initialize(opts = {})
         @url = opts[:url] || "localhost"
-        @options = opts[:options] || {}
-        @connection_impl = opts[:impl] || Cqpid::Connection.new(@url, convert_options)
+        @options = convert_options(opts[:options] || {})
+        @connection_impl = opts[:impl] || Cqpid::Connection.new(@url, @options)
       end
 
       def connection_impl # :nodoc:
@@ -132,7 +134,7 @@ module Qpid
       def session name
         begin
           session_impl = @connection_impl.getSession name
-          Qpid::Messaging::Session.new session_impl if session_impl
+          Qpid::Messaging::Session.new self, session_impl if session_impl
         rescue
           raise Qpid::Messaging::SessionNameException.new "No such session: #{name}"
         end
@@ -141,29 +143,12 @@ module Qpid
       # Returns the username used to authenticate with the connection.
       def authenticated_username; @connection_impl.getAuthenticatedUsername if open?; end
 
-      # inherited from Handle
-
-      # Returns whether the underlying handle is valid; i.e., not null.
-      def valid?
-        @connection_impl.isValid
-      end
-
-      # Returns whether the underlying handle is null.
-      def null?
-        @connection_impl.isNull
-      end
-
-      # Swaps the underlying connection handle.
-      def swap connection
-        @connection_impl.swap connection.connection_impl
-      end
-
       private
 
-      def convert_options
+      def convert_options(options)
         result = {}
-        unless @options.nil? || @options.empty?
-          @options.each_pair {|key, value| result[key.to_s] = value.to_s}
+        unless options.nil? || options.empty?
+          options.each_pair {|key, value| result[key.to_s] = value.to_s}
         end
 
         return result
diff --git a/cpp/bindings/qpid/ruby/lib/qpid/duration.rb b/cpp/bindings/qpid/ruby/lib/qpid/duration.rb
index c1f44e9281..1544075d70 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid/duration.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid/duration.rb
@@ -33,14 +33,27 @@ module Qpid
     # :MINUTE :: 60,000ms
     class Duration
 
-      def initialize duration # :nodoc:
-        @duration_impl = Cqpid::Duration.new duration
+      # Creates a Duration with the specified length, in milliseconds.
+      def initialize length
+        @duration_impl = Cqpid::Duration.new length
       end
 
       def duration_impl # :nodoc:
         @duration_impl
       end
 
+      # Returns the period of time in milliseconds
+      #
+      # ==== Examples
+      #
+      #   duration = Qpid::Messaging::Duration.new :length => 5000
+      #   puts "Waiting #{duration.milliseconds} ms for a message."
+      #   msg = receiver.fetch duration
+      #
+      def milliseconds
+        @duration_impl.getMilliseconds
+      end
+
       def self.add_item(key, value) # :nodoc:
         @hash ||= {}
         @hash[key] = Duration.new value
diff --git a/cpp/bindings/qpid/ruby/lib/qpid/message.rb b/cpp/bindings/qpid/ruby/lib/qpid/message.rb
index 9b1b68c7c3..edef0ac2a0 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid/message.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid/message.rb
@@ -23,105 +23,306 @@ module Qpid
 
   module Messaging
 
-    # Message represents a message.
+    # A +Message+ represents an routable piece of information.
+    #
+    # The content for a message is automatically encoded and decoded.
+    #
     class Message
 
-      def initialize(args = {}, message_impl = nil)
-        @message_impl = message_impl
+      # Creates a new instance of +Message+.
+      #
+      # ==== Options
+      #
+      # * :content - The content.
+      #
+      # ==== Examples
+      #
+      #   message = Qpid::Messaging::Message.new :content => "This is a message."
+      #
+      def initialize(args = {})
+        @message_impl = (args[:impl] if args[:impl]) || nil
         @message_impl = Cqpid::Message.new if @message_impl.nil?
-        @message_impl.setContent args[:content].to_s if args[:content]
         @content = nil
+        args = {} if args.nil?
+        self.content = args[:content] if args[:content]
       end
 
       def message_impl # :nodoc:
         @message_impl
       end
 
-      # Assigns the reply to address.
-      # The address must be an instance of Address.
-      def reply_to=(address); @message_impl.setReplyTo address.address_impl; end
+      # Sets the address to which replies should be sent for the +Message+.
+      #
+      # *NOTE:* The address must be an instance of Address.
+      #
+      # ==== Options
+      #
+      # * address - an instance of +Address+
+      #
+      # ==== Examples
+      #
+      #   msg.reply_to = Qpid:Messaging::Address.new "my-responses"
+      #
+      def reply_to=(address)
+        raise ArgumentError, "Agument must be an Address" unless address.is_a? Qpid::Messaging::Address
+        @message_impl.setReplyTo address.address_impl
+      end
 
-      # Returns the reply to address for the message as an instance of +Address+.
+      # 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
         Qpid::Messaging::Address.new(nil, nil, nil, nil, address_impl) if address_impl
       end
 
-      # Sets the subject.
+      # Sets the subject for the +Message+.
+      #
+      # ==== Options
+      #
+      # * subject - the subject
+      #
+      # ==== Examples
+      #
+      #   msg.subject = "mysubject"
+      #
       def subject=(subject); @message_impl.setSubject subject; end
 
-      # Returns the subject.
+      # Returns the subject of the +Message+.
+      #
+      # ==== Options
+      #
+      #   puts "The subject is #{msg.subject}"
+      #
       def subject; @message_impl.getSubject; end
 
-      # Sets the content type.
+      # Sets the content type for the +Message+.
+      #
+      # This should be set by the sending applicaton and indicates to
+      # recipients of the message how to interpret or decode the content.
+      #
+      # By default, only dictionaries and maps are automatically given a content
+      # type. If this content type is replaced then retrieving the content will
+      # not behave correctly.
+      #
+      # ==== Options
+      #
+      # * content_type - the content type.
+      #
       def content_type=(content_type); @message_impl.setContentType content_type; end
 
-      # Returns the content type.
+      # Returns the content type for the +Message+.
+      #
+      # ==== Examples
+      #
+      #   case msg.content_type
+      #     when "myapp/image"
+      #       ctl.handle_image msg
+      #       end
+      #     when "myapp/audio"
+      #       ctl.handle_audio msg
+      #       end
+      #   end
+      #
       def content_type; @message_impl.getContentType; end
 
       # Sets the message id.
+      #
+      # *NOTE:* this field must be a UUID type currently. A non-UUID value will
+      # be converted to a zero UUID, though a blank ID will be left untouched.
+      #
+      # ==== Options
+      #
+      # * id - the id
+      #
+      # ==== Examples
+      #
+      #
       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.
+      # Sets the user id for the +Message+.
+      #
+      # This should in general be the user-id which was used when authenticating
+      # the connection itself, as the messaging infrastructure will verify
+      # this.
+      #
+      # 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
+      #
       def user_id=(user_id); @message_impl.setUserId user_id; end
 
-      # Returns the user id.
+      # Returns the user id for the +Message+.
+      #
+      # See +user_id=+ for details.
+      #
       def user_id; @message_impl.getUserId; end
 
-      # Sets the correlation id.
+      # 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
+      # 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
+      #
+      # *NOTE:* If the id is not a +String+ then the id is setup using
+      # the object's string representation.
+      #
+      # ==== Options
+      #
+      # * id - the id
+      #
       def correlation_id=(correlation_id); @message_impl.setCorrelationId correlation_id; end
 
-      # Returns the correlation id.
+      # Returns the correlation id of the +Message+.
+      #
+      # *NOTE:* See +correlation_id=+ for details.
+      #
       def correlation_id; @message_impl.getCorrelationId; end
 
-      # Sets the priority.
+      # Sets the priority of the +Message+.
+      #
+      # This may be used by the messaging infrastructure to prioritize
+      # delivery of messages with higher priority.
+      #
+      # *NOTE:* If the priority is not an integer type then it is set using
+      # the object's integer representation. If the integer value is greater
+      # than 8-bits then only the first 8-bits are used.
+      #
+      # ==== Options
+      #
+      # * priority - the priority
+      #
       def priority=(priority); @message_impl.setPriority priority; end
 
-      # Returns the priority.
+      # Returns the priority for the +Message+.
+      #
       def priority; @message_impl.getPriority; end
 
       # Sets the time-to-live in milliseconds.
-      def ttl=(duration); @message_impl.setTtl duration; end
+      #
+      # ==== Options
+      #
+      # * duration - the number of milliseconds
+      #
+      def ttl=(duration)
+        if duration.is_a? Qpid::Messaging::Duration
+          @message_impl.setTtl duration.duration_impl
+        else
+          @message_impl.setTtl Cqpid::Duration.new duration.to_i
+        end
+      end
 
       # Returns the time-to-live in milliseconds.
-      def ttl; @message_impl.getTtl; end
-
-      # Sets the durability.
+      def ttl; Qpid::Messaging::Duration.new @message_impl.getTtl.getMilliseconds; end
+
+      # Sets the durability of the +Message+.
+      #
+      # 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.
+      #
+      # ==== Options
+      #
+      # * durable - the durability flag (def. false)
+      #
       def durable=(durable); @message_impl.setDurable durable; end
 
-      # Returns the durability.
+      # Returns the durability for the +Message+.
+      #
       def durable; @message_impl.getDurable; end
 
-      # Allows marking the message as redelivered.
+      # This is a hint to the messaging infrastructure that if de-duplication
+      # is required, that this message should be examined to determine if it
+      # is a duplicate.
+      #
+      # ==== Options
+      #
+      # * redelivered - sets the redelivered state (def. false)
+      #
+      # ==== Examples
+      #
+      #   # processed is an array of processed message ids
+      #   msg.redelivered = true if processed.include? msg.message_id
+      #
       def redelivered=(redelivered); @message_impl.setRedelivered redelivered; end
 
-      # Returns if the message was redelivered.
+      # Returns whether the +Message+ has been marked as redelivered.
+      #
       def redelivered; @message_impl.getRedelivered; end
 
       # Returns all named properties.
-      # *NOTE:* It is recommended to use the +foo[key]+ method for
-      # retrieving properties.
+      #
+      # *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
+      #
+      # ==== Examples
+      #
+      #   # use of message properties to mark a message as digitally signed
+      #   verify(msg) if msg[:signed]
+      #
       def [](key); self.properties[key.to_s]; end
 
       # Assigns a value to the named property.
+      #
+      # *NOTE:* Both the key or the value may be a symbol, but they will
+      # both be converted to a +String+ for ease of transport.
+      #
+      # ==== Options
+      #
+      # * name - the property name
+      # * value - the property value
       def []=(key, value); @message_impl.setProperty(key.to_s, value.to_s); end
 
-      # Sets the content.
+      # 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
+      # specify how recipients should process the content.
+      #
+      # ==== Options
+      #
+      # * content - the content
+      #
+      # ==== Examples
+      #
+      #   msg.content = "This is a simple message." # a simple message
+      #   msg.content = {:foo => :bar} # content is automatically encoded
+      #
       def content=(content)
         content_type = nil
         @content = content
         case @content
         when Hash
           content_type = "amqp/map"
+          new_content  = {}
+          content.each_pair{|key, value| new_content[key.to_s] = value.to_s}
+          @content = new_content
         when Array
+          new_content  = []
           content_type = "amqp/list"
+          content.each {|element| new_content << element.to_s}
+          @content = new_content
         end
         if content_type.nil?
           @message_impl.setContent @content
@@ -130,7 +331,16 @@ module Qpid
         end
       end
 
-      # Returns the content.
+      # Returns the content of the +Message+.
+      #
+      # Content is automatically decoded based on the specified content type.
+      # If the content type is application-specific, then no decoding is
+      # performed and the content is returnedas a +String+ representation.
+      #
+      # For example, if an array of integers are sent, then the receiver will
+      # find the message content to be an array of String objects, where each
+      # String is a representation of the sent integer value.
+      #
       def content
         if @content.nil?
           @content = @message_impl.getContent
@@ -147,6 +357,7 @@ module Qpid
       end
 
       # Returns the content's size.
+      #
       def content_size; @message_impl.getContentSize; end
 
     end
diff --git a/cpp/bindings/qpid/ruby/lib/qpid/receiver.rb b/cpp/bindings/qpid/ruby/lib/qpid/receiver.rb
index 886364d397..100ee4ea76 100644
--- a/cpp/bindings/qpid/ruby/lib/qpid/receiver.rb
+++ b/cpp/bindings/qpid/ruby/lib/qpid/receiver.rb
@@ -166,7 +166,7 @@ module Qpid
       private
 
       def create_message_wrapper message_impl # :nodoc:
-        Qpid::Messaging::Message.new({}, message_impl)
+        Qpid::Messaging::Message.new(:impl => message_impl)
       end
 
     end