Module: Treequel::PagedResultsControl

Includes:
Control
Defined in:
lib/treequel/controls/pagedresults.rb

Overview

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

Constant Summary collapse

OID =

The control’s OID

'1.2.840.113556.1.4.319'
DEFAULT_PAGE_SIZE =

The default number of results per page

100

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Control

#get_client_controls

Instance Attribute Details

The (opaque) cookie value that will be sent to the server on the next search.



64
65
66
 
# File 'lib/treequel/controls/pagedresults.rb', line 64

def paged_results_cookie
  @paged_results_cookie
end

#paged_results_setsize ⇒ Object

The number of results per page



61
62
63
 
# File 'lib/treequel/controls/pagedresults.rb', line 61

def paged_results_setsize
  @paged_results_setsize
end

Instance Method Details

#done_paging? ⇒ Boolean

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

Returns:

  • (Boolean) 


111
112
113
 
# File 'lib/treequel/controls/pagedresults.rb', line 111

def done_paging?
  return self.paged_results_cookie == ''
end

#each(&block) ⇒ Object

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



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/treequel/controls/pagedresults.rb', line 118

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

#has_more_results? ⇒ Boolean

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

Returns:

  • (Boolean) 


104
105
106
 
# File 'lib/treequel/controls/pagedresults.rb', line 104

def has_more_results?
  return true unless self.done_paging?
end

#initialize ⇒ Object

Add the control’s instance variables to including Branchsets.



50
51
52
53
 
# File 'lib/treequel/controls/pagedresults.rb', line 50

def initialize
  @paged_results_cookie = nil
  @paged_results_setsize = nil
end

#with_paged_results(setsize = DEFAULT_PAGE_SIZE) ⇒ Object

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



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/treequel/controls/pagedresults.rb', line 68

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

#without_paging ⇒ Object

Clone the Branchset without paging and return it.



88
89
90
91
92
 
# File 'lib/treequel/controls/pagedresults.rb', line 88

def without_paging
  copy = self.clone
  copy.without_paging!
  return copy
end

#without_paging! ⇒ Object

Remove any paging control associated with the receiving Branchset.



96
97
98
99
 
# File 'lib/treequel/controls/pagedresults.rb', line 96

def without_paging!
  self.paged_results_cookie = nil
  self.paged_results_setsize = nil
end