Ubuntu Manpage: UR::DataSource - manage the the relationship between objects and a specific storage system

NAME

       UR::DataSource - manage the the relationship between objects and a specific storage system

SYNOPSIS

         package MyApp::DataSource::DB;

         class MyApp::DataSource::DB {
             is => ['UR::DataSource::Oracle','UR::Singleton'],
         };
         sub server { 'main_db_server' }
         sub login  { 'db_user' }
         sub auth   { 'db_passwd' }
         sub owner  { 'db_owner' }
         1;

DESCRIPTION

       Data source instances represent a logical source of data to the application.  Most of them are likely to
       be some kind of relational database, but not all are.  UR::DataSource is an abstract base class inherited
       by other data sources.

       In normal use, your data sources will probably inherit from an abstract data source class such as
       UR::DataSource::Oracle or UR::DataSource::File, as well as UR::Singleton.  This makes it easy to link
       classes to this data source, since the class name will be the same as its ID, and the module autoloader
       will instantiate it automatically.

INHERITANCE

       UR::Object

Methods

       User applications will seldom interact with data sources directly.

       autogenerate_new_object_id_for_class_name_and_rule
             my $id = $datasource->autogenerate_new_object_id_for_class_name_and_rule($class,$boolexpr);

           UR::Object::Type  calls this when the application calls create() on a class to create a new instance,
           but does not specify a value for the ID property.  The default  implementation  throws  an  exception
           with  "die", but UR::DataSource::RDBMS is able to query a sequence in the database to generate unique
           IDs.  A developer implementing a new data source will need to override  this  method  and  provide  a
           sensible implementation.

       next_dummy_autogenerated_id
             my $int = $datasource->next_dummy_autogenerated_id()

           In  a  testing  situation,  is  often  preferable  to  avoid  using  the  database's  sequence for ID
           autogeneration but still make ID values that are unique.  UR::DataSource::RDBMS calls this method  if
           the  "use_dummy_autogenerated_ids"  (see  below)  flag is true.  The IDs generated by this method are
           unique during the life of the process.  In addition, objects with dummy-generated IDs will  never  be
           saved to a real data source during UR::Context::commit().

       use_dummy_autogenerated_ids
             $bool = $datasource->use_dummy_autogenerated_ids();
             $datasource->use_dummy_autogenerated_ids($bool);

           Get  or  set  a  flag controlling how object IDs are autogenerated.  Data source child classes should
           look     at     the     value     of     this     flag     inside     their     implementation     of
           "autogenerate_new_object_id_for_class_name_and_rule".       If     true,     they     should     call
           "next_dummy_autogenerated_id" and return that value instead of attempting to generate an ID on  their
           own.  This flag is also tied to the UR_USE_DUMMY_AUTOGENERATED_IDS environment variable.

       resolve_data_sources_for_rule
             $possibly_other_data_source = $data_source->resolve_data_sources_for_rule($boolexpr);

           When  UR::Context is determining which data source to use to process a get() request, it looks at the
           class metadata for its data source, and then calls "resolve_data_sources_for_rule" to give that  data
           source a chance to defer to another data source.

       create_iterator_closure_for_rule_template_and_values
             $subref = $datasource->create_iterator_closure_for_rule_template_and_values(
                                        $boolexpr_tmpl,
                                        @values
                                    );

           A front-end for the more widely used "create_iterator_closure_for_rule"

       create_iterator_closure_for_rule
             $subref = $datasource->create_iterator_closure_for_rule($boolexpr);

           This is the main entry point UR::Context uses to get data from its underlying data sources.  There is
           no  default implementation; each subclass implementing specific data source types must supply its own
           code.

           The method must accept a UR::BoolExpr $boolexpr (rule), and return a subref.  Each time the subref is
           called it must return one arrayref of data satisfying the rule, and undef when there is no more  data
           to return.

       _sync_database
             $bool = $datasource->_sync_database(changed_objects => $listref);

           Called  by  UR::Context commit().  $listref will contain all the changed objects that should be saved
           to that data source.  The default implementation prints a warning message and  returns  true  without
           saving  anything.  UR::DataSource::RDBMS has a functioning _sync_database() capable of generating SQL
           to update, insert and delete rows from the database's tables.

           The data source should return true if all the changes were successfully made,  false  if  there  were
           problems.

       commit
             $bool = $datasource->commit()

           Called  by  UR::Context commit().  After all data sources return true from _sync_database(), "commit"
           must make those changes permanent.  For RDBMS-type data sources, this commits the transaction.

           Return true if the commit is successful, false otherwise.

       rollback
             $bool = $datasource->rollback()

           Called by "commit" in UR::Context if any data sources has problems during _sync_database  or  commit.
           It  is  also  called  by  "rollback" in UR::Context.  Data sources should reverse any changes applied
           during a prior "_sync_database" that has not been made permanent by "commit".

       get_default_handle
             $scalar = $datasource->get_default_handle();

           Should return the "handle" associated with any underlying logical data.  For an  RDBMS  data  source,
           this is the DBI database handle.  For a file-based data source, this is the <IO::File> file handle.

       create_from_inline_class_data
             $datasource = $data_source_class_name->create_from_inline_class_data(
                                                        $class_data_hashref,
                                                        $datasource_data_hashref
                                                    );

           Called  by  the class initializer when a class definition contains an in-line data source definition.
           See "Inline Data Sources" in UR::Object::Type::Initializer.

       _ignore_table
             $bool = $datasource->_ignore_table($table_name);

           Used to indicate whether the "ur update classes" command should create a class for the named table or
           not.  If _ignore_table() returns true, then it will not create a class.

Internal API Methods

       _get_class_data_for_loading
       _generate_class_data_for_loading
             $hashref = $datasource->_resolve_query_plan($class_meta);

           These  two  methods  are  called  by  UR::Context  as   part   of   the   object   loading   process.
           "_generate_class_data_for_loading"  collects  information  about  a  class  and its metadata, such as
           property names, subclassing information and tables connected to  the  class,  and  stores  that  data
           inside the class's metadata object.

           "_get_class_data_for_loading" is the main entry point; it calls "_generate_class_data_for_loading" if
           the data has not been generated and cached yet, and caches the data in the class metadata object.

       _resolve_query_plan
       _generate_template_data_for_loading
             $hashref = $datasource->_resolve_query_plan($boolexpr_tmpl);

           These   two   methods   are   called   by   UR::Context  as  part  of  the  object  loading  process.
           "_generate_template_data_for_loading"   collects   information   from   the    UR::BoolExpr::Template
           $boolexpr_tmpl  (rule  template)  and  returns a hashref used later by the data source.  This hashref
           includes hints about what classes will be involved in loading the resulting data, how  those  classes
           are  joined  together  and  how  columns  in the underlying query against the data source will map to
           properties of the class.

           "_resolve_query_plan" is the main entry point; it calls "_generate_template_data_for_loading" if  the
           data has not been generated and cached yet, and caches the data in the rule template object.

       _generate_loading_templates_arrayref
             my $listref = $datasource->_generate_loading_templates_arrayref($listref);

           Called by _generate_template_data_for_loading().  The input is a listref of listrefs about properties
           involved in a query.  The second-level data is sets of quads:

           1. The class object for this property
           2. The property metadata object
           3. The database table name the data will come from
           4 The "object number", starting with 0.  This is used in inheritance or delegation where a table join
           will be required.

           It  returns  a listref of hashrefs, one hashref for every class involved in the request; usually just
           1, but can be more than one if inheritance or delegation is involved.  The data includes  information
           about  the  class's properties, ID properties, and which columns of the result set the values will be
           found.

MetaDB

       Each Namespace created through "ur define namespace" will have a data  source  called  the  MetaDB.   For
       example,  the  MyApp  namespace's  MetaDB is called MyApp::DataSource::Meta.  The MetaDB is used to store
       information about the schemas of other data sources in  the  database.   UR  itself  has  a  MetaDB  with
       information about the MetaDB's schema, called UR::DataSource::Meta.

NAME

SYNOPSIS

DESCRIPTION

INHERITANCE

Methods

Internal API Methods

MetaDB

SEE ALSO