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

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.