Permalink
Browse files

changes to factory method and better documentation

  • Loading branch information...
1 parent dc16a0b commit 8c3146621e985d3eb717225ee5a64b73279e0044 @dweinand dweinand committed Jun 15, 2007
View
32 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.
@@ -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
@@ -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
View
@@ -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
View
@@ -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]
View
@@ -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)
View
@@ -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)
View
@@ -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

0 comments on commit 8c31466

Please sign in to comment.