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.