/ 
Gestinanna-POF-0.02
/ Gestinanna::POF::Base

NAME

Gestinanna::POF::Base - Base framework object

SYNOPSIS

package My::DataStore;

use base qw(Gestinanna::POF::Base);

use fields qw(attribute list);

__PACKAGE__->valid_params (
   parameter list
);

sub load { }

sub save { }

sub delete { }

sub find { }



package My::DataObject::Base;

use base qw(My::DataStore);



package My::DataObject;

use base qw(My::DataObject::Base);

# any attribute access method overrides here
sub attribute {
    my $self = shift;

    if( @_ ) { # setting
        # do checks here, returning or throwing an exception if 
        # there is a problem
    }

    $self -> SUPER::attribute(@_);
}

DESCRIPTION

This module provides the base for the data store classes. Data store classes should never be used directly to create objects or access data. Instead, object classes should be derived from the data store classes.

METHODS

The following methods need to be implemented in any data store class.

load

This method is used by the factory to load data when creating a new object.

save

This method is called when the object needs to save its data to the data store. This method may assume that any required locking has taken place if locking is being used.

delete

This method is called when the object's data is to be deleted from the data store.

find

$factory -> find($type => ( 
    where => [ ... ],
    limit => [ ... ],
));
limit

The limit may be either a scalar value, in which case no more than that number of objects or object identifiers will be returned, or an array reference. The array reference should point to an array with two elements. The first element indicates the maximum number of objects or object identifiers to return. The second element indicates at which position to begin.

where

An example may be the quickest way to illustrate how the search criteria work:

[ AND => (
    [ 'name', '=', 'some name' ],
    [ OR => (
         [ 'age',  '<', '40' ],
         [ 'postalcode', '=', '12345' ]
      )
    ]
  )
]

Three words are reserved in the initial position of an array reference: AND, OR, and NOT.

This would be comparable to the following SQL SELECT statement:

select * from Table 
    where name = 'some name' 
      AND ( age < 40 
         OR postalcode = 12345 
      );

This would also be comparable to the following LDAP search string:

(&(name=some name)
  (|(!(age>=40))
    (postalcode=12345)
  )
)

Data stores are expected to support AND, OR, and negation of statements via NOT as well as the =, !=, <, >, <=, and >= comparisons. More may be added later (such as IN or BETWEEN from SQL and an existance operation similar to LDAP's =* comparison or SQL's IS NULL).

This method should return a list of objects which satisfy the search criteria. If no objects match, an empty list should be returned. If there is an error, then either an exception should be thrown or undef returned.

See Gestinanna::POF::Iterator for more information.

TRANSACTIONS

The save and delete methods should call the log_transaction_rollback with one or more CODE references that can be called to rollback the save or delete operation.

sub save {
    my $self = shift;
    
    $self -> log_transaction_rollback( sub {
        # do something to un-save
    } );
    
    # do the save
}

This is needed if the data store class is to support transactions (especially if the data store itself does not have transaction support). Note that transaction support relies on the program having full control and realizing when transactions need to be rolled back. It does not guard against abnormal program termination. Support in the data store itself is required to protect data integrity in case the program does terminate abnormally. The transaction support here is meant for those times when a sequence of actions must be taken across several different data stores and the program needs a way to undo what it did when it detects a problem part way through the sequence of data changes.

Transaction support is not fully implemented yet.

SEE ALSO

Gestinanna::POF::Alzabo, Gestinanna::POF::Container, Gestinanna::POF::LDAP, Gestinanna::POF::MLDBM.

AUTHOR

James 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.