NAME

DiaColloDB::WWW::Handler - diachronic collocation db, www wrappers: abstract handler class API

SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::WWW::Handler;
 
 ##========================================================================
 ## API
 
 $h = $class_or_obj->new(%options);
 $bool = $h->prepare($server,$path);
 $rsp = $h->run($server, $clientConn, $httpRequest);
 undef = $h->finish($server, $clientConn);
 
 ##========================================================================
 ## Generic Utilities
 
 $rsp = $h->headResponse();
 $rsp = $CLASS_OR_OBJECT->response($code=RC_OK, $msg=status_message($code), $hdr, $content);
 undef = $h->cerror($csock, $status=RC_INTERNAL_SERVER_ERROR, @msg);
 $rsp = $h->dumpResponse(\$contentRef, %opts);
 

DESCRIPTION

DiaColloDB::WWW::Handler is an abstract API for request handlers used by DiaColloDB::WWW::Server.

Globals

Variable: @ISA

DiaColloDB::WWW::Handler inherits from DiaColloDB::Logger.

API

new

 $h = $class_or_obj->new(%options);

constructor.

run

 $rsp = $h->run($server, $clientConn, $httpRequest);

Handle a single request. Parameters:

$server

The server which received the request, a DiaColloDB::WWW::Server object.

$clientConn

The client connect socket to which the response is to be sent.

$httpRequest

An HTTP::Request object representing the client request.

The method should return a HTTP::Response object to be passed back to the client. If the call die()s or returns undef, $server should generate an appropriate error response and send it to the client instead if it the connection is still open.

This method may return the data to the client itself; if so, it should close the client connection ($csock->shutdown(2); $csock->close()) and return undef to prevent bogus error messages.

finish

 undef = $h->finish($server, $clientConn);

Clean up handler state after run(); default implementation does nothing.

Generic Utilities

headResponse

 $rsp = $h->headResponse();
 $rsp = $h->headResponse(\@headers);
 $rsp = $h->headResponse($httpHeaders);

Rudimentary handling for HEAD requests; always returns HTTP::Status::RC_OK.

response

 $rsp = $CLASS_OR_OBJECT->response($code, $msg, $hdr, $content);

Generate an HTTP::Response object with status code $code, status message $msg, header(s) $hdr, and (optional) content $content. $code defaults to HTTP::Status::RC_OK, $msg defaults to status_message($code), adn $hdr may be an HTTP::Headers object, an ARRAY-ref or a HASH-ref. Wraps HTTP::Response->new().

cerror

 undef = $h->cerror($csock, $status=RC_INTERNAL_SERVER_ERROR, @msg);

Creates an error response and sends it to the client socket; also logs the error at level ($c->{logError}||'warn') and shuts down the socket.

dumpResponse

 $rsp = $h->dumpResponse(\$contentRef, %opts);

Create and return a new data-dump response. Known %opts:

 raw => $bool,      ##-- return raw data (text/plain) ; default=$h->{returnRaw}
 type => $mimetype, ##-- mime type if not raw mode
 charset => $enc,   ##-- character set, if not raw mode
 filename => $file, ##-- attachment name, if not raw mode

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Bryan Jurish

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.14.2 or, at your option, any later version of Perl 5 you may have available.

SEE ALSO

DiaColloDB::WWW::Handler::cgi(3pm), DiaColloDB::WWW::Handler::static(3pm), DiaColloDB::WWW::Server(3pm), perl(1), ...