/ 
Gestinanna-POF-0.02
/ Gestinanna::POF

NAME

Gestinanna::POF - Gestinanna Persistant Object Framework

SYNOPSIS

package My::POF::Factory;

use base q(Gestinanna::POF);

package main;

My::POF::Factory -> register_factory_type( $type => $class );
My::POF::Factory -> add_factory_type( $type => $class);

My::POF::Factory -> new( $type, @params );

$factory = My::POF::Factory -> ( _factory => ( %presets ) );
$object = $factory -> new( $type => ( object_id => $id ) );

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

while($id = $cursor -> next_id) { }
while($ob = $cursor -> next) { }

DESCRIPTION

The Gestinanna Persistant Object Framework is designed to work with the Gestinanna application framework currently under development. This framework consists of two major parts: the object factory and the object classes.

The object factory is based on this module, Gestinanna::POF. A particular factory is an instance of a custom class that inherits from Gestinanna::POF so that object type to Perl class mappings can be kept segregated. The factory instance can also track some of the attributes that might be needed to create objects. This allows such things as data sources to be configured in the factory. The code that needs a particular object doesn't need to know where the data for that object comes from or even which Perl class is used to construct the object.

Object factories keep track of which class to use for constructing a particular object. These mappings are created by calling the register_factory_type or add_factory_type static methods. See Class::Factory for more information on these methods.

See the various object base classes for more information on how to use them. The base classes included with Gestinanna::POF are

Gestinanna::POF::Base

The base class used to define the various data store classes. Don't use this except when defining a class for a new, previously unsupported, data store.

Gestinanna::POF::Alzabo

This class allows objects to be created from rows in an RDBMS (SQL) table using the Alzabo schema management system.

Gestinanna::POF::Container

This class allows objects to be defined as aglomerations of other data classes and object types.

Gestinanna::POF::LDAP

This class allows objects to be defined using entries from an LDAP directory. This class is still alpha code at best.

Gestinanna::POF::MLDBM

This class allows objects to be entries in an MLDBM file.

In addition to simple data access, support is provided for attribute-level security. See Gestinanna::POF::Secure for more information.

NAMESPACES

The tertiary Gestinanna::POF::* namespace should be used for general data store modules (e.g., Gestinanna::POF::Alzabo). This namespace should not be used for modules directly instantiated by the factory (e.g., a table-specific sub-class of Gestinanna::POF::Alzabo).

General security policy implementations may reside in Gestinanna::POF::Secure::*.

Lock implementations may reside in Gestinanna::POF::Lock::*.

METHODS

The following methods are defined in addition to the methods inherited from Class::Factory.

get_object_type
$type = Gestinanna::POF -> get_object_type($object_class |  $object)

Given either an object or its class, this will return the object type the class is associated with. If the class is associated with more than one object type, the return value is undefined (the first match is returned).

The object type may be used to create a new object of this type:

Gestinanna::POF -> new($type => %params);

If the object class is not known to Gestinanna::POF then undef is returned.

Gestinanna::POF -> new(_factory => %params)

This will return a Gestinanna::POF object with %params as default parameters for further object creation. This is useful for specifying default Alzabo schemas or actors for secured object types. Default parameters that are not appropriate for the requested object type are not passed to the object during creation.

$factory -> find($type => %params);

*** This is still in development ***

Given a factory object, this will return an iterator which will iterate over all the objects of type $type that match the where parameter. Other parameters may be passed to override specific parameters that are stored in the factory object.

For example:

$cursor = $factory -> find(user => (
   where => [ 'age', '>', '18' ],
   limit => 5,
));

while($object = $cursor -> next) {
    ...
}

while($id = $cursor -> next_id) {
    ...
}

This will iterate through all the users with an age of more than 18 (or five, whichever is less). The limit is optional.

Since the criteria are parsed in the basic data store objects, see Gestinanna::POF::Base for a more detailed explanation of the criteria syntax.

N.B.: This is not the most efficient way to find objects. It is currently the only way within this framework to do a search that is independent of the underlying data store, though. Due to requirements for consolidating lazy iterators in Gestinanna::POF::Container, some iterators are not as efficient as they could be (e.g., the MLDBM iterator must create a list of all the keys and then sort them, though finding the next valid object identifier is done lazily).

SEE ALSO

Class::Factory, Gestinanna::POF::Base, Gestinanna::POF::Container, Gestinanna::POF::Iterator, Gestinanna::POF::Lock, Gestinanna::POF::Secure.

BUGS

Please report bugs to either the request tracker for CPAN (http://rt.cpan.org/) or at the SourceForge project (http://sourceforge.net/projects/gestinanna/).

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.