HTTP::Throwable::Factory - a factory that throws HTTP::Throwables for you
version 0.018
HTTP::Throwable is a role that makes it easy to build exceptions that, once thrown, can be turned into PSGI-style HTTP responses. Because HTTP::Throwable and all its related roles are, well, roles, they can't be instantiated or thrown directly. Instead, they must be built into classes first. HTTP::Throwable::Factory takes care of this job, building classes out of the roles you need for the exception you want to throw.
You can use the factory to either build or throw an exception of either a generic or specific type. Building and throwing are very similar -- the only difference is whether or not the newly built object is thrown or returned. To throw an exception, use the throw method on the factory. To return it, use the new_exception method. In the examples below, we'll just use throw.
throw
new_exception
To throw a generic exception -- one where you must specify the status code and reason, and any other headers -- you pass throw a hashref of arguments that will be passed to the exception class's constructor.
HTTP::Throwable::Factory->throw({ status_code => 301, reason => 'Moved Permanently', additional_headers => [ Location => '/new', ], });
To throw a specific type of exception, include an exception type identifier, like this:
HTTP::Throwable::Factory->throw(MovedPermanently => { location => '/new' });
The type identifier is (by default) the end of a role name in the form HTTP::Throwable::Role::Status::IDENTIFIER. The full list of such included roles is given in the HTTP::Throwable docs.
HTTP::Throwable::Role::Status::IDENTIFIER
You can import routines called http_throw and http_exception that work like the throw and new_exception methods, respectively, but are not called as methods. For example:
http_throw
http_exception
use HTTP::Throwable::Factory 'http_exception'; builder { mount '/old' => http_exception('Gone'), };
One of the big benefits of using HTTP::Throwable::Factory is that you can subclass it to change the kind of exceptions it provides.
If you subclass it, you can change its behavior by overriding the following methods -- provided in the order of likelihood that you'd want to override them, most likely first.
This method returns a list of role names that will be included in any class built by the factory. By default, it includes only HTTP::Throwable::Role::TextBody to satisfy HTTP::Throwable's requirements for methods needed to build a body.
This is the method you're most likely to override in a subclass.
This methods convert the exception type identifier to a role to apply. For example, if you call:
Factory->throw(NotFound => { ... })
...then roles_for_ident is called with "NotFound" as its argument.
roles_for_ident
If throw is called without a type identifier, roles_for_no_ident is called.
roles_for_no_ident
By default, roles_for_ident returns HTTP::Throwable::Role::Status::$ident and roles_for_no_ident returns HTTP::Throwable::Role::Generic and HTTP::Throwable::Role::BoringText.
HTTP::Throwable::Role::Status::$ident
This is the base class that will be subclassed and into which all the roles will be composed. By default, it is Moose::Object, the universal base Moose class.
This method returns the roles that are expected to be applied to every HTTP::Throwable exception. This method's results might change over time, and you are encouraged not to alter it.
Stevan Little <stevan.little@iinteractive.com>
Ricardo Signes <rjbs@cpan.org>
This software is copyright (c) 2011 by Infinity Interactive, Inc..
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install HTTP::Throwable, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTTP::Throwable
CPAN shell
perl -MCPAN -e shell install HTTP::Throwable
For more information on module installation, please visit the detailed CPAN module installation guide.