NAME

       UR::DataSource::FileMux - Parent class for datasources which can multiplex many files together

DEPRECATED

       This module is deprecated.  Use UR::DataSource::Filesystem instead.

SYNOPSIS

         package MyNamespace::DataSource::MyFileMux;
         class MyNamespace::DataSource::MyFileMux {
             is => ['UR::DataSource::FileMux', 'UR::Singleton'],
         };
         sub column_order { ['thing_id', 'thing_name', 'thing_color'] }
         sub sort_order { ['thing_id'] }
         sub delimiter { "\t" }
         sub constant_values { ['thing_type'] }
         sub required_for_get { ['thing_type'] }
         sub file_resolver {
             my $thing_type = shift;
             return '/base/path/to/files/' . $thing_type;
         }

         package main;
         class MyNamespace::ThingMux {
             id_by => ['thing_id', 'thing_type' ],
             has => ['thing_id', 'thing_type', 'thing_name','thing_color'],
             data_source => 'MyNamespace::DataSource::MyFileMux',
         };

         my @objs = MyNamespace::Thing->get(thing_type => 'people', thing_name => 'Bob');

DESCRIPTION

       UR::DataSource::FileMux provides a framework for file-based data sources where the data files are split
       up between one or more parameters of the class.  For example, in the synopsis above, the data for the
       class is stored in several files in the directory /base/path/to/files/.  Each file may have a name such
       as 'people' and 'cars'.

       When a get() request is made on the class, the parameter 'thing_type' must be present in the rule, and
       the value of that parameter is used to complete the file's pathname, via the file_resolver() function.
       Note that even though the 'thing_type' parameter is not actually stored in the file, its value for the
       loaded objects gets filled in because that parameter exists in the constant_values() configuration list,
       and in the get() request.

   Configuration
       These methods determine the configuration for your data source and should appear as properties of the
       data source or as functions in the package.

       delimiter()
       record_separator()
       skip_first_line()
       column_order()
       sort_order()
           These configuration items behave the same as in a UR::DataSource::File-based data source.

       required_for_get()
           required_for_get()  should  return a listref of parameter names.  Whenever a get() request is made on
           the  class,  the   listed   parameters   must   appear   in   the   rule,   or   be   derivable   via
           UR::Context::infer_property_value_from_rule().

       file_resolver()
           file_resolver()  is  called  as  a  function  (not  a  method).   It should accept the same number of
           parameters as are mentioned in required_for_get().   When  a  get()  request  is  made,  those  named
           parameters  are  extracted  from  the  rule and passed in to the file_resolver() function in the same
           order.  file_resolver() must return a string that is used as the pathname to the file  that  contains
           the needed data.  The function must not have any other side effects.

           In  the  case where the data source is a regular object (not a UR::Singleton'), then the file_resover
           parameter should return a coderef.

       constant_values()
           constant_values() should return a listref of parameter names.  These parameter names are used by  the
           object  loader  system  to  fill in data that may not be present in the data files.  If the class has
           parameters that are not actually stored in the data files, then the parameter  values  are  extracted
           from the rule and stored in the loaded object instances before being returned to the user.

           In  the  synopsis  above,  thing_type  is  not  stored  in the data files, even though it exists as a
           parameter of the MyNamespace::ThingMux class.

   Theory of Operation
       As part of the data-loading infrastructure inside UR, the parameters in a get() request  are  transformed
       into  a UR::BoolExpr instance, also called a rule.  UR::DataSource::FilMux hooks into that infrastructure
       by implementing create_iterator_closure_for_rule().  It first collects the values for all the  parameters
       mentioned    in    required_for_get()    by    passing    the    rule    and    needed    parameter    to
       infer_property_value_from_rule() of the current  Context.   If  any  of  the  needed  parameters  is  not
       resolvable, an exception is raised.

       Some  of  the rule's parameters may have multiple values.  In those cases, all the combinations of values
       are expanded.  For example of param_a has 2 values, and param_b has 3 values, then there are  6  possible
       combinations.

       For  each combination of values, the file_resolver() function is called and returns a pathname.  For each
       pathname, a file-specific  data  source  is  created  (if  it  does  not  already  exist),  the  server()
       configuration  parameter created to return that pathname.  Other parameters are copied from the values in
       the FileMux data source, such  as  column_names  and  delimiter.   create_iterator_closure_for_rule()  is
       called on each of those data sources.

       Finally, an iterator is created to wrap all of those iterators, and is returned.

INHERITANCE

       UR::DataSource

SEE ALSO

       UR, UR::DataSource, UR::DataSource::File

perl v5.38.2                                       2024-06-15                       UR::DataSource::FileMux(3pm)