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



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 137

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:



84
85
86
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 84

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



93
94
95
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 93

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.



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

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



87
88
89
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 87

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



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

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



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

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



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

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,



90
91
92
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 90

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.



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

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.



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

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.



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 58

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.



163
164
165
 
# File 'lib/jamf/api/jamf_pro/other_classes/pager.rb', line 163

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.



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

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]

  if @instantiate
    data.map! do |r|
      r[:cnx] = @cnx
      @instantiate.new(**r)
    end
  end

  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) 


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

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