NAME
Class::EHierarchy - Base class for handling hierarchally ordered objects
VERSION
$Id: EHierarchy.pm,v 0.90 2011/08/18 23:58:51 acorliss Exp $
SYNOPSIS
package FooObj;
sub _initalize ($@) {
my $obj = shift;
my %args = @_;
my $rv = 1;
if ( -t $args{FILE} ) {
_declProp( $obj, CEH_PRIV | CEH_SCALAR, 'counter' );
$obj->property( 'counter', 1 );
$rv = _declProp( $obj, CEH_PUB | CEH_SCALAR, keys %args );
} else {
$rv = 0;
}
return $rv;
}
sub _incCounter ($) {
my $obj = shift;
return $obj->property('counter', $obj->property('counter') + 1 );
}DESCRIPTION
Class::EHierarchy is intended for use as a base class where hierarchally ordered objects are desired. This class allows you to define a parent -> child relationship between objects and ensures an orderly destruction of objects according to that relationship, instead of perl's reverse order destruction sequence based on reference counting.
This class also creates opaque objects to prevent any access to internal data except by the published interface.
ORDERLY DESTRUCTION
Objects can adopt other objects which creates a tracked relationship within the class itself. Those child objects can, in turn, adopt objects of their own. The result is a hierarchal tree of objects, with the parent being the trunk.
Perl uses a reference-counting garbage collection system which destroys objects and data structures as the last reference to it goes out of scope. This results in an object being destroyed before any internal data structures or objects is referenced internally. In most cases this works just fine since many programs really don't care how things are destroyed, just as long as they are.
Occasionally, though, we do care. Take, for instance, a database-backed application that delays commits to the database until after all changes are made. Updates made to a collection of records can be flushed as as the parent object goes out of scope. In a regular object framework the parent object would be released, which could be a problem if it owned the database connection object. In this framework, though, the children are pre-emptively released first, triggering their DESTROY methods beforehand, in which the database commit is made.
This, in a nutshell, is the primary purpose of this class.
A few things should be mentioned: because of how the relationships are tracked in the class child objects do have a reference to them stored in the class data structures. This means you can't destroy a reference to them inside of the parent and have them reaped. You must disown them first.
OPAQUE OBJECTS
Objects based on this class will be opaque objects instead of the traditional blessed hash references in which the hash elements could be access directly through dereferencing. This prevents access to internal data structures outside of the published interface. This does mean, though, that you can't access your data directly, either. You must use a provided method to retrieve that data from the class storage.
A side benefit, however, is that this provides some OOP scoping for properties. You can declare your properties as one of three scopes:
private accessible only to members of this object's class
restricted accessible to members of this object's class
and subclasses
public globally accessibleLikewise, the same can be declared for methods.
Scoping of various members are done during object instantiation. Examples are provided below.
NOTE: private properties are not merely restricted from subclasses, they are also hidden, so there's no worries about naming conflicts with subclasses.
SUBROUTINES/METHODS
Subroutines and constants are provided strictly for use by derived classes within their defined methods. To avoid any confusion all of our exportable symbols are *not* exported by default. You have to specifically import the all tag set. Because these subroutines should not be used outside of the class they are all preceded by an underscore, like any other private function.
Methods, on the other hand, are meant for direct and global use. With the exception of new and DESTROY they should all be safe to override.
SUBROUTINES/CONSTANTS
_declProp
$rv = _declProp($obj, SCOPE | TYPE | FLAG, @propNames);This function is meant to be called within a subclass' _initialize method which is called during object instantiation. It is used to create named properties while declaring they access scope and type. The following constants are used to create the second argument:
Scope
---------------------------------------------------------
CEH_PRIV private scope
CEH_RESTR restricted scope
CEH_PUB public scope
Type
---------------------------------------------------------
CEH_SCALAR scalar value or reference
CEH_ARRAY array
CEH_HASH hash
CEH_CODE code reference
CEH_GLOB glob reference
CEH_REF object reference
Flag
---------------------------------------------------------
CEH_NO_UNDEF No undef values are allowed to be
assigned to the propertyConstants describing property attributes are OR'ed together, and only one scope and one type from each list should be used at a time. Using multiple types or scopes to describe any particular property will make it essentially inaccessible.
Type, if omitted, defaults to CEH_SCALAR, Scope defaults to CEH_PUB.
_declMethod
$rv = _declMethod($obj, $attr, @methods);This function is meant to be called within a subclass' _initialize method which is called during object instantiation. It is used to create wrappers for those functions whose access you want to restrict. It works along the same lines as properties and uses the same scoping constants for the attribute.
Only methods defined within the subclass can have scoping declared. You cannot call this method for inherited methods.
METHODS
new
$obj = Class::Foo->new(@args);This method must not be overridden in any subclass, but be used as-is. That said, subclasses still have complete control over whether this method call succeeds via the _initialize method, which all subclasses must provide themselves.
When the object contsructor is called an object is instantiated, then _initialize is called with all of the new arguments passed on unaltered. The _initialize method is responsible for an internal initialization necessary as well as any validation. It must return a boolean value which determines whether a valid object reference is returned by the new method, or undef.
NOTE: all superclasses based on Class::EHierarchy containing a _initialize method will also be called, all prior to the current subclass' method.
_initialize
$rv = $newObj->_initialize(@newArgs);This method is not provided by this class, but is required to be provided by subclasses. It is in this method that you can declare properties and methods with the applicable attributes, perform validation, etc. It must return a boolean value which determines if the object construction can succeed.
children
@crefs = $obj->children;This method returns an array of object references to every object that was adopted by the current object.
siblings
@crefs = $obj->siblings;This method returns an array of object references to every object that shares the same parent as the current object.
adopt
$rv = $obj->adopt($cobj1, $cobj2);This method attempts to adopt the passed objects as children. It returns a boolean value which is true only if all objects were successfully adopted. Only subclasses for Class::EHierarchy can be adopted. Any object that isn't based on this class will cause this method to return a false value.
disown
$rv = $obj->disown($cobj1, $cobj2);This method attempts to disown all the passed objects as children. It returns a boolean value based on its success in doing so. Asking it to disown an object it had never adopted in the first place will be silently ignored and still return true.
Disowning objects is a prerequisite for Perl's garbage collection to work and release those objects completely from memory.
property
$val = $obj->property('FooScalar');
@val = $obj->property('FooArray');
%val = $obj->property('FooHash');
$rv = $obj->property('FooScalar', 'random text or reference');
$rv = $obj->property('FooArray', @foo);
$rv = $obj->property('FooHash', %foo);This method provides a generic property accessor that abides by the scoping attributes given by _declProp. This means that basic reference types are checked for during assignment, as well as flags like CEH_NO_UNDEF.
A boolean value is returned on attempts to set values.
NOTE: Given that the presence of additional arguments after the property name sets this method into 'write' mode, there is obviously no way to use this to empty a hash or array property. For that please see the purge method.
propertyNames
@properties = $obj->propertyNames;This method returns a list of all registered properties for the current object. Property names will be filtered appropriately by the caller's context.
push
$rv = $obj->push($prop, @values);This method pushes additional elements onto the specified array property. Calling this method on any non-array property will cause the program to croak. It returns the return value from the push function.
pop
$rv = $obj->pop($prop);This method pops an element off of the specified array property. Calling this method on any non-array property will cause the program to croak. It returns the return value from the pop function.
unshift
$rv = $obj->unshift($prop, @values);This method unshifts additional elements onto the specified array property. Calling this method on any non-array property will cause the program to croak. It returns the return value from the unshift operation.
shift
$rv = $obj->shift($prop);This method shifts an element off of the specified array property. Calling this method on any non-array property will cause the program to croak. It returns the return value from the shift operation.
exists
$rv = $obj->exists($prop, $key);This method checks for the existance of the specified key in the hash property. Calling this method on any non-hash property will cause the program to croack. It returns the return value from the exists function.
keys
@keys = $obj->keys($prop);This method returns a list of keys from the specified hash property. Calling this method on any non-hash property will cause the program to croak. It returns the return value from the keys function.
store
$obj->add($prop, foo => bar);
$obj->add($prop, 4 => foo, 5 => bar);This method is a unified method for storing elements in both hashes and arrays. Hashes elements are simply key/value pairs, while array elements are provided as ordinal index/value pairs.
retrieve
@values = $obj->retrieve($hash, qw(foo bar) );
@values = $obj->retrieve($array, 3 .. 5 );This method is a unified method for retrieving specific element(s) from both hashes and arrays. Hash values are retrieved in the order of the specified keys, whils array elements are retrieved in the order of the specified ordinal indexes.
remove
$obj->remove($prop, @keys);
$obj->remove($prop, 5, 8 .. 10);This method is a unified method for removing specific elements from both hashes and arrays. A list of keys is needed for hash elements, a list of ordinal indexes is needed for arrays.
NOTE: In the case of arrays please note that an element removed in the middle of an array does cause the following elements to be shifted accordingly. This method is really only useful for removing a few elements at a time from an array. Using it for large swaths of elements will likely prove it to be poorly performing. You're better of retrieving the entire array yourself via the property method, splicing what you need, and calling property again to set the new array contents.
purge
$obj->purge($prop);This is a unified method for purging the contents of both array and hash properties.
DESTROY
A DESTROY method is provided by this class and must not be overridden by any subclass. It is this method that provides the ordered termination property of hierarchal objects. Any code you wish to be executed during this phase can be put into a _deconstruct method in your subclass. If it's available it will be executed after any children have been released.
_deconstruct
$obj->_deconstructThis method is optional, but if needed must be provided by the subclass. It will be called during the DESTROY phase of the object.
DEPENDENCIES
None.
BUGS AND LIMITATIONS
As noted in the CREDIT section below portions of the concept and implementation of opaque objects were taken from Damian Conway's module Class::Std(3). I have chosen to deviate from his implementation in a few key areas, and any or all of them might be considered bugs and/or limitations.
Damian relies on an ident function in his module to provide each module with a unique identifier. Unfortunately, when retrieving internal data structures he wants you to use them for each and every retrieval. While effective, this exercises the stack a bit more and provides a performance penalty.
To avoid that penalty I chose to store the ID in the anonymous scalar we referenced as part of object instantiation. While in theory this could be overwritten and wreak havoc in the class data structures I think the performance benefits outweigh it. I am hedging that most of us won't accidentally dereference our object reference and overwrite it.
Another benefit of storing the ID directly is that the code you'll write based on this class looks a lot more like traditional Perl OO. If you're a devout Damian disciple that's probably not a benefit, but his '$attr_foo{ident $self}' notation really rubs me the wrong way.
Another performance concern I had with Class::Std was the heavy reliance on internal hashes. This penalizes you on both memory and performance utilization. So, I changed my internal _ident function to be based purely on an ordinal index value, which allowed me to use arrays to store all of the applicable class data.
End sum, this module gives you the hierarchal qualities I needed along with some of the opaque object benefits of Class::Std(3), but in a manner that possibly interferes less with one's natural style of coding while being generally more efficient and system friendly.
CREDIT
The notion and portions of the implementation of opaque objects were lifted from Damian Conway's Class::Std(3) module. Conway has a multitude of great ideas, and I'm grateful that he shares so much with the community.
AUTHOR
Arthur Corliss (corliss@digitalmages.com)
LICENSE AND COPYRIGHT
This software is licensed under the same terms as Perl, itself. Please see http://dev.perl.org/licenses/ for more information.
(c) 2009, Arthur Corliss (corliss@digitalmages.com)