qpid_proton 0.18.1 → 0.19.0

data/lib/core/url.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,24 +14,25 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#++
+
 
 module Qpid::Proton
 
+  # @deprecated use {URI} or {String}
   class URL
+    include Util::Deprecation
 
     attr_reader :scheme
     attr_reader :username
+    alias user username
     attr_reader :password
     attr_reader :host
-    attr_reader :port
     attr_reader :path
 
     # Parse a string, return a new URL
     # @param url [#to_s] the URL string
-    def initialize(url = nil, options = {})
-      options[:defaults] = true
-
+    def initialize(url = nil)
+      deprecated self.class, 'URI or String'
       if url
         @url = Cproton.pn_url_parse(url.to_s)
         if @url.nil?
@@ -62,14 +62,18 @@ module Qpid::Proton
       Cproton.pn_url_get_port(@url).to_i
     end
 
+    # @return [String] Convert to string
     def to_s
       "#{@scheme}://#{@username.nil? ? '' : @username}#{@password.nil? ? '' : '@' + @password + ':'}#{@host}:#{@port}/#{@path}"
     end
 
+    # @return [String] Allow implicit conversion by {String#try_convert}
+    alias to_str to_s
+
     private
 
     def defaults
-      @scheme = @scheme || "ampq"
+      @scheme = @scheme || "amqp"
       @host = @host || "0.0.0.0"
       @port = @port || 5672
     end

data/lib/handler/adapter.rb

@@ -0,0 +1,78 @@
+# 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.
+
+
+# @private
+module Qpid::Proton
+  module Handler
+
+    def self.handler_method?(method) /^on_/ =~ name; end
+
+    # Handler for an array of handlers of uniform type, with non-conflicting options
+    class ArrayHandler
+
+      def initialize(handlers)
+        raise "empty handler array" if handlers.empty?
+        adapters = (handlers.map { |h| Adapter.adapter(h) }).uniq
+        raise "handler array not uniform, adapters requested: #{adapters}" if adapters.size > 1
+        @proton_adapter_class = adapters[0]
+        @methods = Set.new
+        handlers.each do |h|
+          @methods.merge(h.methods.select { |m| handler_method? m }) # Collect handler methods
+        end
+      end
+
+      attr_reader :options, :proton_adapter_class
+
+      def method_missing(name, *args)
+        if respond_to_missing?(name)
+          @adapters.each { |a| a.__send__(name, *args) if a.respond_to? name}
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(name, private=false); @methods.include?(name); end
+      def respond_to?(name, all=false) super || respond_to_missing?(name); end # For ruby < 1.9.2
+    end
+
+    # Base adapter for raw proton events
+    class Adapter
+      def initialize(h) @handler = h; end
+
+      # Create and return an adapter for handler, or return h if it does not need adapting.
+      def self.adapt(handler)
+        return unless handler
+        a = Array(handler)
+        h = (a.size == 1) ? a[0] : ArrayHandler.new(a)
+        ac = adapter(h)
+        ac ? ac.new(h) : h
+      end
+
+      # Adapter class if requested by handler, else default to MessagingHandler
+      def self.adapter(handler)
+        handler.respond_to?(:proton_adapter_class) ? handler.proton_adapter_class : MessagingAdapter
+      end
+
+      def proton_adapter_class() nil; end # Adapters don't need adapting
+
+      def forward(method, *args)
+        (@handler.__send__(method, *args); true) if @handler.respond_to? method
+      end
+    end
+  end
+end

data/lib/handler/messaging_adapter.rb

@@ -0,0 +1,127 @@
+# 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.
+
+
+# @private
+module Qpid::Proton
+  module Handler
+
+    # Adapt raw proton events to {MessagingHandler} events.
+    class MessagingAdapter  < Adapter
+
+      def delegate(method, *args)
+        forward(method, *args) or forward(:on_unhandled, method, *args)
+      end
+
+      def delegate_error(method, context)
+        unless forward(method, context) || forward(:on_error, context.condition)
+          forward(:on_unhandled, method, context)
+          # Close the whole connection on an un-handled error
+          context.connection.close(context.condition)
+        end
+      end
+
+      def on_container_start(container) delegate(:on_container_start, container); end
+      def on_container_stop(container) delegate(:on_container_stop, container); end
+
+      # Define repetative on_xxx_open/close methods for each endpoint type
+      def self.open_close(endpoint)
+        Module.new do
+          define_method(:"on_#{endpoint}_remote_open") do |event|
+            begin
+              delegate(:"on_#{endpoint}_open", event.context)
+              event.context.open if event.context.local_uninit?
+            rescue StopAutoResponse
+            end
+          end
+
+          define_method(:"on_#{endpoint}_remote_close") do |event|
+            delegate_error(:"on_#{endpoint}_error", event.context) if event.context.condition
+            begin
+              delegate(:"on_#{endpoint}_close", event.context)
+              event.context.close if event.context.local_active?
+            rescue StopAutoResponse
+            end
+          end
+        end
+      end
+      # Generate and include open_close modules for each endpoint type
+      # Using modules so we can override to extend the behavior later in the handler.
+      [:connection, :session, :link].each { |endpoint| include open_close(endpoint) }
+
+      def on_transport_error(event)
+        delegate_error(:on_transport_error, event.context)
+      end
+
+      def on_transport_closed(event)
+        delegate(:on_transport_close, event.context) rescue StopAutoResponse
+      end
+
+      # Add flow control for link opening events
+      def on_link_local_open(event) add_credit(event); end
+      def on_link_remote_open(event) super; add_credit(event); end
+
+
+      def on_delivery(event)
+        if event.link.receiver?       # Incoming message
+          d = event.delivery
+          if d.aborted?
+            delegate(:on_delivery_abort, d)
+          elsif d.complete?
+            if d.link.local_closed? && d.receiver.auto_accept
+              d.release         # Auto release after close
+            else
+              begin
+                delegate(:on_message, d, d.message)
+                d.accept if d.receiver.auto_accept  && !d.settled?
+              rescue Reject
+                d.reject unless d.settled?
+              rescue Release
+                d.release unless d.settled?
+              end
+            end
+          end
+          delegate(:on_delivery_settle, d) if d.settled?
+          add_credit(event)
+        else                      # Outgoing message
+          t = event.tracker
+          case t.state
+          when Delivery::ACCEPTED then delegate(:on_tracker_accept, t)
+          when Delivery::REJECTED then delegate(:on_tracker_reject, t)
+          when Delivery::RELEASED then delegate(:on_tracker_release, t)
+          when Delivery::MODIFIED then delegate(:on_tracker_modify, t)
+          end
+          delegate(:on_tracker_settle, t) if t.settled?
+          t.settle if t.sender.auto_settle
+        end
+      end
+
+      def on_link_flow(event)
+        add_credit(event)
+        sender = event.sender
+        delegate(:on_sendable, sender) if sender && sender.open? && sender.credit > 0
+      end
+
+      def add_credit(event)
+        return unless (r = event.receiver)
+        if r.open? && (r.drained == 0) && r.credit_window && (r.credit_window > r.credit)
+          r.flow(r.credit_window - r.credit)
+        end
+      end
+    end
+  end
+end

data/lib/handler/messaging_handler.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,202 +14,153 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#++
-
-module Qpid::Proton::Handler
-
-  # A general purpose handler that simplifies processing events.
-  #
-  class MessagingHandler < Qpid::Proton::BaseHandler
-
-    attr_reader :handlers
-
-    # Creates a new instance.
-    #
-    # @param [Integer] prefetch
-    # @param [Boolean] auto_accept
-    # @param [Boolean] auto_settle
-    # @param [Boolean] peer_close_is_error
-    #
-    def initialize(prefetch = 10, auto_accept = true, auto_settle = true, peer_close_is_error = false)
-      @handlers = Array.new
-      @handlers << CFlowController.new(prefetch) unless prefetch.zero?
-      @handlers << EndpointStateHandler.new(peer_close_is_error, self)
-      @handlers << IncomingMessageHandler.new(auto_accept, self)
-      @handlers << OutgoingMessageHandler.new(auto_settle,self)
-    end
 
-    # Called when the peer closes the connection with an error condition.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_connection_error(event)
-      EndpointStateHandler.print_error(event.connection, "connection")
-    end
 
-      # Called when the peer closes the session with an error condition.
-      #
-      # @param event [Qpid:Proton::Event::Event] The event.
+module Qpid::Proton
+  module Handler
+
+    # @deprecated use {Qpid::Proton::MessagingHandler}
+    class MessagingHandler
+      include Util::Deprecation
+
+      # @private
+      def proton_adapter_class() Handler::ReactorMessagingAdapter; end
+
+
+      # @overload initialize(opts)
+      #   Create a {MessagingHandler} with options +opts+
+      #   @option opts [Integer] :prefetch (10)
+      #    The number of messages to  fetch in advance, 0 disables prefetch.
+      #   @option opts [Boolean] :auto_accept  (true)
+      #    If true, incoming messages are accepted automatically after {#on_message}.
+      #    If false, the application can accept, reject or release the message
+      #    by calling methods on {Delivery} when the message has been processed.
+      #   @option opts [Boolean] :auto_settle (true) If true, outgoing
+      #    messages are settled automatically when the remote peer settles. If false,
+      #    the application must call {Delivery#settle} explicitly.
+      #   @option opts [Boolean] :auto_open (true)
+      #    If true, incoming connections are  opened automatically.
+      #    If false, the application must call {Connection#open} to open incoming connections.
+      #   @option opts [Boolean] :auto_close (true)
+      #    If true, respond to a remote close automatically with a local close.
+      #    If false, the application must call {Connection#close} to finish closing connections.
+      #   @option opts [Boolean] :peer_close_is_error (false)
+      #    If true, and the remote peer closes the connection without an error condition,
+      #    the set the local error condition {Condition}("error", "unexpected peer close")
       #
-    def on_session_error(event)
-      EndpointStateHandler.print_error(event.session, "session")
-      event.connection.close
-    end
+      # @overload initialize(prefetch=10, auto_accept=true, auto_settle=true, peer_close_is_error=false)
+      # @deprecated use +initialize(opts)+ overload
+      def initialize(*args)
+        deprecated MessagingHandler, Qpid::Proton::MessagingHandler
+        @options = {}
+        if args.size == 1 && args[0].is_a?(Hash)
+          @options.replace(args[0])
+        else                      # Fill options from deprecated fixed arguments
+          [:prefetch, :auto_accept, :auto_settle, :peer_close_is_error].each do |k|
+            opts[k] = args.shift unless args.empty?
+          end
+        end
+        # NOTE: the options are processed by {Handler::Adapater}
+      end
+
+      public
+
+      # @return [Hash] handler options, see {#initialize}
+      attr_reader :options
+
+      # @!method on_transport_error(event)
+      # Called when the transport fails or closes unexpectedly.
+      # @param event [Event] The event.
+
+      # !@method on_connection_error(event)
+      # Called when the peer closes the connection with an error condition.
+      # @param event [Event] The event.
+
+      # @!method on_session_error(event)
+      # Called when the peer closes the session with an error condition.
+      # @param event [Qpid:Proton::Event] The event.
 
-    # Called when the peer closes the link with an error condition.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_link_error(event)
-      EndpointStateHandler.print_error(event.link, "link")
-      event.connection.close
-    end
+      # @!method on_link_error(event)
+      # Called when the peer closes the link with an error condition.
+      # @param event [Event] The event.
 
-    # Called when the event loop starts.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_reactor_init(event)
-      self.on_start(event)
-    end
+      # @!method on_start(event)
+      # Called when the event loop starts.
+      # @param event [Event] The event.
 
-    # Called when the event loop starts.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_start(event)
-    end
+      # @!method on_connection_closed(event)
+      # Called when the connection is closed.
+      # @param event [Event] The event.
 
-    # Called when the connection is closed.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_connection_closed(event)
-    end
+      # @!method on_session_closed(event)
+      # Called when the session is closed.
+      # @param event [Event] The event.
 
-    # Called when the session is closed.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_session_closed(event)
-    end
+      # @!method on_link_closed(event)
+      # Called when the link is closed.
+      # @param event [Event] The event.
 
-    # Called when the link is closed.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_link_closed(event)
-    end
+      # @!method on_connection_closing(event)
+      # Called when the peer initiates the closing of the connection.
+      # @param event [Event] The event.
 
-    # Called when the peer initiates the closing of the connection.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_connection_closing(event)
-    end
+      # @!method on_session_closing(event)
+      # Called when the peer initiates the closing of the session.
+      # @param event [Event] The event.
 
-    # Called when the peer initiates the closing of the session.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_session_closing(event)
-    end
+      # @!method on_link_closing(event)
+      # Called when the peer initiates the closing of the link.
+      # @param event [Event] The event.
 
-    # Called when the peer initiates the closing of the link.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_link_closing(event)
-    end
+      # @!method on_disconnected(event)
+      # Called when the socket is disconnected.
+      # @param event [Event] The event.
 
-    # Called when the socket is disconnected.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_disconnected(event)
-    end
+      # @!method on_sendable(event)
+      # Called when the sender link has credit and messages can therefore
+      # be transferred.
+      # @param event [Event] The event.
 
-    # Called when the sender link has credit and messages can therefore
-    # be transferred.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_sendable(event)
-    end
+      # @!method on_accepted(event)
+      # Called when the remote peer accepts an outgoing message.
+      # @param event [Event] The event.
 
-    # Called when the remote peer accepts an outgoing message.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_accepted(event)
-    end
+      # @!method on_rejected(event)
+      # Called when the remote peer rejects an outgoing message.
+      # @param event [Event] The event.
 
-    # Called when the remote peer rejects an outgoing message.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_rejected(event)
-    end
+      # @!method on_released(event)
+      # Called when the remote peer releases an outgoing message for re-delivery as-is.
+      # @param event [Event] The event.
 
-    # Called when the remote peer releases an outgoing message.
-    #
-    # Note that this may be in response to either the RELEASE or
-    # MODIFIED state as defined by the AMPQ specification.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_released(event)
-    end
+      # @!method on_modified(event)
+      # Called when the remote peer releases an outgoing message for re-delivery with modifications.
+      # @param event [Event] The event.
 
-    # Called when the remote peer has settled hte outgoing message.
-    #
-    # This is the point at which it should never be retransmitted.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_settled(event)
-    end
+      # @!method on_settled(event)
+      # Called when the remote peer has settled hte outgoing message.
+      # This is the point at which it should never be retransmitted.
+      # @param event [Event] The event.
 
-    # Called when a message is received.
-    #
-    # The message itself can be obtained as a property on the event. For
-    # the purpose of referring to this message in further actions, such as
-    # explicitly accepting it) the delivery should be used. This is also
-    # obtainable vi a property on the event.
-    #
-    # This method needs to be overridden.
-    #
-    # @param event [Qpid::Proton::Event::Event] The event.
-    #
-    def on_message(event)
-    end
+      # @!method on_message(event)
+      # Called when a message is received.
+      #
+      # The message is available from {Event#message}, to accept or reject the message
+      # use {Event#delivery}
+      # @param event [Event] The event.
 
-  end
+      # @!method on_aborted(event)
+      # Called when message delivery is aborted by the sender.
+      # The {Event#delivery} provides information about the delivery, but the message should be ignored.
 
+      # @!method on_error(event)
+      # If +on_xxx_error+ method is missing, {#on_error} is called instead.
+      # If {#on_error} is missing, the connection is closed with the error.
+      # @param event [Event] the event, {Event#method} provides the original method name.
+
+      # @!method on_unhandled(event)
+      # If an +on_xxx+ method is missing, {#on_unhandled} is called instead.
+      # @param event [Event] the event, {Event#method} provides the original method name.
+    end
+  end
 end