NAME

       Bio::DB::GenericWebAgent - helper base class for parameter-based remote server access and
       response retrieval.

SYNOPSIS

         # DO NOT USE DIRECTLY

         See Bio::DB::EUtilities for an example implementation

DESCRIPTION

       WARNING: Please do NOT spam the web servers with multiple requests.

       Bio::DB::GenericWebAgent is a generic wrapper around a web agent (LWP::UserAgent), an
       object which can retain, format, and build parameters for the user agent
       (Bio::ParameterBaseI), and a BioPerl class parser that processes response content received
       by the user agent. The Bio::ParameterBaseI object should be state-aware, e.g. know when
       changes occur to parameters, so that identical requests are not repeatedly sent to the
       server (this base class takes this into consideration).

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to one of the Bioperl mailing lists. Your
       participation is much appreciated.

         bioperl-l@lists.open-bio.org               - General discussion
         http://bioperl.org/Support.html  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their
       resolution.  Bug reports can be submitted via the web.

         https://github.com/bioperl/bioperl-live/issues

AUTHOR

       Email cjfields at bioperl dot org

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

   new
        Title   : new
        Usage   : Bio::DB::GenericWebAgent->new(@args);
        Function: Create new Bio::DB::GenericWebAgent instance.
        Returns :
        Args    : None specific to this base class.  Inheriting classes will
                  likely set specific parameters in their constructor;
                  Bio::DB::GenericWebAgent is primarily a test bed.

GenericWebAgent methods

   parameter_base
        Title   : parameter_base
        Usage   : $dbi->parameter_base($pobj);
        Function: Get/Set Bio::ParameterBaseI.
        Returns : Bio::ParameterBaseI object
        Args    : Bio::ParameterBaseI object

   ua
        Title   : ua
        Usage   : $dbi->ua;
        Function: Get/Set LWP::UserAgent.
        Returns : LWP::UserAgent
        Args    : LWP::UserAgent

   get_Response
        Title   : get_Response
        Usage   : $agent->get_Response;
        Function: Get the HTTP::Response object by passing it an HTTP::Request (generated from
                  Bio::ParameterBaseI implementation).
        Returns : HTTP::Response object or data if callback is used
        Args    : (optional)

                  -cache_response - flag to cache HTTP::Response object;
                                    Default is 1 (TRUE, caching ON)

                  These are passed on to LWP::UserAgent::request() if stipulated

                  -cb     - use a LWP::UserAgent-compliant callback
                  -file   - dumps the response to a file (handy for large responses)
                            Note: can't use file and callback at the same time
                  -read_size_hint - bytes of content to read in at a time to pass to callback
        Note    : Caching and parameter checking are set

   get_Parser
        Title   : get_Parser
        Usage   : $agent->get_Parser;
        Function: Return HTTP::Response content (file, fh, object) attached to defined parser
        Returns : None
        Args    : None
        Note    : Abstract method; defined by implementation

   delay
        Title   : delay
        Usage   : $secs = $self->delay($secs)
        Function: get/set number of seconds to delay between fetches
        Returns : number of seconds to delay
        Args    : new value

       NOTE: the default is to use the value specified by delay_policy().  This can be overridden
       by calling this method.

   delay_policy
        Title   : delay_policy
        Usage   : $secs = $self->delay_policy
        Function: return number of seconds to delay between calls to remote db
        Returns : number of seconds to delay
        Args    : none

       NOTE: The default delay policy is 3s.  Override in subclasses to implement delays.  The
       timer has only second resolution, so the delay will actually be +/- 1s.

   _sleep
        Title   : _sleep
        Usage   : $self->_sleep
        Function: sleep for a number of seconds indicated by the delay policy
        Returns : none
        Args    : none

       NOTE: This method keeps track of the last time it was called and only imposes a sleep if
       it was called more recently than the delay_policy() allows.

LWP::UserAgent related methods

   proxy
        Title   : proxy
        Usage   : $httpproxy = $db->proxy('http')  or
                  $db->proxy(['http','ftp'], 'http://myproxy' )
        Function: Get/Set a proxy for use of proxy
        Returns : a string indicating the proxy
        Args    : $protocol : an array ref of the protocol(s) to set/get
                  $proxyurl : url of the proxy to use for the specified protocol
                  $username : username (if proxy requires authentication)
                  $password : password (if proxy requires authentication)

   authentication
        Title   : authentication
        Usage   : $db->authentication($user,$pass)
        Function: Get/Set authentication credentials
        Returns : Array of user/pass
        Args    : Array or user/pass