/ 
DTA-CAB-1.115
River stage zero No dependents
/ DTA::CAB::Server::HTTP::Handler

NAME

DTA::CAB::Server::HTTP::Handler - abstract handler API class for DTA::CAB::Server::HTTP

SYNOPSIS

##========================================================================
## PRELIMINARIES

use DTA::CAB::Server::HTTP::Handler;

##========================================================================
## API

$h = $class_or_obj->new(%options);
$bool = $h->prepare($server,$path);
$rsp = $h->run($server, $localPath, $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);

##========================================================================
## Handler class aliases (for derived classes)

undef = DTA::CAB::Server::HTTP::Handler->registerAlias($aliasName=>$fqClassName, ...);
$className_or_undef = DTA::CAB::Server::HTTP::Handler->fqClass($alias_or_class_suffix);

DESCRIPTION

DTA::CAB::Server::HTTP::Handler is a common base class and abstract API for request handlers used by DTA::CAB::Server::HTTP.

Subclasses

Currently supported subclasses include:

DTA::CAB::Server::HTTP::Handler::CGI

CAB HTTP Server: request handler: CGI form processing

DTA::CAB::Server::HTTP::Handler::Directory

CAB HTTP Server: request handler: directory

DTA::CAB::Server::HTTP::Handler::File

CAB HTTP Server: request handler: static file

DTA::CAB::Server::HTTP::Handler::Query

CAB HTTP Server: request handler: analyzer queries by CGI form

DTA::CAB::Server::HTTP::Handler::Response

CAB HTTP Server: request handler: static response

DTA::CAB::Server::HTTP::Handler::XmlRpc

CAB HTTP Server: request handler: XML-RPC queries (backwards-compatible)

API

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

Create a new handler. Default implementation just blesses \%options into the appropriate class.

prepare
$bool = $h->prepare($server,$path);

Perfvorm server-dependent initialization for handler $h as called by DTA::CAB::Server::HTTP $srv for path (string) $path. Should return true on success.

Default implementation just returns true.

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

Run the handler to respond to an HTTP::Request $httpRequest sent to the DTA::CAB::Server::HTTP object $server matching server path $localPath by the client socket $clientConn.

Should return a HTTP::Response object to pass to the client. If the method call die()s or returns undef, an error response will be sent 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.

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

Creates and returns a new HTTP::Response. $hdr may be a HTTP::Headers object, an array or hash-ref. Really just a wrapper for 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 $csock. Also logs the error at level ($h->{logError}||'error') 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) ; defualt=$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
)

Handler class aliases (for derived classes)

%ALIAS

Hash of fully qualified handler class names indexed by short alias names.

registerAlias
undef = DTA::CAB::Server::HTTP::Handler->registerAlias($aliasName=>$fqClassName, ...);

Registers an alias $aliasName for the handler class $fqClassName.

fqClass
$className_or_undef = DTA::CAB::Server::HTTP::Handler->fqClass($alias_or_class_suffix);

Returns a fully qualified class name for an alias or class suffix $alias_or_class_suffix.

AUTHOR

Bryan Jurish <moocow@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2010-2019 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.24.1 or, at your option, any later version of Perl 5 you may have available.

SEE ALSO

DTA::CAB::Server::HTTP(3pm), DTA::CAB::Server::HTTP::Handler::Builtin(3pm) DTA::CAB::Server::HTTP::Handler::CGI(3pm) DTA::CAB::Server::HTTP::Handler::Directory(3pm) DTA::CAB::Server::HTTP::Handler::File(3pm) DTA::CAB::Server::HTTP::Handler::Query(3pm) DTA::CAB::Server::HTTP::Handler::Response(3pm) DTA::CAB::Server::HTTP::Handler::XmlRpc(3pm) DTA::CAB(3pm), perl(1), ...