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
       paremeter 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 excpetion 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