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

VERSION
    version 0.04006

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

    *   AnnoCPAN: Annotated CPAN documentation

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

    *   CPAN Ratings

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

    *   Search CPAN

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

