--- name: "HTTP::Exception" section: "3pm" platform: "linux" package: "libhttp-exception-perl" version: "0.04007-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/HTTP::Exception" --- # HTTP::Exception(3pm) throw HTTP-Errors as (Exception::Class-) Exceptions ## NAME HTTP::Exception - throw HTTP-Errors as (Exception::Class-) Exceptions ## VERSION version 0.04007 ## 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 ### HTTP::Throwable, built on top of the more modern Throwable framework (the successor to Exception::Class) ### 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.