NAME
MooX::Failover - Instantiate Moo classes with failover
SYNOPSIS
# In your class:
package MyClass;
use Moo;
use MooX::Failover;
has 'attr' => ( ... );
# after attributes are defined:
failover_to 'OtherClass';
...
# When using the class
my $obj = MyClass->new( %args );
# If %args contains missing or invalid values or new otherwise
# fails, then $obj will be of type "OtherClass".DESCRIPTION
This role provides constructor failover for Moo classes.
If a class cannot be instantiated because of invalid arguments (perhaps from an untrusted source), then instead it returns the failover class (passing the same arguments to that class).
It is roughly equivalent to using
my $obj = eval { MyClass->new(%args) //
OtherClass->new( %args, error => $@ );This allows for cleaner design, by not forcing you to duplicate type checking for class parameters.
A use case for this module is for instantiating Web::Machine::Resource objects, where a resource class's attributes correspond to URL arguments. A type failure would normally cause an internal serror error (HTTP 500). Using MooX::Failover, we can return a different resource object that examines the error, and returns a more appropriate error code, e.g. bad request (HTTP 400).
Your failover class should support the same methods as the original class, so that it (roughly) satisfies the Liskov Substitution Principle, where all provable properties of the original class are also provable of the failover class. In practice, we only care about the properties (methods and attributes) that are actually used in our programs.
EXPORTS
The following function is always exported:
failover_to
failover_to $class => %options;This specifies the class to instantiate if the constructor dies.
It should be specified after all of the attributes have been declared.
The following options are supported.
class-
The name of the class to fail over to. It defaults to
$class. constructor-
The name of the constructor method. It defaults to "new".
args-
The arguments to pass to the failover class. When omitted, it will pass the same arguments as the original class.
This can be a scalar (single argument), hash reference or array reference.
err_arg-
This is the name of the constructor argument to pass the error to (it defaults to "error". This is useful if the failover class can inspect the error and act appropriately.
For example, if the original class is a handler for a website, where the attributes correspond to URL parameters, then the failover class can return HTTP 400 responses if the errors are for invalid parameters.
To disable it, set it to
undef. class_arg-
This is the name of the constructor argument to pass the name class that failed. It defaults to "class".
To disable it, set it to
undef.
This was originally a Moo port of MooseX::Failover. The interface was redesigned significantly, to be more efficient.
ATTRIBUTES
None. Since v0.2.0, there is no longer a failover_to attribute.
SEE ALSO
AUTHOR
Robert Rothenberg <rrwo@thermeon.com>
Acknowledgements
COPYRIGHT
Copyright 2014 Thermeon Europe.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.