qpid_proton 0.18.1 → 0.19.0

data/lib/core/delivery.rb

@@ -1,11 +1,9 @@
-#--
 # 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
 #
@@ -15,257 +13,84 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#++
 
-module Qpid::Proton
-
-  # A Delivery maintains detail on the delivery of data to an endpoint.
-  #
-  # A Delivery has a single parent Qpid::Proton::Link
-  #
-  # @example
-  #
-  #   # SCENARIO: An event comes in notifying that data has been delivered to
-  #   #           the local endpoint. A Delivery object can be used to check
-  #   #           the details of the delivery.
-  #
-  #   delivery = @event.delivery
-  #   if delivery.readable? && !delivery.partial?
-  #     # decode the incoming message
-  #     msg = Qpid::Proton::Message.new
-  #     msg.decode(link.receive(delivery.pending))
-  #   end
-  #
-  class Delivery
-
-    # @private
-    include Util::Wrapper
-
-    # @private
-    def self.wrap(impl) # :nodoc:
-      return nil if impl.nil?
-      self.fetch_instance(impl, :pn_delivery_attachments) || Delivery.new(impl)
-    end
-
-    # @private
-    def initialize(impl)
-      @impl = impl
-      @local = Disposition.new(Cproton.pn_delivery_local(impl), true)
-      @remote = Disposition.new(Cproton.pn_delivery_remote(impl), false)
-      self.class.store_instance(self, :pn_delivery_attachments)
-    end
-
-    # @private
-    include Util::SwigHelper
-
-    # @private
-    PROTON_METHOD_PREFIX = "pn_delivery"
-
-    # @!attribute [r] tag
-    #
-    # @return [String] The tag for the delivery.
-    #
-    proton_caller :tag
-
-    # @!attribute [r] writable?
-    #
-    # A delivery is considered writable if it is the current delivery on an
-    # outgoing link, and the link has positive credit.
-    #
-    # @return [Boolean] Returns if a delivery is writable.
-    #
-    proton_caller :writable?
-
-    # @!attribute [r] readable?
-    #
-    # A delivery is considered readable if it is the current delivery on an
-    # incoming link.
-    #
-    # @return [Boolean] Returns if a delivery is readable.
-    #
-    proton_caller :readable?
-    # @!attribute [r] updated?
-    #
-    # A delivery is considered updated whenever the peer communicates a new
-    # disposition for the dlievery. Once a delivery becomes updated, it will
-    # remain so until cleared.
-    #
-    # @return [Boolean] Returns if a delivery is updated.
-    #
-    # @see #clear
-    #
-    proton_caller :updated?
-
-    # @!method clear
-    #
-    # Clear the updated flag for a delivery.
-    #
-    proton_caller :clear
-
-    # @!attribute [r] pending
-    #
-    # @return [Integer] Return the amount of pending message data for the
-    # delivery.
-    #
-    proton_caller :pending
-
-    # @!attribute [r] partial?
-    #
-    # @return [Boolean] Returns if the delivery has only partial message data.
-    #
-    proton_caller :partial?
-
-    # @!attribute [r] settled?
-    #
-    # @return [Boolean] Returns if the delivery is remotely settled.
-    #
-    proton_caller :settled?
-
-
-    # @!method settle
-    #
-    # Settles a delivery.
-    #
-    #  A settled delivery can never be used again.
-    #
-    proton_caller :settle
-
-    # @!method dump
-    #
-    #  Utility function for printing details of a delivery.
-    #
-    proton_caller :dump
-
-    # @!attribute [r] buffered?
-    #
-    # A delivery that is buffered has not yet been written to the wire.
-    #
-    # Note that returning false does not imply that a delivery was definitely
-    # written to the wire. If false is returned, it is not known whether the
-    # delivery was actually written to the wire or not.
-    #
-    # @return [Boolean] Returns if the delivery is buffered.
-    #
-    proton_caller :buffered?
-
-    include Util::Engine
-
-    def update(state)
-      impl = @local.impl
-      object_to_data(@local.data, Cproton.pn_disposition_data(impl))
-      object_to_data(@local.annotations, Cproton.pn_disposition_annotations(impl))
-      object_to_data(@local.condition, Cproton.pn_disposition_condition(impl))
-      Cproton.pn_delivery_update(@impl, state)
-    end
-
-    # Returns the local disposition state for the delivery.
-    #
-    # @return [Disposition] The local disposition state.
-    #
-    def local_state
-      Cproton.pn_delivery_local_state(@impl)
-    end
-
-    # Returns the remote disposition state for the delivery.
-    #
-    # @return [Disposition] The remote disposition state.
-    #
-    def remote_state
-      Cproton.pn_delivery_remote_state(@impl)
-    end
-
-    # Returns the next delivery on the connection that has pending operations.
-    #
-    # @return [Delivery, nil] The next delivery, or nil if there are none.
-    #
-    # @see Connection#work_head
-    #
-    def work_next
-      Delivery.wrap(Cproton.pn_work_next(@impl))
-    end
-
-    # Returns the parent link.
-    #
-    # @return [Link] The parent link.
-    #
-    def link
-      Link.wrap(Cproton.pn_delivery_link(@impl))
-    end
-
-    # Returns the parent session.
-    #
-    # @return [Session] The session.
-    #
-    def session
-      self.link.session
-    end
-
-    # Returns the parent connection.
-    #
-    # @return [Connection] The connection.
-    #
-    def connection
-      self.session.connection
-    end
 
-    # Returns the parent transport.
-    #
-    # @return [Transport] The transport.
-    #
-    def transport
-      self.connection.transport
-    end
-
-    # @private
-    def local_received?
-      self.local_state == Disposition::RECEIVED
-    end
-
-    # @private
-    def remote_received?
-      self.remote_state == Disposition::RECEIVED
-    end
-
-    # @private
-    def local_accepted?
-      self.local_state == Disposition::ACCEPTED
-    end
-
-    # @private
-    def remote_accepted?
-      self.remote_state == Disposition::ACCEPTED
-    end
-
-    # @private
-    def local_rejected?
-      self.local_state == Disposition::REJECTED
-    end
-
-    # @private
-    def remote_rejected?
-      self.remote_state == Disposition::REJECTED
-    end
-
-    # @private
-    def local_released?
-      self.local_state == Disposition::RELEASED
-    end
-
-    # @private
-    def remote_released?
-      self.remote_state == Disposition::RELEASED
-    end
-
-    # @private
-    def local_modified?
-      self.local_state == Disposition::MODIFIED
-    end
-
-    # @private
-    def remote_modified?
-      self.remote_state == Disposition::MODIFIED
+module Qpid::Proton
+  # Allow a {Receiver} to indicate the status of a received message to the {Sender}
+  class Delivery < Transfer
+    def initialize(*args) super; @message = nil; end
+
+    # @return [Receiver] The parent {Receiver} link.
+    def receiver() link; end
+
+    # Accept the receiveed message.
+    def accept() settle ACCEPTED; end
+
+    # Reject a message, indicating to the sender that is invalid and should
+    # never be delivered again to this or any other receiver.
+    def reject() settle REJECTED; end
+
+    # Release a message, indicating to the sender that it was not processed
+    # but may be delivered again to this or another receiver.
+    #
+    # @param opts [Hash] Instructions to the sender to modify re-delivery.
+    #  To allow re-delivery with no modifications at all use +release(nil)+
+    #
+    # @option opts [Boolean] :failed (true) Instruct the sender to increase
+    #  {Message#delivery_count} so future receivers will know there was a
+    #  previous failed delivery.
+    #
+    # @option opts [Boolean] :undeliverable (false) Instruct the sender that this
+    #  message should never be re-delivered to this receiver, although it may be
+    #  delivered other receivers.
+    #
+    # @option opts [Hash] :annotations Instruct the sender to update the
+    #  {Message#annotations} with these +key=>value+ pairs before re-delivery,
+    #  replacing existing entries in {Message#annotations} with the same key.
+    def release(opts = nil)
+      opts = { :failed => false } if (opts == false) # deprecated
+      failed = !opts || opts.fetch(:failed, true)
+      undeliverable = opts && opts[:undeliverable]
+      annotations = opts && opts[:annotations]
+      annotations = nil if annotations && annotations.empty?
+      if failed || undeliverable || annotations
+        d = Cproton.pn_delivery_local(@impl)
+        Cproton.pn_disposition_set_failed(d, true) if failed
+        Cproton.pn_disposition_set_undeliverable(d, true) if undeliverable
+        Codec::Data.from_object(Cproton.pn_disposition_annotations(d), annotations) if annotations
+        settle(MODIFIED)
+      else
+        settle(RELEASED)
+      end
+    end
+
+    # @deprecated use {#release} with modification options
+    def modify()
+      deprecated __method__, "release(modification_options)"
+      release failed=>true
+    end
+
+    # @return [Boolean] True if the transfer was aborted by the sender.
+    proton_caller :aborted?
+
+    # @return true if the incoming message is complete, call {#message} to retrieve it.
+    def complete?() readable? && !aborted? && !partial?; end
+
+    # Get the message from the delivery.
+    # @return [Message] The message
+    # @raise [AbortedError] if the message has been aborted (check with {#aborted?}
+    # @raise [UnderflowError] if the message is incomplete (check with {#complete?}
+    # @raise [::ArgumentError] if the delivery is not the current delivery on a receiving link.
+    def message
+      unless @message
+        raise AbortedError, "message aborted by sender" if aborted?
+        raise UnderflowError, "incoming message incomplete" if partial?
+        raise ArgumentError, "no incoming message" unless readable?
+        @message = Message.new
+        @message.decode(link.receive(pending))
+        link.advance
+      end
+      @message
     end
-
   end
-
 end

data/lib/core/disposition.rb

@@ -1,4 +1,3 @@
-#--
 # 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,38 +14,31 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#++
+
 
 module Qpid::Proton
 
-  # Disposition records the current state and/or final outcome of a transfer.
-  #
-  # Every delivery contains both a local and a remote disposition. The local
-  # disposition holds the local state of the delivery, and the remote
-  # disposition holds the *last known* remote state of the delivery.
-  #
+  # @deprecated use {Delivery}
   class Disposition
+    include Util::Deprecation
 
-    include Util::Constants
+    # @private
+    PROTON_METHOD_PREFIX = "pn_disposition"
+    # @private
+    include Util::Wrapper
 
-    # Indicates the delivery was received.
-    self.add_constant(:RECEIVED, Cproton::PN_RECEIVED)
-    # Indicates the delivery was accepted.
-    self.add_constant(:ACCEPTED, Cproton::PN_ACCEPTED)
-    # Indicates the delivery was rejected.
-    self.add_constant(:REJECTED, Cproton::PN_REJECTED)
-    # Indicates the delivery was released.
-    self.add_constant(:RELEASED, Cproton::PN_RELEASED)
-    # Indicates the delivery was modified.
-    self.add_constant(:MODIFIED, Cproton::PN_MODIFIED)
 
-    # @private
-    include Util::Engine
+    ACCEPTED = Cproton::PN_ACCEPTED
+    REJECTED = Cproton::PN_REJECTED
+    RELEASED = Cproton::PN_RELEASED
+    MODIFIED = Cproton::PN_MODIFIED
+    RECEIVED =  Cproton::PN_RECEIVED
 
     attr_reader :impl
 
     # @private
     def initialize(impl, local)
+      deprecated self.class, Delivery
       @impl = impl
       @local = local
       @data = nil
@@ -54,35 +46,29 @@ module Qpid::Proton
       @annotations = nil
     end
 
-    # @private
-    include Util::SwigHelper
-
-    # @private
-    PROTON_METHOD_PREFIX = "pn_disposition"
-
     # @!attribute section_number
     #
     # @return [Integer] The section number of the disposition.
     #
-    proton_accessor :section_number
+    proton_set_get :section_number
 
     # @!attribute section_offset
     #
     #  @return [Integer] The section offset of the disposition.
     #
-    proton_accessor :section_offset
+    proton_set_get :section_offset
 
     # @!attribute failed?
     #
     # @return [Boolean] The failed flag.
     #
-    proton_accessor :failed, :is_or_get => :is
+    proton_set_is :failed
 
     # @!attribute undeliverable?
     #
     # @return [Boolean] The undeliverable flag.
     #
-    proton_accessor :undeliverable, :is_or_get => :is
+    proton_set_is :undeliverable
 
     # Sets the data for the disposition.
     #
@@ -103,7 +89,7 @@ module Qpid::Proton
       if @local
         @data
       else
-        data_to_object(Cproton.pn_disposition_data(@impl))
+        Codec::Data.to_object(Cproton.pn_disposition_data(@impl))
       end
     end
 
@@ -126,11 +112,11 @@ module Qpid::Proton
       if @local
         @annotations
       else
-        data_to_object(Cproton.pn_disposition_annotations(@impl))
+        Codec::Data.to_object(Cproton.pn_disposition_annotations(@impl))
       end
     end
 
-    # Sets the condition for the disposition.
+   # Sets the condition for the disposition.
     #
     # @param condition [Codec::Data] The condition.
     #
@@ -149,7 +135,7 @@ module Qpid::Proton
       if @local
         @condition
       else
-        condition_to_object(Cproton.pn_disposition_condition(@impl))
+        Condition.convert(Cproton.pn_disposition_condition(@impl))
       end
     end