Bric::Util::Coll(3p)  User Contributed Perl Documentation Bric::Util::Coll(3p)



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:

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

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

           Side Effects: NONE.

           Notes: NONE.

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

           Throws:

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

           Side Effects: NONE.

           Notes: NONE.

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

           Throws:

           o   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:

           o   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:

           o   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:

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

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

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

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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:

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

           Side Effects: NONE.

           Notes: NONE.

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

           Throws:

           o   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:

           o   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:

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

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

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

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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:

           o   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:

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

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

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

           o   Unable to connect to database.

           o   Unable to prepare SQL statement.

           o   Unable to select column into arrayref.

           o   Unable to execute SQL statement.

           o   Unable to bind to columns to statement handle.

           o   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



perl v5.12.2                      2006-03-17              Bric::Util::Coll(3p)
