Class: Jamf::Pager

Inherits:
Object show all
Defined in:
lib/jamf/api/jamf_pro/other_classes/pager.rb

Overview

an object that performs a paged query for a pageable resource, possibly sorted and filtered. One of these is returned by class method .pager class method of CollectionResources the .change_log_pager method of ChangeLog resources

Constant Summary collapse

MIN_PAGE_SIZE =

Constants

1
MAX_PAGE_SIZE = 
2000
DEFAULT_PAGE_SIZE = 
100
PAGE_SIZE_RANGE = 
(MIN_PAGE_SIZE..MAX_PAGE_SIZE).freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(list_path:, page_size: DEFAULT_PAGE_SIZE, sort: nil, filter: nil, instantiate: nil, cnx: Jamf.cnx) ⇒ Pager 



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 144

def initialize(list_path:, page_size: DEFAULT_PAGE_SIZE, sort: nil, filter: nil, instantiate: nil, cnx: Jamf.cnx)
  validate_page_size(page_size)

  @cnx = cnx
  @list_path = list_path
  @sort = Jamf::Sortable.parse_url_sort_param(sort)
  @filter = Jamf::Filterable.parse_url_filter_param(filter)
  @page_size = page_size
  @instantiate = instantiate

  # start with page 0, the first page
  # This will be incremented and appended to the query path each time we call
  # next_page
  @next_page = 0

  @query_path = "#{@list_path}?page-size=#{@page_size}#{@sort}#{@filter}"

  # get one item which will contain the total count
  @total_count = cnx.jp_get("#{@query_path}?page-size=1&page=0#{@filter}")[:totalCount]
  # can't know total pages of filtered query
  @total_pages = @filter ? nil : (@total_count / @page_size.to_f).ceil
end

Instance Attribute Details

#cnx ⇒ Jamf::Connection (readonly) 



95
96
97
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 95

def cnx
  @cnx
end

#filter ⇒ String? (readonly) 



104
105
106
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 104

def filter
  @filter
end

#list_path ⇒ String (readonly) 



98
99
100
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 98

def list_path
  @list_path
end

#next_page ⇒ Integer (readonly) 



110
111
112
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 110

def next_page
  @next_page
end

#page_size ⇒ Integer (readonly) 



107
108
109
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 107

def page_size
  @page_size
end

#query_path ⇒ Object (readonly) 



114
115
116
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 114

def query_path
  @query_path
end

#sort ⇒ String? (readonly) 



101
102
103
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 101

def sort
  @sort
end

#total_count ⇒ Integer? (readonly) 



119
120
121
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 119

def total_count
  @total_count
end

#total_pages ⇒ Integer? (readonly) 



123
124
125
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 123

def total_pages
  @total_pages
end

Class Method Details

.all_pages(list_path:, sort: nil, filter: nil, instantiate: false, cnx: Jamf.cnx) ⇒ Type

Return all results from a pageable list path.

Since the JPAPI always returns results in pages of 2000, if there are more than that many in the collection we must loop through the pages to get them all.



69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 69

def self.all_pages(list_path:, sort: nil, filter: nil, instantiate: false, cnx: Jamf.cnx)
  sort &&= Jamf::Sortable.parse_url_sort_param(sort)
  filter &&= Jamf::Filterable.parse_url_filter_param(filter)

  pager = new(
    page_size: MAX_PAGE_SIZE,
    list_path: list_path,
    sort: sort,
    filter: filter,
    instantiate: instantiate,
    cnx: cnx
  )

  fetched_page = pager.fetch_next_page
  data = fetched_page
  until fetched_page.empty?
    fetched_page = pager.fetch_next_page
    data += fetched_page
  end
  data
end

Instance Method Details

#fetch_next_page ⇒ Array 



170
171
172
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 170

def fetch_next_page
  page @next_page, increment_next: true
end

#page(page_number, increment_next: false) ⇒ Array

Retrieve an arbitrary page of the result.

IMPORTANT: In the Jamf Pro API, page numbers are zero-based! The first page is 0, the second is 1, and so on. Asking for page 27 will give you the 28th page of results

If increment_next is true, then subsequent calls to #next_page will continue from whatever page number was requested.

When increment_next is false (the default), the sequence of pages returned by #next_page is unchanged, regardless of which page you return here.



207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 207

def page(page_number, increment_next: false)
  page_number = 0 if page_number == :first
  if page_number == :last
    raise Jamf::UnsupportedError, 'Cannot use :last with filtered queries' if @filter

    page_number = (@total_pages - 1)
  end

  validate_page_number page_number

  data = @cnx.jp_get "#{@query_path}&page=#{page_number}"
  data =
    if @instantiate
      data[:results].map { |r| @instantiate.new r }
    else
      data[:results]
    end

  @next_page = (page_number + 1) if increment_next
  data
end

#reset(to_page = 0) ⇒ Object

Reset the pager to start at a specific page (by default, the beginning) so that #fetch_next_page will start from there the next time it’s called.

Raises:

  • (ArgumentError) 


176
177
178
179
180
181
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 176

def reset(to_page = 0)
  to_page = 0 if to_page == :first
  raise ArgumentError, 'Page number must be an Integer 0 or higher' if !to_page.is_a?(Integer) || to_page.negative?

  @next_page = to_page
end