view release on metacpan or  search on metacpan

Transaction.pod  view on Meta::CPAN

	$obj->commit();
	$obj->uncache();
	$obj->abandon();
	$oldobj = $obj->old();

	$reference = $obj->objectref();
	$obj = $reference->loadref();

	$id = sub id { ... }
	$restart_commit = sub precommit() { }
	@passby = sub presave($old) { ... }
	sub postsave($old,@passby) { ... }
	$newid = sub preload($id) { .... }
	sub postload() { ... }
	sub preremove() { ... }
	sub postremove() { ... }

=head1 DESCRIPTION

B<Object::Transaction> provides transaction support for hash-based objects that 
are stored one-per-file using Storable.  Multiuser access is supported.
In the future, serializing methods other than Storable will be supported.

B<Object::Transaction> is a virtual base class.  In order to use it, you must
inherit from it and override the C<new> method and the C<file>
method.

Optomistic locking is used: it is possible that a transaction will fail
because the data that is is based upon has changed out from under it.

=head1 EXAMPLE

	package User;

	@ISA = qw(Object::Transaction);

	use Object::Transaction;

	my $top = "/some/path";

	sub new { 
		my ($package, $login) = @_;
		die unless getpwnam($login);
		return bless { UID => getpwnam($login) };
	}

	sub file { 
		my ($ref, $id) = @_;
		$id = $ref->id() unless $id;
		return "$top/users/$id/data.storable";
	}

	sub id {
		my ($this) = @_;
		return $this->{UID};
	}

	sub preload
	{
		my ($id) = @_;
		return if getpwuid($id);
		return getpwnam($id) if getpwnam($id);
		die;
	}

	sub postload
	{
		my ($this) = @_;
		my ($name,$passwd,$uid,$gid,$quota,$comment,$gcos,$dir,
			$shell,$expire) = getpwuid($this->{UID});
		$this->{SHELL} = $shell;
	}

	sub presave
	{
		my ($this, $old) = @_;
		my $id = $this->{UID};
		mkdir("$top/users/$id", 0700);
		delete $this->{SHELL};
	}

	sub postsave
	{
		goto &postload;
	}

	sub postremove
	{
		delete from pw file...
	}

	my $joe = new User "joe";
	$joe->savelater();

	my $fred = new User "fred";
	$fred->savelater();

	$joe->commit();

=head1 METHODS PROVIDED

B<Object::Transaction> provides the following methods.

=over 15

=item C<load($id)>

C<load> is the way to bring an object into memory.   It is usually
invoked as C<my $obj = load MyObject $id>.   

There are two opportunities to customize the behavior of C<load>:
C<preload> for things that should happen before loading and
C<postload> for things that should happen after loading.

B<Object::Transaction> caches objects that are loaded.  This is
done both for performance reasons and to make sure that only one
copy of an object is in memory at a time.  If caching is not desired,
the C<uncache> method must be invoked after loading.

X<savelater>

=item C<savelater()>

C<savelater> is the usual method of saving an object.  The object
is not saved at the time that C<savelater> is invoked.  It is actually
saved when C<commit> is invoked.  

There are two opportunities to customize the behavior of C<savelater>:
C<presave> for things that should happen before saving and
C<postsave> for things that should happen after saving.  These