Class::Container - Glues object frameworks together transparently
version 0.13
package Car;
use Class::Container;
@ISA = qw(Class::Container);
__PACKAGE__->valid_params
(
paint => {default => 'burgundy'},
style => {default => 'coupe'},
windshield => {isa => 'Glass'},
radio => {isa => 'Audio::Device'},
);
__PACKAGE__->contained_objects
(
windshield => 'Glass::Shatterproof',
wheel => { class => 'Vehicle::Wheel',
delayed => 1 },
radio => 'Audio::MP3',
);
sub new {
my $package = shift;
# 'windshield' and 'radio' objects are created automatically by
# SUPER::new()
my $self = $package->SUPER::new(@_);
$self->{right_wheel} = $self->create_delayed_object('wheel');
... do any more initialization here ...
return $self;
}
This class facilitates building frameworks of several classes that
inter-operate. It was first designed and built for "HTML::Mason", in
which the Compiler, Lexer, Interpreter, Resolver, Component, Buffer, and
several other objects must create each other transparently, passing the
appropriate parameters to the right class, possibly substituting other
subclasses for any of these objects.
The main features of "Class::Container" are:
- •
- Explicit declaration of containment relationships
(aggregation, factory creation, etc.)
- •
- Declaration of constructor parameters accepted by each
member in a class framework
- •
- Transparent passing of constructor parameters to the class
that needs them
- •
- Ability to create one (automatic) or many (manual)
contained objects automatically and transparently
Suppose you've got a class called "Parent", which contains an object
of the class "Child", which in turn contains an object of the class
"GrandChild". Each class creates the object that it contains. Each
class also accepts a set of named parameters in its "new()" method.
Without using "Class::Container", "Parent" will have to
know all the parameters that "Child" takes, and "Child"
will have to know all the parameters that "GrandChild" takes. And
some of the parameters accepted by "Parent" will really control
aspects of "Child" or "GrandChild". Likewise, some of the
parameters accepted by "Child" will really control aspects of
"GrandChild". So, what happens when you decide you want to use a
"GrandDaughter" class instead of the generic "GrandChild"?
"Parent" and "Child" must be modified accordingly, so that
any additional parameters taken by "GrandDaughter" can be
accommodated. This is a pain - the kind of pain that object-oriented
programming was supposed to shield us from.
Now, how can "Class::Container" help? Using
"Class::Container", each class ("Parent",
"Child", and "GrandChild") will declare what arguments
they take, and declare their relationships to the other classes
("Parent" creates/contains a "Child", and
"Child" creates/contains a "GrandChild"). Then, when you
create a "Parent" object, you can pass "Parent->new()"
all the parameters for all three classes, and they will trickle down to the
right places. Furthermore, "Parent" and "Child" won't have
to know anything about the parameters of its contained objects. And finally,
if you replace "GrandChild" with "GrandDaughter", no
changes to "Parent" or "Child" will likely be necessary.
Any class that inherits from "Class::Container" should also inherit
its "new()" method. You can do this simply by omitting it in your
class, or by calling "SUPER::new(@_)" as indicated in the SYNOPSIS.
The "new()" method ensures that the proper parameters and objects
are passed to the proper constructor methods.
At the moment, the only possible constructor method is "new()". If you
need to create other constructor methods, they should call "new()"
internally.
This class method is used to register what other objects, if any, a given class
creates. It is called with a hash whose keys are the parameter names that the
contained class's constructor accepts, and whose values are the default class
to create an object of.
For example, consider the "HTML::Mason::Compiler" class, which uses
the following code:
__PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );
This defines the relationship between the "HTML::Mason::Compiler"
class and the class it creates to go in its "lexer" slot. The
"HTML::Mason::Compiler" class "has a" "lexer".
The "HTML::Mason::Compiler->new()" method will accept a
"lexer" parameter and, if no such parameter is given, an object of
the "HTML::Mason::Lexer" class should be constructed.
We implement a bit of magic here, so that if
"HTML::Mason::Compiler->new()" is called with a
"lexer_class" parameter, it will load the indicated class
(presumably a subclass of "HTML::Mason::Lexer"), instantiate a new
object of that class, and use it for the Compiler's "lexer" object.
We're also smart enough to notice if parameters given to
"HTML::Mason::Compiler->new()" actually should go to the
"lexer" contained object, and it will make sure that they get passed
along.
Furthermore, an object may be declared as "delayed", which means that
an object
won't be created when its containing class is constructed.
Instead, these objects will be created "on demand", potentially more
than once. The constructors will still enjoy the automatic passing of
parameters to the correct class. See the "create_delayed_object()"
for more.
To declare an object as "delayed", call this method like this:
__PACKAGE__->contained_objects( train => { class => 'Big::Train',
delayed => 1 } );
Specifies the parameters accepted by this class's "new()" method as a
set of key/value pairs. Any parameters accepted by a superclass/subclass will
also be accepted, as well as any parameters accepted by contained objects.
This method is a get/set accessor method, so it returns a reference to a hash
of these key/value pairs. As a special case, if you wish to set the valid
params to an empty set and you previously set it to a non-empty set, you may
call "__PACKAGE__->valid_params(undef)".
"valid_params()" is called with a hash that contains parameter names
as its keys and validation specifications as values. This validation
specification is largely the same as that used by the
"Params::Validate" module, because we use
"Params::Validate" internally.
As an example, consider the following situation:
use Class::Container;
use Params::Validate qw(:types);
__PACKAGE__->valid_params
(
allow_globals => { type => ARRAYREF, parse => 'list', default => [] },
default_escape_flags => { type => SCALAR, parse => 'string', default => '' },
lexer => { isa => 'HTML::Mason::Lexer' },
preprocess => { type => CODEREF, parse => 'code', optional => 1 },
postprocess_perl => { type => CODEREF, parse => 'code', optional => 1 },
postprocess_text => { type => CODEREF, parse => 'code', optional => 1 },
);
__PACKAGE__->contained_objects( lexer => 'HTML::Mason::Lexer' );
The "type", "default", and "optional" parameters
are part of the validation specification used by "Params::Validate".
The various constants used, "ARRAYREF", "SCALAR", etc. are
all exported by "Params::Validate". This means that any of these six
parameter names, plus the "lexer_class" parameter (because of the
"contained_objects()" specification given earlier), are valid
arguments to the Compiler's "new()" method.
Note that there are also some "parse" attributes declared. These have
nothing to do with "Class::Container" or
"Params::Validate" - any extra entries like this are simply ignored,
so you are free to put extra information in the specifications as long as it
doesn't overlap with what "Class::Container" or
"Params::Validate" are looking for.
If a contained object was declared with "delayed => 1", use this
method to create an instance of the object. Note that this is an object
method, not a class method:
my $foo = $self->create_delayed_object('foo', ...); # YES!
my $foo = __PACKAGE__->create_delayed_object('foo', ...); # NO!
The first argument should be a key passed to the "contained_objects()"
method. Any additional arguments will be passed to the "new()"
method of the object being created, overriding any parameters previously
passed to the container class constructor. (Could I possibly be more
alliterative? Veni, vedi, vici.)
Allows you to adjust the parameters that will be used to create any delayed
objects in the future. The first argument specifies the "name" of
the object, and any additional arguments are key-value pairs that will become
parameters to the delayed object.
When called with only a $name argument and no list of parameters to set, returns
a hash reference containing the parameters that will be passed when creating
objects of this type.
Returns the class that will be used when creating delayed objects of the given
name. Use this sparingly - in most situations you shouldn't care what the
class is.
Version 0.09 of Class::Container added [as yet experimental] support for
so-called "decorator" relationships, using the term as defined in
Design Patterns by Gamma, et al. (the Gang of Four book). To declare a
class as a decorator of another class, simply set @ISA to the class which will
be decorated, and call the decorator class's "decorates()" method.
Internally, this will ensure that objects are instantiated as decorators. This
means that you can mix & match extra add-on functionality classes much
more easily.
In the current implementation, if only a single decoration is used on an object,
it will be instantiated as a simple subclass, thus avoiding a layer of
indirection.
Returns a hash reference suitable for passing to the
"Params::Validate" "validate" function. Does
not
include any arguments that can be passed to contained objects.
Returns a hash reference of every parameter this class will accept,
including parameters it will pass on to its own contained objects. The
keys are the parameter names, and the values are their corresponding
specifications from their "valid_params()" definitions. If a
parameter is used by both the current object and one of its contained objects,
the specification returned will be from the container class, not the
contained.
Because the parameters accepted by "new()" can vary based on the
parameters
passed to "new()", you can pass any parameters to
the "allowed_params()" method too, ensuring that the hash you get
back is accurate.
Returns the object that created you. This is remembered by storing a reference
to that object, so we use the "Scalar::Utils" "weakref()"
function to avoid persistent circular references that would cause memory
leaks. If you don't have "Scalar::Utils" installed, we don't make
these references in the first place, and calling "container()" will
result in a fatal error.
If you weren't created by another object via "Class::Container",
"container()" returns "undef".
In most cases you shouldn't care what object created you, so use this method
sparingly.
This method returns a string meant to describe the containment relationships
among classes. You should not depend on the specific formatting of the string,
because I may change things in a future release to make it prettier.
For example, the HTML::Mason code returns the following when you do
"$interp->show_containers":
HTML::Mason::Interp=HASH(0x238944)
resolver -> HTML::Mason::Resolver::File
compiler -> HTML::Mason::Compiler::ToObject
lexer -> HTML::Mason::Lexer
request -> HTML::Mason::Request (delayed)
buffer -> HTML::Mason::Buffer (delayed)
Currently, containment is shown by indentation, so the Interp object contains a
resolver and a compiler, and a delayed request (or several delayed requests).
The compiler contains a lexer, and each request contains a delayed buffer (or
several delayed buffers).
Returns a hash reference containing a set of parameters that should be
sufficient to re-create the given object using its class's "new()"
method. This is done by fetching the current value for each declared parameter
(i.e. looking in $object for hash entries of the same name), then recursing
through all contained objects and doing the same.
A few words of caution here. First, the dumped parameters represent the
current state of the object, not the state when it was originally
created.
Second, a class's declared parameters may not correspond exactly to its data
members, so it might not be possible to recover the former from the latter. If
it's possible but requires some manual fudging, you can override this method
in your class, something like so:
sub dump_parameters {
my $self = shift;
my $dump = $self->SUPER::dump_parameters();
# Perform fudgery
$dump->{incoming} = $self->{_private};
delete $dump->{superfluous};
return $dump;
}
Params::Validate
Originally by Ken Williams <
[email protected]> and Dave Rolsky
<
[email protected]> for the HTML::Mason project. Important feedback
contributed by Jonathan Swartz <
[email protected]>. Extended by Ken
Williams for the AI::Categorizer project.
Currently maintained by Ken Williams.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.