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), ...