NAME

HTTP::Response::Switch::Handler - handle one specific type of HTTP::Response

VERSION

This module is part of distribution HTTP-Response-Switch v1.1.1.

This distribution's version numbering follows the conventions defined at semver.org.

SYNOPSIS

A handler that handles an "expected" response:

    package MyProject::PageHandler::RawDataPage;
    use Moose;
    with 'HTTP::Response::Switch::Handler';

    sub handle {
        my $self = shift;

        # Each handler should only deal with one concern; let other
        # handlers deal with other things.
        $self->decline
            if $self->response->headers->content_type ne 'text/csv';

        # This response holds something that this handler can handle.
        return STRUCTURED_DATA_FROM( $self->response->content );
    }

A handler that handles an "unexpected" or undesired response:

    package MyProject::PageHandler::RawDataForm;
    use Moose;
    with 'HTTP::Response::Switch::Handler';

    sub handle {
        my $self = shift;
        $self->decline
            if NOT_A_RAW_DATA_FORM( $self->response->content );

        # If the web server is providing a form, there's a problem with
        # user data.  Extract the errors and throw an exception.
        die MyProject::Error::UserDataProblem->new(
            errors => EXTRACT_ERRORS_FROM( $self->response->content ),
        );
    }

DESCRIPTION

A "handler" class holds the logic to identify one particular type of HTTP::Response that might be returned by a web application, and perform an appropriate action like:

• parsing the page and returning structured data; or

• throwing a specific exception in the case of specific "unexpected" or undesired web server responses.

These "handler" classes are called upon by a "dispatcher" class, which is responsible for delegating a response to the correct handlers in the correct order.

METHODS TO DEFINE IN CONSUMING CLASSES

These methods must be defined in order for the consuming class to work.

handle

    my %structured_data = $instance->handle;
    my @structured_data = $instance->handle;
    my $structured_data = $instance->handle;

Obtain the "response" object and "decline" to analyse it if it doesn't concern this handler. Otherwise, return some sort of structured data or throw a specific exception as appropriate.

The specific type of data to return, if any, depends entirely on what the caller wants.

If this method returns without error (even if it returns nothing), it is deemed to have successfully handled the response and subsequent handlers will not be invoked by the dispatcher.

METHODS AVAILABLE WITHIN CONSUMING CLASSES

These methods are intended only to be called on a consuming class by that class itself, and not by code external to the class.

response

    my $http_response = $self->response;

The HTTP::Response object to analyse.

decline

    $self->decline if NOT_MY_TYPE( $self->response );

Indicate that this particular handler cannot handle this particular "response". This is done by throwing an HTTP::Response::Switch::HandlerDeclinedResponse exception, which prevents further execution of the handler from occurring.

SEE ALSO

• HTTP::Response::Switch

• HTTP::Response::Switch::HandlerDeclinedResponse

AUTHOR

Alex Peters <lxp@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Alex Peters.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

The full text of the license can be found in the 'LICENSE' file included with this distribution.

cpanm HTTP::Response::Switch

perl -MCPAN -e shell
install HTTP::Response::Switch