• NAME
• VERSION
• DATE
• SYNOPSIS
• DESCRIPTION
• INTERFACE
  • Constructors
  • Destructors
  • Public Class Methods
  • Public Instance Methods
• PRIVATE
  • Private Class Methods
  • Private Instance Methods
  • Private Functions
• NOTES
• AUTHOR
• SEE ALSO
• POD ERRORS

NAME

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

VERSION

$Revision: 1.6 $

DATE

$Date: 2002/01/06 04:40:36 $

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);

# 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

$org = Bric::Util::Coll->new($params)

Instanticates a new collection by calling the href() method of the class managed by the collection. The class name must be identified by the class_name() method of Bric::Util::Coll subclasses. That class 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 are the object 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 $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 || @obj_ids)

Deletes objects. Use either IDs or objects - but use them consistently!

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.

$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

NONE.

Private Functions

$self = &$populate($self)

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.

NOTES

NONE.

AUTHOR

David Wheeler <david@wheeler.net>

SEE ALSO

Bric

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 216:

=back doesn't take any parameters, but you said =back 4

Around line 242:

'=item' outside of any '=over'

Around line 299:

You forgot a '=back' before '=head2'