METHODS

$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

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.