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) —

    Should the results be instantiated as the given class?

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

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



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)

Returns The Connection object used for the query.

Returns:



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

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



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

def filter
  @filter
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



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)

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

Returns:

  • (Integer) —

    The page which will be returned when next_page is called



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)

Returns How many items to return per page.

Returns:

  • (Integer) —

    How many items to return per page



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)

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



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

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,



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

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.



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)

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.



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.

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 (Boolean) (defaults to: false) —

    Defaults to false. Should the items in the returned Array(s) be ruby instances of the CollectionObject subclass, or plain Hashes of data as returned by the API?

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

    The API connection to use, default: Jamf.cnx

Returns:

  • (Type) —

    description_of_returned_object



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

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.



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.

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.



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