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.