qpid_messaging 0.20.2 → 0.22.0

data/lib/qpid_messaging/address.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,7 +15,7 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
 module Qpid
 
@@ -24,13 +24,17 @@ module Qpid
     # Address represents an address to which messages can be sent or from
     # which they can be received.
     #
-    # An Address can be described using the following pattern:
+    # == The +Address+ String
+    #
+    # An +Address+ can be described using the following pattern:
     #
     # <address> [ / <subject> ] ; [ { <key> : <value> , ... } ]
     #
     # where *address* is a simple name and *subject* is a subject or subject
     # pattern.
     #
+    # === Options
+    #
     # The options, enclosed in curly braces, are key:value pairs delimited by
     # a comma. The values can be nested maps also enclosed in curly braces.
     # Or they can be lists of values, where they are contained within square
@@ -40,44 +44,45 @@ module Qpid
     #
     # The following are the list of supported options:
     #
-    # [:create]
+    # [create]
     #   Indicates if the address should be created; values are *always*,
     #   *never*, *sender* or *reciever*.
     #
-    # [:assert]
+    # [assert]
     #   Indicates whether or not to assert any specified node properties;
     #   values are *always*, *never*, *sender* or *receiver*.
     #
-    # [:delete]
+    # [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]
+    # [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.
+    #   (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]
+    # [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]
+    # [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 from an address string.
+      # Creates a new +Address+ from an address string.
       #
-      # ==== Options
+      # ==== Attributes
       #
-      # * address - the address string
+      # * +address+ - the address string
       #
       # ==== Examples
       #
+      #   # create a new address for a queue named "my-queue" that will
+      #   # be created if it doesn't already exist
       #   addr = Qpid::Messaging::Address.new "my-queue;{create:always}"
       #
       def initialize(address, address_impl = nil)
@@ -92,7 +97,10 @@ module Qpid
       #
       # ==== Examples
       #
-      #   puts "The address name is #{addr.name}."
+      #    # display the name of the address
+      #    addr = Qpid::Messaging::Address.new "foo;{create:always}"
+      #    # outputs the word 'foo'
+      #    puts addr.name
       #
       def name; @address_impl.getName; end
 
@@ -100,6 +108,9 @@ module Qpid
       #
       # ==== Examples
       #
+      #   # create a new address with the name "my-queue"
+      #   addr = Qpid::Messaging::Address.new "my-queue/my-subject;{create:always}"
+      #   # changes the name to "my-new-queue"
       #   addr.name = "my-new-queue"
       #
       def name=(name); @address_impl.setName name; end
@@ -108,7 +119,8 @@ module Qpid
       #
       # ==== Examples
       #
-      #   puts "The subject is #{addr.subject}."
+      #   # creates a new address with the subject "bar"
+      #   addr = Qpid::Messaging::Address.new "my-queue/bar;{create:always}"
       #
       def subject; @address_impl.getSubject; end
 
@@ -116,30 +128,40 @@ module Qpid
       #
       # ==== Examples
       #
-      #   addr.subject = "testing"
+      #   # creates an address with the subject "example"
+      #   addr = Qpid::Messaging::Address.new "my-queue/example;{create:always}"
+      #   # changes the subject to "test"
+      #   addr.subject = "test"
       #
       def subject=(subject); @address_impl.setSubject(subject); end
 
       # 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 address_type; @address_impl.getType; end
 
       # Sets the type for the +Address+.
       #
       # 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.
+      # are constructed for it. It also affects how a reply-to address is
+      # encoded.
+      #
+      # If no type is specified then it will be determined by querying the
+      # broker. Explicitly setting the type prevents this.
+      #
+      # Values are either *queue* or *topic*.
+      #
+      # ==== Options
+      #
+      # * +type+ - the address type
       #
-      # ===== Options
+      # ==== Examples
       #
-      # * type - the address type
+      #   # creates an queue address
+      #   addr = Qpid::Messaging::Address.new "my-queue;{create:always}"
+      #   addr.address_type = "queue"
       #
       def address_type=(type); @address_impl.setType(type); end
 
@@ -153,6 +175,7 @@ module Qpid
       # ==== Examples
       #
       #   addr.options = :create => :always
+      #   addr.options = :create => :always, :delete => :always
       #
       def options=(options = {}); @address_impl.setOptions(convert_options(options)); end
 

data/lib/qpid_messaging/connection.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,56 +15,59 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
 module Qpid
 
   module Messaging
 
-    # Establishes a connection to a remote endpoint.
+    # A +Connection+ represents a network connection to a remote endpoint.
     class Connection
 
       attr_reader :options # :nodoc:
 
-      # Creates a connection object, but does not actually connect to
-      # the specified location.
+      # Creates a connection object. Raises a MessagingError if an invalid
+      # connection option is used.
       #
-      # ==== Options
+      # == Options
       #
-      #   :url - the URL for the broker (def. +"localhost"+)
-      #   :options - connection options (def. +{}+)
+      # * +:url+ - the URL for the broker
+      # * +:options+ - connection options
       #
-      # ==== Controlling Reconnect Behavior
+      # == Controlling Reconnect Behavior
       #
       # The following connection options can be used to configure
       # the reconnection behavior for this connection.
       #
-      # * :username
-      # * :password
-      # * :heartbeat
-      # * :tcp_nodelay
-      # * :sasl_mechanism
-      # * :sasl_service
-      # * :sasl_min_ssf
-      # * :sasl_max_ssf
-      # * :transport
-      # * :reconnect - +true+ or +false+; indicates wehtehr to attempt reconnections
-      # * :reconnect_timeout - the number of seconds to attempt reconnecting
-      # * :reconnect_limit - the number of retries before reporting failure
-      # * :reconnect_interval_min - initial delay, in seconds, before attempting a reconnection
-      # * :reconnect_interval_max - number of seconds to wait before additional reconnect attempts
-      # * :reconnect_interval - shorthand for setting both min and max values
-      # * :reconnect_urls - a list of alternate URLs to use for reconnection attempts
-      #
-      # ==== Examples
-      #
+      # * +:username+ - the authentication username
+      # * +:password+ - the authentication password
+      # * +:heartbeat+
+      # * +:tcp_nodelay+
+      # * +:sasl_mechanism+
+      # * +:sasl_service+
+      # * +:sasl_min_ssf+
+      # * +:sasl_max_ssf+
+      # * +:transport+
+      # * +:reconnect+ - indicates whether to attempt reconnections
+      # * +:reconnect_timeout+ - the number of seconds to attempt reconnecting
+      # * +:reconnect_limit+ - the number of retries before reporting failure
+      # * +:reconnect_interval_min+ - initial delay, in seconds, before attempting a reconnection
+      # * +:reconnect_interval_max+ - number of seconds to wait before additional reconnect attempts
+      # * +:reconnect_interval+ - shorthand for setting both min and max values
+      # * +:reconnect_urls+ - a list of alternate URLs to use for reconnection attempts
+      #
+      # == Examples
+      #
+      #   # creates a connection to the broker running local *localhost*
       #   conn = Qpid::Messaging::Connnection.new
+      #   # creates a connection to *broker1.domain.com* on port *5672*
       #   conn = Qpid::Messaging::Connection.new :url => "amqp:tcp:broker1.domain.com:5672"
+      #   # creates a connection to localhost with the specified authentication credentials
       #   conn = Qpid::Messaging::Connection.new :options => {:username => "login", :password => "password"}
       #
       def initialize(opts = {})
         @url = opts[:url] || "localhost"
-        @options = convert_options(opts[:options] || {})
+        @options = Qpid::Messaging.stringify(opts[:options] || {})
         @connection_impl = opts[:impl] || Cqpid::Connection.new(@url, @options)
       end
 
@@ -74,8 +77,9 @@ module Qpid
 
       # Establishes the connection.
       #
-      # ==== Examples
+      # == Examples
       #
+      #   # open a connection if it's not already open
       #   conn.open unless conn.open?
       #
       def open
@@ -84,25 +88,34 @@ module Qpid
 
       # Reports whether the connection is open.
       #
-      # ==== Examples
+      # == Examples
       #
+      #   # close the connection if it's not already closed
       #   conn.close if conn.open?
       #
       def open?; true && !@connection_impl.nil? && @connection_impl.isOpen; end
 
       # Closes the connection.
+      #
+      # == Examples
+      #
+      #   # close a connection
+      #   conn.close
+      #
       def close; @connection_impl.close; end
 
       # Creates a new session.
       #
-      # ==== Arguments
+      # == Arguments
       #
-      # * :name - specifies the name for this session
-      # * :transactional - if +true+ then a creates a transaction session (def. +false+)
+      # * +:name+ - specifies the name for this session
+      # * +:transactional+ - if +true+ then a creates a transaction session (def. +false+)
       #
-      # ==== Examples
+      # == Examples
       #
+      #   # create a session named 'session1'
       #   session = conn.create_session :name => "session1"
+      #   # create a transactional session
       #   session = conn.create_session :transaction => true
       #
       def create_session(args = {})
@@ -119,26 +132,42 @@ module Qpid
         end
       end
 
-      # Returns a session for the specified session name.
+      # Returns a Session with the given name. Raises an exception if no
+      # session with the given name exists.
+      #
+      # == Options
       #
-      # ==== Examples
+      # * +name+ - the existing session's name
       #
+      # == Examples
+      #
+      #   # retrieve a session named 'mysession' from the current connection
+      #   name = "my-session"
+      #   # if no such session exists then catchh the exception raised
       #   begin
-      #     session = conn.session "mysession"
-      #   rescue SessionNameException => error
-      #      puts "No such session."
+      #     session = conn.session name
+      #   rescue MessagingException => error
+      #      puts "No such session: #{name}."
       #   end
       #
       def session name
-        begin
-          session_impl = @connection_impl.getSession name
-          Qpid::Messaging::Session.new self, session_impl if session_impl
-        rescue
-          raise Qpid::Messaging::SessionNameException.new "No such session: #{name}"
-        end
+        session_impl = @connection_impl.getSession name
+        Qpid::Messaging::Session.new self, session_impl if session_impl
       end
 
       # Returns the username used to authenticate with the connection.
+      #
+      # If the connection did not user authentication credentials, then the
+      # username returned is "anonymous".
+      #
+      # == Examples
+      #
+      #   # create a new connection for user "qpiduser"
+      #   conn = Qpid::Messaging::Connection.new :username => "qpiduser"
+      #   conn.open
+      #   # displays the authenticate username
+      #   puts "Connected as #{conn.authenticated_username}" # should say 'qpiduser'
+      #
       def authenticated_username; @connection_impl.getAuthenticatedUsername if open?; end
 
       private

data/lib/qpid_messaging/duration.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,7 +15,7 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
 module Qpid
 
@@ -23,19 +23,21 @@ module Qpid
 
     # A Duration represents a period of time in milliseconds
     #
-    # It defines the following named values as symbols:
+    # == Named Durations
+    #
+    # The following named +Durations+ are available as symbols:
     #
-    # [:FOREVER]
+    # [FOREVER]
     #   The maximum integer value for the platform. Effectively this will wait
     #   forever.
     #
-    # [:IMMEDIATE]
+    # [IMMEDIATE]
     #   An alias for 0 milliseconds.
     #
-    # [:SECOND]
+    # [SECOND]
     #   An alias for 1,000 milliseconds.
     #
-    # [:MINUTE]
+    # [MINUTE]
     #   And alias for 60,000 millisecons.
     #
     class Duration
@@ -44,12 +46,13 @@ module Qpid
       #
       # ==== Options
       #
-      # * length - The duration in milliseconds.
+      # * +length+ - The duration in +milliseconds+.
       #
       # ==== Examples
       #
-      #   # Wait up to 10 seconds for an incoming message
-      #   receiver.get Qpid::Messaging::Duration.new 10000
+      #   # creates a duration of 15 seconds
+      #   # REMEMBER: Duration deals in milliseconds
+      #   delay = Qpid::Messaging::Duration.new 15000
       #
       def initialize length
         @duration_impl = Cqpid::Duration.new length
@@ -59,18 +62,50 @@ module Qpid
         @duration_impl
       end
 
-      # Returns the period of time in milliseconds
+      # 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
+      #   # doubling growth in waiting for messages in a loop
+      #   do loop
+      #     set the base duration waiting length
+      #     timeout = Qpid::Messaging::Duration::SECOND
+      #     msg = nil
+      #     # loop until we receive a message
+      #     while msg.nil?
+      #       puts "Waiting #{timeout.milliseconds}ms"
+      #       msg = recv.get timeout
+      #       # if nothing was received, double the duration
+      #       if msg.nil?
+      #         # double out timeout
+      #         timeout = timeout * 2
+      #       else
+      #         # do something with the message
+      #         puts "Received: #{msg.content}"
+      #       end
+      #     end
+      #   end
       #
       def milliseconds
         @duration_impl.getMilliseconds
       end
 
+      # Multiplies the duration of the +Duration+ and returns a new instance.
+      #
+      # Raises exceptions on a negative factor. Returns
+      # Qpid::Messaging::Duration::IMMEDIATE when the factor is 0.
+      #
+      # ==== Examples
+      #
+      #   # return a duration that is 2 minutes (120,000 ms)
+      #   twominutes = Qpid::Messaging::Duration::MINUTE * 2
+      #
+      def *(factor)
+        raise TypeError.new "Factors must be non-zero positive values" if factor < 0
+        return Qpid::Messaging::Duration::IMMEDIATE if factor.zero?
+        Qpid::Messaging::Duration.new((self.milliseconds * factor).floor)
+      end
+
       def self.add_item(key, value) # :nodoc:
         @hash ||= {}
         @hash[key] = Duration.new value