.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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 "Tangram::Storage 3pm"
.TH Tangram::Storage 3pm "2015-11-09" "perl v5.20.2" "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"
Tangram::Storage \- persistent object database
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use Tangram;
\&   
\&   $storage = Tangram::Storage\->connect( $schema,
\&      $data_source, $username, $password );
\&
\&   $oid = $storage\->insert( $obj );
\&   @oids = $storage\->insert( @objs );
\&
\&   $storage\->update( $obj );
\&   $storage\->update( @objs );
\&
\&   $obj = $storage\->load( $oid );
\&   @objs = $storage\->load( @oids );
\&
\&   @objs = $storage\->select( $class );
\&   @objs = $storage\->select( $remote, $filter );
\&
\&   $cursor = $storage\->cursor( $remote, $filter );
\&
\&   if ($storage\->oid_isa($oid, "ClassName")) {
\&       # oid $oid is a ClassName
\&   }
\&
\&   $storage\->disconnect();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A Tangram::Storage object is a connection to a database configured for
use with Tangram.
.SH "MEMORY MANAGEMENT"
.IX Header "MEMORY MANAGEMENT"
Starting with version 1.18, Tangram attempts to use the support for
weak reference that was introduced in Perl 5.6. Whether that support
is found or not has a major impact on how Storage influences object
lifetime.
.PP
If weakref support \fIis\fR available, Storage uses weak references to
keep track of objects that have already been loaded. This does \fInot\fR
prevent the objects from being reclaimed by Perl. \s-1IOW,\s0 the \fIclient\fR
code decides how long an object remains in memory.
.PP
If weakref support \fIis not\fR available, Storage uses normal, 'strong'
references. Storage will pin in memory all the objects that have been
loaded \fIand\fR inserted through it, until you call \*(L"disconnect\*(R" or
\&\*(L"unload\*(R".
.PP
In either case, Tangram will \fInot\fR break circular structures for you.
.PP
Note that caching objects between transactions is a great way to ruin
the transactional guarantees that your database (hopefully) provides.
.PP
That being said, be sure to check out the \f(CW\*(C`unload_all()\*(C'\fR method.
.SH "INTERNAL CONNECTION"
.IX Header "INTERNAL CONNECTION"
Except in the implementation of \fIcursor()\fR, Tangram uses a single \s-1DBI\s0
connection in its operations.  That connection is called the
\&'internal' connection. Since, in general, database managers do not
allow multiple result sets on the same connection, the internal
connection can be used only to carray a single task at a time.
.PP
Tangram::Cursors returned by \fIcursor()\fR do not suffer from this
limitation because they use a separate \s-1DBI\s0 connection.
.SH "CLASS METHODS"
.IX Header "CLASS METHODS"
.SS "connect"
.IX Subsection "connect"
.Vb 2
\&   $storage = connect( $schema,
\&      $data_source, $username, $auth, \e%options )
.Ve
.PP
Connects to a storage and return a handle object. Dies in case of failure.
.PP
\&\f(CW$schema\fR is an Tangram::Schema object consistent with the database.
.PP
\&\f(CW$data_source\fR, \f(CW$username\fR and \f(CW$auth\fR are passed directly to
\&\fIDBI::connect()\fR.
.PP
\&\e%options is a reference to a hash that may contain the following
fields:
.IP "\(bu" 4
dbh
.Sp
Pass in an already connected \s-1DBI\s0 handle
.IP "\(bu" 4
no_tx
.Sp
Specify explicitly whether or not transactions are possible.  If they
are not, then Tangram can guarantee consistency by serialising
transaction updates \- which guarantees poor performance and means that
you can never use \f(CW\*(C`$storage\->rollback\*(C'\fR.
.Sp
If you are using MySQL, you should consider using the InnoDB table
type to avoid this problem.  Also note that you will explicitly have
to set this option if you have InnoDB tables configured, as there is
no real way of telling if transactions are available for any given
query without either trying to do a rollback, or querying the table
types for every table.  Which I don't think it's Tangram's duty to do!
.IP "\(bu" 4
no_subselects
.Sp
Functions that need to perform sub-selects will die immediately or
attempt to emulate the functionality required, rather than relying on
the \s-1RDBMS\s0 to return a failure.
.Sp
This is currently ignored, but that's not functionally relevant :\-).
It can be read as \f(CW\*(C`$storage\->{no_subselects}\*(C'\fR however, as the
correct value is automatically detected on connection.
.PP
All fields are optional.
.PP
\&\f(CW\*(C`dbh\*(C'\fR can be used to connect a Storage via an existing \s-1DBI\s0
handle. \f(CW$data_source\fR, \f(CW$username\fR and \f(CW$auth\fR are still needed because
Tangram may need to open extra connections (see below).
.SH "INSTANCE METHODS"
.IX Header "INSTANCE METHODS"
.SS "insert"
.IX Subsection "insert"
.Vb 1
\&   $storage\->insert( @objs );
.Ve
.PP
Inserts objects in storage. Returns the \s-1ID\s0(s) assigned to the
object(s).  This method is valid in both \*(L"scalar and list contexts\*(R".
.PP
The inserted objects must be of a class described in the schema
associated to the storage.
.PP
Attempting to insert an object that is already persistent in the
storage is an error.
.PP
Tangram will automatically insert any object that is refered by \f(CW$obj\fR
if it is not already present in storage. In the following example:
.PP
.Vb 10
\&   my $homer = NaturalPerson\->new(
\&      firstName => \*(AqHomer\*(Aq, name => \*(AqSimpson\*(Aq,
\&      children => Set::Object\->new(
\&         NaturalPerson\->new(
\&            firstName => \*(AqBart\*(Aq, name => \*(AqSimpson\*(Aq ),
\&         NaturalPerson\->new(
\&            firstName => \*(AqLisa\*(Aq, name => \*(AqSimpson\*(Aq ),
\&         NaturalPerson\->new(
\&            firstName => \*(AqMaggie\*(Aq, name => \*(AqSimpson\*(Aq
\&      ) ) );
\&
\&   $storage\->insert( $homer );
.Ve
.PP
\&...Tangram automatically inserts the kids along with Homer.
.SS "update"
.IX Subsection "update"
.Vb 1
\&   $storage\->update( @objs );
.Ve
.PP
Save objects to storage.  This method is valid in both \*(L"scalar and
list contexts\*(R".
.PP
The objects must be of a class described in the schema associated to
the storage.
.PP
Attempting to update an object that is not already present in the
storage is an error.
.PP
Tangram will automatically insert any object that is refered by an
inserted object if it is not already present in storage. It will not
automatically update the refered objects that are already stored. In
the following example:
.PP
.Vb 3
\&   my $homer = NaturalPerson\->new(
\&      firstName => \*(AqHomer\*(Aq, name => \*(AqSimpson\*(Aq );
\&   $storage\->insert( $homer );
\&
\&   my $marge = NaturalPerson\->new(
\&      firstName => \*(AqMarge\*(Aq, name => \*(AqSimpson\*(Aq,
\&      age => 34 );
\&   $storage\->insert( $marge );
\&
\&   $marge\->{age} = 35;
\&
\&   $homer\->{partner} = $marge;
\&
\&   $homer\->{children} = Set::Object\->new(
\&      NaturalPerson\->new(
\&         firstName => \*(AqBart\*(Aq, name => \*(AqSimpson\*(Aq ),
\&      NaturalPerson\->new(
\&         firstName => \*(AqLisa\*(Aq, name => \*(AqSimpson\*(Aq ),
\&      NaturalPerson\->new(
\&         firstName => \*(AqMaggie\*(Aq, name => \*(AqSimpson\*(Aq ) );
\&
\&   $storage\->update( $homer );
.Ve
.PP
\&...Tangram automatically inserts the kids when their father is
updated. \s-1OTOH,\s0 \f(CW$marge\fR will not be automatically inserted nor updated;
her age will remain '34' in persistent storage.
.PP
Tangram does not perform any deadlock detection on updates.  You have
to rely on your database back-end for that.
.SS "id"
.IX Subsection "id"
.Vb 2
\&   $id = $storage\->id( $obj );
\&   @id = $storage\->id( @obj );
.Ve
.PP
Returns the IDs of the given objects. If an object is not persistent
in storage yet, its corresponding \s-1ID\s0 is \fIundef()\fR.
.PP
This method is valid in both \*(L"scalar and list contexts\*(R".
.SS "oid_isa"
.IX Subsection "oid_isa"
.Vb 3
\&   if ($storage\->oid_isa($id, "ClassName")) {
\&      ...
\&   }
.Ve
.PP
Checks that the passed Object \s-1ID, \s0\f(CW$id\fR, is a \*(L"ClassName\*(R" according
to the schema.  This check relies solely on the information in the
schema, not Perl's idea of \f(CW\*(C`\->isa\*(C'\fR relationships.
.SS "load"
.IX Subsection "load"
.Vb 2
\&   $obj = $storage\->load( $id );
\&   @obj = $storage\->load( @id );
.Ve
.PP
Returns a list of objects given their IDs.
Dies if any \s-1ID\s0 has no corresponding persistent object in storage.
.PP
This method is valid in both \*(L"scalar and list contexts\*(R".
.SS "remote"
.IX Subsection "remote"
.Vb 1
\&   @remote = $storage\->remote( @classes );
.Ve
.PP
Returns a list of \f(CW\*(C`Tangram::Remote\*(C'\fR objects of given classes.  See
Tangram::Remote for a more detailed description.  These objects are
called \fIremote\fR objects in the documentation.
.SS "select"
.IX Subsection "select"
.Vb 1
\&   @objs = $storage\->select( $remote );
\&
\&   @objs = $storage\->select( $remote, $filter );
\&
\&   @objs = $storage\->select( $remote,
\&      opt1 => val1, opt2 => val2, ...);
.Ve
.PP
Valid only in list context. Returns a list containing all the objects
that satisfy \f(CW$filter\fR.
.PP
\&\f(CW$remote\fR can be either a \fIremote\fR object of an array of \fIremote\fR
objects. If it is a single \fIremote\fR object, a list of objects is
returned. If it is an array, a list of arrays of objects is returned.
.PP
If one argument is passed, return all the objects of the given type.
.PP
If two arguments are passed, the second argument must be a
Filter. \f(CW\*(C`select()\*(C'\fR returns the objects that satisfy \f(CW$filter\fR and
are type-compatible with the corresponding \fIremote\fR object.
.PP
If more than two arguments are passed, the arguments after \f(CW$remote\fR
are treated as key/value pairs.  Currently Tangram recognizes the
following directives:
.IP "\(bu" 4
filter
.IP "\(bu" 4
distinct
.IP "\(bu" 4
order
.IP "\(bu" 4
desc
.IP "\(bu" 4
distinct
.IP "\(bu" 4
limit
.IP "\(bu" 4
outer_filter
.IP "\(bu" 4
force_outer
.PP
\&\f(CW\*(C`filter\*(C'\fR specifies a Filter that can be used to restrict the result
set.
.PP
Filters are based on simple Perl expressions involving \fIremote\fR objects.
The expression is eventually compiled into its \s-1SQL\s0 equivalent, becoming
part of a WHERE-CLAUSE.
.PP
For example:
.PP
.Vb 5
\&    my $remote_person = $storage\->remote(\*(AqFoo::Person\*(Aq);
\&    my @martians = $storage\->select(
\&        $remote_person,
\&        filter => ($remote_person\->{location} eq \*(AqMars\*(Aq)
\&    );
.Ve
.PP
Would retrieve all martians from the database.
.PP
Note that the fields are accessed as hash reference keys instead of the
(expected) method calls.
.PP
In the previous example, \f(CW\*(C`\->{location}\*(C'\fR is seen as a scalar from Perl
and as some derivative of a \s-1VARCHAR/TEXT\s0 field on the database side.
But filters can operate on many other types, including references to other
persistent objects. For instance:
.PP
.Vb 3
\&    # instantiate the obj and add it to the DB
\&    my $mars = Foo::Location\->new( name => \*(AqMars\*(Aq);
\&    $storage\->insert($mars);
\&
\&    my $remote_person = $storage\->remote(\*(AqFoo::Person\*(Aq);
\&    my @martians = $storage\->select(
\&        $remote_person,
\&        filter => ($remote_person\->{location} == $mars)
\&    );
.Ve
.PP
In this case, having a reference to the persistent object \f(CW$mars\fR
handy allows us to look for all objects that reference it. Keep in
mind that these are introductory examples \- the relationship between
two classes of objects and how they behave depends on defined
relationships between them \- whether it's a \f(CW\*(C`ref\*(C'\fR, an \f(CW\*(C`array\*(C'\fR, etc
\&\*(-- see Tangram::Schema and Tangram::Type for more information on
relationship types.
.PP
Filters can also be joined together with boolean expressions:
.PP
.Vb 7
\&    my $r_user = $storage\->remote(\*(AqMy::Users\*(Aq);
\&    my @active_premium_users = $storage\->select( $r_user,
\&        filter => (# "&" is not a typo \- see below
\&                   ($r_user\->{is_logged_in} eq \*(AqY\*(Aq) &
\&                   ($r_user\->{is_premium} eq \*(AqY\*(Aq )
\&                  )
\&    );
.Ve
.PP
This select retrieves all the users currently logged in who also have
a premium account. Note the use of \f(CW\*(C`&\*(C'\fR instead of \f(CW\*(C`&&\*(C'\fR (or \f(CW\*(C`and\*(C'\fR) \-
this is due to a problem in the way Perl handles operator overloading
(\f(CW\*(C`&&\*(C'\fR may not be overloaded).  For the basic boolean operators, use
\&\f(CW\*(C`&\*(C'\fR as \s-1AND, \s0\f(CW\*(C`|\*(C'\fR as \s-1OR\s0 and \f(CW\*(C`!\*(C'\fR as \s-1NOT.\s0
.PP
Other overloaded bits that work as expected are:
.PP
.Vb 1
\&    + \- * / == eq != ne < lt <= le > gt >= ge cos sin acos
.Ve
.PP
\&...which are translated to their \s-1SQL\s0 counterparts as closely as possible.
.PP
Tip: Filters can also be created beforehand by using this simple syntax:
.PP
.Vb 1
\&    my $new_filter = ($r_user\->{is_logged_in} eq \*(AqY\*(Aq);
.Ve
.PP
Then you can add expressions to it by doing (for example):
.PP
.Vb 1
\&    $new_filter &= (r_user\->{is_premium} eq \*(AqY\*(Aq);
.Ve
.PP
and use it in the expression like so:
.PP
.Vb 4
\&    my @active_premium_users = $storage\->select
\&        ( $r_user,
\&          filter => $new_filter
\&        );
.Ve
.PP
As of Tangram 2.08_02, The scalar value \f(CW1\fR may be used as an
\&\*(L"identity\*(R" filter.
.PP
See also \f(CW\*(C`Tangram::Expr\*(C'\fR.
.PP
\&\f(CW\*(C`distinct\*(C'\fR specifies that each object in the result set must be
unique (Tangram generates a \s-1SELECT DISTINCT\s0).
.PP
\&\f(CW\*(C`order\*(C'\fR specifies attributes in terms of one or more of the remote
objects \- any that are being selected, or any that appear in the
filter.
.PP
As of Tangram 2.09, you can also directly use \s-1SQL\s0 expressions in
\&\f(CW\*(C`order\*(C'\fR expressions, though you should consider how portable this
may or may not be.
.PP
\&\f(CW\*(C`desc\*(C'\fR specifies that the order should be descending. For example:
.PP
.Vb 3
\&    $storage\->select( $object, filter => (...),
\&                      order => [ $remote_foo\->{field1} ],
\&                      desc => 1  );
.Ve
.PP
would order \s-1DESC \s0(descending, high to low) all the fields listed in
the \f(CW\*(C`order\*(C'\fR clause.
.PP
Passing:
.PP
.Vb 1
\&                      desc => 0
.Ve
.PP
would order all the fields \s-1ASC \s0(ascending, low to high).
.PP
To specify which fields should be ordered \s-1DESC\s0 and which ones should be
ordered \s-1ASC,\s0 pass an array ref to \f(CW\*(C`desc\*(C'\fR, like this:
.PP
.Vb 7
\&    $storage\->select( $object, filter => (...),
\&                      order => [
\&                                $remote_foo\->{field1},
\&                                $remote_foo\->{field2},
\&                                $remote_foo\->{field3},
\&                               ],
\&                      desc => [ 1, 0, 1 ]  );
.Ve
.PP
This will order \f(CW\*(C`field1\*(C'\fR and \f(CW\*(C`field3\*(C'\fR descending, and \f(CW\*(C`field2\*(C'\fR
ascending.
.PP
\&\f(CW\*(C`distinct\*(C'\fR is a boolean; a true value specifies that the same object
should ocur only once in the result set.  In general, this is a good
idea;
.PP
\&\f(CW\*(C`limit\*(C'\fR is a maximum number of rows to retrieve; in fact, with some
databases you can give two numbers to this to get the rows between N
and M of a select.  See your \s-1RDBMS\s0 manual for more.  If you want to
specify more than one number, you may use the following syntax:
.PP
.Vb 2
\&   $storage\->select( $object, filter => (...),
\&                     limit => [ 5, 10 ] );
.Ve
.PP
The above example would return rows 6 through 15 on a MySQL database.
.PP
The select method is valid only in list context.
.PP
\&\f(CW\*(C`outer_filter\*(C'\fR and \f(CW\*(C`force_outer\*(C'\fR are \s-1EXPERIMENTAL API\s0 features.
.PP
If you pass any filter conditions into \f(CW\*(C`outer_filter\*(C'\fR instead of
\&\f(CW\*(C`filter\*(C'\fR, then any mentioned tables are connected by an outer join.
What this means is that the object does not necessarily have to be
present for the select to return a row; it may also be \f(CW\*(C`undef\*(C'\fR.
.PP
The \f(CW\*(C`force_outer\*(C'\fR option expects an array ref of Tangram::Remote
objects.  These tables are joined with an outer join clause.
.PP
The outer join related code is extremely hairy, and you are advised to
ensure that you test each outer join query that you are going to use
with new versions of Tangram.
.PP
Do not try to combine inheritance and outer joins if you want to run
your application on toy databases, currently this means SQLite and
MySQL.  SQLite does not parse \s-1SQL\s0 nested join syntax and MySQL just
gets the join all wrong.  At least, on my testbed system.  \s-1YMMV.\s0
.ie n .SS "sum( $expr, [$filter] )"
.el .SS "sum( \f(CW$expr\fP, [$filter] )"
.IX Subsection "sum( $expr, [$filter] )"
Returns the total of the remote expression ($expr) for all rows that
match \f(CW$filter\fR, as summed by the \s-1RDBMS. \s0 \f(CW$filter\fR is optional, and if
not passed the implication is to sum the value for \s-1ALL\s0 objects of that
type.
.PP
.Vb 3
\&   my $r_thing = $storage\->remote("Thing");
\&   $sum = $storage\->sum( $r_thing\->{field},
\&                         ($r_thing\->{foo} eq "bar") );
.Ve
.PP
It is also possible to pass a list of fields to sum, as an array ref:
.PP
.Vb 2
\&   ($sum_expr1, $sum_expr2)
\&       = $storage\->sum( [ $expr1, $expr2 ], $filter );
.Ve
.ie n .SS "count( $expr, [$filter] )"
.el .SS "count( \f(CW$expr\fP, [$filter] )"
.IX Subsection "count( $expr, [$filter] )"
Works as \fB\f(BIsum()\fB\fR, but returns the count of the given objects or
columns instead of the sum.
.PP
This function does \fInot\fR support counting multiple columns by passing
an array ref.  However, this can be achieved using the
\&\f(CW\*(C`\->count()\*(C'\fR remote expression function (see Tangram::Expr).
.PP
If your filter is simple enough, then you can just pass the filter in
without an \f(CW$expr\fR.
.SS "cursor"
.IX Subsection "cursor"
.Vb 4
\&   $cursor = $storage\->cursor( $remote );
\&   $cursor = $storage\->cursor( $remote, $filter );
\&   $cursor = cursor( $remote,
\&      opt1 => val1, op2 => val2, ...);
.Ve
.PP
Valid only in scalar context.
.PP
Returns a Cursor on the objects that are type-compatible with \f(CW$remote\fR.
.PP
If one argument is passed, the cursor returns all the objects of the given type.
.PP
If two arguments are passed, the second argument must be a
Filter. The cursor returns the objects that satisfy \f(CW$filter\fR and are
type-compatible with the corresponding Remote.
.PP
If more than two arguments are passed, the arguments after \f(CW$remote\fR
are treated as key/value pairs. Currently Tangram recognizes the following
directives:
.IP "\(bu" 4
filter
.IP "\(bu" 4
order
.IP "\(bu" 4
desc
.IP "\(bu" 4
distinct
.IP "\(bu" 4
retrieve
.PP
For options \f(CW\*(C`filter\*(C'\fR, \f(CW\*(C`order\*(C'\fR, \f(CW\*(C`desc\*(C'\fR and \f(CW\*(C`distinct\*(C'\fR, see \f(CW\*(C`select\*(C'\fR.
.PP
Option \f(CW\*(C`retrieve\*(C'\fR is an array of Expr, to be retrieved in addition to
the object itself.
.SS "prefetch"
.IX Subsection "prefetch"
.Vb 1
\&   $storage\->prefetch("Class", "collection", $filter);
.Ve
.PP
This method fetches all the \*(L"collection\*(R" collections from \*(L"Class\*(R",
where \f(CW$filter\fR.
.PP
You need to be very careful with your filter \- it is quite easy to end
up with a filter that will include a single table twice with no join.
.PP
You \fBshould not\fR include an expression in the filter that matches the
type of object that you are prefetching, unless that is a *different*
object to the one you want to load.
.PP
You \fBshould\fR replace the text \*(L"Class\*(R" with a Tangram::Remote object
from your \f(CW$filter\fR if it appears in the expression.
.PP
This code is \s-1OK:\s0
.PP
.Vb 2
\&   my $r_parent = $storage\->remote( "NaturalPerson" );
\&   my $filter = ($r_parent\->{age} > 40);
\&
\&   my @parent = $storage\->select($r_parent, $filter);
\&   $storage\->prefetch($r_parent, "children" $filter);
.Ve
.PP
But this code has the problem:
.PP
.Vb 2
\&   my $r_parent = $storage\->remote( "NaturalPerson" );
\&   my $r_child  = $storage\->remote( "NaturalPerson" );
\&
\&   my $filter = (
\&                 ($r_parent\->{age} > 40) &;
\&                  $r_parent\->{children}\->includes($r_child)
\&                );
\&
\&   my @parent = $storage\->select($r_parent, $filter);
\&   my @children = $storage\->select($r_child, $filter);
\&
\&   $storage\->prefetch($r_parent, "children", $filter);
.Ve
.PP
Because \f(CW$filter\fR contains an extra `unnecessary' relationship with
\&\f(CW$r_child\fR, the filter that Tangram builds internally ends up looking
like:
.PP
.Vb 5
\&    (
\&     ($r_parent\->{age} > 40) &
\&     $r_parent\->{children}\->includes($r_child) &
\&     $r_parent\->{children}\->includes($r_child2) &
\&    );
.Ve
.PP
So, you end up including extra tables without joining them.  This
situation does not make any sense, but unfortunately because of the
definition of how \s-1RDBMS\s0' work, it is required behaviour for it to give
you a permutation of all of the unjoined tables.  <sigh>
.SS "erase"
.IX Subsection "erase"
.Vb 1
\&   $storage\->erase( @obj );
.Ve
.PP
Removes objects from persistent storage. The objects remain present in transient storage.
.SS "tx_start"
.IX Subsection "tx_start"
.Vb 1
\&   $storage\->tx_start();
.Ve
.PP
Starts a new Tangram transaction.  Tangram transactions can be nested,
but currently this does not actually make \s-1SQL \s0\f(CW\*(C`SAVEPOINT\*(C'\fR's (for
partial transaction rollback).
.PP
Instead, tangram maintains a transaction nesting count for each
storage object and commits the operations only when that count reaches
zero. This scheme makes it easy for a function to collaborate with its
caller in the management of the \*(L"internal connection\*(R".
.PP
Example:
.PP
.Vb 6
\&   sub f
\&   {
\&      $storage\->tx_start();
\&      $storage\->update( $homer );
\&      $storage\->tx_commit(); # or perhaps rollback()
\&   }
\&
\&   sub g
\&   {
\&      $storage\->tx_start();
\&      f();
\&      $storage\->update( $marge );
\&      $storage\->tx_commit(); # or perhaps rollback()
\&   }
\&
\&   f(); # 1
\&   g(); # 2
.Ve
.PP
In (1), f() commits the changes to \f(CW$homer\fR directly to the database.
.PP
In (2), f() transparently reuses the transaction opened by g().
Changes to both \f(CW$homer\fR and \f(CW$marge\fR are committed to the database when
g() calls \fItx_commit()\fR.
.PP
By default with \s-1ACID\s0 compliant database back-ends (such as Pg,
MySQL/InnoDB, Oracle and pretty much any commercial \s-1RDBMS\s0), the first
time you open a database connection, you are beginning a transaction.
However, this is not the case with the Tangram::SQLite or
Tangram::mysql back-ends, both of which do not implement
transaction isolation; therefore it is not good to assume that the
database can handle concurrent writing efficiently.
.PP
To be run safely on these non-compliant back-ends, you should
explicitly \f(CW\*(C`tx_start()\*(C'\fR at the beginning of transaction blocks rather
than relying on the default behaviour.
.SS "tx_commit"
.IX Subsection "tx_commit"
.Vb 1
\&   $storage\->tx_commit();
.Ve
.PP
Commits the current Tangram transaction for this storage.  If the
transaction being committed is the outermost transaction for this
storage, the \s-1DBI\s0 transaction is also committed.
.PP
When using the SQLite back-end, when the \s-1DBI\s0 transaction is
committed, the connection is also marked read-only (ie, AutoCommit is
enabled).
.SS "tx_rollback"
.IX Subsection "tx_rollback"
.Vb 1
\&   $storage\->tx_rollback();
.Ve
.PP
Rolls back the current Tangram transaction for this storage.
If the transaction being rolled back is the outermost transaction for this storage, the \s-1DBI\s0
transaction is also rolled back.
.SS "tx_do"
.IX Subsection "tx_do"
.Vb 1
\&   $storage\->tx_do( sub { ... } );
.Ve
.PP
Executes \s-1CODEREF\s0 under the protection of a Tangram transaction and
pass it \f(CW@args\fR in the argument list.
.PP
Rolls back the transaction if \s-1CODEREF\s0 dies; in which case the
exception is re-thrown.
.PP
Returns the results of \s-1CODEREF,\s0 either as a scalar or as a list
depending on the context in which tx_do was called.
.PP
Example:
.PP
.Vb 7
\&   $storage\->tx_do(
\&      sub
\&      {
\&         $storage\->update( $homer );
\&         # do things, die perhaps
\&         $storage\->update( $marge );
\&      } );
.Ve
.PP
Both \f(CW$homer\fR and \f(CW$marge\fR will be updated, or none will, depending on
whether the anonymous subroutine passed to \fItx_do()\fR dies.
.SS "unload"
.IX Subsection "unload"
.Vb 1
\&   $storage\->unload( @obj );
.Ve
.PP
Drops references to persistent objects present in memory. \f(CW@objs\fR may
contain both objects and object ids. If \f(CW@objs\fR is empty, unloads all
the objects loaded by this storage.
.PP
Storage keeps track of all the persistent objects that are present in
memory, in order to make sure that loading the same object twice
results in a single copy of the object.
.PP
As a consequence, these objects will not be reclaimed by Perl's
automatic memory management mechanism until either \fIdisconnect()\fR or
\&\fIunload()\fR is called.
.PP
\&\fIunload()\fR should be called only when no other references exist to
persistent objects, otherwise the same object (in the database) may
end up having two copies in transient storage, or vice versa!
.PP
In most cases, you never want to use this function \- letting objects
pass out of scope and be cleaned up is a much more natural way to let
the object cache take care of itself.
.ie n .SS "unload_all( [ $notify_method ])"
.el .SS "unload_all( [ \f(CW$notify_method\fP ])"
.IX Subsection "unload_all( [ $notify_method ])"
Drops references to all objects in the object cache.  If you pass a
notify method, then this will be passed to all objects as they are
dumped (so long as they \f(CW\*(C`\->can()\*(C'\fR handle it).  This can be used,
for instance, with Class::Tangram objects to make sure all circular
references in cached objects are cleared, if you pass \f(CW\*(C`clear_refs\*(C'\fR as
the \f(CW$notify_method\fR.
.PP
Similar warnings apply to this function as \f(CW\*(C`$storage\->unload()\*(C'\fR.
.PP
This function is particularly useful in \s-1OLTP \s0(online transaction
processing) servers.  In those, it should be called before the first
\&\f(CW\*(C`$storage\->tx_start()\*(C'\fR, so that all objects are known to be
\&\*(L"fresh\*(R" in the current transaction.  Due to \s-1ACID\s0 guarantees of
consistent reads etc (not on MySQL/MyISAM!), you should then not have
the classic \*(L"dirty read\*(R" problem \- so long as you wrap the entire
transaction in a function that catches a failure on
\&\f(CW\*(C`\-e<gt\*(C'\fR\fItx_commit()\fR> and attempts a retry (make sure to clear the
cache again before a retry!).
.PP
You might also want to see your \s-1RDBMS\s0 manual under the topic of
\&\*(L"transaction isolation\*(R", in particular the \s-1SQL\s0 command \f(CW\*(C`SET
TRANSACTION ISOLATION LEVEL\*(C'\fR.
.SS "disconnect"
.IX Subsection "disconnect"
.Vb 1
\&   $storage\->disconnect();
.Ve
.PP
Disconnects from the database. Drops references to persistent
objects present in memory (see \f(CW\*(C`unload\*(C'\fR).