NAME HTTP::Exception - throw HTTP-Errors as (Exception::Class-) Exceptions VERSION version 0.04003 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, "" 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 . 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 * AnnoCPAN: Annotated CPAN documentation * CPAN Ratings * Search CPAN 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.