X-Git-Url: http://gitweb.michael.orlitzky.com/?p=mailshears.git;a=blobdiff_plain;f=lib%2Fcommon%2Fdovecot_plugin.rb;h=213e99fd7bcf266b6b436430cad149394f623a65;hp=02e92957cf6994df0e01ebc1a67fa4d07ffbe591;hb=b947ef8844f090eedd50be0383abe417d910bb1a;hpb=72696d3f6e95ef773af9727e9c3459b9038b0fc2

diff --git a/lib/common/dovecot_plugin.rb b/lib/common/dovecot_plugin.rb
index 02e9295..213e99f 100644
--- a/lib/common/dovecot_plugin.rb
+++ b/lib/common/dovecot_plugin.rb
@@ -1,82 +1,98 @@
-require 'common/plugin'
+require 'common/domain'
 require 'common/filesystem'
+require 'common/plugin'
+require 'common/user'
 
+# Code that all Dovecot plugins ({DovecotPrune}, {DovecotRm}, and
+# {DovecotMv}) will share.
+#
 module DovecotPlugin
-  # Code that all Dovecot plugins (Prune, Rm, Mv...) will
-  # share.  That is, we implement the Plugin interface.
+
+  # We implement the Plugin "interface."
   include Plugin
 
+
+  # Initialize this Dovecot {Plugin} with values in *cfg*.
+  #
+  # @param cfg [Configuration] the configuration for this plugin.
+  #
   def initialize(cfg)
-    @domain_root = cfg.mail_root
+    @domain_root = cfg.dovecot_mail_root
   end
 
+  # Describe the given Dovecot domain by its filesystem path. The
+  # domain need not exist to obtain its path.
+  #
+  # @param domain [Domain] the {Domain} object whose description we want.
+  #
+  # @return [String] a String giving the path under which this domain's
+  #   mailboxes would reside on the filesystem.
+  #
   def describe_domain(domain)
-    begin
-      domain_path = get_domain_path(domain)
-      return domain_path
-    rescue NonexistentDomainError => e
-      return "Doesn't exist: #{e.to_s}"
-    end
+    return get_domain_path(domain)
   end
 
+
+  # Describe the given Dovecot user by its filesystem mailbox
+  # path. The user need not exist to obtain its mailbox path.
+  #
+  # @param user [User] the {User} object whose description we want.
+  #
+  # @return [String] a String giving the path where this user's
+  #   mailbox would reside on the filesystem.
+  #
   def describe_user(user)
-    begin
-      user_path = get_user_path(user)
-      return user_path
-    rescue NonexistentUserError => e
-      return "Doesn't exist: #{e.to_s}"
-    end
+    return get_user_path(user)
   end
 
 
   protected;
 
+  # Return the filesystem path for the given {Domain} object.
+  #
+  # @param domain [Domain] the {Domain} whose path we want.
+  #
+  # @return [String] the filesystem path where this domain's mail
+  #   would be located.
+  #
   def get_domain_path(domain)
-    # Return the filesystem path for the given domain.
-    # That is, the directory where its mail is stored.
-    # Only works if the domain directory exists!
-    domain_path = File.join(@domain_root, domain)
-
-    if File.directory?(domain_path)
-      return domain_path
-    else
-      raise NonexistentDomainError.new(domain)
-    end
+    return File.join(@domain_root, domain.to_s())
   end
 
 
+  # Return the filesystem path of this {User}'s mailbox.
+  #
+  # @param user [User] the {User} whose mailbox path we want.
+  #
+  # @return [String] the filesystem path where this user's mail
+  #   would be located.
+  #
   def get_user_path(user)
-    # Return the filesystem path of this user's mailbox.
-    # Only works if the user exists!
-    if not user.include?('@')
-      msg = "#{user}: Users must contain an '@' symbol."
-      raise InvalidUserError.new(msg)
-    end
-
-    user_parts = user.split('@')
-    local_part = user_parts[0]
-    domain_part = user_parts[1]
-
-    begin
-      domain_path = get_domain_path(domain_part)
-    rescue NonexistentDomainError
-      raise NonexistentUserError.new(user)
-    end
-
-    user_path = File.join(domain_path, local_part)
-
-    if File.directory?(user_path)
-      return user_path
-    else
-      raise NonexistentUserError.new(user)
-    end
+    domain_path = get_domain_path(user.domain())
+    return File.join(domain_path, user.localpart())
   end
 
 
+  # Produce a list of domains that exist in the Dovecot mailstore.
+  #
+  # @return [Array<Domain>] an array of {Domain} objects that have
+  #   corresponding directories within the Dovecot mailstore.
+  #
   def list_domains()
-    return Filesystem.get_subdirs(@domain_root)
+    return Filesystem.get_subdirs(@domain_root).map{ |d| Domain.new(d) }
   end
 
+
+  # Produce a list of users belonging to the given *domains* in the
+  # Dovecot mailstore.
+  #
+  # @param domains [Array<Domain>] an array of {Domain} objects whose
+  #   users we'd like to find.
+  #
+  # @return [Array<User>] an array of {User} objects that have
+  #   corresponding directories within the Dovecot mailstore belonging
+  #   to the specified *domains*.
+  #
   def list_domains_users(domains)
     users = []
 
@@ -89,7 +105,7 @@ module DovecotPlugin
         usernames = Filesystem.get_subdirs(domain_path)
 
         usernames.each do |username|
-          users << "#{username}@#{domain}"
+          users << User.new("#{username}@#{domain}")
         end
       rescue NonexistentDomainError
         # Party hard.
@@ -100,6 +116,11 @@ module DovecotPlugin
   end
 
 
+  # Produce a list of all users in the Dovecot mailstore.
+  #
+  # @return [Array<User>] a list of users who have mailbox directories
+  #   within the Dovecot mailstore.
+  #
   def list_users()
     domains = list_domains()
     users = list_domains_users(domains)