Module: Plugin

Included in:
AgendavPlugin, DavicalPlugin, DovecotPlugin, PostfixadminPlugin, RoundcubePlugin
Defined in:
lib/common/plugin.rb

Overview

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).

Defined Under Namespace

Modules: Run

Instance Method Summary collapse

Instance Method Details

#describe(target) ⇒ String

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

Parameters:

  • target (User, Domain) —

    either a user or a domain to describe.

Returns:

  • (String) —

    a string describing the target. The contents of the string depend on the plugin.



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# 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) ⇒ String

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.

Parameters:

  • domain (Domain) —

    the domain to describe.

Returns:

  • (String) —

    a string description of domain.



130
131
132
 
# File 'lib/common/plugin.rb', line 130

def describe_domain(domain)
  return domain.to_s()
end

#describe_user(user) ⇒ String

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.

Parameters:

  • user (User) —

    the domain to describe.

Returns:

  • (String) —

    a string description of user.



144
145
146
 
# File 'lib/common/plugin.rb', line 144

def describe_user(user)
  return user.to_s()
end

#domain_exists(domain) ⇒ Boolean

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.

Parameters:

  • domain (Domain) —

    the domain whose existence is in question.

Returns:

  • (Boolean) —

    true if domain exists for this plugin, and false otherwise.



204
205
206
207
 
# File 'lib/common/plugin.rb', line 204

def domain_exists(domain)
  domains = list_domains()
  return domains.include?(domain)
end

#list_domains ⇒ Array<Domain>

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.

Returns:

  • (Array<Domain>) —

    a list of the domains that this plugin knows about.



173
174
175
176
177
 
# 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) ⇒ Array<User>

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.

Parameters:

  • domains (Array<Domain>) —

    the domains whose users we want.

Returns:

  • (Array<User>) —

    a list of User objects belonging to domains for this plugin.



223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# 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 ⇒ Array<User>

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).

Returns:

  • (Array<User>) —

    a list of the users that this plugin knows about.

Raises:

  • (NotImplementedError) 


156
157
158
 
# File 'lib/common/plugin.rb', line 156

def list_users()
  raise NotImplementedError
end

#user_exists(user) ⇒ Boolean

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.

Parameters:

  • user (User) —

    the user whose existence is in question.

Returns:

  • (Boolean) —

    true if user exists for this plugin, and false otherwise.



189
190
191
192
 
# File 'lib/common/plugin.rb', line 189

def user_exists(user)
  users = list_users()
  return users.include?(user)
end