Net::LDAP::Class::Iterator - iterate over Net::LDAP::Class objects
my $iterator = $user->groups_iterator; while ( my $group = $iterator->next ) { # $group isa Net::LDAP::Class::Group } printf("%d groups found\n", $iterator->count);
Net::LDAP::Class::Iterator handles paged searching using Net::LDAP::Control::Paged.
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.
Accessor for Net::LDAP object. Set in new().
Required in new().
The size of the Net::LDAP::Control::Paged set. Default is 500. Set in new().
The search filter to use. Set in new().
The class to bless results into. Set in new().
Checks that alll required params are defined and sets up the pager.
Returns the number of iterations performed.
Returns true (1) if all the results for this iterator have been seen, false (0) otherwise.
Returns the next Net::LDAP::Class object from the pager. Returns undef if no more results are found.
Tell the server you're done iterating over results. This method is only necessary if you stop before exhausting all the results.
Peter Karman, <karman at cpan.org>
<karman at cpan.org>
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.
bug-net-ldap-class at rt.cpan.org
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 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.
Net::LDAP, Net::LDAP::Batch
To install Net::LDAP::Class, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::LDAP::Class
CPAN shell
perl -MCPAN -e shell install Net::LDAP::Class
For more information on module installation, please visit the detailed CPAN module installation guide.