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

$LastChangedRevision$

$LastChangedDate: 2004-10-19 06:06:35 -0700 (Tue, 19 Oct 2004) $

  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;

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.

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 CW$params hash reference as an argument. If CW$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. 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.

$org->DESTROY

Dummy method to prevent wasting time trying to AUTOLOAD DESTROY. Throws: NONE. Side Effects: NONE. Notes: NONE.

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.

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. Returns a list or array reference of all of the objects that have been added to the collection via CWnew_objs(). Note that, once CWsave() has been called, the new objects are themselves saved, and are no longer considered new objects. If there are no new objects, CWget_new_objs() will return an empty list in an array context, and undef in a scalar context. Throws: NONE. Side Effects: NONE. Notes: NONE. Returns a new object that has been added to the collection. Throws:

*

Bric::_get() - Problems retrieving fields. Side Effects: NONE. Notes: NONE. Adds existing objects to the collection. Throws:

*

Bric::_get() - Problems retrieving fields. Side Effects: NONE. Notes: NONE. Adds existing objects to the collection as new objects. Throws:

*

Bric::_get() - Problems retrieving fields. Side Effects: NONE. Notes: NONE. Deletes the objects in CW@objs or identified by the IDs in CW@obj_ids from the collection, if they're a part of the collection, even if they've been added by CWadd_new_objs() and the collection has not yet been CWsave()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 CWdel_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. 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. 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.

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 CW$objs_href), but this method may be overridden in subclasses to profile different sorting algorithms. Throws: NONE. Side Effects: NONE. Notes: NONE.

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.

NONE.

NONE.

David Wheeler <david@wheeler.net>

Bric