/ 
Gestinanna-POF-Repository-0.03
/ Gestinanna::POF::Repository::Object

NAME

Gestinanna::POF::Repository::Object - objects within the repository

SYNOPSIS

$object = $factory => new(foo => (object_id => '/name') );

$data = $object -> data();
$object->data($new_data);

$object -> log($log_message);

$object -> save()

DESCRIPTION

The object_id is the name of the object (object_id is an alias for name in the constructor). If revision is given, then that revision is loaded. If no revision is given but a tag_path is supplied, then the tags are searched until one is found pointing to a revision of the named object.

Saving an object will not modify any existing row in the RDBMS but will create a new row storing the differences between that version of the object and the previous version. If a more recent version of the object exists in the branch, then a new branch is created. Otherwise, a new revision is created in the same branch. A new branch may be forced at the next save by calling the branch method.

Revision numbers are Perl ordinal strings. For example, v1.1 is the first revision of the first branch. v1.1.1.1 is the first revision of the first branch of the first revision of the first branch. Etc. This is an added feature in Perl 5.6.0.

METHODS

In addition to the usual Gestinanna::POF::Alzabo methods, the following support this class's role in the repository.

branch

$object -> branch

Force a branch at the next save(). Multiple calls do not create multiple branches without intervening saves.

data_columns

@columns = $object -> data_columns

This returns an array of column names that should be treated as under revision control. Override this method if you do not want the default columns (data, and any column name beginning with data_).

revisions

@revisions = $object -> revisions()
@revisions = $object -> revisions($branch)
@revisions = $object -> revisions($min, $max)

This method is fairly DWIMy.

Given zero or one arguments, this will return similar results as revisions_hash except it will not try to load each object.

If both $min and $max are given, then the branch is taken to be the branch indicated by $max. If $min is undefined, then it is assumed to be the first revision in the branch, with the last revision being the revision indicated by $max.

N.B.: This method does not return the actual objects, but a list of revision ordinals. To retrieve an object, use the following code:

$object = $factory -> new(foo => (
     object_id => '/name-of-object',
     revision => $revision
) );

Where $revision is one of the revision ordinal strings returned by the revisions() and /name-of-object is the name of the object.

revisions_hash

%revisions = $object -> revisions();
%revisions = $object -> revisions($branch);

This will return a hash mapping the revision ordinal strings to objects for a particular branch. If no branch is given, then this will assume all branches. Be careful. If there are a lot of revisions, this can consume a fair amount of memory.

unbranch

$object -> unbranch

Forget the forced branching at the next save. This undoes what branch() does. This will not prevent a branching if the there is a newer revision than the object's revision (e.g., if the object is revision 1.2 and there is already a 1.3, then nothing will prevent the creation of 1.2.x.x on the next save--1.2 won't leap frog 1.3 to create 1.4).

BUGS

Iterators for revision lists

It would be nice to return an iterator instead of an entire list of revisions. This code was developed before Gestinanna::POF::Iterator came into existance. This may happen in the near future, in which case the behavior of the revisions and revisions_hash methods will either change completely or depend on the calling context (scalar returns iterator).

AUTHOR

James G. Smith, <jsmith@cpan.org>

COPYRIGHT

Copyright (C) 2002-2003 Texas A&M University. All Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.