NAME

DiaColloDB::WWW::Server - diachronic collocation db, www wrappers: rudimentary standalone http server

SYNOPSIS

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

use DiaColloDB::WWW::Server;

##========================================================================
## Constructors etc.

$srv = $CLASS_OR_OBJECT->new(%args);

##========================================================================
## Methods: Generic Server API

$rc = $srv->prepare();
$rc = $srv->prepareSignalHandlers();
$rc = $srv->prepareLocal(@args_to_prepare);
$rc = $srv->run();
$rc = $srv->finish();

##========================================================================
## Methods: Local: spawn and reap

\&reaper = $srv->reaper();
undef = $srv->reapClient($csock, $handler_or_undef, $chost_or_undef);

##========================================================================
## Methods: Local: path handlers

$handler = $srv->getPathHandler($hreq_uri);
$type_or_undef = $srv->mimetype($filename);
$sub = $srv->handle_ttk($uri_path,$ttk_path);
$sub = $srv->handle_raw($file_path);

##========================================================================
## Methods: Local: error handling

undef = $srv->clientError($clientSock,$status,@message);

DESCRIPTION

DiaColloDB::WWW::Server implements a rudimentary standalone HTTP server providing a simple web-service API and user interface for local DiaColloDB diachronic collocation index directories, including various online visualization modes. See dcdb-www-server.perl(1) for the top-level script.

Globals

Variable: @ISA

DiaColloDB::WWW::Server inherits from DiaColloDB::Logger.

Constructors etc.

new

$srv = $that->new(%args);

%args, %$srv:

##-- user data (REQUIRED)
wwwdir     => $wwwdir,        ##-- root directory for www wrapper data (default=File::ShareDir::dist_dir("DiaColloDB-WWW")."/htdocs"
dbdir      => $dbdir,         ##-- local DiaColloDB index directory
##
##-- underlying HTTP::Daemon server
daemonMode => $daemonMode,    ##-- one of 'serial' or 'fork' [default='serial']
daemonArgs => \%daemonArgs,   ##-- args to HTTP::Daemon->new(); default={LocalAddr=>'0.0.0.0',LocalPort=>6066}
daemon     => $daemon,        ##-- underlying HTTP::Daemon object
cgi        => $dbcgi,         ##-- DiaColloDB::WWW::CGI object for handling CGI requests
cgiArgs    => \%cgiArgs,      ##-- args to DiaColloDB::WWW::CGI->new(); default=none
mimetypes  => $mt,            ##-- a MIME::Types object for guessing mime types
##
##-- logging
logAttempt => $level,        ##-- log connection attempts at $level (default='trace')
logConnect => $level,        ##-- log successful connections (client IP and requested path) at $level (default='debug')
logRquestData => $level,     ##-- log full client request data at $level (default='trace')
logResponse => $level,       ##-- log full client response at $level (default='trace')
logClientError => $level,    ##-- log errors to client at $level (default='debug')
logClose => $level,          ##-- log close client connections (default='trace')

Methods: Generic Server API

prepare

$rc = $srv->prepare();

Prepare static server data prior to running; default implementation initializes logger.

prepareSignalHandlers

$rc = $srv->prepareSignalHandlers();

initialize signal handlers (really only interesting for threaded servers).

prepareLocal

$rc = $srv->prepareLocal(@args_to_prepare);

subclass-local initialization, called by prepare() after default prepare() guts have run.

run

$rc = $srv->run();

runs the actual main server loop; never returns in the usual case.

finish

$rc = $srv->finish();

cleanup method; should be called when server dies or after run() has completed.

Methods: Local: spawn and reap

reaper

\&reaper = $srv->reaper();

zombie-harvesting code; installed to local %SIG

reapClient

undef = $srv->reapClient($csock, $handler_or_undef, $chost_or_undef);

closes down the connection to client $csock, calls $handler->finish() to shutdown the handler if defined.

Methods: Local: path handlers

getPathHandler

$handler = $srv->getPathHandler($hreq_uri);

returns a DiaColloDB::WWW::Handler object for handling the request URI $hreq_uri.

mimetype

$type_or_undef = $srv->mimetype($filename);

Gets and returns the stringified MIME-type for $filename via MIME::Types::mimeTypeOf().

Methods: Local: error handling

clientError

undef = $srv->clientError($clientSock,$status,@message);

sends an error message to the client and closes it down; $status defaults to HTTP::Status::RC_INTERNAL_SERVER_ERROR.

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(3pm), DiaColloDB(3pm), perl(1), ...