NAME

       Sympa::DataSource - Base class of Sympa data source subclasses

SYNOPSIS

         # To implemnt Sympa::DataSource::Foo:

         package Sympa::DataSource::Foo;

         use base qw(Sympa::DataSource);

         sub _open {
             my $self = shift;
             ...
             return $handle;
         }

         sub _next {
             my $self = shift;
             ...
             return [$email, $gecos];
         }

         1;

         # To use Sympa::DataSource::Foo:

         usr Sympa::DataSource;

         $ds = Sympa::DataSource->new('Foo', 'member', context => $list,
             key => val, ...);
         if ($ds and $ds->open) {
             while (my $member = $ds->next) {
                 ...
             }
             $ds->close;
         }

DESCRIPTION

       TBD.

   Methods
       new ( $type, $role, context => $that, [ key => val, ... ] )
           Constructor.  Creates a new instance of Sympa::DataSource.

           Parameters:

           $type
               Type of data source.  This corresponds to implemented subclasses.

           $role
               Role of data source.  'member', 'owner', 'editor' or 'custom_attribute'.

           context => $that
               Context. Sympa::List instance and so on.

           key => val, ...
               Optional or mandatory parameters.

           Returns:

           A new instance, or "undef" on failure.

       close ( )
           Instance method.  Closes backend and does cleanup.

       is_external ( )
           Instance  method.   Returns  true value if the data source is external data source.  "External" means
           that it is not "include_sympa_list" (the instance of Sympa::DataSource::List) or  not  including  any
           lists on local domain.

           Known bug:

           •   If  a  data  source  is  a list included from the other external data source(s), this method will
               treat it as non-external so that some requests not allowed for external  data  sources,  such  as
               "move_user" request, on corresponding users may be allowed.

       next ( )
           Instance method.  Returns the next entry in data source.  Data source should have been opened.

       open ( )
           Instance method.  Opens backend and returns handle.

       get_id ( )
           Instance method.  Gets unique ID of the instance.

       get_short_id ( )
           Instance method.  Gets data source ID, a hexadecimal string with 8 columns.

       name ( )
           Instance method.  Gets human-readable name of data source.  Typically it is value of {name} attribute
           or result of get_short_id().

       role ( )
           Instance method.  Returns $role set by new().

       __dsh ( )
           Instance  method,  protected.   Returns native query handle which _open() returned.  This may be used
           only at inside of each subclass.

   Methods subclass should implement
       required_modules
           Class or instance method.  TBD.

       _open ( [ options... ] )
           Instance mthod.  TBD.

       _next ( [ options... ] )
           Instance method, mandatory.  TBD.

       _next_ca ( [ options... ] )
           Instance method, mandatory if the data source supports custom attribute.  TBD.

       _close (  )
           Instance method.  TBD.

   Attributes
       {context}
           Context of the data source set by new().

       Others
           The other options set by new() may be accessed as attributes.

HISTORY

       Sympa::DataSource appeared on Sympa 6.2.45b.  See also "HISTORY" in Sympa::Request::Handler::include.

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