NAME

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

INSTALLATION

    To install this module, run the following commands:

        perl Build.PL
        ./Build
        ./Build test
        ./Build install

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

 HTTP::Throwable, built on top of the more modern Throwable framework (the
 successor to Exception::Class)

 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.