NAME

MyDB - provide database independent interface for CIToolkit ``persistant object store''


MODULE

base


SYNOPSIS

  use MyDB;
  $db = MyDB->new($datasource, "$rwc_access_mode", %args);
  @things = $db->list_keys();
  $item = $db->fetch_flat($named_thing);
  $obj = $db->fetch($named_thing);
  $name = $db->delete($named_thing);
  $db->store($obj->name, $obj);
  $db->close();

This synopsis only lists the major methods, see METHODS section below for more details.


DESCRIPTION

This package provides for inheritance of basic database routines and for ``redirection'' of connect requests to the appropriate database interface module, based on the connect string. The goal is to provide a set of methods to provide a consistent interface to the CIToolkit object store, regardless of the underlying database being used.

The actual interface methods are implemented in other modules, such as MyDB::GDBM and MyDB::LDAP. MyDB simply provides an intelligent connection method, common supporting routines, and a template for data access and manipulation methods.


METHODS

The following methods should be supported by all MyDB:: modules.

new - connect to the database
  $db = MyDB->new($datasource, "$rwc_access_mode");
  $db = MyDB->new($datasource, "$rwc_access_mode", %args) or die;

This method establishes a connection to the requested data source, returning a database object.

The $datasource connect string has the form:
DBTYPE:connect_options:more_connect_info

Only the first ``:'' delimited field is required by MyDB. Other fields provide information to the underyling modules as to where and how to connect to the database. For example, the $datasource connect string should look similar to the following: GDBM:/cluster/config/cluster LDAP:localhost:389:cluster LDAP:::cluster LDAP:::test-db LDAP:BOOTHOST::cluster

The $rwc_access_mode determines whether the database is opened for read or write access, or if a new object store should be created (or initialized, depending on the underlying db.) ``r'' should be used for read access, ``w'' for write access, and ``c'' for create. Write access implies read access, and creating the database implies both read and write.

An additional $rwc_access_mode, ``l'', is available if you wish to create a (read only) local copy of the database. This can be useful for long-running commands, to keep them from locking the database for too long.

In the case that new tries to create a database that already exists, it will die with a message reminding the user to remove it first. This can be done with the remove_db command.

Additional arguments can be passed through the %args hash, such as {username=>``foo'',password=>``bar''}, although it is up to the low-level database modules to decide what to do with them.

store - store an object in the database
  $db->store($obj->name, $obj);

This method takes an object name and an object instance and stores it in the persistant object store for later retrieval. In most cases, the object will be flattened and stored as a string. store returns the flattend string on success, undef on failure.

delete - remove an object in the database
  $name = $db->delete($named_thing);

This method completely removes an object from the db. No checking is done to see if it is a collection that might be providing ``the only path to another object''. The only argument is the name of the object (device or collection) to delete. delete returns the name of the object deleted on success, undef on failure.

fetch_flat - retrieve an object in flattened string form
  $item = $db->fetch_flat($named_thing);

This method retrieves an object from the database by name and returns it in a flattened string form, such as can be easily printed or eval'ed into object form. On failure, undef is returned.

fetch - retrieve an object
  $obj = $db->fetch($named_thing);

This is the basic method for retrieving an object from the database. fetch retrieves an object by name and returns the object, ready to use. On failure, undef is returned.

explode - convert from flattened string to object
  $obj = $db->explode($item);

Takes a flattened string of the form returned by fetch_flat and converts it into a perl object, as returned by fetch. On failure, undef is returned.

fetch_attr - get the value of a specific attribute for an object
  $val = $db->fetch_attr($named_thing,$attrib_name);

Gets the value of the attribute of the database entry if possible. Otherwise, fetch_attr returns undef. This method should only be used if you are only interested in one attribute for an object, as it is much more efficient to fetch the object first if you will be accessing many of it's attributes.

fetch_by_value - find all objects that have a specified attribute, value pair.
  @objs = $db->fetch_by_value($value,$attrib_name);

This method searches through all objects in the database for those that have the specified attribute set to the specified value. The result of the search is returned as a list of objects. If no matches are found, an empty list is returned (not undef.) Fetching by value can be very powerful, but can also be VERY slow on large databases, so don't use it unless you have to.

list_keys - find the names of all objects in the database
  @names = $db->list_keys();

This method returns a list of names of all objects in the database. This includes devices and collections.

close - disconnect from the database
  $db->close();

This method performs any necessary cleanup and disconnects from the database.

remove_db - completely remove a persistant object store
  MyDB->remove_db($datasource);

This method wipes out the specified database. The datasource parameter is specified in the same way as for new. All data will be lost, so use with caution!!!


SEE ALSO

MyDB::GDBM

MyDB::LDAP