Overview

POPFile consists of a collection of Perl modules that use Perl's OO features. There are three types of module used:

  1. A “POPFile Loadable Module” (PLM) is a standard Perl Module that starts with the line # POPFILE LOADABLE MODULE and which will be loaded dynamically by the POPFile module POPFile::Loader. All PLMs are subclasses (or sub-subclasses etc.) of POPFile::Module where a great deal of documentation can be found.
  2. Non-PLM modules that are parent classes for PLMs. Examples are Proxy::Proxy, POPFile::Module, UI::HTTP.
  3. Modules that are neither of the two above and are loaded by some part of POPFile. Examples are POPFile::Loader, Classifier::MailParse, Classifier::WordMangle.

Private, Protected and Public

Because Perl doesn't provide a mechanism for controlling access to methods and member variables, POPFile uses a convention of decorating methods and variables to identify whether they are private, protected or public.

  1. A private method/variable is appended with __ (double underscore) to indicate that it may not be called/accessed from outside the class.
  2. A protected method/variable is appended with _ (single underscore) to indicate that it may not be called/accessed from outside the class except by a subclass.
  3. A public method/variable is not decorated in any way.

Object Relationships

The main objects are related as follows:

                                                   POPFile::Module
                                                          ^
                                                          |            
                                                          |
           +---------------------------------+------------+-----------+------------+-----------------+----------------------+--------------+
           |                                 |                        |            |                 |                      |              |
           |                                 |                        |            |                 |                      |              |
    Classifier::Bayes                  Proxy::Proxy                UI::HTTP   UI::XMLRPC   POPFile::Configuration   POPFile::Logger   POPFile::MQ
    (has a Classifier::MailParse             ^                        ^
     and a Classifier::WordMangle)           |                        | 
                                             |                        |
                               +-------------+-----------+            |
                               |             |           |            |
                          Proxy::POP3  Proxy::SMTP  Proxy:NNTP     UI::HTML

POPFile::Module

This module implements the base class for all POPFile Loadable Modules and contains collection of methods that are common to all POPFile modules and only selected ones need be overriden by subclasses. The public functions are all called by POPFile::Loader during the normal running of POPFile.

  1. initialize() - called after the class is created to set default values for internal variables and global configuration information
  2. start() - called once all configuration has been read and POPFile is ready to start operating
  3. stop() - called when POPFile is shutting down
  4. service() - called by the main POPFile process to allow a submodule to do its own work (this is optional for modules that do not need to perform any service)
  5. prefork() - called when a module has requested a fork, but before the fork happens
  6. forked() - called when a module has forked the process. This is called within the child process and should be used to clean up
  7. postfork() - called in the parent process to tell it that the fork has occurred. This is like forked but in the parent
  8. reaper() - called when a process has terminated to give a module a chance to do whatever clean up is needed
  9. name() - returns a simple name for the module by which other modules can get access through the %components hash. The name returned here will be the name used as the key for this module in %components
  10. deliver() - called by the message queue to deliver a message

The following methods are PROTECTED and should be accessed by sub classes:

  1. log_() - sends a string to the logger
  2. config_() - gets or sets a configuration parameter for this module
  3. mq_post_() - post a message to the central message queue
  4. mq_register_() register for messages from the message queue
  5. register_configuration_item_() register a UI configuration item

Module Access to Configuration Parameters

Some PLMs may want to persist information between POPFile sessions and/or make parameters configurable. POPFile provides a generic mechanism for persistent parameters managed by the POPFile::Configuration module.

Any PLM can register and access its own parameters through the config_ method. Called with a single parameter (e.g. $self→config_( 'my_param' )) config_ retrieves the value of a configuration parameter. This can be done once the PLM's initialize() function has been called. Called with two parameters config_ will set the value of a parameter and tell the POPFile::Configuration module that the parameter table is dirty and needs to be saved to disk.

To set default values for a parameter a PLM calls config_ in its initialize method. After all PLMs have had initialize called POPFile will load the current parameters from disk and both default and disk values will be taken into account.

There is no danger of a clash between parameter names in different modules as each parameter is assigned its own namespace before being persisted or accessed. This is currently determined by the name that the PLM sets using name. It is essential to set the PLM's name before any calls to config_; this is usually done in the PLM's new method. Currently the name is prepended to the parameter name with an _ in between. Thus modules with names foo and bar may define different parameters called param which will get translated before storage to disk as foo_param and bar_param. Since this could change at any time a PLM must not use this knowledge and should only access parameters through config_.

Sometimes a PLM needs to read a parameter from another module. This can be done by calling module_config_ with the name of the module (the name it set with a call to its name) and the parameter. e.g. a PLM could access the foo module's param parameter by calling $self→module_config_( 'foo', 'param' ). This should be done sparingly.

In addition there are global parameters that can be accessed through global_config_.

Inter-Module Communication

POPFile::MQ is a generic message queuing system that all subclasses of POPFile::Module have access to for sending message to other modules. Any module can post a message for asynchronous delivery to any other module that has registered for the specific message type.

A module registers for a message type by calling mq_register_. It must implement the public function deliver through which messages will be delivered. A module sends a message with mq_post_. Messages are currently freeform and there is no central repository of message types; if a new message is added add documentation of it at the beginning of POPFile::MQ.

The current messages are:

MessageID Explanation Send By Monitored By
CLASS A message was classified, message is the bucket and the parameter is null Proxy::Proxy UI::HTML
UIREG Register a UI component, message is the component type and the parameter is a the element and reference to the object registering Proxy::POP3, Proxy::SMTP, Proxy::NNTP, UI::XMLRPC UI::HTML
TICKD Occurs when an hour has passed since the last TICKD POPFile::Logger UI::HTML, POPFile::Logger
LOGIN Occurs when a proxy logs into a remote server, the message is the username sent Proxy::Proxy UI::HTML
NEWFL Occurs when a new file has been written to the history cache on disk. The message is the filename. Proxy::Proxy UI::HTML

UIREG is sent by calling register_configuration_item_ in POPFile::Module.

The following diagram gives an idea of who sends and monitors which messages.

              UI::HTML
               ^  ^  ^
               |  |  |
               |  |  +------------------------+
               |  |                           |
       +-------+  +----------+                |
       |                     |                |
       | +------+          NEWFL              |
       | |      |          LOGIN              |
      TICKD     |          CLASS            UIREG
        |       |            |                |
POPFile::Logger |      Proxy::Proxy       Proxy::POP3
       ^        |      (via pipe from     Proxy::NNTP
       |        |       POP3/SMTP/NNTP)   Proxy::SMTP
       +--------+                         UI::XMLRPC
 
devel/objectmodel.txt · Last modified: 2008/02/08 19:49 by 127.0.0.1

Should you find anything in the documentation that is incomplete, unclear, outdated or just plain wrong, please let us know and leave a note in the Documentation Forum.

Recent changes RSS feed Donate Driven by DokuWiki
The content of this wiki is protected by the GNU Fee Documentation License