qpid_messaging 0.16.0

data/lib/qpid_messaging/receiver.rb

@@ -0,0 +1,184 @@
+#
+# 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
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+require 'cqpid'
+
+module Qpid
+
+  module Messaging
+
+    # Receiver is the entity through which messages are received.
+    #
+    # An instance of Receiver can only be created using an active (not
+    # previously closed) Session.
+    #
+    # ==== Example
+    #
+    #   conn     = Qpid::Messaging::Connection.new :url => "mybroker:5762"
+    #   conn.open
+    #   session  = conn.create_session
+    #   receiver = session.create_receiver "my-sender-queue"
+    class Receiver
+
+      def initialize(session, receiver_impl) # :nodoc:
+        @session       = session
+        @receiver_impl = receiver_impl
+      end
+
+      def receiver_impl # :nodoc:
+        @receiver_impl
+      end
+
+      # 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.
+      #
+      # ==== Options
+      # * duration - the timeout to wait (def. Duration::FOREVER)
+      #
+      # ==== Examples
+      #
+      #   msg = rcvr.get # Uses the default timeout of forever
+      #
+      #   msg = rcvr.get Qpid::Messaging::Duration::IMMEDIATE # returns a message or exits immediately
+      #
+      #   # 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
+      #   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?
+      end
+
+      # 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.
+      #
+      # ==== 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
+      #   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+.
+      #
+      # ==== Options
+      #
+      # * capacity - the capacity
+      #
+      # ==== Examples
+      #
+      #   receiver.capacity = 50 # sets the incoming capacity to 50 messages
+      #
+      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.
+      #
+      # This differs from +capacity+ in that it is the available slots in
+      # the capacity for holding incoming messages, where available <= capacity.
+      #
+      # ==== Examples
+      #
+      #   puts "You can receive #{rcv.available} messages before blocking."
+      #
+      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+.
+      def close; @receiver_impl.close; end
+
+      # Returns whether the receiver is closed.
+      #
+      # ==== Examples
+      #
+      #   recv.close unless recv.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+.
+      def session; @session; end
+
+      private
+
+      def create_message_wrapper message_impl # :nodoc:
+        Qpid::Messaging::Message.new(:impl => message_impl)
+      end
+
+    end
+
+  end
+
+end
+

data/lib/qpid_messaging/sender.rb

@@ -0,0 +1,152 @@
+#
+# 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
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# 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.
+    #
+    # An instance of Sender can only be created using an active (not previously
+    # closed) Session.
+    #
+    # ==== Examples
+    #
+    #   conn    = Qpid::Messaging::Connection.new :url => "mybroker:5762"
+    #   conn.open
+    #   session = conn.create_session
+    #   sender  = session.create_session "my-sender-queue;{create:always}"
+    class Sender
+
+      def initialize(session, sender_impl) # :nodoc:
+        @session     = session
+        @sender_impl = sender_impl
+      end
+
+      def sender_impl # :nodoc:
+        @sender_impl
+      end
+
+      # Sends a message.
+      #
+      # If a block is given, then it will be invoked after the message
+      # is sent.
+      #
+      # ==== Options
+      #
+      # * message - The message to send.
+      # * :sync - See note below on synching.
+      #
+      # ==== Synching
+      #
+      # If :sync => true, then the call will block until the broker confirms
+      # receipt of the message. Otherwise it will only block for available
+      # capacity; i.e., until pending is equal to capacity.
+      #
+      # ==== Examples
+      #
+      #   sender.send message do |message|
+      #     puts "Message sent: #{message.content}"
+      #   end
+      #
+      def send(message, args = {}, &block)
+        sync = args[:sync] || false
+        @sender_impl.send message.message_impl, sync
+        block.call message unless block.nil?
+      end
+
+      # Closes this +Sender+.
+      #
+      # This does not affect the +Session+.
+      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.
+      #
+      # ==== Options
+      #
+      # * capacity - the capacity
+      #
+      # ==== Examples
+      #
+      #   sender.capacity = 50 # sets the outgoing capacity to 50 messages
+      #
+      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.
+      #
+      # This differs from +capacity+ in that it is the available slots in
+      # 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
+      #
+      def session; @session; end
+
+    end
+
+  end
+
+end
+

data/lib/qpid_messaging/session.rb

@@ -0,0 +1,269 @@
+#
+# 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
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+require 'cqpid'
+
+module Qpid
+
+  module Messaging
+
+    # A Session represents a distinct conversation between end points.
+    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.
+      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.
+      #
+      # ==== Arguments
+      #
+      # * +address+ The end point address.
+      #
+      # ==== Examples
+      #
+      #   sender = session.create_sender "my-queue;{create:always}"
+      #
+      def create_sender(address)
+        _address = address
+
+        if address.class == Qpid::Messaging::Address
+          _address = address.address_impl
+        end
+
+        sender_impl = @session_impl.createSender(_address)
+        sender_name = sender_impl.getName
+
+        @senders[sender_name] = Qpid::Messaging::Sender.new(self, sender_impl)
+
+        @senders[sender_name]
+      end
+
+      # Retrieves the +Sender+ with the specified name.
+      #
+      # The +Sender+ must have been previously created using
+      # the +create_sender+ method.
+      #
+      # ==== Arguments
+      #
+      # * +name+ The +Sender+ name.
+      #
+      # ==== Examples
+      #
+      #   sender = session.sender "my-queue"
+      #
+      def sender(name)
+        raise Qpid::Messaging::KeyError, "No such sender: #{name}" unless @senders.has_key? name
+
+        @senders[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.
+      #
+      # ==== Arguments
+      #
+      # * +address+ The end point address.
+      #
+      # ==== Examples
+      #
+      #   receiver = session.create_receiver "my-queue"
+      #
+      def create_receiver(address)
+        result        = nil
+        receiver_impl = nil
+
+        if address.class == Qpid::Messaging::Address
+          address_impl = address.address_impl
+          receiver_impl = @session_impl.createReceiver address_impl
+        else
+          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]
+      end
+
+      # Retrieves the +Receiver+ with the specified name.
+      #
+      # The +Receiver+ must have been previously created using
+      # the +create_receiver+ method.
+      #
+      # ==== Arguments
+      #
+      # * +name+ The +Receiver+ name.
+      #
+      # ==== Examples
+      #
+      #   receiver = session.receiver "my-queue"
+      #
+      def receiver(name)
+        raise Qpid::Messaging::KeyError, "No such receiver: #{name}" unless @receivers.has_key? name
+
+        @receivers[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.
+      def close; @session_impl.close; end
+
+      # Commits any pending transactions for a transactional session.
+      def commit; @session_impl.commit; end
+
+      # Rolls back any uncommitted transactions on a transactional session.
+      def rollback; @session_impl.rollback; end
+
+      # Acknowledges one or more outstanding messages that have been received
+      # on this session.
+      #
+      # ==== 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)
+      #
+      # ==== Examples
+      #
+      #   session.acknowledge                     # acknowledges all received messages
+      #   session.acknowledge :message => message # acknowledge one message
+      #   session.acknowledge :sync => true       # blocks until the call completes
+      #
+      #--
+      # TODO: Add an optional block to be used for blocking calls.
+      #++
+      def acknowledge(args = {})
+        sync = args[:sync] || false
+        message = args[:message] if args[:message]
+
+        unless message.nil?
+          @session_impl.acknowledge message.message_impl, sync
+        else
+          @session_impl.acknowledge sync
+        end
+      end
+
+      # Rejects the specified message. A rejected message will not be
+      # redelivered.
+      #
+      # NOTE: A message cannot be rejected once it has been acknowledged.
+      def reject(message); @session_impl.reject message.message_impl; end
+
+      # Releases the message, which allows the broker to attempt to
+      # redeliver it.
+      #
+      # 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.
+      #
+      # ==== Arguments
+      #
+      # * :block - if true then the call blocks until the server acknowledges it (def. false)
+      #
+      #--
+      # TODO: Add an optional block to be used for blocking calls.
+      #++
+      def sync(args = {})
+        block = args[:block] || false
+        @session_impl.sync block
+      end
+
+      # Returns the total number of receivable messages, and messages already
+      # 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.
+      def unsettled_acks; @session_impl.getUnsettledAcks; end
+
+      # Fetches the +Receiver+ for the next message.
+      #
+      # ==== Arguments
+      #
+      # * timeout - time to wait for a +Receiver+ before timing out
+      #
+      # ==== 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}"
+      #   end
+      def next_receiver(timeout = Qpid::Messaging::Duration::FOREVER, &block)
+        receiver_impl = @session_impl.nextReceiver(timeout.duration_impl)
+
+        unless receiver_impl.nil?
+          recv = Qpid::Messaging::Receiver.new self, receiver_impl
+          block.call recv unless block.nil?
+        end
+
+        return recv
+      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,
+      # this method will result in that exception being raised.
+      #
+      # If none have occurred, then no exceptions are raised.
+      #
+      # ==== Examples
+      #
+      #   if @session.errors?
+      #     begin
+      #       @session.errors
+      #     rescue Exception => error
+      #       puts "An error occurred: #{error}"
+      #     end
+      #   end
+      def errors; @session_impl.checkError; end
+
+    end
+
+  end
+
+end
+