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

Returns a new instance of Pager.

Parameters:

  • list_path (String) —

    The Resource URL path that provides the paged query results

  • page_size (Integer) (defaults to: DEFAULT_PAGE_SIZE) —

    How many items to return per page

  • sort (String) (defaults to: nil) —

    The optional sort parameter for the query

  • filter (String) (defaults to: nil) —

    The optional RSQL filter parameter for the query

  • instantiate (Class) (defaults to: nil) —

    Instantiate the results as the given class by passing the raw JSON data to the class’ .new method

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    The Connection object used for the query. Defaults to the Default connection



154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 154

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 ||= DEFAULT_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("#{@list_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)

Returns The Connection object used for the query.

Returns:



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

def cnx
  @cnx
end

#filter ⇒ String? (readonly)

Returns The optional filter parameter for the query.

Returns:

  • (String, nil) —

    The optional filter parameter for the query



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

def filter
  @filter
end

#last_fetched_page ⇒ nil, Integer (readonly)

Returns The most recent page number fetched by fetch_next_page, or nil if it hasn’t been called yet.

Returns:

  • (nil, Integer) —

    The most recent page number fetched by fetch_next_page, or nil if it hasn’t been called yet.



117
118
119
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 117

def last_fetched_page
  @last_fetched_page
end

#list_path ⇒ String (readonly)

Returns The Resource URL path that provides the paged query results.

Returns:

  • (String) —

    The Resource URL path that provides the paged query results



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

def list_path
  @list_path
end

#next_page ⇒ Integer (readonly)

Returns The page which will be returned when fetch_next_page is called.

Returns:

  • (Integer) —

    The page which will be returned when fetch_next_page is called



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

def next_page
  @next_page
end

#page_size ⇒ Integer (readonly)

Returns How many items to return per page.

Returns:

  • (Integer) —

    How many items to return per page



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

def page_size
  @page_size
end

#query_path ⇒ Object (readonly)

Returns [] The full r#source URL, with page_size, sort, and filter, but without the ‘page’ parameter.

Returns:

  • The full r#source URL, with page_size, sort, and filter, but

    without the ‘page’ parameter



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

def query_path
  @query_path
end

#sort ⇒ String? (readonly)

Returns The optional sort parameter for the query,.

Returns:

  • (String, nil) —

    The optional sort parameter for the query,



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

def sort
  @sort
end

#total_count ⇒ Integer? (readonly)

How many items are there in total? NOTE: this does not apply any given filter, which might reduce the number of items returned by a pager.

Returns:

  • (Integer, nil) —

    How many items are there in total? NOTE: this does not apply any given filter, which might reduce the number of items returned by a pager.



129
130
131
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 129

def total_count
  @total_count
end

#total_pages ⇒ Integer? (readonly)

Returns How many pages needed to retrieve the total_count? nil if using a filter, since that may return fewer than the total count.

Returns:

  • (Integer, nil) —

    How many pages needed to retrieve the total_count? nil if using a filter, since that may return fewer than the total count.



133
134
135
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 133

def total_pages
  @total_pages
end

Class Method Details

.all_pages(list_path:, sort: nil, filter: nil, instantiate: nil, cnx: Jamf.cnx) ⇒ Array<Hash,Jamf::OAPIObject>

Return all results from a pageable list path.

Pageable resources are always returned in pages, usually defaulting to 100 items per page, but the max allowed page size is 2000. If there are more than 2000 items, we must loop through the pages to get them all.

This method is used to get all pages of data from a giving path, automatically looping through the pages and collecting the data to be returned in a single Array. It uses a Pager object to do that, but the Pager itself is transient, only the resulting Array is returned.

Parameters:

  • list_path (String) —

    The Resource URL path that provides the paged query results

  • sort (String) (defaults to: nil) —

    The optional sort parameter for the query

  • filter (String) (defaults to: nil) —

    The optional RSQL filter parameter for the query

  • instantiate (Class) (defaults to: nil) —

    Instantiate the results as the given class by passing the raw JSON data to the class’ .new method. WARNING: Be sure the data returned from the API is appropriate for instantiating this class.

  • cnx (Jamf::Connection) (defaults to: Jamf.cnx) —

    The API connection to use, default: Jamf.cnx

Returns:

  • (Array<Hash,Jamf::OAPIObject>) —

    All of the pages of data, returned as one array, optionally instantiated into a subclass of Jamf::OAPIObject.



75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 75

def self.all_pages(list_path:, sort: nil, filter: nil, instantiate: nil, 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

Returns The next page of the collection, i.e. whichever page is indicated in the next_page attribute.

Returns:

  • (Array) —

    The next page of the collection, i.e. whichever page is indicated in the next_page attribute.



180
181
182
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 180

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 #fetch_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.

Parameters:

  • number (Integer, Symbol) —

    Which page to retrieve. The Symbols :first and :last will work as expected. Otherwise, the zero-based page number is needed. Will return an empty array if greater than the total number of pages in the query result

  • increment_next (Boolean) (defaults to: false) —

    should the next_page value be reset to the page number plus 1? This makes #fetch_next_page continue from this one.

Returns:

  • (Array) —

    The desired page of the result, containing up to #page_size items. Will be empty if the page is greater than the total available.



217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 217

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 = data[:results]
  data.map! { |r| @instantiate.new r } if @instantiate

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

  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) 


186
187
188
189
190
191
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 186

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