qpid_messaging 0.20.2 → 0.22.0

data/lib/qpid_messaging/sender.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,39 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
 module Qpid
 
   module Messaging
 
-    # Sender is the entity through which messages sent.
+    # +Sender+ is the entity through which messages are sent.
     #
-    # An instance of Sender can only be created using an active (not previously
-    # closed) Session.
+    # An instance of +Sender+ can only be created using an active (not previously
+    # closed) Session. See Qpid::Messaging::Session.create_sender for more details.
     #
     # ==== Examples
     #
-    #   conn    = Qpid::Messaging::Connection.new :url => "mybroker:5762"
+    #   # create a connection
+    #   conn = Qpid::Messaging::Connection.new "mybroker:5672"
     #   conn.open
-    #   session = conn.create_session
-    #   sender  = session.create_session "my-sender-queue;{create:always}"
+    #
+    #   if conn.open?
+    #
+    #     # create a session
+    #     session = conn.create_session
+    #
+    #     # create a sender that posts messages to the "updates" queue
+    #     sender = session.create_sender "updates;{create:always}
+    #
+    #     # begin sending updates
+    #     loop do
+    #       # wait for the next event content then send it
+    #       content = wait_for_event
+    #       sender.send Qpid::Messaging::Message.new :content => content
+    #     end
+    #   end
+    #
     class Sender
 
       def initialize(session, sender_impl) # :nodoc:
@@ -43,15 +59,13 @@ module Qpid
         @sender_impl
       end
 
-      # Sends a message.
-      #
-      # If a block is given, then it will be invoked after the message
-      # is sent.
+      # Sends a message, optionally blocking until the message is received
+      # by the broker.
       #
       # ==== Options
       #
-      # * message - The message to send.
-      # * :sync - See note below on synching.
+      # * +message+ - The message to send.
+      # * +:sync+ - Block until received. See note below on synching.
       #
       # ==== Synching
       #
@@ -61,9 +75,13 @@ module Qpid
       #
       # ==== Examples
       #
-      #   sender.send message do |message|
-      #     puts "Message sent: #{message.content}"
-      #   end
+      #   # send a message
+      #   outgoing = Qpid::Messaging::Message.new :content => content
+      #   sender.send outgoing
+      #
+      #   # send a message, wait for confirmation from the broker
+      #   outgoing = Qpid::Messaging::Message.new :content => content
+      #   sender.send outgoing, :sync => true
       #
       def send(message, args = {}, &block)
         sync = args[:sync] || false
@@ -73,52 +91,27 @@ module Qpid
 
       # Closes this +Sender+.
       #
-      # This does not affect the +Session+.
+      # This does not affect the owning Session or Connection.
       def close; @sender_impl.close; end
 
       # Returns the human-readable name for this +Sender+.
-      #
-      # ==== Examples
-      #
-      #   puts "Sender: #{sender.name}"
-      #
       def name; @sender_impl.getName; end
 
       # Sets the capacity for this +Sender+.
       #
       # The capacity is the number of outgoing messages that can be held
-      # pending confirmation or receipt by the broker.
+      # pending confirmation of receipt by the broker.
       #
       # ==== Options
       #
-      # * capacity - the capacity
-      #
-      # ==== Examples
-      #
-      #   sender.capacity = 50 # sets the outgoing capacity to 50 messages
-      #
+      # * +capacity+ - the capacity
       def capacity=(capacity); @sender_impl.setCapacity capacity; end
 
       # Returns the capacity.
-      #
-      # The capacity is the total number of outgoing messages that can be
-      # sent before a called to +send+ begins to block by default.
-      #
-      # ==== Examples
-      #
-      #   puts "You can send a maximum of #{sender.capacity} messages."
-      #
       def capacity; @sender_impl.getCapacity; end
 
       # Returns the number of messages sent that are pending receipt
       # confirmation by the broker.
-      #
-      # ==== Examples
-      #
-      #   if sender.unsettled > 0
-      #     puts "There are #{sender.unsettled} messages pending."
-      #   end
-      #
       def unsettled; @sender_impl.getUnsettled; end
 
       # Returns the available slots for sending messages.
@@ -127,21 +120,11 @@ module Qpid
       # the senders capacity for holding outgoing messages. The difference
       # between capacity and available is the number of messages that
       # have not been delivered yet.
-      #
-      # ==== Examples
-      #
-      #   puts "You can send #{sender.available} messages before blocking."
-      #
       def available
         @sender_impl.getAvailable
       end
 
-      # Returns the +Session+ for this sender.
-      #
-      # ==== Examples
-      #
-      #   recv.session.close if done
-      #
+      # Returns the Session for this sender.
       def session; @session; end
 
     end

data/lib/qpid_messaging/session.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,44 +15,41 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
 module Qpid
 
   module Messaging
 
-    # A Session represents a distinct conversation between end points.
+    # A +Session+ represents a distinct conversation between end points. They are
+    # created from an active (i.e., not closed) Connection.
+    #
+    # A +Session+ is used to acknowledge individual or all messages that have
+    # passed through it
     class Session
 
       def initialize(connection, session) # :nodoc:
         @connection   = connection
         @session_impl = session
-        @senders      = Hash.new
-        @receivers    = Hash.new
       end
 
       def session_impl # :nodoc:
         @session_impl
       end
 
-      # Returns the +Connection+ associated with this session.
+      # Returns the Connection associated with this session.
       def connection
         @connection
       end
 
       # Creates a new endpoint for sending messages.
       #
-      # The +address+ can either be an instance +Address+ or else a
-      # string that describes an address endpoint.
+      # The address can either be an instance Address or else an
+      # address string.
       #
       # ==== Arguments
       #
-      # * +address+ The end point address.
-      #
-      # ==== Examples
-      #
-      #   sender = session.create_sender "my-queue;{create:always}"
-      #
+      # * +address+ - the end point address.
       def create_sender(address)
         _address = address
 
@@ -63,43 +60,28 @@ module Qpid
         sender_impl = @session_impl.createSender(_address)
         sender_name = sender_impl.getName
 
-        @senders[sender_name] = Qpid::Messaging::Sender.new(self, sender_impl)
-
-        @senders[sender_name]
+        Qpid::Messaging::Sender.new(self, sender_impl)
       end
 
-      # Retrieves the +Sender+ with the specified name.
+      # Retrieves the Sender with the specified name.
       #
-      # The +Sender+ must have been previously created using
-      # the +create_sender+ method.
+      # Raises an exception if no such Sender exists.
       #
       # ==== Arguments
       #
-      # * +name+ The +Sender+ name.
-      #
-      # ==== Examples
-      #
-      #   sender = session.sender "my-queue"
-      #
+      # * +name+ - the name of the Sender
       def sender(name)
-        raise Qpid::Messaging::KeyError, "No such sender: #{name}" unless @senders.has_key? name
-
-        @senders[name]
+        Qpid::Messaging::Sender.new self, @session_impl.getSender(name)
       end
 
       # Creates a new endpoint for receiving messages.
       #
-      # The +address+ can either be an instance +Address+ or else a
-      # string that describes an address endpoint.
+      # The +address+ can either be an instance Address or else an
+      # address string.
       #
       # ==== Arguments
       #
-      # * +address+ The end point address.
-      #
-      # ==== Examples
-      #
-      #   receiver = session.create_receiver "my-queue"
-      #
+      # * +address+ - the end point address.
       def create_receiver(address)
         result        = nil
         receiver_impl = nil
@@ -111,36 +93,24 @@ module Qpid
           receiver_impl = @session_impl.createReceiver(address)
         end
 
-        receiver_name = receiver_impl.getName
-
-        @receivers[receiver_name] = Qpid::Messaging::Receiver.new self, receiver_impl
-
-        @receivers[receiver_name]
+        Qpid::Messaging::Receiver.new self, receiver_impl
       end
 
-      # Retrieves the +Receiver+ with the specified name.
-      #
-      # The +Receiver+ must have been previously created using
-      # the +create_receiver+ method.
+      # Retrieves the +Receiver+ with the specified name, or nil if no such
+      # Receiver exists.
       #
       # ==== Arguments
       #
-      # * +name+ The +Receiver+ name.
-      #
-      # ==== Examples
-      #
-      #   receiver = session.receiver "my-queue"
-      #
+      # * +name+ - the name of the Receiver
       def receiver(name)
-        raise Qpid::Messaging::KeyError, "No such receiver: #{name}" unless @receivers.has_key? name
-
-        @receivers[name]
+        Qpid::Messaging::Receiver.new self, @session_impl.getReceiver(name)
       end
 
       # Closes the +Session+ and all associated +Sender+ and +Receiver+ instances.
       #
-      # NOTE: All +Session+ instances for a +Connection+ are closed when the
-      # +Connection+ is closed.
+      # *NOTE:* All +Session+ instances for a Connection are closed when the
+      # Connection is closed. But closing a +Session+ does not affect the
+      # owning Connection.
       def close; @session_impl.close; end
 
       # Commits any pending transactions for a transactional session.
@@ -154,21 +124,30 @@ module Qpid
       #
       # ==== Arguments
       #
-      # * :message - if specified, then only the +Message+ specified is acknowledged
-      # * :sync - if true then the call will block until processed by the server (def. false)
+      # * +options+ - the set of options
+      #
+      # ==== Options
+      #
+      # * :message - if specified, then only that Message is acknowledged
+      # * :sync - if true, the call will block until processed by the broker
       #
       # ==== Examples
       #
-      #   session.acknowledge                     # acknowledges all received messages
-      #   session.acknowledge :message => message # acknowledge one message
-      #   session.acknowledge :sync => true       # blocks until the call completes
+      #   # acknowledge all received messages
+      #   session.acknowledge
+      #
+      #   # acknowledge a single message
+      #   session.acknowledge :message => message
+      #
+      #   # acknowledge all messages, wait until the call finishes
+      #   session.acknowledge :sync => true
       #
       #--
       # TODO: Add an optional block to be used for blocking calls.
       #++
-      def acknowledge(args = {})
-        sync = args[:sync] || false
-        message = args[:message] if args[:message]
+      def acknowledge(options = {})
+        sync = options[:sync] || false
+        message = options[:message] if options[:message]
 
         unless message.nil?
           @session_impl.acknowledge message.message_impl, sync
@@ -189,11 +168,15 @@ module Qpid
       # NOTE: A message connot be released once it has been acknowled.
       def release(message); @session_impl.release message.message_impl; end
 
-      # Requests synchronization with the server.
+      # Requests synchronization with the broker.
       #
       # ==== Arguments
       #
-      # * :block - if true then the call blocks until the server acknowledges it (def. false)
+      # * +options+ - the list of options
+      #
+      # ==== Options
+      #
+      # * +:block+ - if true, the call blocks until the broker acknowledges it
       #
       #--
       # TODO: Add an optional block to be used for blocking calls.
@@ -204,26 +187,43 @@ module Qpid
       end
 
       # Returns the total number of receivable messages, and messages already
-      # received, by +Receiver+ instances associated with this +Session+.
+      # received, by Receiver instances associated with this +Session+.
       def receivable; @session_impl.getReceivable; end
 
-      # Returns the number of messages that have been acknowledged by this session
-      # whose acknowledgements have not been confirmed as processed by the server.
+      # Returns the number of messages that have been acknowledged by this
+      # +Session+ whose acknowledgements have not been confirmed as processed
+      # by the broker.
       def unsettled_acks; @session_impl.getUnsettledAcks; end
 
-      # Fetches the +Receiver+ for the next message.
+      # Fetches the next Receiver with a message pending. Waits the specified
+      # number of milliseconds before timing out.
+      #
+      # For a Receiver to be returned, it must have a capacity > 0 and have
+      # Messages locally queued.
+      #
+      # If no Receiver is found within the time out period, then a MessageError
+      # is raised.
       #
       # ==== Arguments
       #
-      # * timeout - time to wait for a +Receiver+ before timing out
+      # * +timeout+ - the duration
       #
       # ==== Examples
       #
-      #   recv = session.next_receiver # wait forever for the next +Receiver+
-      #   # execute a block on the next receiver
-      #   session.next_receiver do |recv|
-      #     msg = recv.get
-      #     puts "Received message: #{msg.content}"
+      #   loop do
+      #
+      #     begin
+      #       # wait a maximum of one minute for the next receiver to be ready
+      #       recv = session.next_receiver Qpid::Messaging::Duration::MINUTE
+      #
+      #       # get and dispatch the message
+      #       msg = recv.get
+      #       dispatch_message msg
+      #
+      #     rescue
+      #       puts "No receivers were returned"
+      #     end
+      #
       #   end
       def next_receiver(timeout = Qpid::Messaging::Duration::FOREVER, &block)
         receiver_impl = @session_impl.nextReceiver(timeout.duration_impl)
@@ -237,10 +237,6 @@ module Qpid
       end
 
       # Returns true if there were exceptions on this session.
-      #
-      # ==== Examples
-      #
-      #   puts "There were session errors." if @session.errors?
       def errors?; @session_impl.hasError; end
 
       # If the +Session+ has been rendered invalid due to some exception,
@@ -250,6 +246,7 @@ module Qpid
       #
       # ==== Examples
       #
+      #   # show any errors that occurred during the Session
       #   if @session.errors?
       #     begin
       #       @session.errors

metadata

@@ -1,96 +1,86 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: qpid_messaging
-version: !ruby/object:Gem::Version
-  version: 0.20.2
+version: !ruby/object:Gem::Version 
+  hash: 71
   prerelease: 
+  segments: 
+  - 0
+  - 22
+  - 0
+  version: 0.22.0
 platform: ruby
-authors:
+authors: 
 - Apache Qpid Project
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-03-07 00:00:00.000000000 Z
+
+date: 2013-06-18 00:00:00 Z
 dependencies: []
+
 description: Qpid is an enterprise messaging framework.
 email: dev@qpid.apache.org
 executables: []
-extensions:
+
+extensions: 
 - ext/cqpid/extconf.rb
-extra_rdoc_files:
-- README.rdoc
-files:
+extra_rdoc_files: []
+
+files: 
 - LICENSE
+- ChangeLog
 - README.rdoc
-- Rakefile
 - TODO
 - lib/qpid_messaging.rb
-- lib/qpid_messaging/address.rb
-- lib/qpid_messaging/connection.rb
 - lib/qpid_messaging/duration.rb
-- lib/qpid_messaging/encoding.rb
-- lib/qpid_messaging/errors.rb
-- lib/qpid_messaging/message.rb
 - lib/qpid_messaging/receiver.rb
-- lib/qpid_messaging/sender.rb
 - lib/qpid_messaging/session.rb
-- lib/qpid_messaging/version.rb
-- examples/client.rb
-- examples/drain.rb
+- lib/qpid_messaging/connection.rb
+- lib/qpid_messaging/message.rb
+- lib/qpid_messaging/address.rb
+- lib/qpid_messaging/encoding.rb
+- lib/qpid_messaging/sender.rb
+- ext/cqpid/cqpid.cpp
+- ext/cqpid/extconf.rb
+- examples/spout.rb
+- examples/server.rb
 - examples/hello_world.rb
 - examples/map_receiver.rb
 - examples/map_sender.rb
-- examples/server.rb
-- examples/spout.rb
-- ext/cqpid/cqpid.cpp
-- ext/cqpid/extconf.rb
-- features/closing_a_connection.feature
-- features/closing_a_session.feature
-- features/connecting_to_a_broker.feature
-- features/creating_a_receiver.feature
-- features/creating_a_sender.feature
-- features/creating_a_session.feature
-- features/getting_the_connections_authenticated_username.feature
-- features/receiving_a_message.feature
-- features/sending_a_message.feature
-- features/session_returns_its_connection.feature
-- features/sessions_have_names.feature
-- features/step_definitions/address_steps.rb
-- features/step_definitions/connection_steps.rb
-- features/step_definitions/receiver_steps.rb
-- features/step_definitions/sender_steps.rb
-- features/step_definitions/session_steps.rb
-- features/support/env.rb
-- spec/qpid_messaging/address_spec.rb
-- spec/qpid_messaging/connection_spec.rb
-- spec/qpid_messaging/duration_spec.rb
-- spec/qpid_messaging/encoding_spec.rb
-- spec/qpid_messaging/message_spec.rb
-- spec/qpid_messaging/receiver_spec.rb
-- spec/qpid_messaging/sender_spec.rb
-- spec/qpid_messaging/session_spec.rb
-- spec/spec_helper.rb
+- examples/drain.rb
+- examples/client.rb
 homepage: http://qpid.apache.org
 licenses: []
+
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Qpid is an enterprise messaging framework.
 test_files: []
+