A Treequel::Control module that implements the “LDAP Control Extension for Simple Paged Results Manipulation” (RFC 2696).

== Usage

As with all Controls, you must first register the control with the Treequel::Directory object you're intending to search:

dir = Treequel.directory( 'ldap://ldap.acme.com/dc=acme,dc=com' ) dir.register_controls( Treequel::PagedResultsControl )

Once that's done, any Treequel::Branchset you create will have the

#with_paged_results method that will allow you to specify the number¶ ↑

of results you wish to be returned per “page”:

# Fetch people in pages people = dir.ou( :People ) paged_people = people.filter( :objectClass => :person ).with_paged_results( 25 )

The Branchset will also respond to has_more_results?, which will be true while there are additional pages to be fetched, or before the search has taken place:

# Display each set of 25, waiting for keypress between each set while paged_people.has_more_results? # do something with this set of 25 people… end

Constants

DEFAULT_PAGE_SIZE: The default number of results per page
OID: The control's OID

Attributes

paged_results_cookie[RW]: The (opaque) cookie value that will be sent to the server on the next search.
paged_results_setsize[RW]: The number of results per page

Public Class Methods

anchor

new()

Add the control's instance variables to including Branchsets.

# File lib/treequel/controls/pagedresults.rb, line 49
def initialize
        @paged_results_cookie = nil
        @paged_results_setsize = nil
end

Public Instance Methods

anchor

done_paging?()

Returns true if results have yet to be fetched, or if they have all been fetched.

# File lib/treequel/controls/pagedresults.rb, line 110
def done_paging?
        return self.paged_results_cookie == ''
end

anchor

each( &block )

Override the Enumerable method to update the cookie value each time a page is fetched.

# File lib/treequel/controls/pagedresults.rb, line 117
def each( &block )
        super do |branch|
                if paged_control = branch.controls.find {|control| control.oid == OID }
                        returned_size, cookie = paged_control.decode
                        self.log.debug "Paged control in result with size = %p, cookie = %p" %
                                [ returned_size, cookie ]
                        self.paged_results_cookie = cookie
                else
                        self.log.debug "No paged control in results. Setting cookie to ''."
                        self.paged_results_cookie = ''
                end

                block.call( branch )
        end
end

anchor

has_more_results?()

Returns true if the first page of results has been fetched and there are more pages remaining.

# File lib/treequel/controls/pagedresults.rb, line 103
def has_more_results?
        return true unless self.done_paging?
end

anchor

with_paged_results( setsize=DEFAULT_PAGE_SIZE )

Clone the Branchset with a paged results control with paging set to setsize.

# File lib/treequel/controls/pagedresults.rb, line 67
def with_paged_results( setsize=DEFAULT_PAGE_SIZE )
        self.log.warn "This control will likely not work in ruby-ldap versions " +
                " <= 0.9.9. See http://code.google.com/p/ruby-activeldap/issues/" +
                "detail?id=38 for details." if LDAP::PATCH_VERSION < 10

        newset = self.clone

        if setsize.nil? || setsize.zero?
                self.log.debug "Removing paged results control."
                newset.paged_results_setsize = nil
        else
                self.log.debug "Adding paged results control with page size = %d." % [ setsize ]
                newset.paged_results_setsize = setsize
        end

        return newset
end

anchor

without_paging()

Clone the Branchset without paging and return it.

# File lib/treequel/controls/pagedresults.rb, line 87
def without_paging
        copy = self.clone
        copy.without_paging!
        return copy
end

anchor

without_paging!()

Remove any paging control associated with the receiving Branchset.

# File lib/treequel/controls/pagedresults.rb, line 95
def without_paging!
        self.paged_results_cookie = nil
        self.paged_results_setsize = nil
end

Protected Instance Methods

anchor

get_server_controls()

Treequel::Control API – Get the set of server controls currently configured for the receiver.

# File lib/treequel/controls/pagedresults.rb, line 140
def get_server_controls
        controls = super
        if pagesize = self.paged_results_setsize && self.paged_results_setsize.nonzero?
                self.log.debug "Setting up paging for sets of %d" % [ pagesize ]
                value = LDAP::Control.encode( pagesize.to_i, self.paged_results_cookie.to_s )
                controls << LDAP::Control.new( OID, value, true )
        else
                self.log.debug "No paging for this %p; not adding the PagedResults control" %
                        [ self.class ]
        end

        return controls
end