changes to factory method and better documentation

Author: dweinand

README

@@ -1,17 +1,31 @@
 = Fetcher
 
-Simplified message fetching
+Fetcher is a simple message fetcher perfect for using in a daemon.
+
+It implements the following common pattern:
+
+1. Connect to a server
+2. Download available messages
+3. Send each message to another object for further processing
+4. Remove downloaded messages from the remote server
 
 Install using:
 script/plugin install svn://rubyforge.org/var/svn/slantwise/fetcher/trunk
 
 == Usage
 
-  @fetcher = Fetcher.new(:pop, :server => 'mail.example.com',
-                               :username => 'user',
-                               :password => 'pass',
-                               :reciever => IncomingMailHandler)
-  loop do
-    @fetcher.fetch
-    sleep 60
-  end
+Create a new fetcher object like the following:
+
+  @fetcher = Fetcher.create({:type => :pop,
+                             :receiver => IncomingMailHandler,
+                             :server => 'mail.example.com',
+                             :username => 'jim',
+                             :password => 'test'})
+
+The receiver object is expected to have a receive method that takes a message as it's only argument.
+
+Call fetch to run the process.
+
+  @fetcher.fetch
+
+You can also subclass Fetcher::Base or one of the protocol-specific classed to override the standard behavior.

generators/fetcher_daemon/templates/config.yml

@@ -1,14 +1,17 @@
 development:
+  type: pop
   server: localhost
   username: username
   password: password
 
 test:
+  type: pop
   server: localhost
   username: username
   password: password
 
 production:
+  type: pop
   server: localhost
   username: username
   password: password

generators/fetcher_daemon/templates/daemon

@@ -12,8 +12,8 @@ class <%=class_name%>FetcherDaemon < Daemon::Base
   @sleep_time = @config.delete(:sleep_time)
   def self.start
     puts "Starting <%=class_name%>Fetcher"
-    # Add your own receiver object below and specify fetcher subclass
-    @fetcher = Fetcher::Base.new({:receiver => nil, :type => nil}.merge(@config))
+    # Add your own receiver object below
+    @fetcher = Fetcher.create({:receiver => nil}.merge(@config))
 
     loop do
       @fetcher.fetch

lib/fetcher.rb

@@ -1,11 +1,18 @@
 module Fetcher
   # Use factory-style initialization or insantiate directly from a subclass
+  #
+  # Options:
+  # * <tt>:type</tt> - Name of class as a symbol to instantiate
+  #
+  # Other options are the same as Fetcher::Base.new
   # 
   # Example:
   # 
-  # Fetcher.new(:pop) is equivalent to
+  # Fetcher.create(:type => :pop) is equivalent to
   # Fetcher::Pop.new()
-  def self.new(klass, options={})
+  def self.create(options={})
+    klass = options.delete(:type)
+    raise ArgumentError, 'Must supply a type' unless klass
     module_eval "#{klass.to_s.capitalize}.new(options)"
   end
 end

lib/fetcher/base.rb

@@ -1,6 +1,19 @@
 module Fetcher
   class Base
-    
+    # Options:
+    # * <tt>:server</tt> - Server to connect to.
+    # * <tt>:username</tt> - Username to use when connecting to server.
+    # * <tt>:password</tt> - Password to use when connecting to server.
+    # * <tt>:receiver</tt> - Receiver object to pass messages to. Assumes the
+    # receiver object has a receive method that takes a message as it's argument
+    #
+    # Additional protocol-specific options implimented by sub-classes
+    #
+    # Example: 
+    #   Fetcher::Base.new(:server => 'mail.example.com',
+    #                     :username => 'pam',
+    #                     :password => 'test',
+    #                     :receiver => IncomingMailHandler)
     def initialize(options={})
       %w(server username password receiver).each do |opt|
         raise ArgumentError, "#{opt} is required" unless options[opt.to_sym]

lib/fetcher/imap.rb

@@ -5,7 +5,8 @@ class Imap < Base
 
     protected
 
-    # Adds authentication option
+    # Additional Options:
+    # * <tt>:authentication</tt> - authentication type to use, defaults to PLAIN
     def initialize(options={})
       @authentication = options.delete(:authentication) || 'PLAIN'
       super(options)

lib/fetcher/pop.rb

@@ -5,7 +5,8 @@ class Pop < Base
 
     protected
 
-    # Adds ssl option
+    # Additional Options:
+    # * <tt>:ssl</tt> - whether or not to use ssl encryption
     def initialize(options={})
       @ssl = options.delete(:ssl)
       super(options)

test/fetcher_test.rb

@@ -49,12 +49,12 @@ class FactoryFetcherTest < Test::Unit::TestCase
 
   def setup
     @receiver = mock()
-    @pop_fetcher = Fetcher.new(:pop, :server => 'test.host',
+    @pop_fetcher = Fetcher.create(:type => :pop, :server => 'test.host',
                                :username => 'name',
                                :password => 'password',
                                :receiver => @receiver)
 
-  @imap_fetcher = Fetcher.new(:imap, :server => 'test.host',
+  @imap_fetcher = Fetcher.create(:type => :imap, :server => 'test.host',
                               :username => 'name',
                               :password => 'password',
                               :receiver => @receiver)
@@ -65,6 +65,10 @@ def test_should_be_sublcass
     assert_equal Fetcher::Imap, @imap_fetcher.class
   end
 
+  def test_should_require_type
+    assert_raise(ArgumentError) { Fetcher.create({}) }
+  end
+  
 end
 
 # Write tests for sub-classes