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.

6.2.70                                             2023-01-26                             Sympa::Spindle(3Sympa)