qpid_proton 0.18.1 → 0.19.0

data/lib/core/messaging_handler.rb

@@ -0,0 +1,190 @@
+ # 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::Proton
+
+  # A handler for AMQP messaging events.
+  #
+  # Subclass the handler and provide the #on_xxx methods with your event-handling code.
+  #
+  # An AMQP endpoint (connection, session or link) must be opened and closed at
+  # each end.  Normally proton responds automatically to an incoming
+  # open/close. You can prevent the automatic response by raising
+  # {StopAutoResponse} from +#on_xxx_open+ or +#on_xxx_close+. The application becomes responsible
+  # for calling +#open/#close+ at a later point.
+  #
+  class MessagingHandler
+
+    # @return [Hash] handler options, see {#initialize}
+    attr_reader :options
+
+    # @!group Most common events
+
+    # @!method on_container_start(container)
+    # The container event loop is started
+    # @param container [Container] The container.
+
+    # @!method on_container_stop(container)
+    # The container event loop is stopped
+    # @param container [Container] The container.
+
+    # @!method on_message(delivery, message)
+    # A message is received.
+    # @param delivery [Delivery] The delivery.
+    # @param message [Message] The message
+
+    # @!method on_sendable(sender)
+    # A message can be sent
+    # @param sender [Sender] The sender.
+
+    # @!endgroup
+
+    # @!group Endpoint lifecycle events
+
+    # @!method on_connection_open(connection)
+    # The remote peer opened the connection
+    # @param connection
+
+    # @!method on_connection_close(connection)
+    # The remote peer closed the connection
+    # @param connection
+
+    # @!method on_connection_error(connection)
+    # The remote peer closed the connection with an error condition
+    # @param connection
+
+    # @!method on_session_open(session)
+    # The remote peer opened the session
+    # @param session
+
+    # @!method on_session_close(session)
+    # The remote peer closed the session
+    # @param session
+
+    # @!method on_session_error(session)
+    # The remote peer closed the session with an error condition
+    # @param session
+
+    # @!method on_sender_open(sender)
+    # The remote peer opened the sender
+    # @param sender
+
+    # @!method on_sender_detach(sender)
+    # The remote peer detached the sender
+    # @param sender
+
+    # @!method on_sender_close(sender)
+    # The remote peer closed the sender
+    # @param sender
+
+    # @!method on_sender_error(sender)
+    # The remote peer closed the sender with an error condition
+    # @param sender
+
+    # @!method on_receiver_open(receiver)
+    # The remote peer opened the receiver
+    # @param receiver
+
+    # @!method on_receiver_detach(receiver)
+    # The remote peer detached the receiver
+    # @param receiver
+
+    # @!method on_receiver_close(receiver)
+    # The remote peer closed the receiver
+    # @param receiver
+
+    # @!method on_receiver_error(receiver)
+    # The remote peer closed the receiver with an error condition
+    # @param receiver
+
+    # @!endgroup
+
+    # @!group Delivery events
+
+    # @!method on_tracker_accept(tracker)
+    # The receiving end accepted a delivery
+    # @param tracker [Tracker] The tracker.
+
+    # @!method on_tracker_reject(tracker)
+    # The receiving end rejected a delivery
+    # @param tracker [Tracker] The tracker.
+
+    # @!method on_tracker_release(tracker)
+    # The receiving end released a delivery
+    # @param tracker [Tracker] The tracker.
+
+    # @!method on_tracker_modify(tracker)
+    # The receiving end modified a delivery
+    # @param tracker [Tracker] The tracker.
+
+    # @!method on_tracker_settle(tracker)
+    # The receiving end settled a delivery
+    # @param tracker [Tracker] The tracker.
+
+    # @!method on_delivery_settle(delivery)
+    # The sending end settled a delivery
+    # @param delivery [Delivery] The delivery.
+
+    # @!method on_delivery_abort(delivery)
+    # A message was begun but aborted by the sender, so was not received.
+    # @param delivery [Delivery] The delivery.
+
+    # @!endgroup
+
+    # @!group Flow control events
+
+    # @!method on_sender_drain_start(sender)
+    # The remote end of the sender requested draining
+    # @param sender [Sender] The sender.
+
+    # @!method on_receiver_drain_finish(receiver)
+    # The remote end of the receiver completed draining
+    # @param receiver [Receiver] The receiver.
+
+    # @!endgroup
+
+    # @!group Transport events
+
+    # @!method on_transport_open(transport)
+    # The underlying network channel opened
+    # @param transport [Transport] The transport.
+
+    # @!method on_transport_close(transport)
+    # The underlying network channel closed
+    # @param transport [Transport] The transport.
+
+    # @!method on_transport_error(transport)
+    # The underlying network channel is closing due to an error.
+    # @param transport [Transport] The transport.
+
+    # @!endgroup
+
+    # @!group Unhandled events
+
+    # @!method on_error(error_condition)
+    # The fallback error handler when no specific on_xxx_error is defined
+    # @param error_condition [Condition] Provides information about the error.
+
+    # @!method on_unhandled(method_name, *args)
+    # Called for events with no handler. Similar to ruby's standard #method_
+    # @param method_name [Symbol] Name of the event method that would have been called.
+    # @param args [Array] Arguments that would have been passed
+
+    # @!endgroup
+  end
+end

data/lib/core/receiver.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,7 +14,7 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#++
+
 
 module Qpid::Proton
 
@@ -25,11 +24,43 @@ module Qpid::Proton
   #
   class Receiver < Link
 
-    # @private
-    include Util::SwigHelper
-
     # @private
     PROTON_METHOD_PREFIX = "pn_link"
+    # @private
+    include Util::Wrapper
+
+    # Open {Receiver} link
+    #
+    # @overload open_receiver(address)
+    #   @param address [String] address of the source to receive from
+    # @overload open_receiver(opts)
+    #   @param opts [Hash] Receiver options, see {Receiver#open}
+    #   @option opts [Boolean] :credit_window automatically maintain this much credit
+    #     for messages to be pre-fetched while the current message is processed.
+    #   @option opts [Boolean] :auto_accept if true, deliveries that are not settled by
+    #     the application in {MessagingHandler#on_message} are automatically accepted.
+    #   @option opts [Integer] :credit_window (10) automatically replenish credits for flow control.
+    #   @option opts [Boolean] :dynamic (false) dynamic property for source {Terminus#dynamic}
+    #   @option opts [String,Hash] :source source address or source options, see {Terminus#apply}
+    #   @option opts [String,Hash] :target target address or target options, see {Terminus#apply}
+    #   @option opts [String] :name (generated) unique name for the link.
+    def open(opts=nil)
+      opts ||= {}
+      opts = { :source => opts } if opts.is_a? String
+      @credit_window =  opts.fetch(:credit_window, 10)
+      @auto_accept = opts.fetch(:auto_accept, true)
+      source.apply(opts[:source])
+      target.apply(opts[:target])
+      source.dynamic = !!opts[:dynamic]
+      super()
+      self
+    end
+
+    # @return [Integer] credit window, see {#open}
+    attr_reader :credit_window
+
+    # @return [Boolean] auto_accept flag, see {#open}
+    attr_reader :auto_accept
 
     # @!attribute drain
     #
@@ -43,7 +74,7 @@ module Qpid::Proton
     #
     # @return [Boolean] True if drain mode is set.
     #
-    proton_accessor :drain
+    proton_set_get :drain
 
     # @!attribute [r] draining?
     #
@@ -77,7 +108,7 @@ module Qpid::Proton
     # @param limit [Integer] The maximum bytes to receive.
     #
     # @return [Integer, nil] The number of bytes received, or nil if the end of
-    # the stream was reached.t
+    # the stream was reached.
     #
     # @see Deliver#pending To see how much buffer space is needed.
     #

data/lib/core/sasl.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,7 +14,7 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#++
+
 
 module Qpid::Proton
 
@@ -30,6 +29,7 @@ module Qpid::Proton
   #
   # @note Do not instantiate directly, use {Transport#sasl} to create a SASL object.
   class SASL
+    include Util::Deprecation
 
     # Negotation has not completed.
     NONE = Cproton::PN_SASL_NONE
@@ -40,7 +40,7 @@ module Qpid::Proton
 
     private
 
-    include Util::SwigHelper
+    include Util::Wrapper
     PROTON_METHOD_PREFIX = "pn_sasl"
 
     public
@@ -53,11 +53,11 @@ module Qpid::Proton
 
     # @!attribute allow_insecure_mechs
     #   @return [Bool] true if clear text authentication is allowed on insecure connections.
-    proton_accessor :allow_insecure_mechs
+    proton_set_get :allow_insecure_mechs
 
     # @!attribute user [r]
     #   @return [String] the authenticated user name
-    proton_reader :user
+    proton_get :user
 
     # Set the mechanisms allowed for SASL negotation
     # @param mechanisms [String] space-delimited list of allowed mechanisms
@@ -66,9 +66,7 @@ module Qpid::Proton
     end
 
     # @deprecated use {#allowed_mechs=}
-    def mechanisms(m)
-      self.allowed_mechs = m
-    end
+    deprecated_alias :mechanisms, :allowed_mechs=
 
     # True if extended SASL negotiation is supported
     #
@@ -83,44 +81,43 @@ module Qpid::Proton
       Cproton.pn_sasl_extended()
     end
 
-    # Set the sasl configuration path
-    #
-    # This is used to tell SASL where to look for the configuration file.
-    # In the current implementation it can be a colon separated list of directories.
-    #
-    # The environment variable PN_SASL_CONFIG_PATH can also be used to set this path,
-    # but if both methods are used then this pn_sasl_config_path() will take precedence.
-    #
-    # If not set the underlying implementation default will be used.
-    #
-    # @param path the configuration path
-    #
-    def self.config_path=(path)
-      Cproton.pn_sasl_config_path(nil, path)
-      path
-    end
-
-    # @deprecated use {config_path=}
-    def self.config_path(path)
-      self.config_path = path
-    end
-
-    # Set the configuration file name, without extension
-    #
-    # The name with an a ".conf" extension will be searched for in the
-    # configuration path.  If not set, it defaults to "proton-server" or
-    # "proton-client" for a server (incoming) or client (outgoing) connection
-    # respectively.
-    #
-    # @param name the configuration file name without extension
-    #
-    def self.config_name=(name)
-      Cproton.pn_sasl_config_name(nil, name)
-    end
-
-    # @deprecated use {config_name=}
-    def self.config_name(name)
-      self.config_name = name
+    class << self
+      include Util::Deprecation
+
+      # Set the sasl configuration path
+      #
+      # This is used to tell SASL where to look for the configuration file.
+      # In the current implementation it can be a colon separated list of directories.
+      #
+      # The environment variable PN_SASL_CONFIG_PATH can also be used to set this path,
+      # but if both methods are used then this pn_sasl_config_path() will take precedence.
+      #
+      # If not set the underlying implementation default will be used.
+      #
+      # @param path the configuration path
+      #
+      def config_path=(path)
+        Cproton.pn_sasl_config_path(nil, path)
+        path
+      end
+
+      # Set the configuration file name, without extension
+      #
+      # The name with an a ".conf" extension will be searched for in the
+      # configuration path.  If not set, it defaults to "proton-server" or
+      # "proton-client" for a server (incoming) or client (outgoing) connection
+      # respectively.
+      #
+      # @param name the configuration file name without extension
+      #
+      def config_name=(name)
+        Cproton.pn_sasl_config_name(nil, name)
+      end
+
+      # @deprecated use {config_path=}
+      deprecated_alias :config_path, :config_path=
+      # @deprecated use {config_name=}
+      deprecated_alias :config_name, :config_name=
     end
   end
 end

data/lib/core/sender.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,7 +14,7 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#++
+
 
 module Qpid::Proton
 
@@ -28,49 +27,73 @@ module Qpid::Proton
     # @private
     include Util::ErrorHandler
 
-    # @private
-    can_raise_error :stream, :error_class => Qpid::Proton::LinkError
-
-    # Signals the availability of deliveries.
+    # Open the {Sender} link
     #
+    # @overload open_sender(address)
+    #   @param address [String] address of the target to send to
+    # @overload open_sender(opts)
+    #   @option opts [Boolean] :auto_settle (true) if true, automatically settle transfers
+    #   @option opts [Boolean] :dynamic (false) dynamic property for source {Terminus#dynamic}
+    #   @option opts [String,Hash] :source source address or source options, see {Terminus#apply}
+    #   @option opts [String,Hash] :target target address or target options, see {Terminus#apply}
+    #   @option opts [String] :name (generated) unique name for the link.
+    def open(opts=nil)
+      opts = { :target => opts } if opts.is_a? String
+      opts ||= {}
+      target.apply opts[:target]
+      source.apply opts[:source]
+      target.dynamic = !!opts[:dynamic]
+      @auto_settle = opts.fetch(:auto_settle, true)
+      super()
+      self
+    end
+
+    # @return [Boolean] auto_settle flag, see {#open}
+    attr_reader :auto_settle
+
+    # Hint to the remote receiver about the number of messages available.
+    # The receiver may use this to optimize credit flow, or may ignore it.
     # @param n [Integer] The number of deliveries potentially available.
-    #
     def offered(n)
       Cproton.pn_link_offered(@impl, n)
     end
 
-    # Sends the specified data to the remote endpoint.
-    #
-    # @param object [Object] The content to send.
-    # @param tag [Object] The tag
-    #
-    # @return [Integer] The number of bytes sent.
-    #
-    def send(object, tag = nil)
-      if object.respond_to? :proton_send
-        object.proton_send(self, tag)
-      else
-        stream(object)
+    # TODO aconway 2017-12-05: incompatible, used to return bytes sent.
+
+    # @!method send(message)
+    # Send a message.
+    # @param message [Message] The message to send.
+    # @return [Tracker] Tracks the outcome of the message.
+    def send(message, *args)
+      tag = nil
+      if args.size > 0
+        # deprecated: allow tag in args[0] for backwards compat
+        raise ArgumentError("too many arguments") if args.size > 1
+        tag = args[0]
       end
+      tag ||= next_tag
+      t = Tracker.new(Cproton.pn_delivery(@impl, tag))
+      Cproton.pn_link_send(@impl, message.encode)
+      Cproton.pn_link_advance(@impl)
+      t.settle if snd_settle_mode == SND_SETTLED
+      return t
     end
 
-    # Send the specified bytes as part of the current delivery.
-    #
-    # @param bytes [Array] The bytes to send.
-    #
-    # @return [Integer] The number of bytes sent.
-    #
+    # @deprecated use {#send}
     def stream(bytes)
+      deprecated __method__, "send"
       Cproton.pn_link_send(@impl, bytes)
     end
 
-    def delivery_tag
-      @tag_count ||= 0
-      result = @tag_count.succ
-      @tag_count = result
-      return "#{result}"
-    end
+    # @deprecated internal use only
+    def delivery_tag() deprecated(__method__); next_tag; end
 
-  end
+    private
 
+    def initialize(*arg) super; @tag_count = 0; end
+    def next_tag() (@tag_count += 1).to_s(32); end
+    can_raise_error :stream, :error_class => Qpid::Proton::LinkError
+  end
 end
+
+