Name

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

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:

Side Effects: NONE.

Notes: NONE.

my $org = Bric::Util::Coll->lookup()

Not implemented - not needed.

Throws:

Side Effects: NONE.

Notes: NONE.

Bric::Util::Coll->list()

Not implemented - not needed.

Throws:

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:

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:

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:

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:

Side Effects: NONE.

Notes: NONE.

$self = $coll->add_objs(@objs)

Adds existing objects to the collection.

Throws:

Side Effects: NONE.

Notes: NONE.

$self = $coll->add_new_objs(@objs)

Adds existing objects to the collection as new objects.

Throws:

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:

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:

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:

Side Effects: NONE.

Notes: NONE.

Private Functions

NONE.

Notes

NONE.

Author

David Wheeler <david@justatheory.com>

See Also

Bric