.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "UR::DataSource 3pm"
.TH UR::DataSource 3pm "2019-01-02" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
UR::DataSource \- manage the the relationship between objects and a specific storage system
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  package MyApp::DataSource::DB;
\&   
\&  class MyApp::DataSource::DB {
\&      is => [\*(AqUR::DataSource::Oracle\*(Aq,\*(AqUR::Singleton\*(Aq],
\&  };
\&  sub server { \*(Aqmain_db_server\*(Aq }
\&  sub login  { \*(Aqdb_user\*(Aq }
\&  sub auth   { \*(Aqdb_passwd\*(Aq }
\&  sub owner  { \*(Aqdb_owner\*(Aq }
\&  1;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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 \s-1ID,\s0 and the module autoloader will instantiate it automatically.
.SH "INHERITANCE"
.IX Header "INHERITANCE"
UR::Object
.SH "Methods"
.IX Header "Methods"
User applications will seldom interact with data sources directly.
.IP "autogenerate_new_object_id_for_class_name_and_rule" 4
.IX Item "autogenerate_new_object_id_for_class_name_and_rule"
.Vb 1
\&  my $id = $datasource\->autogenerate_new_object_id_for_class_name_and_rule($class,$boolexpr);
.Ve
.Sp
UR::Object::Type calls this when the application calls \fBcreate()\fR on a
class to create a new instance, but does not specify a value for the \s-1ID\s0
property.  The default implementation throws an exception with \f(CW\*(C`die\*(C'\fR,
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.
.IP "next_dummy_autogenerated_id" 4
.IX Item "next_dummy_autogenerated_id"
.Vb 1
\&  my $int = $datasource\->next_dummy_autogenerated_id()
.Ve
.Sp
In a testing situation, is often preferable to avoid using the database's
sequence for \s-1ID\s0 autogeneration but still make \s-1ID\s0 values that are unique.
UR::DataSource::RDBMS calls this method if the
\&\*(L"use_dummy_autogenerated_ids\*(R" (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 \fBUR::Context::commit()\fR.
.IP "use_dummy_autogenerated_ids" 4
.IX Item "use_dummy_autogenerated_ids"
.Vb 2
\&  $bool = $datasource\->use_dummy_autogenerated_ids();
\&  $datasource\->use_dummy_autogenerated_ids($bool);
.Ve
.Sp
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 \f(CW\*(C`autogenerate_new_object_id_for_class_name_and_rule\*(C'\fR.  If
true, they should call \f(CW\*(C`next_dummy_autogenerated_id\*(C'\fR and return that value
instead of attempting to generate an \s-1ID\s0 on their own.  This flag is also 
tied to the \s-1UR_USE_DUMMY_AUTOGENERATED_IDS\s0 environment variable.
.IP "resolve_data_sources_for_rule" 4
.IX Item "resolve_data_sources_for_rule"
.Vb 1
\&  $possibly_other_data_source = $data_source\->resolve_data_sources_for_rule($boolexpr);
.Ve
.Sp
When UR::Context is determining which data source to use to process a
\&\fBget()\fR request, it looks at the class metadata for its data source, and then
calls \f(CW\*(C`resolve_data_sources_for_rule\*(C'\fR to give that data source a chance to
defer to another data source.
.IP "create_iterator_closure_for_rule_template_and_values" 4
.IX Item "create_iterator_closure_for_rule_template_and_values"
.Vb 4
\&  $subref = $datasource\->create_iterator_closure_for_rule_template_and_values(
\&                             $boolexpr_tmpl,
\&                             @values
\&                         );
.Ve
.Sp
A front-end for the more widely used \*(L"create_iterator_closure_for_rule\*(R"
.IP "create_iterator_closure_for_rule" 4
.IX Item "create_iterator_closure_for_rule"
.Vb 1
\&  $subref = $datasource\->create_iterator_closure_for_rule($boolexpr);
.Ve
.Sp
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.
.Sp
The method must accept a UR::BoolExpr \f(CW$boolexpr\fR (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.
.IP "_sync_database" 4
.IX Item "_sync_database"
.Vb 1
\&  $bool = $datasource\->_sync_database(changed_objects => $listref);
.Ve
.Sp
Called by UR::Context \fBcommit()\fR.  \f(CW$listref\fR 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 \fB_sync_database()\fR capable of
generating \s-1SQL\s0 to update, insert and delete rows from the database's tables.
.Sp
The data source should return true if all the changes were successfully 
made, false if there were problems.
.IP "commit" 4
.IX Item "commit"
.Vb 1
\&  $bool = $datasource\->commit()
.Ve
.Sp
Called by UR::Context \fBcommit()\fR.  After all data sources return true from
\&\fB_sync_database()\fR, \f(CW\*(C`commit\*(C'\fR must make those changes permanent.  For
RDBMS-type data sources, this commits the transaction.
.Sp
Return true if the commit is successful, false otherwise.
.IP "rollback" 4
.IX Item "rollback"
.Vb 1
\&  $bool = $datasource\->rollback()
.Ve
.Sp
Called by \*(L"commit\*(R" in UR::Context if any data sources has problems during 
_sync_database or commit.  It is also called by \*(L"rollback\*(R" in UR::Context.
Data sources should reverse any changes applied during a prior
\&\f(CW\*(C`_sync_database\*(C'\fR that has not been made permanent by \f(CW\*(C`commit\*(C'\fR.
.IP "get_default_handle" 4
.IX Item "get_default_handle"
.Vb 1
\&  $scalar = $datasource\->get_default_handle();
.Ve
.Sp
Should return the \*(L"handle\*(R" associated with any underlying logical data.  For
an \s-1RDBMS\s0 data source, this is the \s-1DBI\s0 database handle.  For a file-based
data source, this is the <IO::File> file handle.
.IP "create_from_inline_class_data" 4
.IX Item "create_from_inline_class_data"
.Vb 4
\&  $datasource = $data_source_class_name\->create_from_inline_class_data(
\&                                             $class_data_hashref,
\&                                             $datasource_data_hashref
\&                                         );
.Ve
.Sp
Called by the class initializer when a class definition contains an in-line 
data source definition.  See
\&\*(L"Inline Data Sources\*(R" in UR::Object::Type::Initializer.
.IP "_ignore_table" 4
.IX Item "_ignore_table"
.Vb 1
\&  $bool = $datasource\->_ignore_table($table_name);
.Ve
.Sp
Used to indicate whether the \f(CW\*(C`ur update classes\*(C'\fR command should create a
class for the named table or not.  If \fB_ignore_table()\fR returns true, then
it will not create a class.
.SH "Internal API Methods"
.IX Header "Internal API Methods"
.IP "_get_class_data_for_loading" 4
.IX Item "_get_class_data_for_loading"
.PD 0
.IP "_generate_class_data_for_loading" 4
.IX Item "_generate_class_data_for_loading"
.PD
.Vb 1
\&  $hashref = $datasource\->_resolve_query_plan($class_meta);
.Ve
.Sp
These two methods are called by UR::Context as part of the object loading
process.  \f(CW\*(C`_generate_class_data_for_loading\*(C'\fR 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.
.Sp
\&\f(CW\*(C`_get_class_data_for_loading\*(C'\fR is the main entry point; it calls 
\&\f(CW\*(C`_generate_class_data_for_loading\*(C'\fR if the data has not been generated and
cached yet, and caches the data in the class metadata object.
.IP "_resolve_query_plan" 4
.IX Item "_resolve_query_plan"
.PD 0
.IP "_generate_template_data_for_loading" 4
.IX Item "_generate_template_data_for_loading"
.PD
.Vb 1
\&  $hashref = $datasource\->_resolve_query_plan($boolexpr_tmpl);
.Ve
.Sp
These two methods are called by UR::Context as part of the object loading
process.  \f(CW\*(C`_generate_template_data_for_loading\*(C'\fR collects information from 
the UR::BoolExpr::Template \f(CW$boolexpr_tmpl\fR (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.
.Sp
\&\f(CW\*(C`_resolve_query_plan\*(C'\fR is the main entry point; it calls
\&\f(CW\*(C`_generate_template_data_for_loading\*(C'\fR if the data has not been generated and
cached yet, and caches the data in the rule template object.
.IP "_generate_loading_templates_arrayref" 4
.IX Item "_generate_loading_templates_arrayref"
.Vb 1
\&  my $listref = $datasource\->_generate_loading_templates_arrayref($listref);
.Ve
.Sp
Called by \fB_generate_template_data_for_loading()\fR.  The input is a listref of
listrefs about properties involved in a query.  The second-level data is
sets of quads:
.RS 4
.IP "1. The class object for this property" 4
.IX Item "1. The class object for this property"
.PD 0
.IP "2. The property metadata object" 4
.IX Item "2. The property metadata object"
.IP "3. The database table name the data will come from" 4
.IX Item "3. The database table name the data will come from"
.ie n .IP "4 The ""object number"", starting with 0.  This is used in inheritance or delegation where a table join will be required." 4
.el .IP "4 The ``object number'', starting with 0.  This is used in inheritance or delegation where a table join will be required." 4
.IX Item "4 The object number, starting with 0. This is used in inheritance or delegation where a table join will be required."
.RE
.RS 4
.PD
.Sp
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, \s-1ID\s0 properties, and which columns of the result set the 
values will be found.
.RE
.SH "MetaDB"
.IX Header "MetaDB"
Each Namespace created through \f(CW\*(C`ur define namespace\*(C'\fR 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.  \s-1UR\s0 itself has a MetaDB with
information about the MetaDB's schema, called UR::DataSource::Meta.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.IP "UR::DataSource::RDBMS" 4
.IX Item "UR::DataSource::RDBMS"
The base class for relational database Data Sources, such as
UR::DataSource::Oracle, UR::DataSoure::Pg, UR::DataSource::MySQL
and UR::DataSource::SQLite
.IP "UR::DataSource::File," 4
.IX Item "UR::DataSource::File,"
The base class for comma/tab delimited files
.IP "UR::DataSource::FileMux" 4
.IX Item "UR::DataSource::FileMux"
The base class for file multiplexor data sources.
.PP
UR::Context, UR::DataSource::Meta