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