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

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

=head1 NAME

DiaColloDB::WWW::Handler - diachronic collocation db, www wrappers: abstract handler class API

=cut

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

=head1 SYNOPSIS

 ##========================================================================
 ## PRELIMINARIES
 
 use DiaColloDB::WWW::Handler;
 
 ##========================================================================
 ## API
 
 $h = $class_or_obj->new(%options);
 $bool = $h->prepare($server,$path);
 $rsp = $h->run($server, $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);
 

=cut

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

=head1 DESCRIPTION

DiaColloDB::WWW::Handler
is an abstract API for request handlers used by
L<DiaColloDB::WWW::Server|DiaColloDB::WWW::Server>.

=cut

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

=head2 Globals

=over 4

=item Variable: @ISA

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

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::Handler: API
=pod

=head2 API

=over 4

=item new

 $h = $class_or_obj->new(%options);

constructor.

=item run

 $rsp = $h->run($server, $clientConn, $httpRequest);

Handle a single request.
Parameters:

=over 4

=item $server

The server which received the request,
a L<DiaColloDB::WWW::Server|DiaColloDB::WWW::Server> object.

=item $clientConn

The client connect socket to which the response is to be sent.

=item $httpRequest

An L<HTTP::Request|HTTP::Request> object representing the
client request.

=back

The method should return a L<HTTP::Response|HTTP::Response>
object to be passed back to the client.
If the call die()s or returns C<undef>,
C<$server> should generate an appropriate error response
and send it 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 (C<$csock-E<gt>shutdown(2); $csock-E<gt>close()>)
and return C<undef> to prevent bogus error messages.


=item finish

 undef = $h->finish($server, $clientConn);

Clean up handler state after L<run()|/run>;
default implementation does nothing.

=back

=cut

##----------------------------------------------------------------
## DESCRIPTION: DiaColloDB::WWW::Handler: Generic Utilities
=pod

=head2 Generic Utilities

=over 4

=item headResponse

 $rsp = $h->headResponse();
 $rsp = $h->headResponse(\@headers);
 $rsp = $h->headResponse($httpHeaders);

Rudimentary handling for HEAD requests; always returns L<HTTP::Status::RC_OK|HTTP::Status>.

=item response

 $rsp = $CLASS_OR_OBJECT->response($code, $msg, $hdr, $content);

Generate an L<HTTP::Response|HTTP::Response> object with status code C<$code>,
status message C<$msg>, header(s) C<$hdr>, and (optional) content C<$content>.
C<$code> defaults to L<HTTP::Status::RC_OK|HTTP::Status>,
C<$msg> defaults to L<status_message($code)|HTTP::Status/status_message>,
adn C<$hdr> may be an L<HTTP::Headers|HTTP::Headers> object, an ARRAY-ref or a HASH-ref.
Wraps L<HTTP::Response-E<gt>new()|HTTP::Response>.

=item cerror

 undef = $h->cerror($csock, $status=RC_INTERNAL_SERVER_ERROR, @msg);

Creates an error response and sends it to the client socket;
also logs the error at level ($c-E<gt>{logError}||'warn') and shuts down the socket.


=item dumpResponse

 $rsp = $h->dumpResponse(\$contentRef, %opts);

Create and return a new data-dump response.
Known %opts:

 raw => $bool,      ##-- return raw data (text/plain) ; default=$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

=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::cgi(3pm)|DiaColloDB::WWW::Handler::cgi>,
L<DiaColloDB::WWW::Handler::static(3pm)|DiaColloDB::WWW::Handler::static>,
L<DiaColloDB::WWW::Server(3pm)|DiaColloDB::WWW::Server>,
L<perl(1)|perl>,
...



=cut
