Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tangram::Tour(3)      User Contributed Perl Documentation     Tangram::Tour(3)

       Tangram::Tour - Guided Tour

       In this tour, we	add persistence	to a simple Person design.

       A Person	is either a NaturalPerson or a LegalPerson. Persons (in
       general)	have a collection of addresses.

       An address consists in a	type (a	string)	and a city (also a string).

       NaturalPerson - a subclass of Person - represents persons of flesh and
       blood. NaturalPersons have a name and a firstName (both strings)	and an
       age (an integer). NaturalPersons	sometimes have a partner (another
       NaturalPerson) and even children	(a collection of NaturalPersons).

       LegalPerson - another subclass of Person	- represents companies and
       other entities that the law regards as 'persons'. A LegalPerson has a
       name (a string) and a manager (a	NaturalPerson).

       All this	is expressed in	the following UML diagram:

			      +---------------------+	     +--------------+
			      |	      Person	    |	     |	  Address   |
			      |	    { abstract }    |1<>-->-*|--------------|
			      |---------------------|	     | kind: string |
			      +---------------------+	     | city: string |
					  |		     +--------------+
			   |				 |
		 +-------------------+		 +---------------+
	     +--*|   NaturalPerson   |		 |  LegalPerson	 |
	     |	 |-------------------|manager	 |---------------|
	     V	 | firstName: string |1---<-----1| name: string	 |
	     |	 | name: string	     |		 +---------------+
	     +--*| age:	integer	     |
	children +-------------------+
		       1       1
		       |    partner
		       |       |

       Note that Tangram does not create the corresponding Perl	packages!.
       That's up to the	user. However, to facilitate experimentation, Tangram
       comes with a module that	implements the necessary classes. For more
       information see Tangram::Springfield.

       Before we can actually store objects we must complete two steps:

       1.  Create a Schema

       2.  Create a database

   Creating a Schema
       A Schema	object contains	information about the persistent aspects of a
       system of classes.

       It also gives a degree of control over the way Tangram performs the
       object-relational mapping, but in this tour we will use all the

       Here is the Schema for Springfield:

	  $schema = Tangram::Relational->schema( {

	     classes =>	[

	      Person =>	{
		 abstract => 1,

		 fields	=> {
		     iarray => {
			addresses => { class =>	'Address', aggreg => 1 } }

	     Address =>	{
		fields => {
		   string => [ qw( kind	city ) ],

	     NaturalPerson => {

		bases => [ qw( Person )	],

		fields => {
		   string   => [ qw( firstName name ) ],
		   int	    => [ qw( age ) ],
		   ref	    => [ qw( partner ) ],
		   array    => { children => 'NaturalPerson' },

	     LegalPerson => {
		bases => [ qw( Person )	],

		fields => {
		   string   => [ qw( name ) ],
		   ref	    => [ qw( manager ) ],
	  ] } );

       The Schema lists	all the	classes	that need persistence, along with
       their attributes	and the	inheritance relationships.  We must provide
       type information	for the	attributes, because SQL	is more	typed than
       Perl.  We also tell Tangram that	"Person" is an abstract	class, so it
       wastes no time attempting to retrieve objects of	that exact class.

       Note that Tangram cannot	deduce this information	by itself. While Perl
       makes it	possible to extract the	list of	all the	classes	in an
       application, in general not all classes will need to persist. A class
       may have	both persistent	and non-persistent bases.  As for attributes,
       Perl's most typical representation for objects -	a hash - even allows
       two objects of the same class to	have a different set of	attributes.

       For more	information on creating	Schemas, see Tangram::Relational and

   Setting up a	database
       Now we create a database. The simplest way is to	create an empty
       database	and let	Tangram	initialize it:
	   use Tangram;

	   $dbh	= DBI->connect(
	       @cp );

	   Tangram::Relational->deploy($schema,	$dbh );


       Tangram::Relational is the vanilla object-relational backend. It
       assumes that the	database understands standard SQL, and that both the
       database	and the	related	DBI driver fully implements the	DBI

       Tangram also comes with vendor-specific backends	for Mysql and Sybase.
       When a vendor-specific backend exists, it should	be used	in place of
       the vanilla backend.

       For more	information, see Tangram::Relational, Tangram::Sybase and

   Connecting to a database
       We are now ready	to store objects. First	we connect to the database,
       using the class method Tangram::Relational::connect (or
       Tangram::mysql::connect for Mysql).

       The first argument of connect() the schema object; the others are
       passed directly to DBI::connect.	The method returns a Tangram::Storage
       object that will	be used	to communicate with the	database.

       For example:

	   $storage = Tangram::Relational->connect( $schema,
	       @cp );

       connects	to a database named Springfield	via the	vanilla	Relational
       backend,	using a	specific account and password.

       For more	information on connecting to databases,	see
       Tangram::Relational and Tangram::Storage.

   Inserting objects
       Now we can populate the database:

	  $storage->insert( NaturalPerson->new(
	     firstName => 'Montgomery',	name =>	'Burns'	) );

       This inserts a single NaturalPerson object into the database. We	can
       insert several objects in one call:

	     NaturalPerson->new( firstName => 'Patty', name => 'Bouvier' ),
	     NaturalPerson->new( firstName => 'Selma', name => 'Bouvier' ) );

       Sometimes Tangram saves objects implicitly:

	   @kids = (
	       NaturalPerson->new( firstName =>	'Bart',	name =>	'Simpson' ),
	       NaturalPerson->new( firstName =>	'Lisa',	name =>	'Simpson' ) );

	   $marge = NaturalPerson->new(
	       firstName => 'Marge', name => 'Simpson',
	       addresses => [
		       kind => 'residence', city => 'Springfield' ) ],
	       children	=> [ @kids ] );

	   $homer = NaturalPerson->new(	firstName => 'Homer', name => 'Simpson',
	       addresses => [
		       kind => 'residence', city => 'Springfield' ),
		       kind => 'work', city => 'Springfield' ) ],
	       children	=> [ @kids ] );

	   $homer->{partner} = $marge;
	   $marge->{partner} = $homer;

	   $homer_id = $storage->insert( $homer	);

       In the process of saving	Homer, Tangram detects that it contains
       references to objects that are not persistent yet (Marge, the addresses
       and the kids), and inserts them automatically. Note that	Tangram	can
       handle cycles: Homer and	Marge refer to each other.

       insert()	returns	an object id, or a list	of object ids, that uniquely
       identify	the object(s) that have	been inserted.

       For more	information on inserting objects, see Tangram::Storage.

   Updating objects
       Updating	works pretty much the same as inserting:

	   my $maggie =	NaturalPerson->new(
	     firstName => 'Maggie', name => 'Simpson' );

	   push	@{ $homer->{children} }, $maggie;
	   push	@{ $marge->{children} }, $maggie;

	   $storage->update( $homer, $marge );

       Here again Tangram detects that Maggie is not already persistent	in
       $storage	and automatically inserts it. Note that	we need	to update
       Marge explicitly	because	she was	already	persistent.

       For more	information on updating	objects, see Tangram::Storage.

   Memory management still up to you. Tangram won't break in-memory cycles, it's a
       persistence tool, not a memory management tool. Let's make sure we
       don't leak objects:

	  $homer->{partner} = undef; # do this before $homer goes out of scope

       Also, when we're	finished with a	storage, we can	explicitly disconnect


       Whether it's important or not to	disconnect the Storage depends on what
       version of Perl you use.	If it's	prior to 5.6, you must disconnect the
       storage explicitly (or at least call unload()) otherwise	the Storage
       will prevent the	objects	it controls from being reclaimed by Perl. For
       more information	see see	Tangram::Storage.

   Finding objects
       After reconnecting to Springfield, we now want to retrieve some
       objects.	 But how do we find them? Basically there are three options

       o   We know their IDs.

       o   We obtain them from another object.

       o   We use a query.

   Loading by ID
       When an object is inserted, Tangram assigns an identifier to it.	 IDs
       are numbers that	uniquely identify objects in the database.  "insert"
       returns the ID(s) of the	object(s) it was passed:

	   $storage = Tangram::Relational->connect( $schema,
	       @cp );

	   $ned_id = $storage->insert( NaturalPerson->new(
	       firstNname => 'Ned', name => 'Flanders' ) );

	   @sisters_id = $storage->insert(
	       NaturalPerson->new( firstName =>	'Patty', name => 'Bouvier' ),
	       NaturalPerson->new( firstName =>	'Selma', name => 'Bouvier' ) );

       This enables us to retrieve the objects:

	   $ned	= $storage->load( $ned_id );
	   @sisters = $storage->load( @sisters_id );

       For more	information on loading objects by id, see Tangram::Storage.

   Obtaining objects from other	objects
       Once Homer has been restored to his previous state, including his
       relations with his family. Thus we can say:

	   $storage = Tangram::Relational->connect( $schema,
	       @cp );

	   $homer = $storage->load( $homer_id ); # load	by id

	   $marge = $homer->{partner};
	   @kids = @{ $homer->{children} };

       Actually, when Tangram loads an object that contains references to
       other persistent	objects, it doesn't retrieve the referenced objects
       immediately. Marge is retrieved only when Homer's 'partner' field is
       accessed.  This mechanism is almost totally transparent,	we'd have to
       use "tied" to observe a non-present collection or reference.

       For more	information on relationships, see Tangram::Schema,
       Tangram::Type::Ref::FromMany, Tangram::Type::Array::FromMany,
       Tangram::Type::Array::FromOne, Tangram::Type::Set::FromMany and

       To retrieve all the objects of a	given class, we	use "select":

	   $storage = Tangram::Relational->connect( $schema,
	       @cp );

	   my @people =	$storage->select( 'NaturalPerson' );

       Tangram supports	polymorphic retrieval. Let's first insert a

	   $storage->insert( LegalPerson->new(
	       name => 'Springfield Nuclear Power Plant', manager => $burns ) );

       Now we can retrieve all the Persons - Natural or	Legal -	by making a
       single call to select(),	passing	it the base class name:

	   my @all = $storage->select( 'Person'	);

       For more	information on select(), see Tangram::Storage.

       Usually we won't	want to	load all the NaturalPersons, only those
       objects that satisfy some condition. Say, for example, that we want to
       load only the NaturalPersons whose name field is	'Simpson'. Here's how
       this can	be done:

	   my $person =	$storage->remote( 'NaturalPerson' );
	   my @simpsons	= $storage->select( $person, $person->{name} eq	'Simpson' );

       This will bring in memory only the Simpsons; Burns or the Bouvier
       sisters won't turn up.  The filtering happens on	the database server
       side, not in Perl space.	Internally, Tangram translates the
       "$person-"{name}	eq 'Simpson'> clause into a piece of SQL code that is
       passed down to the database.

       The above example only begins to	scratch	the surface of Tangram's
       filtering capabilities. The following examples are all legal and
       working code:

	   # find all the persons *not*	named Simpson

	   my $person =	$storage->remote( 'NaturalPerson' );
	   my @others =	$storage->select( $person, $person->{name} ne 'Simpson'	);

	   # same thing	in a different way

	   my $person =	$storage->remote( 'NaturalPerson' );
	   my @others =	$storage->select( $person, !($person->{name} eq	'Simpson') );

	   # find all the persons who are older	than me

	   my $person =	$storage->remote( 'NaturalPerson' );
	   my @elders =	$storage->select( $person, $person->{age} > 35 );

	   # find all the Simpsons older than me

	   my $person =	$storage->remote( 'NaturalPerson' );
	   my @simpsons	= $storage->select( $person,
	       $person->{name} eq 'Simpson' & $person->{age} > 35 );

	   # find Homer's wife - note that select *must* be called in list context

	   my ($person1, $person2) = $storage->remote(
	       qw( NaturalPerson NaturalPerson ));

	   my ($marge) = $storage->select( $person1,
	       $person1->{partner} == $person2
	       & $person2->{firstName} eq 'Homer' & $person2->{name} eq	'Simpson' );

	   # find Homer's wife - this time Homer is already in memory

	   my $homer = $storage->load( $homer_id );
	   my $person =	$storage->remote( 'NaturalPerson' );

	   my ($marge) = $storage->select( $person,
	       $person->{partner} == $homer );

	   # find everybody who	works in Springfield

	   my $address = $storage->remote( 'Address' );

	   my @population = $storage->select( $person,
	       $person->{addresses}->includes( $address	)
	       & $address->{kind} eq 'work'
	       & $address->{city} eq 'Springfield');

	   # find the parents of Bart Simpson

	   my ($person1, $person2) = $storage->remote(
	       qw( NaturalPerson NaturalPerson ));

	   my @parents = $storage->select( $person1,
	       $person1->{children}->includes( $person2	)
		  & $person2->{firstName} eq 'Bart'
		  & $person2->{name} eq	'Simpson' );

	   # load Bart
	   my ($bart) =	$storage->select( $person1, $person1->{firstName} eq 'Bart');

	   # find the parents of Bart, this time given an object already loaded
	   my $person =	$storage->remote( 'NaturalPerson' );

	   @parents = $storage->select(	$person,
	       $person->{children}->includes( $bart ) );

       Note that Tangram uses a	single ampersand (&) or	vertical bar (|) to
       represent logical conjunction or	disjunction, not the usual && or ||.
       This is due to a	limitation in Perl's operator overloading mechanism.
       Make sure you never forget this,	because, unfortunately,	using && or ||
       in place	of & or	| is not even a	syntax error :(

       Finally,	Tangram	make it	possible to retrieve tuples of related

	   my ($parent,	$child)	= $storage->remote('NaturalPerson', 'NaturalPerson');

	   @pairs = $storage->select( [	$parent, $child	],
	       $parent->{children}->includes($child) );

       @pairs contains a list of references to arrays of size two; each	array
       contains	a pair of parent and child.

       For more	information on filters,	see Tangram::Expr and Tangram::Remote.

       Cursors provide a way of	retrieving objects one at a time.  This	is
       important is the	result set is potentially large.  cursor() takes the
       same arguments as select() and returns a	Cursor objects that can	be
       used to iterate over the	result set via methods current() and next():

	   $storage = Tangram::Relational->connect( $schema,
	       @cp );

	   # iterate over all the NaturalPersons in storage

	   my $cursor =	$storage->cursor( 'NaturalPerson' );

	   while (my $person = $cursor->current())
	       # process $person


       The Cursor will be automatically	closed when $cursor is garbage-
       collected, but Perl doesn't define just when that may happen :( Thus
       it's a good idea	to explicitly close the	cursor.

       Each Cursor uses	a separate connection to the database. Consequently
       you can have several cursors open at the	same, all with pending
       results.	Of course, mixing reads	and writes to the same tables can
       result in deadlocks.

       For more	information on cursors,	see Tangram::Storage and

   Remote objects
       At this point, most people wonder what $person exactly is and how it
       all works.  This	section	attempts to give an idea of the	mechanisms
       that are	used.

       In Tangram terminology, $person a remote	object.	Its Perl class is
       Tangram::Remote,	but it's really	a placeholder for an object of class
       "NaturalPerson" in the database,	much like a table alias	in SQL-speak.

       When you	request	a remote object	of a given class, Tangram arranges
       that the	remote object looks like an object of the said class. It seems
       to have the same	fields as a regular object, but	don't be misled, it's
       not the real thing, it's	just a way of providing	a nice syntax.

       If you dig it, you'll find out that a Remote is just a hash of
       Tangram::Expr objects.  When you	say $homer->{name}, an Expr is
       returned, which,	most of	the time, can be used like any ordinary	Perl
       scalar. However,	an Expr	represents a value in the database, it's the
       equivalent of Remote, only for expressions, not for objects.

       Expr objects that represent scalar values (e.g. ints, floats, strings)
       can be compared between them, or	compared with straight Perl scalars.
       Reference-like Exprs can	be compared between themselves and with

       Expr objects that represent collections have an "include" methods that
       take a persistent object, a Remote object or an ID.

       The result of comparing Exprs (or calling "include") is a
       Tangram::Expr::Filter that will translate into part of the SQL where-
       clause that will	be passed to the RDBMS.

       For more	information on remote objects, see Tangram::Remote.

   Multiple loads
       What happens when we load the same object twice?	Consider:

	   my $person =	$storage->remote( 'NaturalPerson' );
	   my @simpsons	= $storage->select( $person, $person->{name} eq	'Simpson' );

	   my @people =	$storage->select( 'NaturalPerson' );

       Obviously Homer Simpson will be retrieved by both selects. Are there
       two Homers in memory now? Fortunately not. There	is only	one copy of
       Homer in	memory.	When Tangram load an object, it	checks whether an
       object with the same ID is alredy present. If yes, it keeps the old
       copy, which is desirable, since we may have changed it already.

       Incidentally, this explains why a Storage will hold objects in memory -
       until disconnected (again, this will change when	Perl supports weak

       Tangram wraps database transactions in a	object-oriented	interface:

	   $homer->{partner} = $marge;
	   $marge->{partner} = $homer;
	   $storage->update( $homer, $marge );

       Both Marge and Homer will be updated, or	none will. tx_rollback() drops
       the changes.

       Tangram does not	emulate	transactions for databases that	do not support
       them (like earlier versions of mySql).

       Unlike DBI, Tangram allows the nested transactions:


	       $patty->{partner} = $selma;
	       $selma->{partner} = $patty;

	   $homer->{partner} = $marge;
	   $marge->{partner} = $homer;
	   $storage->update( $homer, $marge );


       Tangram uses a single database transaction, but commits it only when
       the tx_commit()s	exactly	balance	the tx_start()s. Thanks	to this
       feature any piece of code can open all the transactions it needs	and
       still cooperate smoothly	with the rest of the application.  If a	DBI
       transaction is already active, it will be reused; otherwise a new one
       will be started.

       Tangram offer a more robust alternative to the start/commit code
       sandwich.  tx_do() calls	CODEREF	in a transaction. If the CODEREF dies,
       the transaction is rolled back; otherwise it's committed.  The first
       example can be rewritten:

	   $storage->tx_do( sub	{
	       $homer->{partner} = $marge;
	       $marge->{partner} = $homer;
	       $storage->update( $homer, $marge	};
	       } );

       For more	information on transactions, see Tangram::Storage.

perl v5.32.1			  2015-10-09		      Tangram::Tour(3)


Want to link to this manual page? Use this URL:

home | help