Net::LDAP::Class::Iterator(3)

NAME
Net::LDAP::Class::Iterator - iterate over Net::LDAP::Class objects

SYNOPSIS
 my $iterator = $user->groups_iterator;
 while ( my $group = $iterator->next ) {
    # $group isa Net::LDAP::Class::Group
 }
 printf("%d groups found\n", $iterator->count);

DESCRIPTION
Net::LDAP::Class::Iterator handles paged searching using Net::LDAP::Control::Paged.

ITERATORS vs ARRAYS
Many of the relationship methods in Net::LDAP::Class get and set arrays or array refs of related objects. For small (<1000) data sets arrays are just fine but as data sets scale, different techniques become necessary. An iterator has a big resource advantage over an array: instead of holding all the related objects in memory at once, as an array does, an iterator reads one object at a time from the LDAP server.

For example, if you want to look at all the users who are members of a group, and the number of users is large (>1000), some LDAP servers (Active Directory in particular) won't return all of your user objects in a single query. Instead, the results must be paged using Net::LDAP::Control::Paged. You'll see the evidence of this if you call the following code against Active Directory with a group of more than 1000 users.

 my $group = MyADGroup->new( cn => 'myBigGroup', ldap => $ldap )->read;
 my $users = $group->users;  # bitten by AD! returns an empty array ref!
 foreach my $user (@$users) {
   # nothing here -- the array is empty
 }

The call to $group->users returns an empty array because Active Directory refuses to return more than 1000 results at a time. (NOTE the number 1000 is the default maximum; your server may be configured differently.)

So an iterator to the rescue!

 my $users = $group->users_iterator;
 while ( my $user = $users->next ) {
    # do something with $user
 }
 printf("We saw %d users in group %s\n", $users->count, $group->name);

You might ask, why bother with arrays at all if iterators are so great. The answer is convenience. For small data sets, arrays are convenient, especially if you intend to do things with subsets of them at a time. Of course, you could do this:

 my $users = $group->users_iterator;
 my @allusers;
 while ( my $user = $users->next ) {
     push @allusers, $user;
 }

But then you've negated one of the advantages of the iterator: it is less resource-intensive. But hey, if you've got the memory, honey, Perl's got the time.

METHODS

  ldap
Accessor for Net::LDAP object. Set in new().

  base_dn
Required in new().

  page_size
The size of the Net::LDAP::Control::Paged set. Default is 500. Set in new().

  filter
The search filter to use. Set in new().

  class
The class to bless results into. Set in new().

  init
Checks that alll required params are defined and sets up the pager.

  count
Returns the number of iterations performed.

  is_exhausted
Returns true (1) if all the results for this iterator have been seen, false (0) otherwise.

  next
Returns the next Net::LDAP::Class object from the pager. Returns undef if no more results are found.

  finish
Tell the server you're done iterating over results. This method is only necessary if you stop before exhausting all the results.

AUTHOR
Peter Karman, "<karman at cpan.org>"

BUGS
Please report any bugs or feature requests to "bug-net-ldap-class at rt.cpan.org", or through the web interface at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-LDAP-Class>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT
You can find documentation for this module with the perldoc command.

    perldoc Net::LDAP::Class

You can also look for information at:

•   AnnoCPAN: Annotated CPAN documentation

    <http://annocpan.org/dist/Net-LDAP-Class>

•   CPAN Ratings

    <http://cpanratings.perl.org/d/Net-LDAP-Class>

•   RT: CPAN's request tracker

    <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-LDAP-Class>

•   Search CPAN

    <http://search.cpan.org/dist/Net-LDAP-Class>

COPYRIGHT
Copyright 2009 by Peter Karman.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO
Net::LDAP, Net::LDAP::Batch