/ 
HTTP-Exception-0.01001
River stage two • 13 direct dependents • 28 total dependents
/ HTTP::Exception

NAME

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

VERSION

Version 0.01000

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>

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 counterpart 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:

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.