1HTTP::Exception(3) User Contributed Perl Documentation HTTP::Exception(3)
2
6 HTTP::Exception - throw HTTP-Errors as (Exception::Class-) Exceptions
7
9 version 0.04007
10
12 HTTP::Exception lets you throw HTTP-Errors as Exceptions.
13 use HTTP::Exception;
15 # throw a 404 Exception
17 HTTP::Exception->throw(404);
18 # later in your framework
20 eval { ... };
21 if (my $e = HTTP::Exception->caught) {
22 # do some errorhandling stuff
23 print $e->code; # 404
24 print $e->status_message; # Not Found
25 }
26 You can also throw HTTP::Exception-subclasses like this.
28 # same 404 Exception
30 eval { HTTP::Exception::404->throw(); };
31 eval { HTTP::Exception::NOT_FOUND->throw(); };
32 And catch them accordingly.
34 # same 404 Exception
36 eval { HTTP::Exception::404->throw(); };
37 if (my $e = HTTP::Exception::405->caught) { do stuff } # won't catch
39 if (my $e = HTTP::Exception::404->caught) { do stuff } # will catch
40 if (my $e = HTTP::Exception::NOT_FOUND->caught) { do stuff } # will catch
41 if (my $e = HTTP::Exception::4XX->caught) { do stuff } # will catch all 4XX Exceptions
42 if (my $e = HTTP::Exception->caught) { do stuff } # will catch every HTTP::Exception
43 if (my $e = Exception::Class->caught) { do stuff } # catch'em all
44 You can create Exceptions and not throw them, because maybe you want to
46 set some fields manually. See "FIELDS" in HTTP::Exception and
47 "ACCESSORS" in HTTP::Exception for more info.
48 # is not thrown, ie doesn't die, only created
50 my $e = HTTP::Exception->new(404);
51 # usual stuff works
53 $e->code; # 404
54 $e->status_message # Not Found
55 # set status_message to something else
57 $e->status_message('Nothing Here')
58 # fails, because code is only an accessor, see section ACCESSORS below
60 # $e->code(403);
61 # and finally throw our prepared exception
63 $e->throw;
64
66 Every HTTP::Exception is a Exception::Class - Class. So the same
67 mechanisms apply as with Exception::Class-classes. In fact have a look
68 at Exception::Class' docs for more general information on exceptions
69 and Exception::Class::Base for information on what methods a caught
70 exception also has.
71 HTTP::Exception is only a factory for HTTP::Exception::XXX (where X is
73 a number) subclasses. That means that HTTP::Exception->new(404) returns
74 a HTTP::Exception::404 object, which in turn is a HTTP::Exception::Base
75 - Object.
76 Don't bother checking a caught HTTP::Exception::...-class with "isa" as
78 it might not contain what you would expect. Use the code- or
79 status_message-attributes and the is_ -methods instead.
80 The subclasses are created at compile-time, ie the first time you make
82 "use HTTP::Exception". See paragraph below for the naming scheme of
83 those subclasses.
84 Subclassing the subclasses works as expected.
86
88 HTTP::Exception::XXX
89 X is a Number and XXX is a valid HTTP-Statuscode. All HTTP-Statuscodes
90 are supported. See chapter "COMPLETENESS" in HTTP::Exception
91 HTTP::Exception::STATUS_MESSAGE
93 STATUS_MESSAGE is the same name as a HTTP::Status Constant WITHOUT the
94 HTTP_ at the beginning. So see "CONSTANTS" in HTTP::Status for more
95 details.
96
98 It is possible to load only specific ranges of errors. For example
99 use HTTP::Exception qw(5XX);
101 HTTP::Exception::500->throw; # works
103 HTTP::Exception::400->throw; # won't work anymore
104 will only create HTTP::Exception::500 till HTTP::Exception::510. In
106 theory this should save some memory, but I don't have any numbers, that
107 back up this claim.
108 You can load multiple ranges
110 use HTTP::Exception qw(3XX 4XX 5XX);
112 And there are aliases for ranges
114 use HTTP::Exception qw(CLIENT_ERROR)
116 The following aliases exist and load the specified ranges:
118 REDIRECTION => 3XX
120 CLIENT_ERROR => 4XX
121 SERVER_ERROR => 5XX
122 ERROR => 4XX 5XX
123 ALL => 1XX 2XX 3XX 4XX 5XX
124 And of course, you can load multiple aliased ranges
126 use HTTP::Exception qw(REDIRECTION ERROR)
128 ALL is the same as not specifying any specific range.
130 # the same
132 use HTTP::Exception qw(ALL);
133 use HTTP::Exception;
134
136 code
137 A valid HTTP-Statuscode. See HTTP::Status for information on what codes
138 exist.
139 is_info
141 Return TRUE if "$self-"code> is an Informational status code (1xx).
142 This class of status code indicates a provisional response which can't
143 have any content.
144 is_success
146 Return TRUE if "$self-"code> is a Successful status code (2xx).
147 is_redirect
149 Return TRUE if "$self-"code> is a Redirection status code (3xx). This
150 class if status code indicates that further action needs to be taken by
151 the user agent in order to fulfill the request.
152 is_error
154 Return TRUE if "$self-"code> is an Error status code (4xx or 5xx). The
155 function return TRUE for both client error or a server error status
156 codes.
157 is_client_error
159 Return TRUE if "$self-"code> is an Client Error status code (4xx). This
160 class of status code is intended for cases in which the client seems to
161 have erred.
162 is_server_error
164 Return TRUE if "$self-"code> is an Server Error status code (5xx). This
165 class of status codes is intended for cases in which the server is
166 aware that it has erred or is incapable of performing the request.
167 POD for is_ methods is Copy/Pasted from HTTP::Status, so check back
169 there and alert me of changes.
170
172 Fields are the same as ACCESSORS except they can be set. Either you set
173 them during Exception creation (->new) or Exception throwing (->throw).
174 HTTP::Exception->new(200, status_message => "Everything's fine");
176 HTTP::Exception::200->new(status_message => "Everything's fine");
177 HTTP::Exception::OK->new(status_message => "Everything's fine");
178 HTTP::Exception->throw(200, status_message => "Everything's fine");
180 HTTP::Exception::200->throw(status_message => "Everything's fine");
181 HTTP::Exception::OK->throw(status_message => "Everything's fine");
182 Catch them in your Webframework like this
184 eval { ... }
186 if (my $e = HTTP::Exception->caught) {
187 print $e->code; # 200
188 print $e->status_message # "Everything's fine" instead of the usual ok
189 }
190 status_message
192 DEFAULT The HTTP-Statusmessage as provided by HTTP::Status
193 A Message, that represents the Execptions' Status for Humans.
195
197 HTTP::Exception can be used with Plack::Middleware::HTTPExceptions. But
198 HTTP::Exception does not depend on Plack, you can use it anywhere else.
199 It just plays nicely with Plack.
200
202 For the sake of completeness, HTTP::Exception provides exceptions for
203 non-error-http-statuscodes. This means you can do
204 HTTP::Exception->throw(200);
206 which throws an Exception of type OK. Maybe useless, but complete. A
208 more realworld-example would be a redirection
209 # all are exactly the same
211 HTTP::Exception->throw(301, location => 'google.com');
212 HTTP::Exception::301->throw(location => 'google.com');
213 HTTP::Exception::MOVED_PERMANENTLY->throw(location => 'google.com');
214
216 The HTTP::Exception-Subclass-Creation relies on HTTP::Status. It's
217 possible that the Subclasses change, when HTTP::Status' constants are
218 changed.
219 New Subclasses are created automatically, when constants are added to
221 HTTP::Status. That means in turn, that Subclasses disappear, when
222 constants are removed from HTTP::Status.
223 Some constants were added to HTTP::Status' in February 2012. As a
225 result HTTP::Exception broke. But that was the result of uncareful
226 coding on my side. I think, that breaking changes are now quite
227 unlikely.
228
230 Thomas Mueller, "<tmueller at cpan.org>"
231
233 Exception::Class, Exception::Class::Base
234 Consult Exception::Class' documentation for the Exception-Mechanism and
235 Exception::Class::Base' docs for a list of methods our caught Exception
236 is also capable of.
237 HTTP::Status
239 Constants, Statuscodes and Statusmessages
240 HTTP::Throwable, built on top of the more modern Throwable framework (the
242 successor to Exception::Class)
243 Plack, especially Plack::Middleware::HTTPExceptions
244 Have a look at Plack, because it rules in general. In the first place,
245 this Module was written as the companion for
246 Plack::Middleware::HTTPExceptions, but since it doesn't depend on
247 Plack, you can use it anywhere else, too.
248
250 Please report any bugs or feature requests to "bug-http-exception at
251 rt.cpan.org", or through the web interface at
252 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTTP-Exception>. I
253 will be notified, and then you'll automatically be notified of progress
254 on your bug as I make changes.
255
257 You can find documentation for this module with the perldoc command.
258 perldoc HTTP::Exception
260 You can also look for information at:
262 • RT: CPAN's request tracker
264 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTTP-Exception>
266 • AnnoCPAN: Annotated CPAN documentation
268 <http://annocpan.org/dist/HTTP-Exception>
270 • CPAN Ratings
272 <http://cpanratings.perl.org/d/HTTP-Exception>
274 • Search CPAN
276 <https://metacpan.org/release/HTTP-Exception>
278
280 Copyright 2010 Thomas Mueller.
281 This program is free software; you can redistribute it and/or modify it
283 under the terms of either: the GNU General Public License as published
284 by the Free Software Foundation; or the Artistic License.
285 See http://dev.perl.org/licenses/ for more information.
287perl v5.34.0 2022-01-21 HTTP::Exception(3)