NAME

       UR::Context::ObjectFabricator - Track closures used to fabricate objects from data sources

DESCRIPTION

       Object Fabricators are closures that accept listrefs of data returned by data source iterators, take
       slices out of them, and construct UR objects out of the results.  They also handle updating the query
       cache and merging changed DB data with previously cached objects.

       UR::Context::ObjectFabricator objects are used internally by UR::Context, and not intended to be used
       directly.

METHODS

       create_for_loading_template
             my $fab = UR::Context::ObjectFabricator->create_for_loading_template(
                           $context, $loading_tmpl_hashref, $template_data,
                           $rule, $rule_template, $values, $dsx);

           Returns  an  object  fabricator instance that is able to construct objects of the rule's target class
           from rows of data returned by data source iterators.  Object fabricators  are  used  a  part  of  the
           object  loading process, and are called by UR::Context::get_objects_for_class_and_rule() to transform
           a row of data returned by a data source iterator into a UR object.

           For each class involved in a get request, the system prepares a loading template that describes which
           columns of the data source data are to be used to construct an instance of that class.  For  example,
           in  the  case  where a get() is done on a child class, and the parent and child classes store data in
           separate tables linked by a relation-property/foreign-key, then the query  against  the  data  source
           will  involve  and  SQL  join  (for  RDBMS  data  sources).  That join will produce a result set that
           includes data from both tables.

           The $loading_tmpl_hashref will have information about which columns of that result set map  to  which
           properties  of  each  involved class.  The heart of the fabricator closure is a list slice extracting
           the data for that class and assigning it to a hash slice of properties to fill in the initial  object
           data  for  its  class.   The  remainder  of  the  closure  is  bookkeeping  to  keep the object cache
           ($UR::Context::all_objects_loaded) and query cache ($UR::Context::all_params_loaded) consistent.

           The interaction of the object fabricator, the query cache, object cache  pruner  and  object  loading
           iterators  that may or may not have loaded all their data requires that the object fabricators keep a
           list of changes they plan to make to the query cache instead of applying  them  directly.   When  the
           Underlying  Context  Loading iterator has loaded the last row from the Data Source Iterator, it calls
           "finalize()" on the object fabricator to tell it to go  ahead  and  apply  its  changes;  essentially
           treating that data as a transaction.

       all_object_fabricators
             my @fabs = UR::Context::ObjectFabricator->all_object_fabricators();

           Returns a list of all object fabricators that have not yet been finalized

       fabricate
             my $ur_object = $fab->fabricate([columns,from,data,source]);

           Given  a  listref  of  data pulled from a data source iterator, it slices out the appropriate columns
           from the list and constructs a single object to return.

       is_loading_in_progress_for_boolexpr
               my $bool = $fab->is_loading_in_progress_for_boolexpr($boolexpr);

           Given a UR::BoolExpr instance, it returns true if the  given  fabricator  is  prepared  to  construct
           objects  matching  this  boolexpr.   This is used by UR::Context to know if other iterators are still
           pulling in objects that could match another iterator's boolexpr, and it should  therefore  not  trust
           that the object cache is conplete.

       finalize
             $fab->finalize();

           Indicates to the iterator that the caller is done using it for constructing objects, probably because
           the  data  source  has  no  more  data or the iterator that was using this fabricator has gone out of
           scope.

       apply_all_params_loaded
             $fab->apply_all_params_loaded();

           As the fabricator constructs objects, it buffers changes to all_params_loaded  (the  Context's  query
           cache)  to  maintain  consistency if multiple iterators are working concurrently.  At the appripriate
           time, call apply_all_params_loaded() to take those changes and apply them to  the  current  Context's
           all_params_loaded.

perl v5.32.1                                       2022-01-17                 UR::Context::ObjectFabricator(3pm)