##========================================================================
## POD DOCUMENTATION, auto-generated by podextract.perl

##========================================================================
## NAME
=pod

=head1 NAME

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

=cut

##========================================================================
## SYNOPSIS
=pod

=head1 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);
 

=cut

##========================================================================
## DESCRIPTION
=pod

=head1 DESCRIPTION

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

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::Server: globals
=pod

=head2 Globals

=over 4

=item Variable: @ISA

DiaColloDB::WWW::Server inherits from
L<DiaColloDB::Logger|DiaColloDB::Logger>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::Server: constructors etc.
=pod

=head2 Constructors etc.

=over 4

=item 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')

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::Server: Methods: Generic Server API
=pod

=head2 Methods: Generic Server API

=over 4

=item prepare

 $rc = $srv->prepare();

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

=item prepareSignalHandlers

 $rc = $srv->prepareSignalHandlers();

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

=item prepareLocal

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

subclass-local initialization, called by L<prepare()|/prepare> after
default prepare() guts have run.

=item run

 $rc = $srv->run();

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

=item finish

 $rc = $srv->finish();

cleanup method; should be called when server dies or after L<run()|/run> has completed.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::Server: Methods: Local: spawn and reap
=pod

=head2 Methods: Local: spawn and reap

=over 4

=item reaper

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

zombie-harvesting code; installed to local %SIG

=item reapClient

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

closes down the connection to client C<$csock>,
calls L<$handler-E<gt>finish()|DiaColloDB::WWW::Handler/finish> to shutdown
the handler if defined.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::Server: Methods: Local: path handlers
=pod

=head2 Methods: Local: path handlers

=over 4

=item getPathHandler

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

returns a L<DiaColloDB::WWW::Handler|DiaColloDB::WWW::Handler>
object for handling the request L<URI|URI> C<$hreq_uri>.

=item mimetype

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

Gets and returns the stringified MIME-type for $filename via L<MIME::Types::mimeTypeOf()|MIME::Types/mimeTypeOf>.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::Server: Methods: Local: error handling
=pod

=head2 Methods: Local: error handling

=over 4

=item clientError

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

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

=back

=cut

##========================================================================
## END POD DOCUMENTATION, auto-generated by podextract.perl

##======================================================================
## Footer
##======================================================================
=pod

=head1 AUTHOR

Bryan Jurish E<lt>moocow@cpan.orgE<gt>

=head1 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.

=head1 SEE ALSO

L<DiaColloDB::WWW::Handler(3pm)|DiaColloDB::WWW::Handler>,
L<DiaColloDB(3pm)|DiaColloDB>,
L<perl(1)|perl>,
...



=cut
