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.