VERSION

$Id: EHierarchy.pm,v 0.93 2013/07/07 00:17:27 acorliss Exp $

SYNOPSIS

package TelDirectory;
use Class::EHierarchy qw(:all);
use vars qw(@ISA @_properties @_methods);
@ISA = qw(Class::EHierarchy);
@_properties = (
[ CEH_PRIV | CEH_SCALAR, 'counter', 0 ],
[ CEH_PUB | CEH_SCALAR, 'first', '' ],
[ CEH_PUB | CEH_SCALAR, 'last', '' ],
[ CEH_PUB | CEH_ARRAY, 'telephone' ]
);
@_methods = (
[ CEH_PRIV, '_incrCounter' ],
[ CEH_PUB, 'addTel' ]
);
sub _initalize {
my $obj = shift;
my %args = @_;
my $rv = 1;
# Statically defined properties and methods are
# defined above. Dynamically generated/defined
# poperties and methods can be done here.
return $rv;
}
...
package main;
use TelDirectory;
my $entry = new TelDirectory;
$entry->property('first', 'John');
$entry->property('last', 'Doe');
$entry->push('telephone', '555-111-2222', '555-555'5555');

DESCRIPTION

Class::EHierarchy is intended for use as a base class for custom objects, but objects that need one or more of the following features:

• orderly bottom-up destruction of objects
• opaque objects
• class-based access restrictions for properties and methods
• primitive strict property type awareness
• alias-based object retrieval

Each of the above features are described in more depth in the following subsections:

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

    Database Object
        +--> Table1
        |       +--> Row1
        |       +--> Row2
        +--> Table2
                +--> Row1

This, in a nutshell, is the primary purpose of this class.

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.

ACCESS RESTRICTIONS

A benefit of having an opaque object is that allows for scoping of both properties and methods. This provides for the following access restrictions:

    private         accessible only to members of this object's class
    restricted      accessible to members of this object's class  
                    and subclasses
    public          globally accessible

Attempts to access either from outside the approved scope will cause the code to croak. There is an exception, however: private properties. This aren't just protected, they're hidden. This allows various subclasses to use the same names for internal properties without fear of name space violations.

PROPERTY TYPE AWARENESS

Properties can be explicitly declared to be of certain primitive data types. This allows some built in validation of values being set. Known scalar value types are scalar, code, glob, and reference.

Properties can also house hashes and arrays. When this is leveraged it allows for properties contents to be managed in ways similar to their raw counterparts. You can retrieve individual elements, add, set, test for, and so on.

ALIASES

In a hierarchal system of object ownership the parent objects have strong references to their children. This frees you from having to code and track object references yourself. Sometimes, however, it's not always convenient or intuitive to remember which parent owns what objects when you have a multilevel hierarchy. Because of that this class implements an alias system to make retrieval simpler.

Aliases are unique within each hierarchy or tree. Consider the following hierarchy in which every node is an object member:

  Application
     +--> Display
     |       +--> Window1
     |       |      +--> Widget1
     |       |      +--> Widget2
     |       |      +--> Widget3
     |       +--> Window2
     |              +--> Widget1
     +--> Database Handle
     +--> Network Connections

Giving each node a plain name, where it makes sense, makes it trivial for a widget to retrieve a reference to the database object to get or update data.

Aliases can also be search via base names, making it trival to get a list of windows that may need to be updated in a display.

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.

The following subroutines, methods, and/or constants are are orgnanized according to their functional domain (as outlined above).

INSTANTIATION/DESTRUCTION

All classes based on this class must use the new constructor and DESTROY deconstructor provided by this class. That said, subclasses still have an opportunity to do work in both phases.

Before that, however, Class::EHierarchy prepares the base object, defining and scoping properties and methods automatically based on the presence of class variables @_properties and @_methods:

    package Contact;
    use Class::EHierarchy qw(:all);
    use vars qw(@ISA @_properties @_methods);
    @ISA = qw(Class::EHierarchy);
    @_properties = (
        [ CEH_PUB | CEH_SCALAR, 'first' ],
        [ CEH_PUB | CEH_SCALAR, 'last' ],
        [ CEH_PUB | CEH_ARRAY,  'telephone' ],
        [ CEH_PUB | CEH_SCALAR, 'email' ],
        );
    @_methods = (
        [ CEH_PUB, 'full_name' ],
        );
    sub _initialize {
        my $obj = shift;
        my $rv  = 1;
        ....
        return $rv;
    }
    sub _deconstruct {
        my $obj = shift;
        my $rv  = 1;
        ....
        return $rv;
    }
    sub full_name {
        my $obj = shift;
        return $obj->property('first') . ' ' .
               $obj->property('last');
    }

Both methods and properties are defined by their access scope. Properties also add in primitive data types. The constants used to designate these attributes are as follows:

    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 property

You'll note that both @_properties and @_methods are arrays of arrays, which each subarray containing the elements for each property or method. The first element is always the attributes and the second the name of the property or method. In the case of the former a third argument is also allowed: a default value for the property:

  @_properties = (
        [ CEH_PUB | CEH_SCALAR, 'first',     'John' ],
        [ CEH_PUB | CEH_SCALAR, 'last',      'Doe' ],
        [ CEH_PUB | CEH_ARRAY,  'telephone', 
            [ qw(555-555-1212 555-555-5555) ] ],
    );

Properties lacking a data type attribute default to CEH_SCALAR. Likewise, scope defaults to CEH_PUB. Public methods can be omitted from @_methods since they will be assumed to be public.

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

    sub _initialize {
        my $obj  = shift;
        my %args = @_;       # or @args = $_;
        my $rv   = 1;
        # Random initialization stuff here
        return $rv;
    }

Once the basic object has been constructed it calls the _initialize method, giving it a complete set of the arguments the constructor was called with. The form of those arguments, whether as an associative array or simple array, is up to the coder.

You can do whatever you want in this method, including creating and adopting child objects. You can also dynamically generate properties and methods using the _declProp and _declMethod class functions. Both are documented below.

This method must return a boolean value. A false return value will cause the constructor to tear everything back down and return undef to the caller.

_declProp

    $rv = _declProp($obj, SCOPE | TYPE | FLAG, @propNames);

This function is used to create named properties while declaring they access scope and type.

Constants 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.

NOTE: CEH_NO_UNDEF only applies to psuedo-scalar types like proper scalars, references, etc. This has no effect on array members or hash values.

_declMethod

    $rv = _declMethod($attr, @methods);

This function is 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.

NOTE: Since scoping is applied to the class symbol table (not on a per object basis) any given method can only be scoped once. That means you can't do crazy things like make public methods private, or vice-versa.

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

    sub _deconstruct {
        my $obj = shift;
        my $rv  = 1;
        # Do random cleanup stuff here
        return $rv;
    }

This method is optional, but if needed must be provided by the subclass. It will be called during the DESTROY phase of the object.

ORDERLY DESTRUCTION

In order for objects to be destroyed from the bottom up it is important to track the hierarchal relationship between them. This class uses a familial parent/child paradigm for doing so.

In short, objects can adopt and disown other objects. Adopted objects become children of the parent object. Any object being destroyed preemptively triggers deconstruction routines on all of its children before cleaning up itself. This ensures that any child needing parental resources for final commits, etc., has those available.

Additional methods are also present to make it easier for objects to interact with their immediate family of objects. Those are documented in this section. More powerful methods also exist as part of the alias system and are documented in their own section.

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. The DESTROY method provided by this class automatically does this for parent objects going out of scope. You may still need to do this explicitly if your parent object manages objects which may need to be released well prior to any garbage collection on the parent.

parent

    $parent = $obj->parent;

This method returns a reference to this object's parent object, or undef if it has no parent.

children

    @crefs = $obj->children;

This method returns an array of object references to every object that was adopted by the current object.

descendants

    @descendants = $obj->descendants;

This method returns an array of object references to every object descended from 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.

root

    $root = $obj->root;

This method returns a reference to the root object in this object's ancestral tree. In other words, the senior most parent in the current hierarchy.

OPAQUE OBJECTS

Opaque objects can't access their own data directly, and so must use methods to access them. There is one principle method for doing so, but note that in a later section a whole suite of convenience functions also exist to make hash and array property access easier.

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.

Any attempt to access a nonexistent property will cause the code to croak.

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 below.

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.

ACCESS RESTRICTIONS

This section is actually covered as part of ``DESTRUCTION'' in INSTANTIATION above.

PROPERTY TYPE AWARENESS

Properties are validated automatically on set attempts for the various scalar types (code, glob, reference, scalar value), as well as arrays and hashes. Working through a single accessor method for individual array or hash elements, however, can be very inconvenient. For that reason many common array/hash functions have been implemented as methods.

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 existence 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, while 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.

ALIASES

alias

    $rv = $obj->alias($new_alias);
    $alias = $obj->alias;

This method gets/sets the alias for the object. Gets always return a string, while sets return a boolean value. This can be false if the proposed alias is already in use by another object in its hierarchy.

relative

  $oref = $obj->relative($name);

This method retrieves the object known under the passed alias.

relatives

  @orefs = $obj->relatives($name);

This method retrieves a list of all objects with aliases beginning with the passed name.

DEPENDENCIES

None.

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 ([email protected])

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 ([email protected])