ruby-jss 1.3.3 → 1.6.0b1

data/lib/jamf/api/{resources/collection_resources/computer.rb → mixins/filterable.rb}

@@ -1,5 +1,4 @@
 # Copyright 2020 Pixar
-
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in
@@ -23,27 +22,30 @@
 #
 #
 
-# The Module
 module Jamf
 
-  # Classes
-  #####################################
-
-  # A building defined in the JSS
-  class Computer < Jamf::CollectionResource
+  # process filter strings for resources with filter request parameters
+  module Filterable
 
-    # Mix-Ins
-    #####################################
-    include Jamf::Referable
+    # # When this is included
+    # def self.included(klass)
+    #   puts "Filterable was included by #{klass}"
+    # end
+    #
+    # # When this is exdended
+    # def self.extended(klass)
+    #   puts "Filterable was extended by #{klass}"
+    # end
 
-    # Constants
-    #####################################
+    private
 
-    RSRC_PATH = 'inventory/obj/computer'.freeze
+    # generate the RSQL filter to put into the url
+    def parse_collection_filter(filter)
+      return if filter.nil?
 
-    OBJECT_MODEL = {}.freeze
-    parse_object_model
+      "&filter=#{CGI.escape filter}"
+    end
 
-  end # class
+  end # Filterable
 
-end # module
+end # Jamf

data/lib/jamf/api/mixins/pageable.rb

@@ -0,0 +1,208 @@
+# Copyright 2020 Pixar
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+module Jamf
+
+  # methods for dealing with paged collection GET requests
+  #
+  module Pageable
+
+    # # When This is included
+    # def self.included(klass)
+    #   puts "Pageable was included by #{klass}"
+    # end
+    #
+    # # When this is exdended
+    # def self.extended(klass)
+    #   puts "Pageable was extended by #{klass}"
+    # end
+
+    DFT_PAGE_SIZE = 100
+
+    MIN_PAGE_SIZE = 1
+
+    MAX_PAGE_SIZE = 2000
+
+    PAGE_SIZE_RANGE = (MIN_PAGE_SIZE..MAX_PAGE_SIZE).freeze
+
+    # @param rsrc [String] The collection resource GET endpoint
+    #
+    # @param cnx [Jamf::Connection] The API connection to use
+    #
+    # @return [Integer] How many items exist in this collection?
+    #
+    def collection_count(rsrc, cnx: Jamf.cnx)
+      # this should only be true for instances of CollectionResources
+      cnx = @cnx if @cnx
+      cnx.get("#{rsrc}?page=0&page-size=1")[:totalCount]
+    end
+
+    # Get a specific page of a paged collection request,
+    # possibly sorted & filtered.
+    #
+    # @param rsrc [String] The collection resource GET endpoint
+    #
+    # @param page [Integer] which page to get
+    #
+    # @param page_size [Integer] how many items per page
+    #
+    # @param sort [String,Array<String>] server-side sorting parameters
+    #
+    # @param filter [String] RSQL String limiting the result set
+    #
+    # @param cnx [Jamf::Connection] The API connection to use
+    #
+    # @return [Array<Object>] The parsed JSON for the requested page
+    #
+    def fetch_collection_page(rsrc, page, page_size, sort, filter, cnx: Jamf.cnx)
+      page_size ||= DFT_PAGE_SIZE
+      validate_page_params page_size, page
+      raw = cnx.get "#{rsrc}?page=#{page}&page-size=#{page_size}#{sort}#{filter}"
+
+      raw[:results]
+    end
+
+    ################### Private methods
+    private
+
+    # get the first page of a paged collection, and set up for
+    # getting later pages
+    #
+    # @param rsrc [String] The collection resource GET endpoint
+    #
+    # @param page_size [Integer] how many items per page
+    #
+    # @param sort [String,Array<String>] server-side sorting parameters
+    #
+    # @param filter [String] RSQL String limiting the result set
+    #
+    # @param cnx [Jamf::Connection] The API connection to use
+    #
+    # @return [Array<Object>] The first page of the collection for this resource
+    #
+    def first_collection_page(rsrc, page_size, sort, filter, cnx)
+      page_size ||= DFT_PAGE_SIZE
+      validate_page_params page_size
+
+      @collection_rsrc_path = rsrc
+      @collection_cnx = cnx
+      @collection_page = :first
+      @collection_page_size = page_size
+      @collection_sort = sort
+      @collection_filter = filter
+      @collection_paged_fetched_count = 0
+
+      next_collection_page
+    end
+
+    # Fetch the next page of a paged collection request.
+    #
+    # Returns an empty array if there's been no paged request
+    # or if the last one has no more pages.
+    #
+    # @return [Array<Object>] The next page of the collection for this resource
+    #
+    def next_collection_page
+      case @collection_page
+      when :first
+        @collection_page = 0
+      when Integer
+        @collection_page += 1
+      else
+        # if here, we haven't initiated a paged request, or
+        # all pages have already been delivered
+        return []
+      end
+
+      raw = @collection_cnx.get "#{@collection_rsrc_path}?page=#{@collection_page}&page-size=#{@collection_page_size}#{@collection_sort}#{@collection_filter}"
+
+      @collection_paged_fetched_count += raw[:results].size
+      @collection_paged_total_count = raw[:totalCount]
+
+      # did we get everything in the this page?
+      # if so, clear all the paging data
+      clear_collection_paging_data if @collection_paged_fetched_count >= @collection_paged_total_count
+
+      # return the page results
+      raw[:results]
+    end
+
+    def clear_collection_paging_data
+      @collection_rsrc_path = nil
+      @collection_cnx = nil
+      @collection_sort = nil
+      @collection_filter = nil
+      @collection_page = nil
+      @collection_page_size = nil
+      @collection_paged_total_count = nil
+      @collection_paged_fetched_count = nil
+    end
+
+    # ensure valid page && page_size
+    #
+    # @param page_size [Integer] the page_size to be validated, must be in range
+    #
+    # @param page [Integer] the page number requested, must be >= 0
+    #
+    # @return [void]
+    #
+    def validate_page_params(page_size, page = nil)
+      raise ArgumentError, "page_size must be an Integer from #{MIN_PAGE_SIZE} to #{MAX_PAGE_SIZE}" unless PAGE_SIZE_RANGE.include? page_size
+
+      # if page is nil, ignore it, one of the auto paging methods is calling us
+      return if page.nil?
+
+      raise ArgumentError, 'page must be an Integer zero or higher' unless page.is_a?(Integer) && page > -1
+    end
+
+    # Description of #fetch_all_collection_pages
+    #
+    # @param rsrc [String] The collection resource GET endpoint
+    #
+    # @param sort [String,Array<String>] server-side sorting parameters
+    #
+    # @param filter [String] RSQL String limiting the result set
+    #
+    # @param cnx [Type] describe_cnx_here
+    #
+    # @return [Type] description_of_returned_object
+    #
+    def fetch_all_collection_pages(rsrc, sort, filter, cnx)
+      page = 0
+      page_size = MAX_PAGE_SIZE
+
+      raw = cnx.get "#{rsrc}?page=#{page}&page-size=#{page_size}#{sort}#{filter}"
+      results = raw[:results]
+
+      until results.size >= raw[:totalCount]
+        page += 1
+        raw = cnx.get "#{rsrc}?page=#{page}&page-size=#{page_size}#{sort}#{filter}"
+        results += raw[:results]
+      end
+      results
+    end
+
+  end # Pagable
+
+end # Jamf

data/lib/jamf/api/{json_objects/installed_application.rb → mixins/sortable.rb}

@@ -1,5 +1,4 @@
 # Copyright 2020 Pixar
-
 #
 #    Licensed under the Apache License, Version 2.0 (the "Apache License")
 #    with the following modification; you may not use this file except in
@@ -23,37 +22,38 @@
 #
 #
 
-# The module
 module Jamf
 
-  # An installed application on a device
-  class InstalledApplication < Jamf::JSONObject
-
-    OBJECT_MODEL = {
-
-      # @!attribute [r] identifier
-      #   @return [String]
-      identifier: {
-        class: :string,
-        readonly: true
-      },
-
-      # @!attribute [r] name
-      #   @return [String]
-      name: {
-        class: :string,
-        readonly: true
-      },
-
-      # @!attribute [r] version
-      #   @return [String]
-      version: {
-        class: :string,
-        readonly: true
-      }
-    }.freeze
-    parse_object_model
-
-  end # class Mobile Device security
-
-end # module
+  # parse the sort params for collection GET requests
+  module Sortable
+
+    # # When this is included
+    # def self.included(klass)
+    #   puts "Sortable was included by #{klass}"
+    # end
+    #
+    # # When this is exdended
+    # def self.extended(klass)
+    #   puts "Sortable was extended by #{klass}"
+    # end
+
+    private
+
+    # generate the sort params for the url
+    #
+    def parse_collection_sort(sort)
+      case sort
+      when nil
+        sort
+      when String
+        "&sort=#{CGI.escape sort}"
+      when Array
+        "&sort=#{CGI.escape sort.join(',')}"
+      else
+        raise ArgumentError, 'sort criteria must be a String or Array of Strings'
+      end
+    end
+
+  end # Sortable
+
+end # Jamf

data/lib/jamf/api/resources/collection_resources/building.rb

@@ -35,8 +35,8 @@ module Jamf
     # Mix-Ins
     #####################################
 
+    extend Jamf::BulkDeletable
     include Jamf::ChangeLog
-    include Jamf::Referable
 
     # Constants
     #####################################
@@ -54,7 +54,7 @@ module Jamf
       # @!attribute [r] id
       #   @return [Integer]
       id: {
-        class: :integer,
+        class: :j_id,
         identifier: :primary,
         readonly: true
       },
@@ -65,45 +65,52 @@ module Jamf
         class: :string,
         identifier: true,
         validator: :non_empty_string,
-        required: true
+        required: true,
+        filter_key: true
       },
 
       # @!attribute street1
       #   @return [String]
       streetAddress1: {
-        class: :string
+        class: :string,
+        filter_key: true
       },
 
       # @!attribute street2
       #   @return [String]
       streetAddress2: {
-        class: :string
+        class: :string,
+        filter_key: true
       },
 
       # @!attribute city
       #   @return [String]
       city: {
-        class: :string
+        class: :string,
+        filter_key: true
       },
 
       # @!attribute state_province
       #   @return [String]
       stateProvince: {
         class: :string,
-        aliases: %i[state province]
+        aliases: %i[state province],
+        filter_key: true
       },
 
       # @!attribute zip_postal_code
       #   @return [String]
       zipPostalCode: {
         class: :string,
-        aliases: %i[zip zipcode zip_code postal_code postalcode]
+        aliases: %i[zip zipcode zip_code postal_code postalcode],
+        filter_key: true
       },
 
       # @!attribute country
       #   @return [String]
       country: {
-        class: :string
+        class: :string,
+        filter_key: true
       }
     }.freeze
 

data/lib/jamf/api/resources/collection_resources/category.rb

@@ -36,12 +36,11 @@ module Jamf
     #####################################
 
     include Jamf::ChangeLog
-    include Jamf::Referable
 
     # Constants
     #####################################
 
-    RSRC_VERSION = 'v2'.freeze
+    RSRC_VERSION = 'v1'.freeze
 
     RSRC_PATH = 'categories'.freeze
 
@@ -65,13 +64,15 @@ module Jamf
         class: :string,
         identifier: true,
         validator: :non_empty_string,
-        required: true
+        required: true,
+        filter_key: true
       },
 
       # @!attribute priority
       #   @return [Integer]
       priority: {
-        class: :integer
+        class: :integer,
+        filter_key: true
       }
     }.freeze