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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
	   # 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
	   $iter->reset;

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

DESCRIPTION
       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 isbndb.com 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
       Methods are broken in the following groups:

   Constructor
       new($ARGS)
	   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
	   Methods".

	   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:

       first
	   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.

       next
	   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
	   "search".

       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
	   returns.

       reset
	   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.

       fetch_next_page
	   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:

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

       page_size
	   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.

       page_number
	   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.

       shown_results
	   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.

       contents
	   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.

       request_args
	   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.

       index
	   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.

       agent
	   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.

       fetch_page_hook
	   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:

       get_total_results
       get_page_size
       get_page_number
       get_shown_results
       get_contents
       get_request_args
       get_index
       get_agent
	   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_fetch_page_hook($HOOK)
	   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_fetch_page_hook
	   Get the current hook	value, if any.

SEE ALSO
       WebService::ISBNDB::API,	Class::Std

AUTHOR
       Randy J.	Ray <rjray@blackperl.com>

LICENSE
       This module and the code	within are released under the terms of the
       Artistic	License	2.0
       (http://www.opensource.org/licenses/artistic-license-2.0.php). This
       code may	be redistributed under either the Artistic License or the GNU
       Lesser General Public License (LGPL) version 2.1
       (http://www.opensource.org/licenses/lgpl-license.php).

perl v5.24.1			  2017-07-03   WebService::ISBNDB::Iterator(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SEE ALSO | AUTHOR | LICENSE

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

home | help