Sympa::Spool(3Sympa)

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.

next ( )
    Instance method. Gets next message to process, order is controled by name of spool file and so on. Message will be locked to prevent multiple proccessing of a single message.

    Parameters:

    None.

    Returns:

    Two-elements list of message instance and filehandle locking a message.

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.

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.

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

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

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

  Low level functions

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.

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 )
    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', 'DATE', 'PID', 'RAND', 'TIME'. Otherwise it means metadata or property of $message.

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

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.

  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 will be skipped. By default, always returns true value.

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

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

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.