/ 
Net-LDAP-Class-0.27
River stage zero No dependents
/ Net::LDAP::Class::Iterator

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:

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