NAME

Tangram::Storage - persistent object database

SYNOPSIS

   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 );

   $storage->disconnect();

DESCRIPTION

A Tangram::Storage object is a connection to a database configured for use with Tangram.

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.

If weakref support is available, Storage uses weak references to keep track of objects that have already been loaded. This does not prevent the objects from being reclaimed by Perl. IOW, the client code decides how long an object remains in memory.

If weakref support is not available, Storage uses normal, 'strong' references. Storage will pin in memory all the objects that have been loaded and inserted through it, until you call "disconnect" or "unload".

In either case, Tangram will not break circular structures for you.

INTERNAL CONNECTION

Except in the implementation of cursor(), Tangram uses a single DBI 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.

Tangram::Cursors returned by cursor() do not suffer from this limitation because they use a separate DBI connection.

CLASS METHODS

connect

   $storage = connect( $schema,
      $data_source, $username, $auth, \%options )

Connects to a storage and return a handle object. Dies in case of failure.

$schema is an Tangram::Schema object consistent with the database.

$data_source, $username and $auth are passed directly to DBI::connect().

\%options is a reference to a hash that may contain the following fields:

• dbh

All fields are optional.

dbh can be used to connect a Storage via an existing DBI handle. $data_source, $username and $auth are still needed because Tangram may need to open extra connections (see below).

INSTANCE METHODS

insert

   $storage->insert( @objs );

Inserts objects in storage. Returns the ID(s) assigned to the object(s). This method is valid in both "scalar and list contexts".

The inserted objects must be of a class described in the schema associated to the storage.

Attempting to insert an object that is already persistent in the storage is an error.

Tangram will automatically insert any object that is refered by $obj if it is not already present in storage. In the following example:

   my $homer = NaturalPerson->new(
      firstName => 'Homer', name => 'Simpson',
      children => Set::Object->new(
         NaturalPerson->new(
            firstName => 'Bart', name => 'Simpson' ),
         NaturalPerson->new(
            firstName => 'Lisa', name => 'Simpson' ),
         NaturalPerson->new(
            firstName => 'Maggie', name => 'Simpson'
      ) ) );

   $storage->insert( $homer );

...Tangram automatically inserts the kids along with Homer.

update

   $storage->update( @objs );

Save objects to storage. This method is valid in both "scalar and list contexts".

The objects must be of a class described in the schema associated to the storage.

Attempting to update an object that is not already present in the storage is an error.

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:

   my $homer = NaturalPerson->new(
      firstName => 'Homer', name => 'Simpson' );
   $storage->insert( $homer );

   my $marge = NaturalPerson->new(
      firstName => 'Marge', name => 'Simpson',
      age => 34 );
   $storage->insert( $marge );

   $marge->{age} = 35;

   $homer->{partner} = $marge;

   $homer->{children} = Set::Object->new(
      NaturalPerson->new(
         firstName => 'Bart', name => 'Simpson' ),
      NaturalPerson->new(
         firstName => 'Lisa', name => 'Simpson' ),
      NaturalPerson->new(
         firstName => 'Maggie', name => 'Simpson' ) );

   $storage->update( $homer );

...Tangram automatically inserts the kids when their father is updated. OTOH, $marge will not be automatically inserted nor updated; her age will remain '34' in persistent storage.

id

   $id = $storage->id( $obj );
   @id = $storage->id( @obj );

Returns the IDs of the given objects. If an object is not persistent in storage yet, its corresponding ID is undef().

This method is valid in both "scalar and list contexts".

load

   $obj = $storage->load( $id );
   @obj = $storage->load( @id );

Returns a list of objects given their IDs. Dies if any ID has no corresponding persistent object in storage.

This method is valid in both "scalar and list contexts".

remote

   @remote = $storage->remote( @classes );

Returns a list of Tangram::Remote objects of given classes. This method is valid in both "scalar and list contexts".

select

   @objs = select( $remote );

   @objs = select( $remote, $filter );

   @objs = select( $remote,
      opt1 => val1, opt2 => val2, ...);

Valid only in list context. Returns a list containing all the objects that satisfy $filter.

$remote can be either a Remote object of an array of Remote objects. If it is a single Remote, a list of objects is returned. If it is an array, a list of array of objects is returned.

If one argument is passed, return all the objects of the given type.

If two arguments are passed, the second argument must be a Filter. select() returns the objects that satisfy $filter and are type-compatible with the corresponding Remote.

If more than two arguments are passed, the arguments after $remote are treated as key/value pairs. Currently Tangram recognizes the following directives:

• filter

• distinct

• order

• desc

• distinct

filter specifies a Filter that can be used to restrict the result set.

distinct specifies that each object in the result set must be unique (Tangram generates a SELECT DISTINCT).

order THIS OPTION IS DEPRECATED!

desc THIS OPTION IS DEPRECATED!

distinct is a boolean; a true value specifies that the same object should ocur only once in the result set.

Valid only in list context.

cursor

   $cursor = $storage->cursor( $remote );
   $cursor = $storage->cursor( $remote, $filter );
   $cursor = cursor( $remote,
      opt1 => val1, op2 => val2, ...);

Valid only in scalar context.

Returns a Cursor on the objects that are type-compatible with $remote.

If one argument is passed, the cursor returns all the objects of the given type.

If two arguments are passed, the second argument must be a Filter. The cursor returns the objects that satisfy $filter and are type-compatible with the corresponding Remote.

If more than two arguments are passed, the arguments after $remote are treated as key/value pairs. Currently Tangram recognizes the following directives:

• filter

• order

• desc

• distinct

• retrieve

For options filter, order, desc and distinct, see select.

Option retrieve is an array of Expr, to be retrieved in addition to the object itself.

erase

   $storage->erase( @obj );

Removes objects from persistent storage. The objects remain present in transient storage.

tx_start

   $storage->tx_start();

Starts a new Tangram transaction.

Tangram transactions can be nested.

Tangram maintains a transaction nesting count for each storage 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 "internal connection".

Example:

   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

In (1), f() commits the changes to $homer directly to the database.

In (2), f() transparently reuses the transaction opened by g().\ Changes to both $homer and $marge are commited to the database when g() calls tx_commit().

tx_commit

   $storage->tx_commit();

Commits the current Tangram transaction for this storage. If the transaction being commited is the outermost transaction for this storage, the DBI transaction is also commited.

tx_rollback

   $storage->tx_rollback();

Rolls back the current Tangram transaction for this storage. If the transaction being rolled back is the outermost transaction for this storage, the DBI transaction is also rolled back.

tx_do

   $storage->tx_do( sub { ... } );

Executes CODEREF under the protection of a Tangram transaction and pass it @args in the argument list.

Rolls back the transaction if CODEREF dies; in which case the exception is re-thrown.

Returns the results of CODEREF, either as a scalar or as a list depending on the context in which tx_do was called.

Example:

   $storage->tx_do(
      sub
      {
         $storage->update( $homer );
         # do things, die perhaps
         $storage->update( $marge );
      } );

Both $homer and $marge will be updated, or none will, depending on whether the anonymous subroutine passed to tx_do() dies.

unload

   $storage->unload( @obj );

Drops references to persistent objects present in memory. @objs may contain both objects and object ids. If @objs is empty, unloads all the objects loaded by this storage.

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.

As a consequence, these objects will not be reclaimed by Perl's automatic memory management mechanism until either disconnect() or unload() is called.

unload() 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.

disconnect

   $storage->disconnect();

Disconnects from the database. Drops references to persistent objects present in memory (see unload).

cpanm Tangram

perl -MCPAN -e shell
install Tangram