NAME

SPOPS::GDBM - Store SPOPS objects in a GDBM database

SYNOPSIS

 my $obj = Object::Class->new;
 $obj->{parameter1} = 'this';
 $obj->{parameter2} = 'that';
 my $id = $obj->save;

DESCRIPTION

Implements SPOPS persistence in a GDBM database. Currently the interface is not as robust or powerful as the SPOPS::DBI implementation, but if you want more robust data storage, retrieval and searching needs you should probably be using a SQL database anyway.

This is also a little different than the SPOPS::DBI module in that you have a little more flexibility as to how you refer to the actual GDBM file required. Instead of defining one database throughout the operation, you can change in midstream. (To be fair, you can also do this with the SPOPS::DBI module, it is just a little more difficult.) For example:

 # Read objects from one database, save to another
 my @objects = Object::Class->fetch_group({ filename => '/tmp/object_old.gdbm' });
 foreach my $obj ( @objects ) {
     $obj->save({ is_add => 1, gdbm_filename => '/tmp/object_new.gdbm' });
 }

METHODS

id_field

If you want to define an ID field for your class, override this. Can be a class or object method.

class_initialize

Much the same as in DBI. (Nothing interesting.)

initialize( \%params )

Much the same as in DBI, although you are able to initialize an object to use a particular filename by passing a value for the 'GDBM_FILENAME' key in the hashref for parameters when you create a new object:

 my $obj = Object::Class->new( { GDBM_FILENAME = '/tmp/mydata.gdbm' } );

global_datasource_handle( \%params )

Returns a tied hashref if successful.

Note: This is renamed from global_gdbm_tie(). The old method will still work for a while.

There are many different ways of creating a filename used for GDBM. You can define a default filename in your package configuration; you can pass it in with every request (using the parameter 'filename'); you can define a file fragment (non-specific directory name plus a filename, like 'conf/package.gdbm') and then pass a directory to anchor the filename with every request.

Parameters:

perm ($) (default 'read')

Defines the permissions to open the GDBM file. GDBM recognizes three permissions: 'GDBM_READER', 'GDBM_WRITER', 'GDBM_WRCREAT' (for creating and having write access to the file). You only need to pass 'read', 'write', or 'create' instead of these constants.

If you pass nothing, SPOPS::GDBM will assume 'read'. Also note that on some GDBM implementations, specifying 'write' permission to a file that has not yet been created still creates it, so 'create' might be redundant on your system.

filename ($) (optional)

Filename to use. If it is not passed, we look into the 'tmp_gdbm_filename' field of the object, and then the 'filename' key of the 'gdbm_info' key of the class config, and then the 'filename' key of the 'gdbm_info' key of the global configuration.

directory ($) (optional)

Used if you have defined 'file_fragment' within your package configuration; we join the directory and filename with a '/' to create the gdbm filename.

id()

If you have defined a routine that returns the 'id_field' of an object, it returns the value of that for a particular object. Otherwise it executes the coderef found in the 'create_id' key of the class configuration for the object. Usually this is something quite simple:

 ...
 'create_id' => sub { return join( '--', $_[0]->{name}, $_[0]->{version} ) }
 ...

In the config file just joins the 'name' and 'version' parameters of an object and returns the result.

object_key

Creates a key to store the object in GDBM. The default is to prepend the class to the value returned by id() to prevent ID collisions between objects in different classes. But you can make it anything you want.

fetch( $id, \%params

Retrieve a object from a GDBM database. Note that $id corresponds not to the object key, or the value used to store the data. Instead it is a unique identifier for objects within this class.