ruby-jss 1.3.2 → 1.5.3

data/lib/jamf/api/abstract_classes/advanced_search.rb

@@ -1,86 +0,0 @@
-# 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.
-#
-#
-
-# The Module
-module Jamf
-
-  # Classes
-  #####################################
-
-  # A building defined in the JSS
-  class AdvancedSearch < Jamf::CollectionResource
-
-    extend Jamf::Abstract
-
-    # Constants
-    #####################################
-
-    # Object Model / Attributes
-    # See APIObject class documentation for details
-    # of how the OBJECT_MODEL hash works.
-    #####################################
-    OBJECT_MODEL = {
-
-      # @!attribute [r] id
-      #   @return [Integer]
-      id: {
-        class: :integer,
-        identifier: :primary,
-        readonly: true
-      },
-
-      # @!attribute name
-      #   @return [String]
-      name: {
-        class: :string,
-        identifier: true
-      },
-
-      # @!attribute criteria
-      #   @return [Array<Jamf::Criterion>]
-      criteria: {
-        class: Jamf::Criterion,
-        multi: true,
-        required: true
-      },
-
-      # @!attribute displayFields
-      #   @return [Array<String>]
-      displayFields: {
-        class: :string,
-        multi: true
-      },
-
-      # @!attribute site
-      #   @return [Jamf::Site::Reference]
-      site: {
-        class: Jamf::Site::Reference
-      }
-
-    }.freeze
-
-  end # class
-
-end # module

data/lib/jamf/api/abstract_classes/collection_resource.rb

@@ -1,433 +0,0 @@
-# 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.
-#
-#
-
-# The module
-module Jamf
-
-  # A Collection Resource in Jamf Pro
-  #
-  # See {Jamf::Resource} for general info about API resources.
-  #
-  # Collection resources have more than one resource within them, and those
-  # can (usually) be created and deleted as well as fetched and updated.
-  # The entire collection (or a part of it) can also be fetched as an Array.
-  # When the whole collection is fetched, the result is cached for future use.
-  #
-  # # Subclassing
-  #
-  # ## Creatability, & Deletability
-  #
-  # Sometimes the API doesn't support creation of new members of the collection.
-  # If that's the case, just extend the subclass with Jamf::UnCreatable
-  # and the '.create' class method will raise an error.
-  #
-  # Similarly for deletion of members: if the API doesn't have a way to delete
-  # them, extend the subclass with Jamf::UnDeletable
-  #
-  # See also Jamf::JSONObject, which talks about extending subclasses
-  # with Jamf::Immutable
-  #
-  # ## Bulk Deletion
-  #
-  # Some collection resources have a resource for bulk deletion, passing in
-  # a JSON array of ids to delete.
-  #
-  # If so, just define a BULK_DELETE_RSRC, and the .delete class method
-  # will use it, rather than making multiple calls to delete individual
-  # items. See Jamf::Category::BULK_DELETE_RSRC for an example
-  #
-  # @abstract
-  #
-  class CollectionResource < Jamf::Resource
-
-    extend Jamf::Abstract
-    include Comparable
-
-    # Public Class Methods
-    #####################################
-
-    # @return [Array<Symbol>] the attribute names that are marked as identifiers
-    #
-    def self.identifiers
-      self::OBJECT_MODEL.select { |_attr, deets| deets[:identifier] }.keys
-    end
-
-    # The Collection members Array for this class, retrieved from
-    # the RSRC_PATH as Parsed JSON, but not instantiated into instances
-    # unless instantiate: is truthy.
-    #
-    # E.g. for {Jamf::Settings::Building}, this would be the Array of Hashes
-    # returned by GETing the resource .../settings/obj/building
-    #
-    # This Array is cached in the {Jamf::Connection} instance used to
-    # retrieve it, and future calls to .all will return the cached Array
-    # unless refresh is truthy.
-    #
-    # TODO: Investigate https://www.rubydoc.info/github/mloughran/api_cache
-    #
-    # @param refresh[Boolean] re-read the data from the API?
-    #
-    # @param cnx[Jamf::Connection] an API connection to use for the query.
-    #   Defaults to the corrently active connection. See {Jamf::Connection}
-    #
-    # @param instantiate[Boolean] The Array contains instances of this class
-    #   rather than the JSON Hashes from the API.
-    #
-    # @return  [Array<Object>] An Array of all objects of this class in the JSS.
-    #
-    def self.all(refresh = false, cnx: Jamf.cnx, instantiate: false)
-      validate_not_abstract
-      cnx.collection_cache[self] = nil if refresh
-      if cnx.collection_cache[self]
-        return cnx.collection_cache[self] unless instantiate
-
-        return cnx.collection_cache[self].map { |m| new m }
-      end
-
-      # TODO:  make sure all collection resources use this format
-      # for paging. Also -ask Jamf about a  url that returns
-      # ALL objects in one query, regardless of number.
-      page = 0
-      raw = cnx.get "#{rsrc_path}?page=#{page}&size=1000000&sort=id%3Aasc"
-      results = raw[:results]
-
-      until results.size >= raw[:totalCount]
-        page += 1
-        raw = cnx.get "#{rsrc_path}?page=#{page}&size=1000000&sort=id%3Aasc"
-        results += raw[:results]
-      end
-
-
-      cnx.collection_cache[self] = results
-
-      return cnx.collection_cache[self] unless instantiate
-
-      cnx.collection_cache[self].map { |m| new m }
-    end
-
-    # An array of the ids for all collection members. According to the
-    # specs ALL collection resources must have an ID, which is used in the
-    # resource path.
-    #
-    # @param refresh (see .all)
-    #
-    # @param cnx (see .all)
-    #
-    # @return [Array<Integer>]
-    #
-    def self.all_ids(refresh = false, cnx: Jamf.cnx)
-      all(refresh, cnx: cnx).map { |m|  m[:id] }
-    end
-
-    # rubocop:disable Naming/UncommunicativeMethodParamName
-
-    # A Hash of all members of this collection where the keys are some
-    # identifier and values are any other attribute.
-    #
-    # @param ident [Symbol] An identifier of this Class, used as the key
-    #   for the mapping Hash. Aliases are acceptable, e.g. :sn for :serialNumber
-    #
-    # @param to [Symbol] The attribute to which the ident will be mapped.
-    #   Aliases are acceptable, e.g. :name for :displayName
-    #
-    # @param refresh (see .all)
-    #
-    # @param cnx (see .all)
-    #
-    # @return [Hash {Symbol: Object}] A Hash of identifier mapped to attribute
-    #
-    def self.map_all(ident, to:, cnx: Jamf.cnx, refresh: false)
-      real_ident = attr_key_for_alias ident
-      raise Jamf::InvalidDataError, "No identifier #{ident} for class #{self}" unless
-      identifiers.include? real_ident
-
-      real_to = attr_key_for_alias to
-      raise Jamf::NoSuchItemError, "No attribute #{to} for class #{self}" unless self::OBJECT_MODEL.key? real_to
-
-      ident = real_ident
-      to = real_to
-      list = all refresh, cnx: cnx
-      to_class = self::OBJECT_MODEL[to][:class]
-      mapped = list.map do |i|
-        [
-          i[ident],
-          to_class.is_a?(Symbol) ? i[to] : to_class.new(i[to])
-        ]
-      end # do i
-      mapped.to_h
-    end
-    # rubocop:enable Naming/UncommunicativeMethodParamName
-
-    # Given any identfier value for this collection, return the id of the
-    # object that has such an identifier.
-    #
-    # Return nil if there's no match for the given value.
-    #
-    # If you know the value is a certain identifier, e.g. a serialNumber,
-    # then you can specify the identifier for a faster search:
-    #
-    #   valid_id serialNumber: 'AB12DE34' # => Int or nil
-    #
-    # If you don't know wich identifier you have, just pass the value and
-    # all identifiers are searched
-    #
-    #   valid_id 'AB12DE34' # => Int or nil
-    #   valid_id 'SomeComputerName' # => Int or nil
-    #
-    # When the value is a string, the seach is case-insensitive
-    #
-    # TODO: When 'Searchability' is more dialed in via the searchable
-    # mixin, which implements enpoints like 'POST /v1/search-mobile-devices'
-    # then use that before using the 'all' list.
-    #
-    # @param value [Object] A value to search for as an identifier.
-    #
-    # @param refresh[Boolean] Reload the list data from the API
-    #
-    # @param ident: [Symbol] Restrict the search to this identifier.
-    #  E.g. if :serialNumber, then the value must be
-    #  a known serial number, it is not checked against other identifiers
-    #
-    # @param cnx: (see .all)
-    #
-    # @return [Object, nil] the primary identifier of the matching object,
-    #   or nil if it doesn't exist
-    #
-    def self.valid_id(value = nil, refresh: true, cnx: Jamf.cnx, **ident_hash)
-      unless ident_hash.empty?
-        ident, value = ident_hash.first
-        return id_from_other_ident ident, value, refresh, cnx: cnx
-      end
-
-      # check the id itself first
-      return value if all_ids(refresh, cnx: cnx).include? value
-
-      idents = identifiers - [:id]
-      val_is_str = value.is_a? String
-
-      idents.each do |ident|
-        match = all(refresh, cnx: cnx).select do |m|
-          val_is_str ? m[ident].to_s.casecmp?(value) : m[ident] == value
-        end.first
-        return match[:id] if match
-      end # identifiers.each do |ident|
-
-      nil
-    end
-
-    # Bu default, subclasses are creatable, i.e. new instances can be created
-    # with .create, and added to the JSS with .save
-    # If a subclass is NOT creatble for any reason, just add
-    #   extend Jamf::UnCreatable
-    # and this method will return false
-    #
-    # @return [Boolean]
-    def self.creatable?
-      true
-    end
-
-    # Make a new thing to be added to the API
-    def self.create(**params)
-      validate_not_abstract
-      raise Jamf::UnsupportedError, "#{self}'s are not currently creatable via the API" unless creatable?
-
-      cnx = params.delete :cnx
-      cnx ||= Jamf.cnx
-
-      params.delete :id # no such animal when .creating
-
-      params.keys.each do |param|
-        raise ArgumentError, "Unknown parameter: #{param}" unless self::OBJECT_MODEL.key? param
-
-        params[param] = validate_attr param, params[param], cnx: cnx
-      end
-
-      params[:creating_from_create] = true
-      new params, cnx: cnx
-    end
-
-    # Retrieve a member of a CollectionResource from the API
-    #
-    # To create new members to be added to the JSS, use
-    # {Jamf::CollectionResource.create}
-    #
-    # If you know the specific identifier attribute you're looking up, e.g.
-    # :id or :name or :udid, (or an aliase thereof) then you can specify it like
-    # `.fetch name: 'somename'`, or `.fetch udid: 'someudid'`
-    #
-    # If you don't know if (or don't want to type it) you can just use
-    # `.fetch 'somename'`, or `.fetch 'someudid'` and all identifiers will be
-    # searched for a match.
-    #
-    # @param ident_value[Object] A value for any identifier for this subclass.
-    #  All identifier attributes will be searched for a match.
-    #
-    # @param cnx[Jamf::Connection] the connection to use to fetch the object
-    #
-    # @param ident_hash[Hash] an identifier attribute key and a search value
-    #
-    # @return [CollectionResource] The ruby-instance of a Jamf object
-    #
-    def self.fetch(ident_value = nil, cnx: Jamf.cnx, **ident_hash)
-      validate_not_abstract
-
-      id =
-        if ident_value == :random
-          all_ids.sample
-        elsif ident_value
-          valid_id ident_value, cnx: cnx
-        elsif ident_hash.empty?
-          nil
-        else
-          ident, lookup_value = ident_hash.first
-          valid_id ident => lookup_value, cnx: cnx
-        end
-
-      raise Jamf::NoSuchItemError, "No matching #{self}" unless id
-
-      data = cnx.get "#{rsrc_path}/#{id}"
-      new data, cnx: cnx
-    end # fetch
-
-    # By default, CollectionResource subclass instances are deletable.
-    # If not, just extend the subclass with Jamf::UnDeletable, and this
-    # will return false, and .delete & #delete will raise errors
-    def self.deletable?
-      true
-    end
-
-    # Delete one or more objects by identifier
-    # Any valid identifier for the class can be used (id, name, udid, etc)
-    # Identifiers can be provided as an array or as separate parameters
-    #
-    # e.g. .delete [1,3, 34, 4]
-    # or .delete 'myComputer', 'that-computer', 'OtherComputer'
-    #
-    # @param idents[Array<integer>, Integer]
-    #
-    # @param cnx[Jamf::Connection]
-    #
-    # @return [Array] the identifiers that were not found, so couldn't be deleted
-    #
-    def self.delete(*idents, cnx: Jamf.cnx)
-      raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless deletable?
-
-      idents.flatten!
-      no_valid_ids = []
-
-      idents.map do |ident|
-        id = valid_id ident
-        no_valid_ids << ident unless id
-        id
-      end
-      idents.compact!
-
-      # TODO: some rsrcs have a 'bulk delete' version...
-      idents.each { |id| cnx.delete "#{rsrc_path}/#{id}" }
-
-      no_valid_ids
-    end
-
-    # Private Class Methods
-    #####################################
-
-    # TODO: better pluralizing?
-    #
-    def self.create_list_methods(attr_name, attr_def)
-      list_method_name = "all_#{attr_name}s"
-
-      define_singleton_method(list_method_name) do |refresh = false, cnx: Jamf.cnx|
-        all_list = all(refresh, cnx: cnx)
-        if attr_def[:class].is_a? Symbol
-          all_list.map { |i| i[attr_name] }.uniq
-        else
-          all_list.map { |i| attr_def[:class].new i[attr_name] }
-        end
-      end # define_singleton_method
-
-      return unless attr_def[:aliases]
-
-      # aliases - TODO: is there a more elegant way?
-      attr_def[:aliases].each do |a|
-        define_singleton_method("all_#{a}s") do |refresh = false, cnx: Jamf.cnx|
-          send list_method_name, refresh, cnx: cnx
-        end # define_singleton_method
-      end # each alias
-    end # create_list_methods
-    private_class_method :create_list_methods
-
-    # Given an indentier attr. key, and a value,
-    # return the id where that ident has that value, or nil
-    #
-    def self.id_from_other_ident(ident, value, refresh = true, cnx: Jamf.cnx)
-      raise ArgumentError, "Unknown identifier '#{ident}' for #{self}" unless identifiers.include? ident
-
-      # check the id itself first
-      return value if ident == :id && all_ids(refresh, cnx: cnx).include?(value)
-
-      # all ident values => ids
-      ident_map = map_all(ident, to: :id, cnx: cnx, refresh: refresh)
-
-      # case-insensitivity for string values
-      value = ident_map.keys.j_ci_fetch(value) if value.is_a? String
-
-      ident_map[value]
-    end
-    private_class_method :id_from_other_ident
-
-    # Instance Methods
-    #####################################
-
-    def exist?
-      !@id.nil?
-    end
-
-    def rsrc_path
-      return unless exist?
-      "#{self.class.rsrc_path}/#{@id}"
-    end
-
-    def delete
-      raise Jamf::UnsupportedError, "Deleting #{self} objects is not currently supported" unless self.class.deletable?
-      @cnx.delete rsrc_path
-    end
-
-    # Two collection resource objects are the same if their id's are the same
-    def <=>(other)
-      id <=> other.id
-    end
-
-    # Private Instance Methods
-    ############################################
-    private
-
-    def create_in_jamf
-      result = @cnx.post self.class.rsrc_path, to_jamf
-      @id = result[:id]
-    end
-
-  end # class CollectionResource
-
-end # module JAMF