1HTTP::Exception(3)    User Contributed Perl Documentation   HTTP::Exception(3)
2
3
4

NAME

6       HTTP::Exception - throw HTTP-Errors as (Exception::Class-) Exceptions
7

VERSION

9       version 0.04007
10

SYNOPSIS

12       HTTP::Exception lets you throw HTTP-Errors as Exceptions.
13
14           use HTTP::Exception;
15
16           # throw a 404 Exception
17           HTTP::Exception->throw(404);
18
19           # 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
27       You can also throw HTTP::Exception-subclasses like this.
28
29           # same 404 Exception
30           eval { HTTP::Exception::404->throw(); };
31           eval { HTTP::Exception::NOT_FOUND->throw(); };
32
33       And catch them accordingly.
34
35           # same 404 Exception
36           eval { HTTP::Exception::404->throw(); };
37
38           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
45       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
49           # is not thrown, ie doesn't die, only created
50           my $e = HTTP::Exception->new(404);
51
52           # usual stuff works
53           $e->code;               # 404
54           $e->status_message      # Not Found
55
56           # set status_message to something else
57           $e->status_message('Nothing Here')
58
59           # fails, because code is only an accessor, see section ACCESSORS below
60           # $e->code(403);
61
62           # and finally throw our prepared exception
63           $e->throw;
64

DESCRIPTION

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
72       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
77       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
81       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
85       Subclassing the subclasses works as expected.
86

NAMING SCHEME

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
92   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

IMPORTING SPECIFIC ERROR RANGES

98       It is possible to load only specific ranges of errors. For example
99
100           use HTTP::Exception qw(5XX);
101
102           HTTP::Exception::500->throw; # works
103           HTTP::Exception::400->throw; # won't work anymore
104
105       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
109       You can load multiple ranges
110
111           use HTTP::Exception qw(3XX 4XX 5XX);
112
113       And there are aliases for ranges
114
115           use HTTP::Exception qw(CLIENT_ERROR)
116
117       The following aliases exist and load the specified ranges:
118
119           REDIRECTION   => 3XX
120           CLIENT_ERROR  => 4XX
121           SERVER_ERROR  => 5XX
122           ERROR         => 4XX 5XX
123           ALL           => 1XX 2XX 3XX 4XX 5XX
124
125       And of course, you can load multiple aliased ranges
126
127           use HTTP::Exception qw(REDIRECTION ERROR)
128
129       ALL is the same as not specifying any specific range.
130
131           # the same
132           use HTTP::Exception qw(ALL);
133           use HTTP::Exception;
134

ACCESSORS (READONLY)

136   code
137       A valid HTTP-Statuscode. See HTTP::Status for information on what codes
138       exist.
139
140   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
145   is_success
146       Return TRUE if "$self-"code> is a Successful status code (2xx).
147
148   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
153   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
158   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
163   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
168       POD for is_ methods is Copy/Pasted from HTTP::Status, so check back
169       there and alert me of changes.
170

FIELDS

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
175           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
179           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
183       Catch them in your Webframework like this
184
185           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
191   status_message
192       DEFAULT The HTTP-Statusmessage as provided by HTTP::Status
193
194       A Message, that represents the Execptions' Status for Humans.
195

PLACK

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

COMPLETENESS

202       For the sake of completeness, HTTP::Exception provides exceptions for
203       non-error-http-statuscodes. This means you can do
204
205           HTTP::Exception->throw(200);
206
207       which throws an Exception of type OK. Maybe useless, but complete.  A
208       more realworld-example would be a redirection
209
210           # 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

CAVEATS

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
220       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
224       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

AUTHOR

230       Thomas Mueller, "<tmueller at cpan.org>"
231

SEE ALSO

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
238   HTTP::Status
239       Constants, Statuscodes and Statusmessages
240
241   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

BUGS

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

SUPPORT

257       You can find documentation for this module with the perldoc command.
258
259           perldoc HTTP::Exception
260
261       You can also look for information at:
262
263       •   RT: CPAN's request tracker
264
265           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTTP-Exception>
266
267       •   AnnoCPAN: Annotated CPAN documentation
268
269           <http://annocpan.org/dist/HTTP-Exception>
270
271       •   CPAN Ratings
272
273           <http://cpanratings.perl.org/d/HTTP-Exception>
274
275       •   Search CPAN
276
277           <https://metacpan.org/release/HTTP-Exception>
278
280       Copyright 2010 Thomas Mueller.
281
282       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
286       See http://dev.perl.org/licenses/ for more information.
287
288
289
290perl v5.34.0                      2022-01-21                HTTP::Exception(3)
Impressum