POPFile consists of a collection of Perl modules that use Perl's OO features. There are three types of module used:
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.
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
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.
The following methods are PROTECTED and should be accessed by sub classes:
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_.
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
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.