Bio::D...bAgent(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 Bio::DB::GenericWebAgent 💖

okay bestie, gather round, because we're looking at Bio::DB::GenericWebAgent — a helper base class for parameter-based remote server access and response retrieval. she's the backstage crew, not the main character, but nothing works without her. periodt. 💅

✨ 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

like, literally do not touch her directly, she's a base class. go look at Bio::DB::EUtilities if you want to see how this is actually done. 🫶

🦋 DESCRIPTION 🦋

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

no cap, this is the number one rule. be polite to the servers, they are doing their best. 🙈

so Bio::DB::GenericWebAgent is a generic wrapper around three things, and honestly it's giving project manager:

  • a web agent (LWP::UserAgent)
  • an object that can retain, format, and build parameters for the user agent (Bio::ParameterBaseI)
  • a BioPerl class parser that processes response content received by the user agent

and here's the smart part — the Bio::ParameterBaseI object should be state-aware, meaning it knows when changes happen to its parameters, so that identical requests don't get sent to the server over and over again. this base class takes that into consideration, because she's thoughtful like that. 💖

💌 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, fr fr. 🥹

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. there are so many experienced and responsive experts there who will look at the problem and quickly address it — iconic behaviour honestly. please include a thorough description of the problem with code and data examples if at all possible, it helps so much. ✨

🐛 Reporting Bugs

report bugs to the Bioperl bug tracking system to help us keep track of 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 _ (iykyk, that underscore means stay back, this is house business). 🌈

⭐ 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.

make a shiny new Bio::DB::GenericWebAgent instance. note that Returns is just… blank, she gives you nothing back and that's fine. 🎀 and the args? nothing specific to this base class. inheriting classes will likely set their own specific parameters in their constructor, because Bio::DB::GenericWebAgent is primarily a test bed. she's the practice arena, not the final boss. 💀

🧚 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

get or set the Bio::ParameterBaseI. you hand her a Bio::ParameterBaseI object, she hands one back. balanced. 🫶

💜 ua

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

get or set the LWP::UserAgent. same deal, she holds the user agent so you don't have to. ✨

💜 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

this is the one that actually goes and gets the HTTP::Response object, by passing it an HTTP::Request (generated from a Bio::ParameterBaseI implementation). you get back an HTTP::Response object — or just data, if a callback is in play.

the args are optional, here's the tea:

  • -cache_response — flag to cache the HTTP::Response object. Default is 1 (TRUE, caching ON). she remembers things, slay. 🔥
  • these get 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. pick one bestie, you cannot have both. 😭
    • -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

returns the HTTP::Response content (file, fh, object) attached to the defined parser. she returns nothing, takes nothing — she's abstract, defined by the implementation. main character energy with zero lines, honestly. 👑

💜 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

get or set how many seconds to delay between fetches. she returns the number of seconds to delay, and you can feed her a 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

returns how many seconds to delay between calls to the remote db. no args, she just tells you.

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. she's approximate and she's honest about it. 🕐

💜 _sleep

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

sleeps for however many seconds the delay policy says. returns nothing, takes nothing. 😴

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. she's not going to nap if she doesn't need to, that's just efficient. 💅

🍓 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)

get or set a proxy, and she returns a string indicating the proxy. the 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 the proxy requires authentication)
  • $password — password (if the 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

get or set the authentication credentials. she returns an array of user/pass, and you can hand her an array or user/pass. locked in. 🔐

and that's the whole page, bestie!! 🎀💖✨

cute little sign-off for the record: this was documented as perl v5.32.1, dated 2021-08-15, and the page you're reading is Bio::D...bAgent(3pm). go forth and not spam any web servers. 🦋🫶

📦 where this page comes from