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

FreeBSD Manual Pages


home | help
WebService::ISBNDB::ItUseroContributed Perl DocWebService::ISBNDB::Iterator(3)

       WebService::ISBNDB::Iterator - Iterator class for large result-sets

	   # The search() method of API-derived	classes	returns	an Iterator
	   $iter = WebService::ISBNDB::API->search(Books =>
						   { author =>
						    'poe_edgar_allan' });

	   print $iter->get_total_results, " books found.\n";
	   while ($book	= $iter->next)
	       print $book->get_title, "\n";

	   # Reset the iterator

	   # Do	something else with all	the elements found by the search
	   for ($iter->all)

       This class provides an iterator object to abstract the results from a
       search.	Searches may return anywhere from no matches to	thousands.
       Besides the fact	that trying to allocate	all of that data at once could
       overwhelm system	memory,	the service returns data in
       "pages",	rather than risk sending an overwhelming response.

       The iterator stores information about the initial request, and as the
       user progresses past the	in-memory slice	of data, it makes subsequent
       requests	behind the scenes to refresh the data until the	end of the
       results-set is reached.

       It is not expected that users will manually create iterators. Iterators
       will be created as needed by the	"search" method	in the API classes.

       Methods are broken in the following groups:

	   The constructor is based on the Class::Std model. The argument it
	   takes is a hash-reference whose key/value pairs are attribute names
	   and values. The attributes are defined below, in "Accessor

	   The only required attributes	in the arguments list are
	   "request_args" and "contents". The first is the set of arguments
	   used	in the initial request made to the service. They are reused
	   when	subsequent pages need to be fetched. The second	is the initial
	   set of objects, fetched from	the first page of results.

   Iterator Methods
       These methods are the general-use interface between the user and	the
       iterator.  In most cases, an application	will only need to use the
       methods listed here:

	   Return the first element in the results-set.	Regardless of the
	   current position within the iterator, this is always	the very first
	   element (or "undef",	if there were no elements found	by the
	   search). This does not alter	the position of	the internal pointer,
	   or trigger any additional requests to the data source.

	   Return the next element off the iterator, or	"undef"	if the
	   iterator is exhausted. All elements returned	by an iterator descend
	   from	WebService::ISBNDB::API. All elements in a given iterator will
	   always be from the same implementation class. The iterator does not
	   explicitly identify the class of the	objects, since the application
	   had to have had some	degree of knowledge before making the call to

       all Returns the full set	of results from	the iterator, from the
	   beginning to	the end	(if the	iterator has already been read some
	   number of times, it is reset	before the list	is constructed). The
	   return value	is the list of elements	when called in a list-context,
	   or a	list-reference of the elements when called in a	scalar
	   context. The	iterator will be in an exhausted state after this

	   Resets the internal counter within the iterator to the beginning of
	   the list.  This allows the iterator to be re-used when and if the
	   user	desires.

	   When	a request (via next()) goes past the internal set of data,
	   this	method is called to request the	next page of results from the
	   data	source,	until the last page has	been read. This	method alters
	   the "page_number", "contents" and "shown_results" attributes. If
	   the user has	set a hook (via	set_fetch_page_hook()),	it is called
	   with	the arguments for the request just prior to the	request
	   itself. The arguments are those provided in the "request_args"
	   attribute, plus a "page_number" argument set	to the page that is
	   being requested.

   Accessor Methods
       The accessor methods provide access to the internal attributes of the
       object.	These attributes are:

	   The total number of results in the result-set, not to be confused
	   with	the number of results currently	in memory.

	   The size of the "page" returned by the data source, in turn the
	   maximum number of elements held internally by the iterator at any
	   given time. As the index proceeds to	the end	of the in-memory list,
	   a new page is fetched and this many new elements replace the
	   previous set	internally.

	   The number of the page of results currently held within the
	   iterator. When the iterator fetches a new page, this	is
	   incremented.	When the iterator is reset, this is set	to 1.

	   The number of results currently held	within the iterator. When the
	   last	page of	a results-set is fetched, it may have fewer than
	   "page_size" elements	in it. This attribute will always identify the
	   number of elements currently	kept internally.

	   The list reference used internally to store the current set of
	   objects for the page	of results held	by the iterator. Be careful
	   with	this value, as changing	its contents can change	the internal
	   state of the	iterator.

	   The hash reference that stores the original request arguments used
	   to fetch the	initial	page of	data from the data source. This	is
	   used	to make	any additional requests	for subsequent pages, as
	   needed. Be careful with the value, as changing its contents can
	   affect the iterator's ability to fetch further pages.

	   The integer value that marks	the current position within the
	   iterator. The value is the position within the whole	set of
	   results, not	just within the	single page held internally.

	   The WebService::IDBNDB::Agent instance that is used to fetch
	   additional pages as needed. It is generally set at object-
	   construction	time by	the API	object that creates the	iterator. If
	   it is not specified in the constructor, the "get_default_agent"
	   method of WebService::ISBNDB::API is	called.

	   If this attribute has a value that is a code-reference, the code-
	   reference is	invoked	with the arguments that	are going to be	passed
	   to the "request" method of the "agent". The hook (or	callback) will
	   receive the iterator	object referent	and the	hash-reference of
	   arguments, as if it had been	called as a method in this class. The
	   arguments are those stored in "request_args"	as well	as one
	   additional argument,	"page_number", containing the number of	the
	   page	being requested.

	   Note	that the hook will not be called for the first page fetched
	   from	the data source. That is because that fetch is done outside
	   the scope of	the iterator class, and	the data from that initial
	   fetch is provided when the iterator is constructed.

       Note that for most of the attributes, only the "get" accessor is
       documented.  Users should not need to manually set any of the
       attributes (except for "fetch_page_hook") unless	they are sub-classing
       this class:

	   Return the relevant attribute's value. Note,	again, that
	   get_contents() and get_request_args() return	the actual reference
	   value used internally. Changes to the contents of those reference
	   values may impact the behavior of the iterator itself.

	   Set a hook (callback) to be called each time	the iterator has to
	   fetch a new page from the data source. The value is a code-
	   reference, and is called with the iterator object and a hash-
	   reference of	the request arguments as parameters. Any return	value
	   is ignored. If the hook dies, an exception is thrown	by
	   fetch_next_page() with the error message.

	   Get the current hook	value, if any.

       WebService::ISBNDB::API,	Class::Std

       Randy J.	Ray <>

       This module and the code	within are released under the terms of the
       Artistic	License	2.0
       ( This
       code may	be redistributed under either the Artistic License or the GNU
       Lesser General Public License (LGPL) version 2.1

perl v5.32.0			  2020-08-25   WebService::ISBNDB::Iterator(3)


Want to link to this manual page? Use this URL:

home | help