fmq 0.1.0 → 0.1.1

data/bin/fmq

@@ -4,20 +4,26 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
 #
-
+# == Command line options
+#
+#  usage: /usr/bin/fmq [create <project_name>]
+#
+# * Invocation without parameter will start server
+# * Invocation with parameter <em>create</em> *project_name* 
+#   will create a project folder with the name *project_name*  
 begin
   require "fmq"
 rescue LoadError

data/default-server/config.yml

@@ -40,6 +40,14 @@ queue-manager:
     test-queue-3:
       path: /fmq_test/test3
       class: MyTestQueue
+    # this is a forwarding queue wich forwards one message
+    # to some other queues
+    test-queue-forward:
+      path: /fmq_test/forward_to_1_and_2
+      class: FreeMessageQueue::ForwardQueue
+      # you can add as may queues as you want
+      # but seperate them with a space char
+      forward_to: /fmq_test/test1 /fmq_test/test2
     # the admin queue is a special queue, that is used to
     # administrate the queue_manager
     admin-page-backend:

data/lib/fmq.rb

@@ -3,18 +3,18 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
 #
 
 # load all queues and manager and server

data/lib/fmq/boot.rb

@@ -3,18 +3,18 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
 #
 require 'yaml' 
 require 'logger'
@@ -25,16 +25,29 @@ require File.dirname(__FILE__) + '/queue_manager'
 require File.dirname(__FILE__) + '/mongrel_server'
 
 module FreeMessageQueue
+  # This is the standard server header that will be used by mongel and other web servers
   SERVER_HEADER = "FMQ/#{FreeMessageQueue::VERSION::STRING} (#{RUBY_PLATFORM}) Ruby/#{RUBY_VERSION}"
   
+  # This method returns the ruby logger instance for the
+  # free message queue, so that it is simple to access
+  # the logger from somewhere in the project 
   def self.logger
     $FMQ_GLOBAL_LOGGER
   end
   
+  # This method creates the logger instance once (even if it is called twice).
   def self.create_logger(log_to = STDOUT)
     $FMQ_GLOBAL_LOGGER ||= Logger.new(log_to)
   end
   
+  # This method sets the log level of the fmq logger
+  # the level must be a string (either downcase or upcase)
+  # that contains one of the following levels:
+  # * FATAL => Server side errors
+  # * ERROR => Server side error backtraces
+  # * WARN  => Client side errors
+  # * INFO  => Setup information (config stuff etc.)
+  # * DEBUG => All operations of the queue manager and others
   def self.set_log_level(level)
     case level
       when /fatal/i
@@ -51,7 +64,12 @@ module FreeMessageQueue
     FreeMessageQueue.logger.debug "[Logger] set log level to #{level}"
   end
   
+  # The class implements a simple interface to the configuration file
+  # and creates and setup the logger instance
   class Configuration
+    # the yaml config file from <em>file_path</em> will be read and 
+    # parsed. After parsing the global free message queue logger is
+    # created and setup vor further use
     def initialize(file_path)
       # open and read file
       f = open(file_path, "r")
@@ -59,28 +77,36 @@ module FreeMessageQueue
       f.close
       @config = YAML.load( data )
       
-      # set log level
+      # create logger and setup log level
+      @log = FreeMessageQueue.create_logger
       FreeMessageQueue.set_log_level(server["log-level"])
       
       # debug the configuration
-      FreeMessageQueue.logger.debug("[Configuration] Server: " + YAML.dump(server))
-      FreeMessageQueue.logger.debug("[Configuration] QueueManager: " + YAML.dump(queue_manager))
+      @log.debug("[Configuration] Server: " + YAML.dump(server))
+      @log.debug("[Configuration] QueueManager: " + YAML.dump(queue_manager))
     end
     
+    # the configuration for the server (MongrelHandler, ...)
     def server
       @config["server"]
     end
     
+    # the configuration for the queue manager
     def queue_manager
       @config["queue-manager"]
     end
   end
   
+  # Boot deals with the tasks to create up a project and start the server etc.
   class Boot
+    # The configuration file <em>config.yml</em> must be in the same directory.
+    # It is the starting point for booting the server.
+    # After reading the configuration the QueueManager and HttpServer (MongrelHandler)
+    # will be created and start listening.
+    # This method will stop when the server goes down otherwise it will run infinitely
     def self.start_server
-      # create logger and setup log level
-      logger = FreeMessageQueue.create_logger
       conf = FreeMessageQueue::Configuration.new("config.yml")
+      logger = FreeMessageQueue.logger
       
       # create queue manager
       queue_manager = FreeMessageQueue::QueueManager.new(conf.queue_manager)
@@ -92,6 +118,13 @@ module FreeMessageQueue
       servsock.run.join
     end
     
+    # This message will copy the <em>default-server</em> project files
+    # to the passed (<em>project_name</em>) location.
+    # The <em>default-server</em> contains some basic and sample stuff
+    # so that the free message queue can be used as fast as possible. Including:
+    # * The Admin UI (Ajax Interface) => so that you can make changes
+    # * The default configuration => with some sample queues
+    # * A custom queue implementation => to basically show how to create my own queues
     def self.create_project(project_name)
       FileUtils.cp_r(File.dirname(__FILE__) + '/../../default-server', project_name)
     end

data/lib/fmq/client.rb

@@ -3,28 +3,56 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
 #
 require 'net/http'
 
 module FreeMessageQueue
+  # Here you can find the client side api for the free message queue.
+  # This api is build using the net/http facilitys
+  #
+  # Some sample usage of the client api:
+  #
+  #  require "fmq"
+  #  
+  #  # queue adress
+  #  QA = "http://localhost/webserver_agent/urgent_messages"
+  #  
+  #  my_remote_queue = FreeMessageQueue::ClientQueue.new(QA)
+  #  
+  #  # pick one message
+  #  msg = my_remote_queue.get()
+  #  puts " == URGENT MESSSAGE == "
+  #  puts msg
+  #  
+  #  # put an urgent message on the queue e.g.in yaml
+  #  msg = "
+  #    title: server don't answer a ping request
+  #    date_time: 2008-06-01 20:19:28
+  #    server: 10.10.30.62
+  #  "
+  #  
+  #  my_remote_queue.put(msg)
+  #
   class ClientQueue
+    # create a connection to a queue (by url)
     def initialize(url)
       @url = url
     end
-    
-    def get()
+
+    # this returns one message from the queue as a string
+    def poll()
       url = URI.parse(@url)
       req = Net::HTTP::Get.new(url.path)
       res = Net::HTTP.start(url.host, url.port) do |http|
@@ -33,11 +61,16 @@ module FreeMessageQueue
       res.body
     end
     
+    alias get poll
+    
+    # this puts one message to the queue as a string
     def put(data)
       url = URI.parse(@url)
       res = Net::HTTP.start(url.host, url.port) do |http|
         http.post(url.path, data)
       end
     end
+    
+    alias post put
   end
 end

data/lib/fmq/mongrel_server.rb

@@ -4,18 +4,18 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
 #
 begin
   require "mongrel"
@@ -25,12 +25,17 @@ rescue LoadError
 end
 
 module FreeMessageQueue
+  # This implements the MongrelServlet that serves free message queue
+  # in a mongrel enviroment
   class MongrelHandler < Mongrel::HttpHandler
+    # When creationg a mongrel handler you have to pass the <em>queue_manager</em>
+    # that should be distributed by mongrel
     def initialize(queue_manager)
       @queue_manager = queue_manager
       @log = FreeMessageQueue.logger
     end
   
+    # Process incoming request and send them to the right sub processing method like <em>process_get</em>
     def process(request, response)
       queue_path = request.params["REQUEST_PATH"]
       method = request.params["REQUEST_METHOD"]
@@ -42,7 +47,8 @@ module FreeMessageQueue
         if method.match(/^(GET|POST|HEAD|DELETE)$/) then
           self.send("process_" + method.downcase, request, response, queue_path)
         else
-          raise QueueManagerException.new("[MongrelHandler] Method is not supported '#{method}'", caller)
+          client_exception(request, response, queue_path, 
+            ArgumentError.new("[MongrelHandler] Method is not supported '#{method}'"))
         end
       rescue QueueManagerException => ex
         client_exception(request, response, queue_path, ex)
@@ -51,10 +57,10 @@ module FreeMessageQueue
       end
     end
   
-  private
+  protected
   
-    # returns an item from queue and sends it to the client
-    # if there is no item to fetch send an 204 (NoContent) and same as HEAD
+    # Returns an item from queue and sends it to the client.
+    # If there is no item to fetch send an 204 (NoContent) and same as HEAD
     def process_get(request, response, queue_path)
       queue_item = @queue_manager.poll(queue_path)
       
@@ -78,7 +84,7 @@ module FreeMessageQueue
       end
     end
     
-    # put new item to the queue and and return sam e as head action
+    # Put new item to the queue and and return sam e as head action (HTTP 200)
     def process_post(request, response, queue_path)
       @log.debug("[MongrelHandler] Response to POST (200)")
       data = request.body.read
@@ -91,7 +97,7 @@ module FreeMessageQueue
       end
     end
     
-    # just return server header and queue size
+    # Just return server header and queue size (HTTP 200)
     def process_head(request, response, queue_path)
       @log.debug("[MongrelHandler] Response to HEAD (200)")
       
@@ -101,7 +107,7 @@ module FreeMessageQueue
       end
     end
     
-    # delete the queue and return server header
+    # Delete the queue and return server header (HTTP 200)
     def process_delete(request, response, queue_path)
       @log.debug("[MongrelHandler] Response to DELETE (200)")
       @queue_manager.delete_queue(queue_path)
@@ -111,7 +117,9 @@ module FreeMessageQueue
       end
     end
     
-    # inform the client that he did something wrong
+    # Inform the client that he did something wrong (HTTP 400).
+    # HTTP-Header field Error contains information about the problem.
+    # The client errorwill also be reported to warn level of logger.
     def client_exception(request, response, queue_path, ex)
       @log.warn("[MongrelHandler] Client error: #{ex}")
       response.start(400) do |head,out|
@@ -120,7 +128,10 @@ module FreeMessageQueue
       end
     end
     
-    # report server error
+    # Report server error (HTTP 500).
+    # HTTP-Header field Error contains information about the problem.
+    # The body of the response contains the full stack trace.
+    # The error and stack trace will also be reported to logger.
     def server_exception(request, response, queue_path, ex)
       @log.fatal("[MongrelHandler] System error: #{ex}")
       for line in ex.backtrace

data/lib/fmq/queue_manager.rb

@@ -3,36 +3,52 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
 # 
 module FreeMessageQueue
-  class QueueManagerException < RuntimeError
+  # All queue manager exceptions are raised using this class
+  class QueueManagerException < Exception
     attr_accessor :message, :backtrace
   
-    def initialize(message, callstack)
+    # Create exception with message and backtrace (if needed)
+    def initialize(message, callstack = [])
       @message = message
       @backtrace = callstack
     end
     
+    # Returns the message of the exception
     def to_s
       @message
     end
   end
 
+  # The queue manager is one of the core components of the system.
+  # This component manages the queues by pathname and checks on the
+  # corresponding constraints. Every queue that is created by this
+  # queue manager will get a reference (<em>manager</em>) for later use.
   class QueueManager
+    # This value is used to decribe that a constraint has no limit e.g.
+    #  :max_messages => INFINITE
+    # means that there is no limitation for messages
     INFINITE = -1
+    
+    # this is the default queue class if no other is specified this
+    # class will be created when setting up a queue
+    DEFAULT_QUEUE_CLASS = FreeMessageQueue::SyncronizedQueue
   
+    # setup the queue manager using the configuration from the configuration
+    # file (which is basically a hash)
     def initialize(config)
       @queue = {}
       @config = config
@@ -41,11 +57,15 @@ module FreeMessageQueue
       setup_queue_manager()
     end
     
+    # returns if the creation of queues should be done on demand
+    # (if someone sends a post to a queue)
     def auto_create_queues?
       @config["auto-create-queues"]
     end
    
-    def create_queue(name, max_messages = INFINITE, max_size = INFINITE, default_class = FreeMessageQueue::SyncronizedQueue)
+    # Create a queue (<em>name</em> => <em>path</em>). The path must contain a leading "/" and a 3 character name
+    # at minimum. Exceptions will be raised if the queue allready exists.
+    def create_queue(name, max_messages = INFINITE, max_size = INFINITE, default_class = DEFAULT_QUEUE_CLASS)
       # path must begin with /
       raise QueueManagerException.new("[QueueManager] Leading / in path '#{name}' missing", caller) if name[0..0] != "/"
       
@@ -67,6 +87,7 @@ module FreeMessageQueue
       @queue[name]
     end
    
+    # Delete the queue by name (path)
     def delete_queue(name)
       if @queue[name]
         @log.info("[QueueManager] Delete queue '#{name}' with #{@queue[name].size} messages")
@@ -78,15 +99,26 @@ module FreeMessageQueue
       end
     end
    
+    # This returns one message from the passed queue
     def poll(name)
       if @queue[name]
         @log.debug("[QueueManager] Poll from queue '#{name}' with #{@queue[name].size} messages")
-        queue_item = @queue[name].poll
+        if @queue[name].respond_to? :poll
+          queue_item = @queue[name].poll
+        else
+          raise QueueManagerException.new("[QueueManager] You can't poll from queue '#{name}'", caller)
+        end
       else
         raise QueueManagerException.new("[QueueManager] There is no queue '#{name}'", caller)
       end
     end
+      
+    alias get poll
    
+    # Puts a message (<em>data</em>) to the queue and checks if the constraints are vaild otherwise
+    # it will raise a QueueManagerException. If <em>auto_create_queues</em> is set to *true* the queue
+    # will be generated if there isn't a queue with the passed name (path). Otherwise
+    # it will raise a QueueManagerException if the passed queue doesn't exists.
     def put(name, data)
       unless @queue[name]
         # only auto create queues if it is configured
@@ -110,36 +142,59 @@ module FreeMessageQueue
       end
    
       @log.debug("[QueueManager] put message to queue '#{name}' with #{@queue[name].size} messages")
-      @queue[name].put(data)
+      if @queue[name].respond_to? :put
+        @queue[name].put(data)
+      else
+        raise QueueManagerException.new("[QueueManager] You can't put to queue '#{name}'", caller)
+      end
     end
-   
+    
+    alias post put
+
+    # Returns the names (paths) of all queues managed by this queue manager
     def queues
       @queue.keys
     end
    
+    # Returns the size of a queue in bytes
     def queue_size(name)
       @queue[name].size
     end
     
+    # Returns the queue constrains as a hash. The hash has the following structure:
+    #  {
+    #    :max_size => "100mb",
+    #    :max_messages => 1000
+    #  }
     def queue_constraints(name)
       @queue_constraints[name]
     end
    
+    # Returns the queue that is passed otherwise nil
     def queue(name)
       @queue[name]
     end
     
+    # Is the name (path) of the queue in use allready
     def queue_exists?(name)
       !queue(name).nil?
     end
     
-    # create a queue from a configuration hash
-    # <em>queue_name</em> this name is just for debugging and organizing the queue
-    # <em>queue_config</em> here you will pass the parameter:
-    # * path:
-    # * [optional] max-size: the maximum size e.g. 10mb
-    # * [optional] max-messages: the maximim messages that can be in the queue e.g. 9999999
+    # create a queue from a configuration hash.
+    # The <em>queue_name</em> is just for debugging and organizing the queue.
+    # The <em>queue_config</em> contains the following parameter:
+    # * path: the path to the queue (with leading "/" and 3 characters at minimum) e.g. "/test_queue"
+    # * [optional] max-size: the maximum size e.g. "10mb", "100kb", "2gb" or (black or -1) for infinite
+    # * [optional] max-messages: the maximim messages that can be in the queue e.g. 1500 or (black or -1) for infinite
     # * [optional] class: the class that implements this queue e.g. FreeMessageQueue::SystemQueue
+    # All other parameter will be send to the queue directly using a naming convention. So if you have the extra parameter
+    #  expire-date: 1h
+    # the QueueManager will set the expire date using this assignment 
+    #  queue.expire_date = "1h"
+    # therefore your queue must implement this method
+    #  def expire_date=(time)
+    #    @expires_after = parse_seconds(time)
+    #  end
     def create_queue_from_config(queue_name, queue_config)
       @log.debug("[QueueManager] setup queue from config '#{queue_name}'")
 
@@ -179,7 +234,7 @@ module FreeMessageQueue
     end
     
   private
-    # retuns count of bytes to a expression with kb, mb or gb
+    # Retuns count of bytes to a expression with kb, mb or gb
     # e.g 10kb will return 10240
     def str_bytes(str)
       case str
@@ -195,7 +250,7 @@ module FreeMessageQueue
       bs
     end
     
-    # create the queues that are defined in the configuration
+    # Create the queues that are defined in the configuration
     def setup_queue_manager
       @log.info("[QueueManager] Create defined queues (#{@config["defined-queues"].size})")
       for defined_queue in @config["defined-queues"]

data/lib/fmq/queues/README.txt

@@ -0,0 +1,36 @@
+== Creating custom queues:
+
+Read this simple description on how to create a queue for your special purpose.
+First of all, this template is where you start.
+1. You have to create a class that is meanful and ends up with "Queue" (for naming convention) e.g. "MyTestQueue"
+2. Name your file to the name of the queue. In this example we have the queue "MyTestQueue" 
+   so the file will be "my_test.rb". Save your new file to the queue folder of your projects folder "queues/my_test.rb"
+3. Change the queue implementation to something you like
+   * every queue must have an <em>manager</em>.
+   * this manager must be able to read <em>bytes</em> and <em>size</em>
+   * the queue should have at least one of the <tt>put(data)</tt> or <tt>poll()</tt> methods defined
+   * when implementing the poll queue the object you returning needs to have a <em>data</em> method.
+     This examples uses OpenStruct for this purpose
+
+  # FILE: my_project/queues/my_test.rb
+
+  require "ostruct"
+  
+  class MyTestQueue
+    attr_accessor :manager
+    attr_reader :bytes, :size
+    
+    def initialize
+      @bytes = @size = 1
+    end
+    
+    def put(data)
+      puts "NEW MESSAGE"
+    end
+    
+    def poll
+      item = OpenStruct.new
+      item.data = "Hello World"
+      item
+    end
+  end

data/lib/fmq/queues/admin.rb

@@ -3,30 +3,47 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
-# 
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
+#
 require 'ostruct'
 
 module FreeMessageQueue
+  # This queue is dedicated to the AJAX based admin interface.
+  #
+  # configuration sample:
+  #  queue-manager:
+  #    auto-create-queues: true
+  #    defined-queues:
+  #      admin-page-backend:
+  #      path: /admin/queue
+  #      class: FreeMessageQueue::AdminQueue
+  #      filter: /admin
   class AdminQueue
+    # QueueManager refrence
     attr_accessor :manager
     
+    # Bytes size is -1. Size is allways 1 message
+    attr_reader :bytes, :size
+    
     def initialize()
       super
+      @bytes = -1
+      @size = 1
       @filter_queues = []
     end
   
+    # returns an json list of visible queues
     def poll()
       item = OpenStruct.new
 
@@ -43,6 +60,7 @@ module FreeMessageQueue
       item
     end
     
+    # can be either used to *create* or *delete* a queue
     def put(data)
       if data.match(/_method=delete&path=(.*)/)
         # delete queue
@@ -54,10 +72,8 @@ module FreeMessageQueue
       end
     end
     
-    def size
-      1 # there is always a message in the queue
-    end
-    
+    # *CONFIGURATION* *OPTION*
+    # sets the paths that should be filterd out, seperate them with space char
     def filter=(str)
       @filter_queues = str.split " "
     end
@@ -73,6 +89,7 @@ module FreeMessageQueue
       skip
     end
   
+    # converts the data of one queue to json format
     def queue_to_json(queue_name)
       constraints = manager.queue_constraints(queue_name)
     

data/lib/fmq/queues/file.rb

@@ -3,50 +3,69 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
-# 
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
+#
 module FreeMessageQueue
+  # This queue returns everytime the same file. This is useful during debugging or
+  # to serve the admin page.
+  # 
+  # configuration sample:
+  #  queue-manager:
+  #    auto-create-queues: true
+  #    defined-queues:
+  #      admin-page-index:
+  #      path: /admin/index
+  #      class: FreeMessageQueue::FileQueue
+  #      file: admin-interface/index.html
+  #      content-type: text/html
+  #
+  # *NOTE* the put method is not implemented in this queue. It is a poll only queue.
   class FileQueue
+    # QueueManager refrence
     attr_accessor :manager
-
-    def initialize()
-      super
+    
+    # Bytes are -1 at startup but fill after first poll. Size is allways 1 message
+    attr_reader :bytes, :size
+    
+    def initialize
+      # there is always one message (the file) in the queue
+      @bytes = -1
+      @size = 1
     end
 
+    # Return the file and content type
     def poll()
       item = OpenStruct.new
 
       f = open(@file_path, "rb")
       item.data = f.read
+      @bytes = item.data.size
       f.close
       
       item.content_type = @content_type
       item
     end
-
-    def put(data)
-      # do nothing
-    end
-
-    def size
-      1 # there is always a message in the queue
-    end
     
+    # *CONFIGURATION* *OPTION*
+    # sets the path to the file that should be read
     def file=(path)
       @file_path = path
     end
     
+    # *CONFIGURATION* *OPTION*
+    # sets the content_type of the file. This option
+    # make sense if you want to test with the webbrowser.
     def content_type=(type)
       @content_type = type
     end

data/lib/fmq/queues/forward.rb

@@ -0,0 +1,60 @@
+#
+# Copyright (c) 2008 Vincent Landgraf
+#
+# This file is part of the Free Message Queue.
+# 
+# Free Message Queue is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# Free Message Queue is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
+#
+require "ostruct"
+
+module FreeMessageQueue
+  # This queue returns sends one message to several queues at a time.
+  # 
+  # configuration sample:
+  #  queue-manager:
+  #    auto-create-queues: true
+  #    defined-queues:
+  #      path: /fmq_test/forward_to_1_and_2
+  #      class: FreeMessageQueue::ForwardQueue
+  #      forward_to: /fmq_test/test1 /fmq_test/test2
+  #
+  # *NOTE* the poll method is not implemented in this queue. It is a put only queue.
+  class ForwardQueue
+    # QueueManager refrence
+    attr_accessor :manager
+    
+    # Bytes and size are allways 0 because this queue holds no data
+    attr_reader :bytes, :size
+    
+    def initialize
+      @bytes = @size = 0
+      @forwards = []
+    end
+    
+    # put the data from this queue to the queues
+    # that are specified in the <em>forward-to</em> configuration option.
+    def put(data)
+      for forward in @forwards do
+        @manager.put(forward, data)
+      end
+    end
+    
+    # *CONFIGURATION* *OPTION
+    # you can add as may queues as you want
+    # but seperate them with a space char
+    def forward_to=(urls)
+      @forwards = urls.split " "
+    end
+  end
+end

data/lib/fmq/queues/linked.rb

@@ -3,33 +3,40 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
-# 
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
+#
 module FreeMessageQueue
+  # Simple queue item class is used, because it is 
+  # considered to be faster than ostruct
   class QueueItem
     attr_accessor :next, :data, :created_at
  
+    # Create queue item
     def initialize(data, created_at = Time.new)
       @data = data
       @created_at = created_at
     end
  
+    # Aize of item in bytes
     def bytes
       @data.size
     end
   end
  
+  # *DO* *NOT* *USE* *THIS* *QUEUE* *DIRECTLY* *IN* *THE* *QUEUE* *MANAGER*
+  # it is not thread safe.
+  # This Queue implements a FIFO based store in system memory.
   class LinkedQueue
     attr_reader :size, :bytes
  
@@ -40,13 +47,14 @@ module FreeMessageQueue
       @bytes = 0
     end
  
-    # remove all items
+    # Remove all items from the queue
     def clear 
       if size > 0
         while self.poll; end
       end
     end
- 
+  
+    # Put an item to the queue
     def put(data)
       return false if data == nil
  
@@ -67,6 +75,7 @@ module FreeMessageQueue
       true
     end
  
+    # Return an item from the queue
     def poll()
       if @size > 0
         # remove allways the first item

data/lib/fmq/queues/load_balanced.rb

@@ -3,24 +3,38 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
-# 
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
+#
 require File.dirname(__FILE__) + '/syncronized'
 
 module FreeMessageQueue
-  class LoadBalancedQueue
-    attr_accessor :queues, :manager
+  # This queue is an approach to the issue that you want to have
+  # multiple threads at one queue at a time. Currently this is not
+  # considered to be a stable queue. Just use it for experimental things.
+  #
+  # configuration sample:
+  #  queue-manager:
+  #    auto-create-queues: true
+  #    defined-queues:
+  #      test-queue-1:
+  #        path: /fmq_test/test1
+  #        max-messages: 1000000
+  #        max-size: 10kb
+  #        class: FreeMessageQueue::LoadBalancedQueue
+  class LoadBalancedQueue    
+    # QueueManager refrence
+    attr_accessor :manager
     
     def initialize(queue_count = 5)
       @queues = []
@@ -31,6 +45,7 @@ module FreeMessageQueue
       @semaphore = Mutex.new
     end
     
+    # delete all messages in all queues
     def clear
       @queues.each { |q| q.clear }
     end
@@ -49,15 +64,17 @@ module FreeMessageQueue
       return tmp_bytes
     end
     
+    # Return one message from one of the queues
     def poll
       @queues[next_poll_index].poll
     end
     
+    # Put an item to one of the queues
     def put(data)
       @queues[next_put_index].put(data)
     end
     
-    private
+  private
     
     # next index acts like 'round robin'
     def next_poll_index

data/lib/fmq/queues/syncronized.rb

@@ -3,23 +3,34 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
-# 
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
+#
 require 'thread'
 require File.dirname(__FILE__) + '/linked'
 
 module FreeMessageQueue
+  # The SyncronizedQueue implements a little wrapper around the 
+  # LinkedQueue to make it thread safe
+  #
+  # configuration sample:
+  #  queue-manager:
+  #    auto-create-queues: true
+  #    defined-queues:
+  #      test-queue-1:
+  #        path: /fmq_test/test1
+  #        max-messages: 1000000
+  #        max-size: 10kb
   class SyncronizedQueue < LinkedQueue
     attr_accessor :manager
   
@@ -28,12 +39,14 @@ module FreeMessageQueue
       @semaphore = Mutex.new
     end
     
+    # Returns one item from the queue
     def poll()
       @semaphore.synchronize {
         super
       }
     end
     
+    # Puts one item to the queue
     def put(data)
       @semaphore.synchronize {
         super(data)

data/lib/fmq/version.rb

@@ -3,24 +3,24 @@
 #
 # This file is part of the Free Message Queue.
 # 
-# Foobar is free software: you can redistribute it and/or modify
+# Free Message Queue is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
 # the Free Software Foundation, either version 3 of the License, or
 # (at your option) any later version.
 # 
-# Foobar is distributed in the hope that it will be useful,
+# Free Message Queue is distributed in the hope that it will be useful,
 # but WITHOUT ANY WARRANTY; without even the implied warranty of
 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 # GNU General Public License for more details.
 # 
 # You should have received a copy of the GNU General Public License
-# along with Foobar.  If not, see <http://www.gnu.org/licenses/>.
+# along with Free Message Queue.  If not, see <http://www.gnu.org/licenses/>.
 #
 module FreeMessageQueue
   module VERSION #:nodoc:
     MAJOR = 0
     MINOR = 1
-    TINY  = 0
+    TINY  = 1
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: fmq
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Vincent Landgraf
@@ -20,8 +20,8 @@ executables:
 - fmq
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- lib/fmq/queues/README.txt
 files: 
 - bin/fmq
 - default-server/admin-interface/images/logo.png
@@ -34,8 +34,10 @@ files:
 - lib/fmq/boot.rb
 - lib/fmq/mongrel_server.rb
 - lib/fmq/queue_manager.rb
+- lib/fmq/queues/README.txt
 - lib/fmq/queues/admin.rb
 - lib/fmq/queues/file.rb
+- lib/fmq/queues/forward.rb
 - lib/fmq/queues/linked.rb
 - lib/fmq/queues/load_balanced.rb
 - lib/fmq/queues/syncronized.rb
@@ -67,7 +69,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: fmq
-rubygems_version: 1.0.1
+rubygems_version: 1.2.0
 signing_key: 
 specification_version: 2
 summary: The project implements a queue system with a server and some client apis. This project wants to be a fast and lightweight implementation with most of the features of MQS or ActiveMQ.