X-Git-Url: http://gitweb.michael.orlitzky.com/?p=mailshears.git;a=blobdiff_plain;f=lib%2Fcommon%2Fdovecot_plugin.rb;h=213e99fd7bcf266b6b436430cad149394f623a65;hp=ab5a40930400af057229ded188d40516cc88b866;hb=5bf27259563a3dda6425dc794722273cc29b69f7;hpb=365d681f1ef45bd3f5f2c9dded07108bdd75a1ff

diff --git a/lib/common/dovecot_plugin.rb b/lib/common/dovecot_plugin.rb
index ab5a409..213e99f 100644
--- a/lib/common/dovecot_plugin.rb
+++ b/lib/common/dovecot_plugin.rb
@@ -1,105 +1,126 @@
-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
 
-  def describe_account(account)
-    begin
-      account_path = get_account_path(account)
-      return account_path
-    rescue NonexistentAccountError => e
-      return "Doesn't exist: #{e.to_s}"
-    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)
+    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
 
 
-  def get_account_path(account)
-    # Return the filesystem path of this account's mailbox.
-    # Only works if the account exists!
-    if not account.include?('@')
-      msg = "#{account}: Accounts must contain an '@' symbol."
-      raise InvalidAccountError.new(msg)
-    end
-
-    account_parts = account.split('@')
-    user_part = account_parts[0]
-    domain_part = account_parts[1]
-
-    begin
-      domain_path = get_domain_path(domain_part)
-    rescue NonexistentDomainError
-      raise NonexistentAccountError.new(account)
-    end
-
-    account_path = File.join(domain_path, user_part)
-
-    if File.directory?(account_path)
-      return account_path
-    else
-      raise NonexistentAccountError.new(account)
-    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)
+    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)
-    accounts = []
+    users = []
 
     domains.each do |domain|
       begin
         # Throws a NonexistentDomainError if the domain's path
         # doesn't exist on the filesystem. In this case, we want
-        # to report zero accounts.
+        # to report zero users.
         domain_path = get_domain_path(domain)
         usernames = Filesystem.get_subdirs(domain_path)
 
         usernames.each do |username|
-          accounts << "#{username}@#{domain}"
+          users << User.new("#{username}@#{domain}")
         end
       rescue NonexistentDomainError
         # Party hard.
       end
     end
 
-    return accounts
+    return users
   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)