NAME

Sympa::Spindle - Base class of subclasses to define Sympa workflows

SYNOPSIS

 package Sympa::Spindle::FOO;
 use base qw(Sympa::Spindle);

 use constant _distaff => 'Sympa::Spool::BAR';
 
 sub _twist {
     my $self = shift;
     my $object = shift;
 
     # Process object...

     return 1;                        # If succeeded.
     return 0;                        # If skipped.
     return undef;                    # If failed.
     return ['Sympa::Spindle::BAZ'];  # Splicing to the other class(es).
 }

 1;

DESCRIPTION

Sympa::Spindle is the base class of subclasses to define particular workflows of Sympa.

A spindle class is a set of features to process objects. If spin() method is called, it retrieves each object from source spool, processes it, at last passes altered object to appropriate destination (another spool or mailer), and removes it as necessity. Processing repeats until source spool is empty.

Public methods

• new ( [ key => value, … ] )

  Constructor. Creates new instance of Sympa::Spindle.

• spin ( )

  Instance method. Fetches an object and handle locking it from source spool, processes them calling _twist() and repeats. If source spool no longer gives content, returns the number of processed objects.

• add_stash ( =parameters… )

  Instance method. Adds arrayref of parameters to a storage for general-purpose.

Properties

Instance of Sympa::Spindle may have following properties.

• {distaff}

  Instance of source spool class _distaff() method returns.

• {finish}

  Read/write. At first this property is false. Once it is set, spin() finishes processing safely.

• Spools

  Instances of spool classes _spools() method returns.

• {start_time}

  Unix time in floating point number when processing of the latest message by spin() began. Introduced by Sympa 6.2.13.

• {stash}

  A reference to array of added data by add_stash().

Methods subclass should implement

• _distaff ( )

  Class method, mandatory if you want to implement spin(). Returns the name of source spool class. source spool class must implement new() and next().

• _init ( $state )

  Instance method. Additional processing when the spindle class is instantiated ($state is 0), before spin() processes next object in source spool ($state is 1) or after it processed object ($state is 2).

  If it returns false value, new() will return undef (when $state is 0) or spin() will terminate processing (when $state is 1). By default it always returns 1.

• _on_garbage ( $handle )

  Instance method, overridable. Executes process when object could not be deserialized (new() method of object failed). By default, quarantines object calling quarantine() method of source spool.

• _on_failure ( $message, $handle )

  Instance method, overridable. Executes process when processing of $message failed (_twist() returned undef). By default, quarantines object calling quarantine() method of source spool.

• _on_skip ( $message, $handle )

  Instance method, overridable. Executes process when $message was skipped (_twist() returned 0). By default, simply unlocks object calling close() method of $handle.

• _on_success ( $message, $handle )

  Instance method, overridable. Executes process when processing of $message succeeded (_twist() returned true value). By default, removes object calling remove() method of source spool.

• _spools ( )

  Class method. If implemented, returns hashref with names of spool classes related to the spindle as values.

• _twist ( $message )

  Instance method, mandatory. Processes an object: Typically, modifies object or creates another object and stores it into appropriate spool.

  Parameter:

  • $message

    An object.

  Returns:

  Status of processing: True value on success; 0 if processing skipped; undef on failure.

  As of Sympa 6.2.13, _twist() may also return the reference to array including name(s) of other classes: In this case spin() and twist() will call _twist() method of given classes in order (not coercing spindle object into them) and uses returned false value at first or true value at last.

SEE ALSO

Sympa::Internals::Workflow, Sympa::Spool.

HISTORY

Sympa::Spindle appeared on Sympa 6.2.10.