GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  HTTP::EXCEPTION (3)

.ds Aq ’

NAME

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

CONTENTS

VERSION

version 0.04006

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 } # wont 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 } # catchem 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 doesnt 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 <B>WITHOUTB> 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; # wont 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 => "Everythings fine");
    HTTP::Exception::200->new(status_message => "Everythings fine");
    HTTP::Exception::OK->new(status_message => "Everythings fine");

    HTTP::Exception->throw(200, status_message => "Everythings fine");
    HTTP::Exception::200->throw(status_message => "Everythings fine");
    HTTP::Exception::OK->throw(status_message => "Everythings fine");



Catch them in your Webframework like this



    eval { ... }
    if (my $e = HTTP::Exception->caught) {
        print $e->code;          # 200
        print $e->status_message # "Everythings fine" instead of the usual ok
    }



    status_message

<B>DEFAULTB> 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:
o RT: CPAN’s request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=HTTP-Exception>

o AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/HTTP-Exception>

o CPAN Ratings

<http://cpanratings.perl.org/d/HTTP-Exception>

o 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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 HTTP::EXCEPTION (3) 2014-02-13

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.