/ 
Gestinanna-POF-0.07
/ 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.

CREATING/LOADING OBJECTS

Objects should be created or loaded through the factory object.

$object = $factory -> new(object_type => object_id => $id);

This is the minimum that should be used. The first parameter is the object type that is registered with the factory. The remaining parameters are used to find the object in the data store or to create the object.

The object id ($id in the above example) may be either a single string or an LDAP-like rdn.

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

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.

SEARCH OPERATIONS

Data stores are expected to support AND, OR, and negation of statements via NOT as well as the following operators. More may be added later (such as IN or BETWEEN from SQL).

Binary Operations

=

Equality. This may be string or numeric equality. Most databases do not distinguish between the two in their syntax, basing it on the data type of the attribute being tested.

!=

This should be the opposite truth of =.

<

Preceeds. This should be true if the left value would sort earlier than the right value in ascending order.

>

Succeeds. This should be true if the left value would sort later than the right value in ascending order.

<=

This should be the opposite truth of >.

>=

This should be the opposite truth of <.

Unary Operations

EXISTS

This should be true if the attribute exists and is set to a defined value.

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.