Provided by: libhttp-exception-perl_0.04004-2_all bug

NAME

       HTTP::Exception - throw HTTP-Errors as (Exception::Class-) Exceptions

VERSION

       version 0.04004

SYNOPSIS

       HTTP::Exception lets you throw HTTP-Errors as Exceptions.

           use HTTP::Exception;

           # throw a 404 Exception
           HTTP::Exception->throw(404);

           # later in your framework
           eval { ... };
           if (my $e = HTTP::Exception->caught) {
               # do some errorhandling stuff
               print $e->code;             # 404
               print $e->status_message;   # Not Found
           }

       You can also throw HTTP::Exception-subclasses like this.

           # same 404 Exception
           eval { HTTP::Exception::404->throw(); };
           eval { HTTP::Exception::NOT_FOUND->throw(); };

       And catch them accordingly.

           # same 404 Exception
           eval { HTTP::Exception::404->throw(); };

           if (my $e = HTTP::Exception::405->caught)       { do stuff } # won't catch
           if (my $e = HTTP::Exception::404->caught)       { do stuff } # will catch
           if (my $e = HTTP::Exception::NOT_FOUND->caught) { do stuff } # will catch
           if (my $e = HTTP::Exception::4XX->caught)       { do stuff } # will catch all 4XX Exceptions
           if (my $e = HTTP::Exception->caught)            { do stuff } # will catch every HTTP::Exception
           if (my $e = Exception::Class->caught)           { do stuff } # catch'em all

       You can create Exceptions and not throw them, because maybe you want to set some fields
       manually. See "FIELDS" in HTTP::Exception and "ACCESSORS" in HTTP::Exception for more
       info.

           # is not thrown, ie doesn't die, only created
           my $e = HTTP::Exception->new(404);

           # usual stuff works
           $e->code;               # 404
           $e->status_message      # Not Found

           # set status_message to something else
           $e->status_message('Nothing Here')

           # fails, because code is only an accessor, see section ACCESSORS below
           # $e->code(403);

           # and finally throw our prepared exception
           $e->throw;

DESCRIPTION

       Every HTTP::Exception is a Exception::Class - Class. So the same mechanisms apply as with
       Exception::Class-classes. In fact have a look at Exception::Class' docs for more general
       information on exceptions and Exception::Class::Base for information on what methods a
       caught exception also has.

       HTTP::Exception is only a factory for HTTP::Exception::XXX (where X is a number)
       subclasses. That means that HTTP::Exception->new(404) returns a HTTP::Exception::404
       object, which in turn is a HTTP::Exception::Base - Object.

       Don't bother checking a caught HTTP::Exception::...-class with "isa" as it might not
       contain what you would expect. Use the code- or status_message-attributes and the is_
       -methods instead.

       The subclasses are created at compile-time, ie the first time you make "use
       HTTP::Exception". See paragraph below for the naming scheme of those subclasses.

       Subclassing the subclasses works as expected.

NAMING SCHEME

   HTTP::Exception::XXX
       X is a Number and XXX is a valid HTTP-Statuscode. All HTTP-Statuscodes are supported. See
       chapter "COMPLETENESS" in HTTP::Exception

   HTTP::Exception::STATUS_MESSAGE
       STATUS_MESSAGE is the same name as a HTTP::Status Constant WITHOUT the HTTP_ at the
       beginning. So see "CONSTANTS" in HTTP::Status for more details.

IMPORTING SPECIFIC ERROR RANGES

       It is possible to load only specific ranges of errors. For example

           use HTTP::Exception qw(5XX);

           HTTP::Exception::500->throw; # works
           HTTP::Exception::400->throw; # won't work anymore

       will only create HTTP::Exception::500 till HTTP::Exception::510. In theory this should
       save some memory, but I don't have any numbers, that back up this claim.

       You can load multiple ranges

           use HTTP::Exception qw(3XX 4XX 5XX);

       And there are aliases for ranges

           use HTTP::Exception qw(CLIENT_ERROR)

       The following aliases exist and load the specified ranges:

           REDIRECTION   => 3XX
           CLIENT_ERROR  => 4XX
           SERVER_ERROR  => 5XX
           ERROR         => 4XX 5XX
           ALL           => 1XX 2XX 3XX 4XX 5XX

       And of course, you can load multiple aliased ranges

           use HTTP::Exception qw(REDIRECTION ERROR)

       ALL is the same as not specifying any specific range.

           # the same
           use HTTP::Exception qw(ALL);
           use HTTP::Exception;

ACCESSORS (READONLY)

   code
       A valid HTTP-Statuscode. See HTTP::Status for information on what codes exist.

   is_info
       Return TRUE if "$self-"code> is an Informational status code (1xx).  This class of status
       code indicates a provisional response which can't have any content.

   is_success
       Return TRUE if "$self-"code> is a Successful status code (2xx).

   is_redirect
       Return TRUE if "$self-"code> is a Redirection status code (3xx). This class if status code
       indicates that further action needs to be taken by the user agent in order to fulfill the
       request.

   is_error
       Return TRUE if "$self-"code> is an Error status code (4xx or 5xx).  The function return
       TRUE for both client error or a server error status codes.

   is_client_error
       Return TRUE if "$self-"code> is an Client Error status code (4xx). This class of status
       code is intended for cases in which the client seems to have erred.

   is_server_error
       Return TRUE if "$self-"code> is an Server Error status code (5xx). This class of status
       codes is intended for cases in which the server is aware that it has erred or is incapable
       of performing the request.

       POD for is_ methods is Copy/Pasted from HTTP::Status, so check back there and alert me of
       changes.

FIELDS

       Fields are the same as ACCESSORS except they can be set. Either you set them during
       Exception creation (->new) or Exception throwing (->throw).

           HTTP::Exception->new(200, status_message => "Everything's fine");
           HTTP::Exception::200->new(status_message => "Everything's fine");
           HTTP::Exception::OK->new(status_message => "Everything's fine");

           HTTP::Exception->throw(200, status_message => "Everything's fine");
           HTTP::Exception::200->throw(status_message => "Everything's fine");
           HTTP::Exception::OK->throw(status_message => "Everything's fine");

       Catch them in your Webframework like this

           eval { ... }
           if (my $e = HTTP::Exception->caught) {
               print $e->code;          # 200
               print $e->status_message # "Everything's fine" instead of the usual ok
           }

   status_message
       DEFAULT The HTTP-Statusmessage as provided by HTTP::Status

       A Message, that represents the Execptions' Status for Humans.

PLACK

       HTTP::Exception can be used with Plack::Middleware::HTTPExceptions. But HTTP::Exception
       does not depend on Plack, you can use it anywhere else. It just plays nicely with Plack.

COMPLETENESS

       For the sake of completeness, HTTP::Exception provides exceptions for non-error-http-
       statuscodes. This means you can do

           HTTP::Exception->throw(200);

       which throws an Exception of type OK. Maybe useless, but complete.  A more realworld-
       example would be a redirection

           # all are exactly the same
           HTTP::Exception->throw(301, location => 'google.com');
           HTTP::Exception::301->throw(location => 'google.com');
           HTTP::Exception::MOVED_PERMANENTLY->throw(location => 'google.com');

CAVEATS

       The HTTP::Exception-Subclass-Creation relies on HTTP::Status.  It's possible that the
       Subclasses change, when HTTP::Status' constants are changed.

       New Subclasses are created automatically, when constants are added to HTTP::Status. That
       means in turn, that Subclasses disappear, when constants are removed from HTTP::Status.

       Some constants were added to HTTP::Status' in February 2012. As a result HTTP::Exception
       broke. But that was the result of uncareful coding on my side.  I think, that breaking
       changes are now quite unlikely.

AUTHOR

       Thomas Mueller, "<tmueller at cpan.org>"

SEE ALSO

   Exception::Class, Exception::Class::Base
       Consult Exception::Class' documentation for the Exception-Mechanism and
       Exception::Class::Base' docs for a list of methods our caught Exception is also capable
       of.

   HTTP::Status
       Constants, Statuscodes and Statusmessages

   Plack, especially Plack::Middleware::HTTPExceptions
       Have a look at Plack, because it rules in general. In the first place, this Module was
       written as the companion for Plack::Middleware::HTTPExceptions, but since it doesn't
       depend on Plack, you can use it anywhere else, too.

BUGS

       Please report any bugs or feature requests to "bug-http-exception at rt.cpan.org", or
       through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTTP-Exception
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTTP-Exception>.  I will be notified, and
       then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

       You can find documentation for this module with the perldoc command.

           perldoc HTTP::Exception

       You can also look for information at:

       •   RT: CPAN's request tracker

           http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTTP-Exception
           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTTP-Exception>

       •   AnnoCPAN: Annotated CPAN documentation

           http://annocpan.org/dist/HTTP-Exception <http://annocpan.org/dist/HTTP-Exception>

       •   CPAN Ratings

           http://cpanratings.perl.org/d/HTTP-Exception <http://cpanratings.perl.org/d/HTTP-
           Exception>

       •   Search CPAN

           https://metacpan.org/release/HTTP-Exception <https://metacpan.org/release/HTTP-
           Exception>

LICENSE AND COPYRIGHT

       Copyright 2010 Thomas Mueller.

       This program is free software; you can redistribute it and/or modify it under the terms of
       either: the GNU General Public License as published by the Free Software Foundation; or
       the Artistic License.

       See http://dev.perl.org/licenses/ for more information.