NAME
   HTTP::Exception - throw HTTP-Errors as (Exception::Class-) Exceptions

VERSION
   version 0.04005

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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.