reliable-msg 1.0.1 → 1.1.0

data/README

@@ -28,7 +28,7 @@ The latest version of Reliable Messaging can be found at
 
 For more information
 
-* http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/RubyReliableMessaging
+* http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/Ruby/ReliableMessaging
 
 
 == Installation
@@ -113,6 +113,10 @@ Stop the queue manager
 
   queues manager stop
 
+== Change log
+
+:include: changelog.txt
+
 
 == License
 

data/Rakefile

@@ -1,30 +1,35 @@
 # Adapted from the rake Rakefile.
 
-require 'rubygems'
+require "rubygems"
 Gem::manage_gems
-require 'rake/testtask'
-require 'rake/rdoctask'
-require 'rake/gempackagetask'
+require "rake/testtask"
+require "rake/rdoctask"
+require "rake/gempackagetask"
 
 
 desc "Default Task"
 task :default => [:tests, :rdoc]
 
 
-desc "Run test case for UUID generator"
-Rake::TestTask.new :test_uuid do |test|
+desc "Run test case for Queue API"
+Rake::TestTask.new :test_queue do |test|
     test.verbose = true
-    test.test_files = ['test/test-uuid.rb']
+    test.test_files = ["test/test-queue.rb"]
 end
-desc "Run test case for Queue API generator"
-Rake::TestTask.new :test_queue do |test|
+desc "Run test case for Topic API"
+Rake::TestTask.new :test_topic do |test|
+    test.verbose = true
+    test.test_files = ["test/test-topic.rb"]
+end
+desc "Run test case for Rails integration"
+Rake::TestTask.new :test_rails do |test|
     test.verbose = true
-    test.test_files = ['test/test-queue.rb']
+    test.test_files = ["test/test-rails.rb"]
 end
 desc "Run all test cases"
-Rake::TestTask.new :tests=>[:test_uuid, :test_queue] do |test|
+Rake::TestTask.new :tests do |test|
     test.verbose = true
-    test.test_files = []
+    test.test_files = ["test/*.rb"]
     #test.warning = true
 end
 
@@ -33,7 +38,7 @@ end
 Rake::RDocTask.new do |rdoc|
     rdoc.main = "README"
     rdoc.rdoc_files.include("README", "lib/**/*.rb")
-    rdoc.title = 'Reliable Messaging'
+    rdoc.title = "Reliable Messaging"
 end
 
 # Handle version number.
@@ -43,7 +48,7 @@ class Version
 
     def initialize file, new_version
         @file = file
-        @version = File.open @file, 'r' do |file|
+        @version = File.open @file, "r" do |file|
             version = nil
             file.each_line do |line|
                 match = line.match PATTERN
@@ -78,7 +83,7 @@ class Version
                 input.each_line do |line|
                     match = line.match PATTERN
                     if match
-                        output.puts "#{match[1]}VERSION = '#{@new_version}'"
+                        output.puts "#{match[1]}VERSION = \"#{@new_version}\""
                     else
                         output.puts line
                     end
@@ -90,12 +95,12 @@ class Version
     end
 
 end
-version = Version.new 'lib/reliable-msg.rb', ENV['version']
+version = Version.new "lib/reliable-msg.rb", ENV["version"]
 
 
 # Create the GEM package.
 gem_spec = Gem::Specification.new do |spec|
-    spec.name = 'reliable-msg'
+    spec.name = "reliable-msg"
     spec.version = version.next
     spec.summary = "Reliable messaging and persistent queues for building asynchronous applications in Ruby"
     spec.description = <<-EOF
@@ -108,18 +113,20 @@ gem_spec = Gem::Specification.new do |spec|
 EOF
     spec.author = "Assaf Arkin"
     spec.email = "assaf@labnotes.org"
-    spec.homepage = "http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/RubyReliableMessaging"
+    spec.homepage = "http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/Ruby/ReliableMessaging"
 
-    spec.files = FileList["{bin,test,lib,docs}/**/*", "README", "MIT-LICENSE", "Rakefile"].to_a
+    spec.files = FileList["{bin,test,lib,docs}/**/*", "README", "MIT-LICENSE", "Rakefile", "changelog.txt"].to_a
     spec.require_path = "lib"
-    spec.autorequire = 'reliable-msg.rb'
+    spec.autorequire = "reliable-msg.rb"
     spec.bindir = "bin"
     spec.executables = ["queues"]
     spec.default_executable = "queues"
     spec.requirements << "MySQL for database store, otherwise uses the file system"
     spec.has_rdoc = true
-    spec.rdoc_options << '--main' << 'README' << '--title' <<  'Reliable Messaging for Ruby' << '--line-numbers'
+    spec.rdoc_options << "--main" << "README" << "--title" <<  "Reliable Messaging for Ruby" << "--line-numbers"
     spec.extra_rdoc_files = ["README"]
+    spec.rubyforge_project = "reliable-msg"
+    spec.add_dependency(%q<uuid>, [">= 1.0.0"])
 end
 
 gem = Rake::GemPackageTask.new(gem_spec) do |pkg|
@@ -130,7 +137,7 @@ end
 
 desc "Look for TODO and FIXME tags in the code"
 task :todo do
-  FileList['**/*.rb'].egrep /#.*(FIXME|TODO|TBD)/
+  FileList["**/*.rb"].egrep /#.*(FIXME|TODO|TBD)/
 end
 
 
@@ -148,7 +155,7 @@ task :release => [:tests, :prerelease, :clobber, :update_version, :package] do
 end
 
 task :prerelease do
-    if !version.changed? && ENV['reuse'] != version.number
+    if !version.changed? && ENV["reuse"] != version.number
         fail "Current version is #{version.number}, must specify reuse=ver to reuse existing version"
     end
 end

data/changelog.txt

@@ -0,0 +1,32 @@
+Release 1.1.0 (Nov 26, 2005)
+
+* Added: Topic class for publishing messages on a topic.
+* Added: Can set delivery option when creating a queue.
+* Added: Queue.name() returns the queue's name.
+* Added: Command line options to list or delete all messages
+  in named queue.
+* Added: Rails integration for easily accessing queues/topics
+  from a Rails controller.
+* Changed: Quque and Topic both extend the base class Client.
+* Changed: Cannot start two queue managers in the same process.
+* Changed: Each message has a created header indicating date/time
+  of creation. Received header no longer exists.
+* Changed: Header retry renamed to delivered, to prevent clash with
+  reserved Ruby keyword.
+* Changed: Selectors are now executed in the client process.
+  Selectors can rely on client variables, methods and constants.
+* Changed: Specify maximum delivery attempts with the header
+  max_deliveries; get the redelivery attempt from the header
+  redelivery; the later is only set on the first redelivery attempt.
+* Fixed: Documentation errors in Queue.
+* Removed: Cannot associate default selector with queue.
+
+
+Release 1.0.1 (Nov 10, 2005)
+
+* Added: Test cases test put/get in memory and by reloading.
+* Fixed: Messages not retrieved in order after queue manager
+  recovers when using MySQL message store.
+* Fixed: Queue manager fails if stopped and then started again.
+
+

data/lib/reliable-msg.rb

@@ -1,12 +1,17 @@
-$:.unshift(File.dirname(__FILE__)) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 module ReliableMsg
 
     PACKAGE = "reliable-msg"
-    VERSION = '1.0.1'
+    VERSION = "1.1.0"
 
 end
 
-require 'reliable-msg/queue'
-require 'reliable-msg/cli'
+require "reliable-msg/queue"
+require "reliable-msg/topic"
+require "reliable-msg/cli"
+begin
+    require "reliable-msg/rails"
+rescue LoadError
+end

data/lib/reliable-msg/cli.rb

@@ -2,12 +2,11 @@
 # = cli.rb - Reliable messaging command-line interface
 #
 # Author:: Assaf Arkin  assaf@labnotes.org
-# Documentation:: http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/RubyReliableMessaging
+# Documentation:: http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/Ruby/ReliableMessaging
 # Copyright:: Copyright (c) 2005 Assaf Arkin
 # License:: MIT and/or Creative Commons Attribution-ShareAlike
 #
 #--
-# Changes:
 #++
 
 
@@ -43,6 +42,12 @@ Available commands:
   manager stop
     Stop a running queue manager.
 
+  list <queue>
+    List headers of messages in the named queue.
+
+  empty <queue>
+    Empty (delete all messages from) the named queue.
+
   install disk [<path>]
     Configure queue manager to use disk-based message store
     using the specified directory. Uses 'queues' by default.
@@ -68,7 +73,9 @@ Available options:
 
 EOF
 
-        class InvalidUsage  < Exception
+        MAX_STRING = 50
+
+        class InvalidUsage  < Exception #:nodoc:
         end
 
         def initialize
@@ -149,6 +156,43 @@ EOF
                         raise InvalidUsage
                     end
 
+                when 'list'
+                    queue = args[1]
+                    raise InvalidUsage unless queue
+                    begin
+                        qm = queue_manager(config_file)
+                        list = qm.list(:queue=>queue)
+                        puts "Found #{list.size} messages in queue #{queue}"
+                        list.each do |headers|
+                            puts "Message #{headers[:id]}"
+                            headers.each do |name, value|
+                                unless name==:id
+                                    case value
+                                    when String
+                                        value = value[0..MAX_STRING - 3] << "..." if value.length > MAX_STRING
+                                        value = '"' << value.gsub('"', '\"') << '"'
+                                    when Symbol
+                                        value = ":#{value.to_s}"
+                                    end
+                                    puts "  :#{name} => #{value}"
+                                end
+                            end
+                        end
+                    rescue DRb::DRbConnError =>error
+                        puts "Cannot access queue manager: is it running?"
+                    end
+
+                when 'empty'
+                    queue = args[1]
+                    raise InvalidUsage unless queue
+                    begin
+                        qm = queue_manager(config_file)
+                        while msg = qm.enqueue(:queue=>queue)
+                        end
+                    rescue DRb::DRbConnError =>error
+                        puts "Cannot access queue manager: is it running?"
+                    end
+
                 else
                     raise InvalidUsage
             end

data/lib/reliable-msg/client.rb

@@ -0,0 +1,213 @@
+#
+# = client.rb - Base class for queue/topic API
+#
+# Author:: Assaf Arkin  assaf@labnotes.org
+# Documentation:: http://trac.labnotes.org/cgi-bin/trac.cgi/wiki/Ruby/ReliableMessaging
+# Copyright:: Copyright (c) 2005 Assaf Arkin
+# License:: MIT and/or Creative Commons Attribution-ShareAlike
+#
+#--
+#++
+
+require 'drb'
+require 'reliable-msg/selector'
+
+
+module ReliableMsg
+
+    # Base class for both Queue and Topic client APIs.
+    class Client
+
+        ERROR_INVALID_SELECTOR = "Selector must be message identifier (String), set of header name/value pairs (Hash), Selector object, or nil" # :nodoc:
+
+        ERROR_INVALID_TX_TIMEOUT = "Invalid transaction timeout: must be a non-zero positive integer" # :nodoc:
+
+        ERROR_INVALID_CONNECT_COUNT = "Invalid connection count: must be a non-zero positive integer" # :nodoc:
+
+        ERROR_SELECTOR_VALUE_OR_BLOCK = "You can either pass a Selector object, or use a block" # :nodoc:
+
+        ERROR_INVALID_INIT_OPTION = "Unrecognized initialization option %s" #:nodoc:
+
+        # The default DRb port used to connect to the queue manager.
+        DRB_PORT = 6438
+
+        DEFAULT_DRB_URI = "druby://localhost:#{DRB_PORT}" #:nodoc:
+
+        # Number of times to retry a connecting to the queue manager.
+        DEFAULT_CONNECT_RETRY = 5
+
+        # Default transaction timeout.
+        DEFAULT_TX_TIMEOUT = 120
+
+        # Thread.current entry for queue transaction.
+        THREAD_CURRENT_TX = :reliable_msg_tx #:nodoc:
+
+        # The name of the dead letter queue (<tt>DLQ</tt>). Messages that expire or fail
+        # to process are automatically sent to the dead letter queue.
+        DLQ = DEAD_LETTER_QUEUE = "$dlq"
+
+        # DRb URI for queue manager. You can override this to change the URI globally,
+        # for all Queue objects that are not instantiated with an alternative URI.
+        @@drb_uri = DEFAULT_DRB_URI
+
+        # Reference to the local queue manager. Defaults to a DRb object, unless
+        # the queue manager is running locally.
+        @@qm = nil #:nodoc:
+
+        # Cache of queue managers referenced by their URI.
+        @@qm_cache = {} #:nodoc:
+
+        # Returns the transaction timeout (in seconds).
+        def tx_timeout
+            @tx_timeout || DEFAULT_TX_TIMEOUT
+        end
+
+        # Sets the transaction timeout (in seconds). Affects future transactions started
+        # by Queue.get. Use +nil+ to restore the default timeout.
+        def tx_timeout= timeout
+            if timeout
+                raise ArgumentError, ERROR_INVALID_TX_TIMEOUT unless timeout.instance_of?(Integer) and timeout > 0
+                @tx_timeout = timeout
+            else
+                @tx_timeout = nil
+            end
+        end
+
+        # Returns the number of connection attempts, before operations fail.
+        def connect_count
+            @connect_count || DEFAULT_CONNECT_RETRY
+        end
+
+        # Sets the number of connection attempts, before operations fail. The minimum is one.
+        # Use +nil+ to restore the default connection count.
+        def connect_count= count
+            if count
+                raise ArgumentError, ERROR_INVALID_CONNECT_COUNT unless count.instance_of?(Integer) and count > 0
+                @connect_count = count
+            else
+                @connect_count = nil
+            end
+        end
+
+        # Create and return a new selector based on the block expression. Same as
+        # Selector.new. For example:
+        #   selector = Queue.selector { priority >= 2 and received > Time.new.to_i - 60 }
+        def self.selector &block
+            raise ArgumentError, ERROR_NO_SELECTOR_BLOCK unless block
+            Selector.new &block
+        end
+
+        # Create and return a new selector based on the block expression. Same as
+        # Selector.new. For example:
+        #   selector = Queue.selector { priority >= 2 and received > Time.new.to_i - 60 }
+        def selector & block
+            raise ArgumentError, ERROR_NO_SELECTOR_BLOCK unless block
+            Selector.new &block
+        end
+
+    private
+
+        # Returns the active queue manager. You can override this method to implement
+        # load balancing.
+        def qm
+            if uri = @drb_uri
+                # Queue specifies queue manager's URI: use that queue manager.
+                @@qm_cache[uri] ||= DRbObject.new(nil, uri)
+            else
+                # Use the same queue manager for all queues, and cache it.
+                # Create only the first time.
+                @@qm ||= DRbObject.new(nil, @@drb_uri || DEFAULT_DRB_URI)
+            end
+        end
+
+        # Called to execute the operation repeatedly and avoid connection failures. This only
+        # makes sense if we have a load balancing algorithm.
+        def repeated &block
+            count = connect_count
+            begin
+                block.call qm
+            rescue DRb::DRbConnError=>error
+                warn error
+                warn error.backtrace
+                retry if (count -= 1) > 0
+                raise error
+            end
+        end
+
+        class << self
+        private
+            # Sets the active queue manager. Used when the queue manager is running in the
+            # same process to bypass DRb calls.
+            def qm= qm
+                @@qm = qm
+            end
+        end
+
+    end
+
+
+    # == Retrieved Message
+    #
+    # Returned from Queue.get holding the last message retrieved from the
+    # queue and providing access to the message identifier, headers and object.
+    #
+    # For example:
+    #   while queue.get do |msg|
+    #     print "Message #{msg.id}"
+    #     print "Headers: #{msg[:created]}"
+    #     print "Headers: #{msg.headers.inspect}"
+    #     print msg.object
+    #     true
+    #   end
+    class Message
+
+        def initialize id, headers, object # :nodoc:
+            @id, @object, @headers = id, object, headers
+        end
+
+        # Returns the message identifier.
+        #
+        # :call-seq:
+        #   msg.id -> id
+        #
+        def id
+            @id
+        end
+
+        # Returns the message object.
+        #
+        # :call-seq:
+        #   msg.object -> obj
+        #
+        def object
+            @object
+        end
+
+        # Returns the message headers.
+        #
+        # :call-seq:
+        #   msg.headers -> hash
+        #
+        def headers
+            @headers
+        end
+
+        # Returns the message header.
+        #
+        # :call-seq:
+        #   msg[symbol] -> obj
+        #
+        def [] symbol
+            @headers[symbol]
+        end
+
+    private
+        def method_missing symbol, *args, &block
+            raise ArgumentError, "Wrong number of arguments (#{args.length} for 0)" unless args.empty?
+            @headers[symbol]
+        end
+
+    end
+
+end
+