module Plugin

Methods that all plugins must provide. Certain operations – for example, user listing – must be supported by all plugins. These operations are defined here, often with naive default implementations, but it is up to each individual plugin to ensure that they are in fact implemented (well).

Public Instance Methods

describe(target) click to toggle source

A generic version of {#describe_user}/{#describe_domain} that dispatches base on the class of the target.

@param target [User,Domain] either a user or a domain to describe.

@return [String] a string describing the target. The contents of

the string depend on the plugin.
# File lib/common/plugin.rb, line 102
def describe(target)
  if target.is_a?(User)
    if user_exists(target) then
      return describe_user(target)
    else
      return 'User not found'
    end
  elsif target.is_a?(Domain)
    if domain_exists(target) then
      return describe_domain(target)
    else
      return 'Domain not found'
    end
  else
    raise NotImplementedError
  end
end
describe_domain(domain) click to toggle source

Provide a description of the given domain. This is output along with the domain name and can be anything of use to the system administrator. The default doesn't do anything useful and should be overridden if possible.

@param domain [Domain] the domain to describe.

@return [String] a string description of domain.

# File lib/common/plugin.rb, line 130
def describe_domain(domain)
  return domain.to_s()
end
describe_user(user) click to toggle source

Provide a description of the given user. This is output along with the username and can be anything of use to the system administrator. The default doesn't do anything useful and should be overridden if possible.

@param user [User] the domain to describe.

@return [String] a string description of user.

# File lib/common/plugin.rb, line 144
def describe_user(user)
  return user.to_s()
end
domain_exists(domain) click to toggle source

Does the given domain exist for this plugin? We use a naive implementation here based on {#list_domains}. Plugins that know about domains should override this with something fast.

@param domain [Domain] the domain whose existence is in question.

@return [Boolean] true if domain exists for this plugin, and

false otherwise.
# File lib/common/plugin.rb, line 204
def domain_exists(domain)
  domains = list_domains()
  return domains.include?(domain)
end
list_domains() click to toggle source

Return a list of all domains managed by this plugin. This must be supplied by the individual plugins (who know how to find their domains). Many plugins will not have a separate concept of “domain”, so the default implementation constructs a list of domains resulting from {#list_users}.

For plugins that do know about domains, smarter implementations are surely possible.

@return [Array<Domain>] a list of the domains that this plugin knows

about.
# File lib/common/plugin.rb, line 173
def list_domains()
  users = list_users()
  domains = users.map{ |u| u.domain() }
  return domains.uniq()
end
list_domains_users(domains) click to toggle source

List all users belonging to the given domains. We say that a user belongs to a domain “example.com” if the domain part of the user's email address is “example.com”.

This uses a naive loop, but relies only on the existence of {#list_users}. Plugins that know about domains should provide a more efficient implementation.

@param domains [Array<Domain>] the domains whose users we want.

@return [Array<User>] a list of {User} objects belonging to

*domains* for this plugin.
# File lib/common/plugin.rb, line 223
def list_domains_users(domains)
  domains_users = []

  users = list_users();
  domains.each do |d|
    matches = users.select do |user|
      user.domainpart() == d.to_s()
    end

    domains_users += matches
  end

  return domains_users
end
list_users() click to toggle source

Return a list of all users managed by this plugin. This must be supplied by the individual plugins (who know how to find their users).

@return [Array<User>] a list of the users that this plugin knows

about.
# File lib/common/plugin.rb, line 156
def list_users()
  raise NotImplementedError
end
user_exists(user) click to toggle source

Does the given user exist for this plugin? We use a naive implementation here based on {#list_users}. Plugins should override this with something faster.

@param user [User] the user whose existence is in question.

@return [Boolean] true if user exists for this plugin, and

false otherwise.
# File lib/common/plugin.rb, line 189
def user_exists(user)
  users = list_users()
  return users.include?(user)
end