Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Das::Request(3)	      User Contributed Perl Documentation      Das::Request(3)

NAME
       Bio::Das::Request - Base	class for a request on a DAS server

SYNOPSIS
	my $dsn			 = $request->dsn;
	my $das_command		 = $request->command;
	my $successful		 = $request->is_success;
	my $error_msg		 = $request->error;
	my @results		 = $request->results;
	my ($username,$password) = $request->auth;

DESCRIPTION
       Each type of request on a DAS server (e.g. an entry_points request) is
       a subclass of Bio::Das::Request.	 The request encapsulates the
       essential information on	the request: the server, the data source, and
       the command that	will be	executed.  After the request is	sent to	the
       server, the request object will contain information pertinent to	the
       outcome of the request, including the success status, the results if
       successful, and an error	message	if not successful.

       Subclasses of Bio::Das::Request include Bio::Das::Request::Dsn,
       Bio::Das::Request::Entry_points,	Bio::Das::Request::Features,
       Bio::Das::Request::Stylesheet, and Bio::Das::Request::Types.

       Creating	the appropriate	request	is done	automatically by Bio::Das.
       Ordinarily you will not have to create a	Bio::Das::Request manually.

   METHODS
       Following is a complete list of methods implemented by
       Bio::Das::Request.

       $request	=
       Bio::Das::Request->new(-dsn=>$dsn,-args=>$args,-callback=>$callback)
	   Create a new	Bio::Das::Request objects.  The	-dsn argument points
	   to the DAS DSN (full	form, including	hostname).  -callback points
	   to an optional coderef that will be invoked for every object
	   returned during execution of	the request.  -args points to a
	   hashref containing request-specific arguments.

	   This	method is trivially overridden by many of the request
	   subclasses in order to accept arguments that	are specific to	each
	   of the requests, such as -segments.

       $command	= $request->command
	   The command() method	returns	the DAS	command	that will be invoked.
	   This	varies from subclass to	subclass.  For example,
	   Bio::Das::Request::Types->command() will return "types."

       $url = $request->url
	   Return the URL for the request on the DAS server.

       $dsn = $request->dsn([$new_dsn])
	   Get the DAS DSN associated with the request.	 This method is	also
	   used	internally to change the DSN.

       $host = $request->host
	   Returns the host associated with the	request.  This is simply
	   delegated to	the DSN	object's host()	method.

       $flag = $request->is_success
	   After the request is	executed, is_success() will return true	if the
	   request was successfully issued and parsed, false otherwise.	 If
	   false, you can retrieve an informative error	message	using the
	   error() method.

       $message	= $request->error
	   If the request was unsuccessful, error() will return	an error
	   message.  In	the case of a successful request, the result of
	   error() is undefined	and should not be relied on.

	   Error messages have the format "NNN XXXXXXXX" where "NNN" is	a
	   numeric status code,	and XXXXXXX is a human-readable	error message.
	   The following error messages	are possible:

		  400 Bad command
		  401 Bad data source
		  402 Bad command arguments
		  403 Bad reference object
		  404 Bad stylesheet
		  405 Coordinate error
		  410 Unknown host
		  411 Couldn't connect
		  412 Communications error
		  413 Authentication scheme 'xxxx" is not supported
		  500 Server error
		  501 Unimplemented feature
		  502 No X-Das-Version header
		  503 Invalid X-Das-Version header
		  504 DAS server is too	old
		  505 No X-Das-Status header
		  506 Data decompression failure

       @results	= $request->results
	   In a	list context this method returns the accumulated results from
	   the DAS request. The	contents of the	results	list is	dependent on
	   the particular request, and you should consult each of the
	   subclasses to see what exactly is returned.

	   In a	scalar context,	this method will return	an array reference.

       ($username,$password) = $request->auth([$username,$password])
	   Get or set the username and password	that will be used for
	   authentication in this request.  This is used internally by the
	   Bio::Das::HTTP::Fetch class and should not ordinarily be
	   manipulated by application code.

       $parser = $request->create_parser()
	   This	method creates an HTML::Parser object that will	be used	to
	   parse the incoming XML data.	 Ordinarily this will not be called by
	   application code.

       $request->tag_starts
	   This	method is called internally during the parse to	handle a start
	   tag.	 It should not be called by application	code.

       $request->tag_stops
	   This	method is called internally during the parse to	handle a stop
	   tag.	 It should not be called by application	code.

       $request->do_tag
	   This	method is called internally during the parse to	handle a tag.
	   It should not be called by application code,	but can	be overridden
	   by a	subclass to provide tag-specific processing.

       $request->char_data
	   This	method is called internally during the parse to	handle
	   character data.  It should not be called by application code.

       $request->cleanup
	   This	method is called internally at the end of the parse to handle
	   any cleanup that is needed.	The default behavior is	to do nothing,
	   but it can be overridden by a subclass to provide more
	   sophisticated processing.

       $request->clear_results
	   This	method is called internally at the start of the	parse to clear
	   any accumulated results and to get ready for	a new parse.

       $request->add_objects(@objects)
	   This	method is called internally during the parse to	add one	or
	   more	objects	(e.g. a	Bio::Das::Feature) to the results list.

       $parser = $request->xml_parser([$new_parser])
	   Internal accessor for getting or setting the	XML parser object used
	   in processing the request.

       $flag = $request->compressed([$new_flag])
	   Internal accessor for getting or setting the	compressed data	stream
	   flag.  This is true when processing a compressed data stream, such
	   as GZIP compression.

       $flag = $request->success([$new_flag])
	   Internal accessor for getting or setting the	success	flag.  This is
	   the read/write version of is_success(), and should not be used by
	   application code.

       $callback = $request->callback([$new_callback])
	   Internal accessor for getting or setting the	callback code that
	   will	be used	to process objects as they are generated by the	parse.

       $args = $request->args([$new_args])
	   Internal accessor for getting or setting the	CGI arguments that
	   will	be passed to the DAS server.  The arguments are	a hashref in
	   which the keys and values correspond	to the CGI parameters.
	   Multivalued CGI parameters are represented as array refs.

       $method = $request->method
	   This	method can be overridden by subclasses to force	the
	   Bio::Das::HTTP::Fetch object	to use a particular HTTP request
	   method.  Possible values that this method can return	are "AUTO",
	   "GET" or "POST."  The base class returns a value of "AUTO,"
	   allowing the	Bio::Das::HTTP::Fetch object to	choose the most
	   appropriate request method.

       $request->headers($das_header_data)
	   The headers() method	is called internally to	parse the HTTP headers
	   returned by the DAS server.	The data is a hashref in which the
	   keys	and values correspond to the HTTP headers and their values.

       $request->start_body()
	   This	internal method	is called by Bio::Das::HTTP::Fetch upon	first
	   encountering	the DAS	document body data.  The method	calls
	   create_parser() to create the appropriately-initialized
	   HTML::Parser	object and stores it internally	using the xml_parser()
	   accessor.

       $request->body($data)
	   This	internal method	is called by Bio::Das::HTTP::Fetch to process
	   each	chunk of DAS document data. The	data is	processed
	   incrementally in multiple steps until the end of document is
	   reached.

       $request->finish_body()
	   This	internal method	is called by Bio::Das::HTTP::Fetch when	the
	   end of document is encountered.

       ($inflated_data,$status)	= $request->inflate($data)
	   This	internal method	is called when processing compressed data.  It
	   returns a two-element list consisting of the	inflated data and a
	   true/false status code.  A false status code	means an error was
	   encountered during inflation, and ordinarily	causes the parsing to
	   terminate.

       $trimmed_string = $request->trim($untrimmed_string)
	   This	internal method	strips leading and trailing whitespace from a
	   string.

   The Parsing Process
       This module and its subclasses use an interesting object-oriented way
       of parsing XML documents	that is	flexible without imposing a large
       performance penalty.

       When a tag start	or tag stop is encountered, the	tag and	its attributes
       are passed to the tag_starts() and tag_stops() methods respectively.
       These methods both look for a defined method called t_TAGNAME (where
       TAGNAME is replaced by the actual name of the tag).  If the method
       exists it is invoked, otherwise the tag and attribute data are passed
       to the do_tag() method, which by	default	simply ignores the tag.

       A Bio::Das::Request subclass that wishes	to process the <FOOBAR>	tag,
       can therefore define a method called t_FOOBAR which takes two
       arguments, the request object and the tag attribute hashref.  The
       method can distinguish between <FOOBAR> and </FOOBAR> by	looking	at the
       attribute argument, which will be defined for the start tag and undef
       for the end tag.	 Here is a simple example:

	 sub t_FOOBAR {
	   my $self	  = shift;
	   my $attributes = shift;
	   if ($attributes) {
	      print "FOOBAR is starting	with the attributes ",join(' ',%$attributes),"\n";
	   } else {
	      print "FOOBAR is ending\n";
	   }
	 }

       The Bio::Das::Request::Dsn subclass is a	good example of	a simple
       parser that uses	t_TAGNAME methods exclusively.
       Bio::Das::Request::Stylesheet is	an example of a	parser that also
       overrides do_tag() in order to process unanticipated tags.

AUTHOR
       Lincoln Stein <lstein@cshl.org>.

       Copyright (c) 2001 Cold Spring Harbor Laboratory

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See DISCLAIMER.txt	for
       disclaimers of warranty.

SEE ALSO
       Bio::Das::Request, Bio::Das::HTTP::Fetch, Bio::Das::Segment,
       Bio::Das::Type, Bio::Das::Stylesheet, Bio::Das::Source, Bio::RangeI

perl v5.32.0			  2010-06-16		       Das::Request(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Bio::Das::Request&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help