|$request = Bio::Das::Request->new(-dsn=>$dsn,-args=>$args,-callback=>$callback)||
Create a new Bio::Das::Request objects. The <B>-dsnB> argument points
to the DAS DSN (full form, including hostname). <B>-callbackB> points
to an optional coderef that will be invoked for every object returned
during execution of the request. <B>-argsB> 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 objects 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:
|@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.|
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:
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.
Lincoln Stein <firstname.lastname@example.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.
Bio::Das::Request, Bio::Das::HTTP::Fetch, Bio::Das::Segment, Bio::Das::Type, Bio::Das::Stylesheet, Bio::Das::Source, Bio::RangeI
|perl v5.20.3||DAS::REQUEST (3)||2010-06-16|