NAME

Trinket::Directory - Persistent object management and lookup

SYNOPSYS

my $dir = new Trinket::Directory();
$dir->create('RAM:test') || die("Creation failed");

$dir = new Trinket::Directory();
$dir->open('RAM:test') || die("Open failed");

$dir = new Trinket::Directory('RAM:test') || die("Open failed.");

my $obj = new MyTrinketObjectSubclass({ foo => 'foo_value' });

my $obj_id = $dir->store($obj) || die "Storage failed";

$obj = $dir->retrieve($obj_id) || die "Retrieval failed.";

my @objs = $dir->search('foo=foo_value');

my @objs = $dir->search('LDAP', 'foo=foo_value');

$dir->delete($obj);

$dir->delete($obj_id);

$dir->close();

DESCRIPTION

Trinket::Directory offers methods for the management and lookup of persistent Perl objects subclassed from Trinket::Object.

It provides an interface for object storage, retrieval, deletion, and searching via a set of selectable data access backend modules and search filter parsing modules.

Data access modules each encapulate the specifics of data management in a particular medium while Trinket::Directory offers a common interface for object persistent management. This relationship is modeled after the DBI and DBD Perl modules, as in this diagram:

Architecture of an Trinket::Directory Application

                      Trinket::Directory::DataAccess::*
                            |   .----------.  |
.------.                      .-|   RAM    |
|      |                      | `----------'
|      | .------------------. | .----------.
|Perl  |-|Trinket::Directory|-+-|BerkeleyDB|
|script| `------------------' | `----------'
|      |                      | .----------.
|      |                      `-|   DBI    |
`------'                        `----------'

A Perl script creates an instance of Trinket::Directory using a directory descriptor, which includes information on which DataAccess module to use, and options to the selected DataAccess module such as identity of the data source, authentication information, and storage options.

As long as the DataAccess module is implemented correctly, the selection of DataAccess is transparent to the Perl script, which makes calls to the methods of Trinket::Directory. Trinket::Directory, in turn, calls upon the selected DataAccess backend to perform the actions specific to a data source to manage object data and lookup.

Search filter parser modules handle various formats of object search queries, such as LDAP-style (RFC1960) filters and SQL-like queries. A particular parser may be specified when searching for objects. Some filter parsers may support query formats which more fully exploit the features of a given data access backend. All filter parsers offer a common lowest denominator of features.

METHODS

$dir = new Trinket::Directory();

$dir = new Trinket::Directory($dir_desc,$options);

Create a Directory instance. The description of a directory and a reference to a hash of additional options may be given to open a data source immediately.

Directory descriptions are colon-separated strings listing the DataAccess module, the name of the directory to use, and a list of semi-colon separated option name/value pairs. For example:

RAM:test
RAM:save_me:file=save_file;cache_objects=0
BerkeleyDB:test2:db_home=dbdir
DBI:test_objs:user=someone;pass=foo;host=localhost

For options available in a DataAccess module which cannot be specified in a string, such as more complex data structures and object references, a hash containing named resources can be supplied as an optional parameter.

See the documentation on Trinket::Directory::DataAccess modules for further details.

$dir->create($dir_desc,$options);

Prepare the data resources for a new directory. This method must be passed a directory description as described in new(), with an optional reference to a hash of additional resources.

This method will return 1 if successful, and will destroy any directory previously identified by the given options. An undef value will be returned on failure.

$dir->open($dir_desc,$options);

Acquire the data resources for an existing directory. This method must be passed a directory description as described in new(), with an optional reference to a hash of additional resources.

This method will return 1 if successful, and an undef value will be returned on failure (such as if the directory does not yet exist).

$dir->close()

Release the data resources for the current opened directory. After this method is called, another directory can be opened, but no further directory operations can made until then.

This method returns 1 on success, and undef on any failures.

$dir->serialize()

If appropriate, return the current opened directory as a serialized binary stream.

This method returns data on success, and undef on any failures.

$dir->deserialize()

If appropriate, populate the current opened directory with data from a serialized binary stream.

This method returns 1 on success, and undef on any failures.

$id = $dir->store($obj);

Store a given object into the directory.

If the object either has no valid id or has not been stored by this directory before, it will be given a new id and its directory property will be set with a reference to this directory.

This method will return the object's method, or undef on failure. '

$obj = $dir->retrieve($id);

Retrieve an object by object id.

A reference to the object will be returned, or undef on failure.

$dir->delete($obj);

$dir->delete($obj_id);

Delete a given object or object by id.

Note that deleting by id is no more efficient than deleting by object reference, as most data access backends need to retrieve the object anyway in order to complete deletion. Deletion by id is just meant as a shortcut.

This method returns 1 on success, and undef on failure.

$objs = $dir->search($parser_name,$filter);

$objs = $dir->search($filter);

Search for objects using a given search filter, optionally using a named search filter parser module. By default, the LDAP search filter parser is used.

This method returns a list of object references found.

AUTHOR

Maintained by Leslie Michael Orchard <deus_x@pobox.com>

COPYRIGHT

Copyright (c) 2000, Leslie Michael Orchard. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.