Provided by: sympa_6.2.70~dfsg-2_amd64 bug

NAME

       Sympa::Spool - Base class of spool classes

SYNOPSIS

         package Sympa::Spool::FOO;

         use base qw(Sympa::Spool);

         sub _directories {
             return {
                 directory     => '/path/to/spool',
                 bad_directory => '/path/to/spool/bad',
             };
         }
         use constant _generator      => 'Sympa::Message';
         use constant _marshal_format => '%s@%s.%ld.%ld,%d';
         use constant _marshal_keys   => [qw(localpart domainpart date PID RAND)];
         use constant _marshal_regexp =>
             qr{\A([^\s\@]+)(?:\@([\w\.\-]+))?\.(\d+)\.(\w+)(?:,.*)?\z};

         1;

DESCRIPTION

       This module is the base class for spool subclasses of Sympa.

   Public methods
       new ( [ options... ] )
           Constructor.  Creates new instance of the class.

       marshal ( $message, [ keep_keys => 1 ] )
           Instance method.  Gets marshalled key (file name) of the message.

           Parameters:

           $message
               Message to be marshalled.

           keep_keys => 1
               See marshal_metadata().

       next ( [ no_filter => 1 ], [ no_lock => 1 ] )
           Instance method.  Gets next message to process, order is controlled by name of spool
           file and so on.  Message will be locked to prevent multiple processing of a single
           message.

           Parameters:

           no_filter => 1
               Won't skip messages when filter defined by _filter() returns false.

           no_lock => 1
               Won't lock messages.

           Returns:

           Two-elements list of message instance and filehandle locking a message.  If parsing
           message fails, list of "undef" and filehandle.  If no more message found, empty array.

           If "no_lock" is set, true scalar value will be returned in place of filehandle.

       quarantine ( $handle )
           Instance method.  Quarantines a message.  On filesystem spool, message will be moved
           into "{bad_directory}" of the spool using rename().

           Parameter:

           $handle
               Filehandle, Sympa::LockedFile instance, locking message.

           Returns:

           True value if message could be quarantined.  Otherwise false value.

           If $handle was not a filehandle, this method will die.

       remove ( $handle )
           Instance method.  Removes a message.

           Parameter:

           $handle
               Filehandle, Sympa::LockedFile instance, locking message.

           Returns:

           True value if message could be removed.  Otherwise false value.

           If $handle was not a filehandle, this method will die.

       size ( )
           Instance method.  Gets the number of messages the spool contains.

           Parameters:

           None.

           Returns:

           Number of messages.

           Note: This method returns the number of messages _load() returns, not applying
           _filter().

       store ( $message, [ original => $original ] )
           Instance method.  Stores the message into spool.

           Parameters:

           $message
               Message to be stored.

           original => $original
               If true value is specified and $message was decrypted, Stores original encrypted
               form.

           Returns:

           If storing succeeded, marshalled metadata (file name) of the message.  Otherwise
           "undef".

       unmarshal ( $marshalled )
           Instance method.  Gets metadata from marshalled key (file name).

           Parameters:

           $marshalled
               Marshalled key.

           Returns:

           Hashref containing metadata.

   Properties
       Instance of Sympa::Spool may have following properties.

       Directories
           Directories _directories() method returns: "{directory}", "{bad_directory}" and so on.

   Low level functions
       build_glob_pattern ( $marshal_format, $marshal_keys, [ key => value, ... ] )
           Function.  Builds a glob pattern from parameters and returns it.  If built pattern is
           empty or contains only punctuations, i.e. "[^0-9A-Za-z\x80-\xFF]", will return
           "undef".

       split_listname ( $robot, $localpart )
           Function.  Split local part of e-mail to list name and type.  Returns an array "(name,
           type)".  Note that the list with returned name may or may not exist.

           If local part looks like listmaster or sympa address, name is "undef" and type is
           either 'listmaster' or 'sympa'.  Otherwise, type is either 'editor', 'owner',
           'return_path', 'subscribe', 'unsubscribe', 'UNKNOWN' or "undef".

           Note: For "-request" and "-owner" suffix, this function returns "owner" and
           "return_path" types, respectively.

       store_spool ( $spool_dir, $message, $marshal_format, $marshal_keys, [ key => value, ... ]
       )
           Function.  Store $message into directory $spool_dir as a file with name as marshalled
           metadata using $marshal_format and $marshal_keys.

       unmarshal_metadata ( $spool_dir, $marshalled, $marshal_regexp, $marshal_keys )
           Function.  Unmarshals metadata.  Returns hashref with keys in arrayref $marshal_keys
           and values with substrings captured by regexp $marshal_regexp.  If $marshalled did not
           match against $marshal_regexp, returns "undef".

           The keys "localpart" and "domainpart" are special.  Following keys are derived from
           them: "context", "listname", "listtype", "priority".

       marshal_metadata ( $message, $marshal_format, $marshal_keys, [ keep_keys => 1 ] )
           Function.  Marshals metadata.  Returns formatted string by sprintf() using
           $marshal_format and metadatas indexed by keys in arrayref $marshal_keys.

           If key is uppercase, it means auto-generated value: 'AUTHKEY', 'KEYAUTH', 'PID',
           'RAND', 'TIME'.  Otherwise it means metadata or property of $message.  If "keep_keys"
           option (added on 6.2.23b) is set, forces using latter.

           sprintf() is executed under "C" locale: Full stop (".") is always used for decimal
           point in floating point number.

   Methods subclass should implement
       _create ( )
           Instance method, overridable.  Creates spool.  By default, creates directories
           returned by _directories().

       _directories ( [ options, ... ] )
           Class or instance method, mandatory for filesystem spool.  Returns hashref with
           directory paths related to the spool as values.  It must have keys at least
           "directory" and (if you wish to implement quarantine() method) "bad_directory".

       _filter ( $metadata )
           Instance method, overridable.  If it returned false value, processing of $metadata by
           next() will be skipped.  By default, always returns true value.

           This method may modify unmarshalled metadata _and_ deserialized messages include it.

       _filter_pre ( $metadata )
           Instance method, overridable.  If it returned false value, processing of $metadata by
           store() will be skipped.  By default, always returns true value.

           This method may modify marshalled metadata _but_ stored messages are not affected.

       _generator ( )
           Class or instance method, mandatory.  Returns name of the class to serialize and
           deserialize messages in the spool.  If spool subclass is the collection (see
           _is_collection), generator class must implement new().  Otherwise, generator class
           must implement dup(), new() and to_string().

       _glob_pattern ( )
           Deprecated.  See _no_glob_pattern ( )

       _init ( $state )
           Instance method.  Additional processing when _load() returns no contents ($state is 1)
           or when the spool class is instantiated ($state is 0).

       _is_collection ( )
           Instance method, overridable.  If the class is collection of spool class, returns true
           value.  By default returns false value.

           Collection class does not have store() method.  Its content is the set of spool
           instances.

       _load ( )
           Instance method, overridable.  Loads sorted content of spool.  Returns arrayref of
           marshalled metadatas.  By default, returns content of "{directory}" directory sorted
           by file name.

       _marshal_format ( )
       _marshal_keys ( )
       _marshal_regexp ( )
           Instance methods, mandatory for filesystem spool.  _marshal_format() and
           _marshal_keys() are used to marshal metadata.  _marshal_keys() and _marshal_regexp()
           are used to unmarshal metadata.  See also marshal_metadata() and unmarshal_metadata().

       _no_glob_pattern ( )
           Class or instance method, overridable for filesystem spool.  If it returns false
           value, glob() is used as much as possible to scan the spool faster.  Otherwise
           readdir() is used for filesystem spool to get all entries.  By default returns false
           value.

       _store_key ( )
           Instance method.  If implemented and returns non-empty string, store() returns an item
           in metadata specified by this method.  By default store() returns marshalled metadata
           (file name on filesystem spool).

   Marshaling and unmarshaling metadata
       Spool class gives generator class the metadata to instantiate it.  On spool based on
       filesystem, it is typically encoded into file names.  For example a file name in incoming
       spool (Sympa::Spool::Incoming)

         listname-owner@domain.name.143599229.12345

       encodes the metadata

         localpart  => 'listname-owner',
         listname   => 'listname',
         listtype   => 'return_path',
         domainpart => 'domain.name',
         date       => 143599229,

       Metadata always includes information of context: List, Robot, Site (or Family).  For
       example:

       - Message in incoming spool bound for <listname@domain.name>:

         context    => Sympa::List <listname@domain.name>,

       - Command message in incoming spool bound for <sympa@domain.name>:

         context    => 'domain.name',

       - Message sent from Sympa to super-listmaster(s):

         context    => '*'

       Context is determined when the generator class is instantiated, and generally never
       changed through lifetime of instance.  Thus, constructor of generator class should take
       context object as an argument.

       "localpart" is encoded in a bit complex manner.

       •   If the context is Site or Robot, it is a value of "email" parameter, typically
           ""sympa"".

       •   If the context is Family, it is encoded as "@family name".  This encoding was added on
           Sympa 6.2.53b.

       •   If the context is List, it is encoded as local part of list address according to
           listtype (See also "get_address" in Sympa).

CONFIGURATION PARAMETERS

       Following site configuration parameters in sympa.conf will be referred.

       default_list_priority
       email
       owner_priority
       list_check_suffix
       listmaster_email
       request_priority
       return_path_suffix
       sympa_priority
           Used to extract metadata from marshalled data (file name).

       umask
           The umask to make directories of spool.

SEE ALSO

       Sympa::Message, especially Serialization.

HISTORY

       Sympa::Spool appeared on Sympa 6.2.  It as the base class appeared on Sympa 6.2.6.

       build_glob_pattern(), size(), _glob_pattern() and _store_key() were introduced on Sympa
       6.2.8.  _filter_pre() was introduced on Sympa 6.2.10.  marshal(), unmarshal() and
       "no_filter" option of next() were introduced on Sympa 6.2.22.  _no_glob_pattern() was
       introduced and _glob_pattern() was deprecated on Sympa 6.2.36.