NAME

HTTP::Response::Tree - Class for a tree of multiple HTTP::Response objects

SYNOPSIS

use HTTP::Response::Tree;

@responses = $tree->descendants;

@responses = $tree->children;

$tree->max_depth([$depth]);

$response = $tree->member($uri);

$tree->add_child($response[,$uri]);

$ref = $tree->cat_all_content([$mime_type]);

DESCRIPTION

This class organizes collections of HTTP::Response objects. It is meant to be convenient to robots that collect related Web pages together. There is also a basic method, cat_all_content(), that may be convenient to robots that need to analyze collected content in aggregate form.

The "tree" structure is very simple. The root object of the tree may be accessed directly, and any descendant may be accessed by calling the root's member() method with the descendant's URI. Also, all descendants within a tree can be enumerated, and so can the immediate children of the tree's root. The methods of each HTTP::Response object within the tree can be accessed as usual.

METHODS

HTTP::Response::Tree is, as its name implies, a subclass of HTTP::Response, and therefore inherits all of its methods. Note that calling an HTTP::Response method directly on the tree (e.g. $tree->content) returns the result for the HTTP::Response object at the tree's root only. If you need to access the method for a specific descendant in the tree, but a reference to that descendant is not (yet) available, use the member() method (e.g. $tree->member($uri)->content).

Here are the methods new to HTTP::Response::Tree:

@responses = $tree->descendants

Enumerates all of the HTTP::Response objects in the tree that are descendants of the root, and returns them in an array.

@responses = $tree->children

Enumerates all of the HTTP::Response objects that are the immediate children of the root, and returns them in an array. To return all descendants of the root and not just the immediate children, use descendants().

$tree->max_depth([$depth])

Sets or returns the maximum depth of the tree. New instances of HTTP::Response::Tree are initialized with a max_depth of 3. 0 means the tree may not be any deeper than the root (essentially no more useful than an HTTP::Response object), 1 means the root may have children but no grandchildren, etc.

This is meant as a convenience to robots (such as crawlers) that use HTTP::Response::Tree to collect multiple objects from a starting point, but need to be kept from straying too far from the starting point. Calls to add_child() that exceed the max_depth limit will return undef.

$response = $tree->member($uri)

Provides access to the HTTP::Response object in the tree with the given URI, or undef if there is no such object. $uri may be a string or an object of type URI; canonization/normalization of the URI is unnecessary.

$tree->add_child($response[,$uri])

Add a new child to the tree. It must be an instance of HTTP::Response (or HTTP::Response::Tree, or anything that inherits from HTTP::Response). If $uri is not given, a new child of the root is added. Otherwise, a child of the descendant with the given URI is added. $uri may be a string or an object of type URI; canonization/normalization is unnecessary. This returns undef on failure (e.g. an object with that URI already exists, or the tree's max_depth would be exceeded).

$ref = $tree->cat_all_content([$mime_type])

Concatenates the content of a selection of objects in the tree, and returns a reference to the resulting string. $mime_type is a string to specify a filter for the type of content to be extracted from the tree; if not specified, it will default to "text/*". (That value is the only one likely to make sense anyway, as the results with any other content type will probably be very messy.)

NOTES

Each HTTP::Response::Tree is constructed recursively as a collection of other HTTP::Response::Tree objects. Therefore, if you create a new class that inherits from this one, be careful overriding or extending add_child(), descendants(), and member(), in particular. (See also "BUGS".)

BUGS

If you create a new class that inherits from HTTP::Response::Tree, the children created with add_child() will still be HTTP::Response::Tree objects.

AUTHOR

Larry Gilbert <larry@n2h2.com>

COPYRIGHT

Copyright 2002 N2H2, Inc. All rights reserved.