NAME¶

HTTP::Throwable::Factory - a factory that throws HTTP::Throwables for you

VERSION¶

version 0.028

OVERVIEW¶

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

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.

  use HTTP::Throwable::Factory 'http_exception';
  builder {
      mount '/old' => http_exception('Gone'),
  };

PERL VERSION¶

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

SUBCLASSING¶

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.

  Factory->throw(NotFound => { ... })

AUTHORS¶

• Stevan Little <stevan.little@iinteractive.com>
• Ricardo Signes <cpan@semiotic.systems>

COPYRIGHT AND LICENSE¶

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.