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

VERSION
    Version 0.01001

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->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 (don't know what that could
    be usefull for, except testing).

        # 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

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

  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.

ACCESSORS
  code Readonly
    The HTTP-Statuscode

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

  is_info
    Return TRUE if $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 $code is a *Successful* status code (2xx).

  is_redirect
    Return TRUE if $code is a *Redirection* status code (3xx). This class of
    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 $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 $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 $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.

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.

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.

    The Changes-File of HTTP::Status indicates, that the last change to its
    constants was made in 2008. I think, that breaking changes are quite
    unlikely.

AUTHOR
    Thomas Mueller, "<thomas.mi.iller at gmail.com>"

INSTALLATION

To install this module, run the following commands:

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

SUPPORT AND DOCUMENTATION

After installing, 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
        http://search.cpan.org/dist/HTTP-Exception/


LICENSE AND COPYRIGHT

Copyright (C) 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.