Bric::Util::Coll(3)

NAME
Bric::Util::Coll - Interface for managing collections of objects.

VERSION
$LastChangedRevision$

DATE
$LastChangedDate: 2006-03-18 01:26:34 +0100 (Sat, 18 Mar 2006) $

SYNOPSIS
  use Bric::Util::Coll::Foo;
  my $foo_coll = Bric::Util::Coll::Foo->new($params);

  # Get all the objects in the collection.
  foreach my $foo ($foo_coll->get_objs) {
      # Do stuff with Foo objects.
  }

  # Create a new object in the collection.
  my Foo $foo = $foo_coll->new_obj($init);

  # Add existing objects to the collection.
  $foo_coll->add_objs(@objs);

  # Delete an object from the collection by reference to its ID.
  $foo_coll->del_objs($foo->get_id);

  # See if existing members of the collection have been looked up in the
  # database.
  my $bool = $foo_coll->is_populated;

  # Save all the changes. None will have propagated to the database until save()
  # is called.
  $foo_coll->save;

DESCRIPTION
This subclassable class assists in the management of collections of objects. It provides a simple interface that's useful for composition, where there's a need to store a collection of objects and do things to them, e.g., create new ones, fetch them, and delete them.

The subclasses of Bric::Util::Coll just have to implement two methods: class_name(), a class method that returns the name of the class of objects that make up the collection; and save(), an instance method that takes all the objects in the collection and saves their changes. The only other requirement for using this class is the addition of the class method href() to the class whose objects make up the collection. The href() method functions exactly as does list(), except that it returns an anonymous hash of objects instead of a list. The hash keys are the object IDs and the values are the objects themselves.

You must implement a subclass of Bric::Util::Coll to use it; it cannot be used on its own.

INTERFACE

  Constructors

my $coll = Bric::Util::Coll->new($params)
    Instanticates a new collection. When data is required from the database, the collection object will call the href() method of the class managed by the collection (as defined by the class_name() method of the Bric::Util::Coll subclasses), passing in the $params hash reference as an argument. If $params is not defined, no data will be retreived from the database.

    The class name identified by the class_name() method of Bric::Util::Coll subclasses must must have an href() class method that works like the list() method, but returns an anonymous hash instead of a list, where the hash keys uniquely identify the objects returned (usually IDs).

    Throws:

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    Side Effects: NONE.

    Notes: NONE.

my $org = Bric::Util::Coll->lookup()
    Not implemented - not needed.

    Throws:

    *   Bric::Util::Coll::lookup() method not implemented.

    Side Effects: NONE.

    Notes: NONE.

Bric::Util::Coll->list()
    Not implemented - not needed.

    Throws:

    *   Bric::Util::Coll::list() method not implemented.

    Side Effects: NONE.

    Notes: NONE.

  Destructors

$org->DESTROY
    Dummy method to prevent wasting time trying to AUTOLOAD DESTROY.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

  Public Class Methods

Bric::Util::Coll->list_ids()
    Not implemented - not needed.

    Throws:

    *   Bric::Util::Coll::list_ids() method not implemented.

    Side Effects: NONE.

    Notes: NONE.

Bric::Util::Coll->class_name()
    Returns the name of the class of objects this collection manages. Must be overridden in subclasses.

    Throws:

    *   Bric::Util::Coll::class_name() method not implemented.

    Side Effects: NONE.

    Notes: Method must be overridden by subclasses.

  Public Instance Methods

my (@objs || $objs_aref) = $coll->get_objs
my (@objs || $objs_aref) = $coll->get_objs(@obj_ids)
    Returns a list or anonymous array of the objects stored in the collection.

    Throws:

    *   Bric::_get() - Problems retrieving fields.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    Side Effects: NONE.

    Notes: NONE.

my (@objs || $objs_aref) = $coll->get_new_objs
    Returns a list or array reference of all of the objects that have been added to the collection via "new_objs()". Note that, once "save()" has been called, the new objects are themselves saved, and are no longer considered new objects. If there are no new objects, "get_new_objs()" will return an empty list in an array context, and undef in a scalar context.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

my $obj = $coll->new_obj($init_href)
    Returns a new object that has been added to the collection.

    Throws:

    *   Bric::_get() - Problems retrieving fields.

    Side Effects: NONE.

    Notes: NONE.

$self = $coll->add_objs(@objs)
    Adds existing objects to the collection.

    Throws:

    *   Bric::_get() - Problems retrieving fields.

    Side Effects: NONE.

    Notes: NONE.

$self = $coll->add_new_objs(@objs)
    Adds existing objects to the collection as new objects.

    Throws:

    *   Bric::_get() - Problems retrieving fields.

    Side Effects: NONE.

    Notes: NONE.

$self = $coll->del_objs(@objs)
$self = $coll->del_objs(@obj_ids)
    Deletes the objects in @objs or identified by the IDs in @obj_ids from the collection, if they're a part of the collection, even if they've been added by "add_new_objs()" and the collection has not yet been "save()"d. All arguments can be either objects or object IDs; however, if you've constructed an object already, pass it in rather than the ID, as "del_objs()" likely will have to construct the object from the ID, anyway.

    Throws:

    *   Bric::_get() - Problems retrieving fields.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    Side Effects: NONE.

    Notes: NONE.

$coll = $coll->is_populated
    Returns true if the collection has been populated with existing objects from the database, and false if it has not.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

$self = $coll->save
    Saves the changes made to all the objects in the collection. Must be overridden.

    Throws:

    *   Bric::Util::Coll::save() method not implemented.

    Side Effects: NONE.

    Notes: Method must be overridden by subclasses.

PRIVATE

  Private Class Methods

Bric::Util::Coll->_sort_objs($objs_href)
    Sorts a list of objects into an internally-specified order. The default is to sort them by IDs (which are the hash keys in $objs_href), but this method may be overridden in subclasses to profile different sorting algorithms.

    Throws: NONE.

    Side Effects: NONE.

    Notes: NONE.

  Private Instance Methods

$self = $self->_populate
    Populates the collection if it has not yet been populated.

    Throws:

    *   Bric::_get() - Problems retrieving fields.

    *   Incorrect number of args to Bric::_set().

    *   Bric::set() - Problems setting fields.

    *   Unable to connect to database.

    *   Unable to prepare SQL statement.

    *   Unable to select column into arrayref.

    *   Unable to execute SQL statement.

    *   Unable to bind to columns to statement handle.

    *   Unable to fetch row from statement handle.

    Side Effects: NONE.

    Notes: NONE.

  Private Functions
NONE.

NOTES
NONE.

AUTHOR
David Wheeler <david@justatheory.com>

SEE ALSO
Bric