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.