.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DBD::Gofer::Transport::Base 3"
.TH DBD::Gofer::Transport::Base 3 "2013-06-25" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DBD::Gofer::Transport::Base \- base class for DBD::Gofer client transports
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  my $remote_dsn = "..."
\&  DBI\->connect("dbi:Gofer:transport=...;url=...;timeout=...;retry_limit=...;dsn=$remote_dsn",...)
.Ve
.PP
or, enable by setting the \s-1DBI_AUTOPROXY\s0 environment variable:
.PP
.Vb 1
\&  export DBI_AUTOPROXY=\*(Aqdbi:Gofer:transport=...;url=...\*(Aq
.Ve
.PP
which will force \fIall\fR \s-1DBI\s0 connections to be made via that Gofer server.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is the base class for all DBD::Gofer client transports.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Gofer transport attributes can be specified either in the attributes parameter
of the \fIconnect()\fR method call, or in the \s-1DSN\s0 string. When used in the \s-1DSN\s0
string, attribute names don't have the \f(CW\*(C`go_\*(C'\fR prefix.
.SS "go_dsn"
.IX Subsection "go_dsn"
The full \s-1DBI DSN\s0 that the Gofer server should connect to on your behalf.
.PP
When used in the \s-1DSN\s0 it must be the last element in the \s-1DSN\s0 string.
.SS "go_timeout"
.IX Subsection "go_timeout"
A time limit for sending a request and receiving a response. Some drivers may
implement sending and receiving as separate steps, in which case (currently)
the timeout applies to each separately.
.PP
If a request needs to be resent then the timeout is restarted for each sending
of a request and receiving of a response.
.SS "go_retry_limit"
.IX Subsection "go_retry_limit"
The maximum number of times an request may be retried. The default is 2.
.SS "go_retry_hook"
.IX Subsection "go_retry_hook"
This subroutine reference is called, if defined, for each response received where \f(CW$response\fR\->err is true.
.PP
The subroutine is pass three parameters: the request object, the response object, and the transport object.
.PP
If it returns an undefined value then the default retry behaviour is used. See \*(L"\s-1RETRY ON ERROR\*(R"\s0 below.
.PP
If it returns a defined but false value then the request is not resent.
.PP
If it returns true value then the request is resent, so long as the number of retries does not exceed \f(CW\*(C`go_retry_limit\*(C'\fR.
.SH "RETRY ON ERROR"
.IX Header "RETRY ON ERROR"
The default retry on error behaviour is:
.PP
.Vb 1
\& \- Retry if the error was due to DBI_GOFER_RANDOM. See L<DBI::Gofer::Execute>.
\&
\& \- Retry if $request\->is_idempotent returns true. See L<DBI::Gofer::Request>.
.Ve
.PP
A retry won't be allowed if the number of previous retries has reached \f(CW\*(C`go_retry_limit\*(C'\fR.
.SH "TRACING"
.IX Header "TRACING"
Tracing of gofer requests and responses can be enabled by setting the
\&\f(CW\*(C`DBD_GOFER_TRACE\*(C'\fR environment variable. A value of 1 gives a reasonably
compact summary of each request and response. A value of 2 or more gives a
detailed, and voluminous, dump.
.PP
The trace is written using \s-1DBI\-\s0>\fItrace_msg()\fR and so is written to the default
\&\s-1DBI\s0 trace output, which is usually \s-1STDERR.\s0
.SH "METHODS"
.IX Header "METHODS"
\&\fIThis section is currently far from complete.\fR
.SS "response_retry_preference"
.IX Subsection "response_retry_preference"
.Vb 1
\&  $retry = $transport\->response_retry_preference($request, $response);
.Ve
.PP
The response_retry_preference is called by DBD::Gofer when considering if a
request should be retried after an error.
.PP
Returns true (would like to retry), false (must not retry), undef (no preference).
.PP
If a true value is returned in the form of a \s-1CODE\s0 ref then, if DBD::Gofer does
decide to retry the request, it calls the code ref passing \f(CW$retry_count\fR, \f(CW$retry_limit\fR.
Can be used for logging and/or to implement exponential backoff behaviour.
Currently the called code must return using \f(CW\*(C`return;\*(C'\fR to allow for future extensions.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tim Bunce, <http://www.tim.bunce.name>
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright (c) 2007\-2008, Tim Bunce, Ireland. All rights reserved.
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
DBD::Gofer, DBI::Gofer::Request, DBI::Gofer::Response, DBI::Gofer::Execute.
.PP
and some example transports:
.PP
DBD::Gofer::Transport::stream
.PP
DBD::Gofer::Transport::http
.PP
DBI::Gofer::Transport::mod_perl