qpid_proton 0.8 → 0.9.0

data/lib/qpid_proton/messenger.rb

@@ -17,9 +17,9 @@
 # under the License.
 #
 
-module Qpid
+module Qpid # :nodoc:
 
-  module Proton
+  module Proton # :nodoc:
 
     # The +Messenger+ class defines a high level interface for
     # sending and receiving Messages. Every Messenger contains
@@ -59,6 +59,11 @@ module Qpid
 
       include Qpid::Proton::ExceptionHandling
 
+      can_raise_exception [:send, :receive, :password=, :start, :stop,
+                           :perform_put, :perform_get, :interrupt,
+                           :route, :rewrite, :accept, :reject,
+                           :incoming_window=, :outgoing_window=]
+
       # Creates a new +Messenger+.
       #
       # The +name+ parameter is optional. If one is not provided then
@@ -94,7 +99,7 @@ module Qpid
       # * password - the password
       #
       def password=(password)
-        check_for_error(Cproton.pn_messenger_set_password(@impl, password))
+        Cproton.pn_messenger_set_password(@impl, password)
       end
 
       # Returns the password property for the Messenger.private_key file.
@@ -179,25 +184,34 @@ module Qpid
         Cproton.pn_error_text(Cproton.pn_messenger_error(@impl))
       end
 
+      # Clears the current error state.
+      #
+      def clear_error
+        error = Cproton.pn_messenger_error(@impl)
+        unless error.nil?
+          Cproton.pn_error_clear(error)
+        end
+      end
+
       # Currently a no-op placeholder.
       # For future compatibility, do not send or recv messages
       # before starting the +Messenger+.
       #
       def start
-        check_for_error(Cproton.pn_messenger_start(@impl))
+        Cproton.pn_messenger_start(@impl)
       end
 
       # Stops the +Messenger+, preventing it from sending or receiving
       # any more messages.
       #
       def stop
-        check_for_error(Cproton.pn_messenger_stop(@impl))
+        Cproton.pn_messenger_stop(@impl)
       end
 
-      # Returns true iff a Messenger is in the stopped state.
+      # Returns true if a Messenger is in the stopped state.
       # This function does not block.
       #
-      def stopped
+      def stopped?
         Cproton.pn_messenger_stopped(@impl)
       end
 
@@ -207,13 +221,19 @@ module Qpid
       # domain portion of the address begins with the '~' character, the
       # Messenger will interpret the domain as host/port, bind to it,
       # and listen for incoming messages. For example "~0.0.0.0",
-      # "amqp://~0.0.0.0" will all bind to any local interface and 
-      # listen for incoming messages.  Ad address of # "amqps://~0.0.0.0" 
+      # "amqp://~0.0.0.0" will all bind to any local interface and
+      # listen for incoming messages.  An address of "amqps://~0.0.0.0"
       # will only permit incoming SSL connections.
       #
-      def subscribe(address)
+      # ==== Options
+      #
+      # * address - the source address to be subscribe
+      # * timeout - an optional time-to-live value, in seconds, for the
+      #             subscription
+      #
+      def subscribe(address, timeout=0)
         raise TypeError.new("invalid address: #{address}") if address.nil?
-        subscription = Cproton.pn_messenger_subscribe(@impl, address)
+        subscription = Cproton.pn_messenger_subscribe_ttl(@impl, address, timeout)
         raise Qpid::Proton::ProtonError.new("Subscribe failed") if subscription.nil?
         Qpid::Proton::Subscription.new(subscription)
       end
@@ -282,10 +302,10 @@ module Qpid
       # Places the content contained in the message onto the outgoing
       # queue of the Messenger.
       #
-      # This method will never block, however it will send any unblocked 
+      # This method will never block, however it will send any unblocked
       # Messages in the outgoing queue immediately and leave any blocked
       # Messages remaining in the outgoing queue.
-      # The send call may then be used to block until the outgoing queue 
+      # The send call may then be used to block until the outgoing queue
       # is empty.  The outgoing attribute may be used to check the depth
       # of the outgoing queue.
       #
@@ -298,18 +318,27 @@ module Qpid
         raise ArgumentError.new("invalid message type: #{message.class}") unless message.kind_of?(Message)
         # encode the message first
         message.pre_encode
-        check_for_error(Cproton.pn_messenger_put(@impl, message.impl))
+        perform_put(message)
         return outgoing_tracker
       end
 
+      private
+
+      def perform_put(message) # :nodoc:
+        Cproton.pn_messenger_put(@impl, message.impl)
+      end
+
+      public
+
+
       # This call will block until the indicated number of messages
       # have been sent, or until the operation times out.
-      # If n is -1 this call will block until all outgoing messages 
-      # have been sent. If n is 0 then this call will send whatever 
+      # If n is -1 this call will block until all outgoing messages
+      # have been sent. If n is 0 then this call will send whatever
       # it can without blocking.
       #
       def send(n = -1)
-        check_for_error(Cproton.pn_messenger_send(@impl, n))
+        Cproton.pn_messenger_send(@impl, n)
       end
 
       # Moves the message from the head of the incoming message queue into
@@ -333,11 +362,19 @@ module Qpid
         else
           msg_impl = msg.impl
         end
-        check_for_error(Cproton.pn_messenger_get(@impl, msg_impl))
+        perform_get(msg_impl)
         msg.post_decode unless msg.nil?
         return incoming_tracker
       end
 
+      private
+
+      def perform_get(msg) # :nodoc:
+        Cproton.pn_messenger_get(@impl, msg)
+      end
+
+      public
+
       # Receives up to limit messages into the incoming queue.  If no value
       # for limit is supplied, this call will receive as many messages as it
       # can buffer internally.  If the Messenger is in blocking mode, this
@@ -349,10 +386,11 @@ module Qpid
       # * limit - the maximum number of messages to receive
       #
       def receive(limit = -1)
-        check_for_error(Cproton.pn_messenger_recv(@impl, limit))
+        Cproton.pn_messenger_recv(@impl, limit)
       end
 
-      def receiving
+      # Returns true if the messenger is currently receiving data.
+      def receiving?
         Cproton.pn_messenger_receiving(@impl)
       end
 
@@ -369,7 +407,7 @@ module Qpid
       # originated the interrupt.
       #
       def interrupt
-        check_for_error(Cproton.pn_messenger_interrupt(@impl))
+        Cproton.pn_messenger_interrupt(@impl)
       end
 
       # Sends or receives any outstanding messages queued for a Messenger.
@@ -377,7 +415,7 @@ module Qpid
       # This will block for the indicated timeout.  This method may also do I/O
       # other than sending and receiving messages.  For example, closing
       # connections after stop() has been called.
-      # 
+      #
       def work(timeout=-1)
         err = Cproton.pn_messenger_work(@impl, timeout)
         if (err == Cproton::PN_TIMEOUT) then
@@ -457,7 +495,7 @@ module Qpid
       #   messenger.route("*", "amqp://user:password@broker/$1")
       #
       def route(pattern, address)
-        check_for_error(Cproton.pn_messenger_route(@impl, pattern, address))
+        Cproton.pn_messenger_route(@impl, pattern, address)
       end
 
       # Similar to #route, except that the destination of
@@ -479,7 +517,7 @@ module Qpid
       # * address - the target address
       #
       def rewrite(pattern, address)
-        check_for_error(Cproton.pn_messenger_rewrite(@impl, pattern, address))
+        Cproton.pn_messenger_rewrite(@impl, pattern, address)
       end
 
       def selectable
@@ -533,7 +571,7 @@ module Qpid
         else
           flag = 0
         end
-        check_for_error(Cproton.pn_messenger_accept(@impl, tracker.impl, flag))
+        Cproton.pn_messenger_accept(@impl, tracker.impl, flag)
       end
 
       # Rejects the incoming message identified by the tracker.
@@ -553,13 +591,13 @@ module Qpid
         else
           flag = 0
         end
-        check_for_error(Cproton.pn_messenger_reject(@impl, tracker.impl, flag))
+        Cproton.pn_messenger_reject(@impl, tracker.impl, flag)
       end
 
       # Gets the last known remote state of the delivery associated with
-      # the given tracker, as long as the Message is still within your 
-      # outgoing window. (Also works on incoming messages that are still 
-      # within your incoming queue. See TrackerStatus for details on the 
+      # the given tracker, as long as the Message is still within your
+      # outgoing window. (Also works on incoming messages that are still
+      # within your incoming queue. See TrackerStatus for details on the
       # values returned.
       #
       # ==== Options
@@ -594,13 +632,13 @@ module Qpid
 
       # Sets the incoming window.
       #
-      # The Messenger will track the remote status of this many incoming 
+      # The Messenger will track the remote status of this many incoming
       # deliveries after they have been accepted or rejected.
       #
       # Messages enter this window only when you take them into your application
       # using get().  If your incoming window size is n, and you get n+1 messages
       # without explicitly accepting or rejecting the oldest message, then the
-      # message that passes beyond the edge of the incoming window will be 
+      # message that passes beyond the edge of the incoming window will be
       # assigned the default disposition of its link.
       #
       # ==== Options
@@ -609,7 +647,7 @@ module Qpid
       #
       def incoming_window=(window)
         raise TypeError.new("invalid window: #{window}") unless valid_window?(window)
-        check_for_error(Cproton.pn_messenger_set_incoming_window(@impl, window))
+        Cproton.pn_messenger_set_incoming_window(@impl, window)
       end
 
       # Returns the incoming window.
@@ -620,7 +658,7 @@ module Qpid
 
       # Sets the outgoing window.
       #
-      # The Messenger will track the remote status of this many outgoing 
+      # The Messenger will track the remote status of this many outgoing
       # deliveries after calling send.
       # A Message enters this window when you call the put() method with the
       # message.  If your outgoing window size is n, and you call put n+1
@@ -633,7 +671,7 @@ module Qpid
       #
       def outgoing_window=(window)
         raise TypeError.new("invalid window: #{window}") unless valid_window?(window)
-        check_for_error(Cproton.pn_messenger_set_outgoing_window(@impl, window))
+        Cproton.pn_messenger_set_outgoing_window(@impl, window)
       end
 
       # Returns the outgoing window.

data/lib/qpid_proton/selectable.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,11 +15,11 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
-module Qpid
+module Qpid # :nodoc:
 
-  module Proton
+  module Proton # :nodoc:
 
     # Selectable enables accessing the underlying file descriptors
     # for Messenger.

data/lib/qpid_proton/strings.rb

@@ -0,0 +1,65 @@
+#--
+# 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 # :nodoc:
+
+  module Proton # :nodoc:
+
+    def self.is_valid_utf?(value)
+      # In Ruby 1.9+ we have encoding methods that can check the content of
+      # the string, so use them to see if what we have is unicode. If so,
+      # good! If not, then just treat is as binary.
+      #
+      # No such thing in Ruby 1.8. So there we need to use Iconv to try and
+      # convert it to unicode. If it works, good! But if it raises an
+      # exception then we'll treat it as binary.
+      if RUBY_VERSION < "1.9"
+        return true if value.isutf8
+        return false
+      else
+        return true if (value.encoding == "UTF-8" ||
+                        value.encode("UTF-8").valid_encoding?)
+
+        return false
+      end
+    end
+
+    # UTFString lets an application explicitly state that a
+    # string of characters is to be UTF-8 encoded.
+    #
+    class UTFString < ::String
+
+      def initialize(value)
+        if !Qpid::Proton.is_valid_utf?(value)
+          raise RuntimeError.new("invalid UTF string")
+        end
+
+        super(value)
+      end
+
+    end
+
+    # BinaryString lets an application explicitly declare that
+    # a string value represents arbitrary data.
+    #
+    class BinaryString < ::String; end
+
+  end
+
+end

data/lib/qpid_proton/subscription.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,11 +15,11 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
-module Qpid
+module Qpid # :nodoc:
 
-  module Proton
+  module Proton # :nodoc:
 
     # A +Subscription+ is an opaque object for working with a +Messenger+'s
     # subscriptions.

data/lib/qpid_proton/tracker.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,11 +15,11 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
-module Qpid
+module Qpid # :nodoc:
 
-  module Proton
+  module Proton # :nodoc:
 
     # A +Tracker+ is used to track the disposition of a +Message+.
     #

data/lib/qpid_proton/tracker_status.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,11 +15,11 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
-module Qpid
+module Qpid # :nodoc:
 
-  module Proton
+  module Proton # :nodoc:
 
     # TrackerStatus contains symbols that represent the status value for a
     # Tracker.

data/lib/qpid_proton/version.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,13 +15,16 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-#
+#++
 
-module Qpid
+module Qpid # :nodoc:
 
-  module Proton
+  module Proton # :nodoc:
 
+    # The major version for the underlying Proton library.
     VERSION_MAJOR = Cproton::PN_VERSION_MAJOR
+
+    # The minor version for the underlying Proton library.
     VERSION_MINOR = Cproton::PN_VERSION_MINOR
 
   end