ruby-jss 1.6.4 → 2.0.0a10

data/lib/{jss → jamf/api/classic/base_classes}/api_object.rb

@@ -1,4 +1,4 @@
-### Copyright 2020 Pixar
+### Copyright 2022 Pixar
 
 ###
 ###    Licensed under the Apache License, Version 2.0 (the "Apache License")
@@ -24,7 +24,7 @@
 ###
 
 ###
-module JSS
+module Jamf
 
   # Classes
   #####################################
@@ -33,7 +33,7 @@ module JSS
   # methods and constants that apply to all API resouces.
   #
   # See the README.md file for general info about using subclasses of
-  # JSS::APIObject
+  # Jamf::APIObject
   #
   # == Subclassing
   #
@@ -56,15 +56,15 @@ module JSS
   # === Object Creation
   #
   # If a subclass should be able to be created in the JSS be sure to include
-  # {JSS::Creatable}
+  # {Jamf::Creatable}
   #
   # The constructor should verify any extra required data in the args
   #
-  # See {JSS::Creatable} for more details.
+  # See {Jamf::Creatable} for more details.
   #
   # === Object Modification
   #
-  # If a subclass should be modifiable in the JSS, include {JSS::Updatable},
+  # If a subclass should be modifiable in the JSS, include {Jamf::Updatable},
   # q.v. for details.
   #
   # === Object Deletion
@@ -156,7 +156,7 @@ module JSS
   #
   # For example, here's a summary-hash for a single MobileDevice from the
   # list-resource  '...JSSResource/mobiledevices', which you might get in the
-  # Array returned by JSS::MobileDevice.all:
+  # Array returned by Jamf::MobileDevice.all:
   #
   #   {
   #     :id=>3964,
@@ -255,7 +255,7 @@ module JSS
   # no way to guarantee which object you get back.
   #
   # In those subclasses, set NON_UNIQUE_NAMES to any value, and a
-  # JSS::AmbiguousError exception will be raised when trying to fetch by name
+  # Jamf::AmbiguousError exception will be raised when trying to fetch by name
   # and the name isn't unique.
   #
   # Because of the extra processing, the check for this state will only happen
@@ -265,21 +265,80 @@ module JSS
   #
   # When that's the case, fetching explicitly by name, or when fetching with a
   # plain search term that matches a non-unique name, will raise a
-  # JSS::AmbiguousError exception,when the name isn't unique. If that happens,
+  # Jamf::AmbiguousError exception,when the name isn't unique. If that happens,
   # you'll have to use some other identifier to fetch the desired object.
   #
   # Note: Fetching, finding valid id, and name collisions are case-insensitive.
   #
   class APIObject
 
+    include Comparable
+
+    # COMPARABLE
+    # APIobjects are == if all of their lookup key values are the same
+    #
+    def <=>(other)
+      idents_combined <=> other.idents_combined
+    end
+
+    def idents_combined
+      my_keys = self.class.lookup_keys.values.uniq
+      my_keys.map { |k| send(k).to_s }.sort.join
+    end
+
+    # Meta Programming
+    ####################################################
+
+    # Loop through the defined lookup keys and make
+    # .all_<key>s methods for each one, with alises as needed.
+    #
+    # This is called automatically when subclasses are loaded by zeitwerk
+    #
+    def self.define_identifier_list_methods
+      Jamf.load_msg "defining list-methods for APIObject subclass #{self}"
+
+      lookup_keys.each do |als, key|
+        meth_name = key.to_s.end_with?('s') ? "all_#{key}es" : "all_#{key}s"
+
+        if als == key
+          # the all_ method - skip if defined in the class
+          next if singleton_methods.include? meth_name
+
+          define_singleton_method meth_name do |refresh = false, cached_list: nil, api: nil, cnx: Jamf.cnx|
+            cnx = api if api
+            list = cached_list || all(refresh, cnx: cnx)
+            list.map { |i| i[key] }
+          end
+          Jamf.load_msg "Defined method #{self}##{meth_name}"
+
+        else
+          # an alias - skip if defined in the class
+          als_name = als.to_s.end_with?('s') ? "all_#{als}es" : "all_#{als}s"
+          next if singleton_methods.include? als_name
+
+          define_singleton_method als_name do |refresh = false, api: nil, cnx: Jamf.cnx|
+            cnx = api if api
+            send meth_name, refresh, cnx: cnx
+          end
+          Jamf.load_msg "Defined alias '#{als_name}' of #{self}##{meth_name}"
+
+        end # if
+      end # lookup_keys.eachs
+      true
+    end # self.define_identifier_list_methods
+
     # Constants
     ####################################
 
+    # which API do APIObjects come from?
+    # The JPAPI equivalent is in Jamf::JPAPIResource
+    API_SOURCE = :classic
+
     # '.new' can only be called from these methods:
-    OK_INSTANTIATORS = ['make', 'fetch', 'block in fetch'].freeze
+    OK_INSTANTIATORS = ['make', 'create', 'fetch', 'block in fetch'].freeze
 
     # See the discussion of 'Lookup Keys' in the comments/docs
-    # for {JSS::APIObject}
+    # for {Jamf::APIObject}
     #
     DEFAULT_LOOKUP_KEYS = {
       id: { fetch_rsrc_key: :id },
@@ -397,11 +456,11 @@ module JSS
 
     # Return an Array of Hashes for all objects of this subclass in the JSS.
     #
-    # This method is only valid in subclasses of JSS::APIObject, and is
+    # This method is only valid in subclasses of Jamf::APIObject, and is
     # the parsed JSON output of an API query for the resource defined in the
     # subclass's RSRC_BASE
     #
-    # e.g. for JSS::Computer, with the RSRC_BASE of :computers,
+    # e.g. for Jamf::Computer, with the RSRC_BASE of :computers,
     # This method retuens the output of the 'JSSResource/computers' resource,
     # which is a list of all computers in the JSS.
     #
@@ -420,12 +479,12 @@ module JSS
     # in the class comments/docs above)
     #
     # Subclasses should provide appropriate .all_xxx class methods for accessing
-    # any other other values as Arrays, e.g. JSS::Computer.all_managed
+    # any other other values as Arrays, e.g. Jamf::Computer.all_managed
     #
     # -- Caching
     #
     # The results of the first call to .all for each subclass is cached in the
-    # .object_list_cache of the given {JSS::APIConnection} and that cache is
+    # .c_object_list_cache of the given {Jamf::Connection} and that cache is
     # used for all future calls, so as to not requery the server every time.
     #
     # To force requerying to get updated data, provided a truthy argument.
@@ -438,60 +497,96 @@ module JSS
     # -- Alternate API connections
     #
     # To query an APIConnection other than the currently active one,
-    # provide one via the api: named parameter.
+    # provide one via the cnx: named parameter.
     #
     # @param refresh[Boolean] should the data be re-queried from the API?
     #
-    # @param api[JSS::APIConnection] an API connection to use for the query.
-    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    # @param cnx [Jamf::Connection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {Jamf::Connection}
     #
     # @return [Array<Hash{:name=>String, :id=> Integer}>]
     #
-    def self.all(refresh = false, api: JSS.api)
+    def self.all(refresh = false, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
       validate_not_metaclass(self)
 
-      cache = api.object_list_cache
+      cache = cnx.c_object_list_cache
       cache_key = self::RSRC_LIST_KEY
-      api.flushcache(cache_key) if refresh
+      cnx.flushcache(cache_key) if refresh
       return cache[cache_key] if cache[cache_key]
 
-      cache[cache_key] = api.get_rsrc(self::RSRC_BASE)[cache_key]
+      cache[cache_key] = cnx.c_get(self::RSRC_BASE)[cache_key]
     end
 
     # @return [Hash {String => Integer}] name => number of occurances
     #
-    def self.duplicate_names(refresh = false, api: JSS.api)
+    def self.duplicate_names(refresh = false, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
       return {} unless defined? self::NON_UNIQUE_NAMES
 
       dups = {}
-      all(refresh, api: api).each do |obj|
+      all(refresh, cnx: cnx).each do |obj|
         if dups[obj[:name]]
           dups[obj[:name]] += 1
         else
           dups[obj[:name]] = 1
         end # if
-      end # all(refresh, api: api).each
+      end # all(refresh, cnx: cnx).each
       dups.delete_if { |k,v| v == 1 }
       dups
     end
 
+    # 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 [Boolean] Re-read the 'all' data from the API? otherwise
+    #   use the cached data if available.
+    #
+    # @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, cached_list: nil)
+      ident = lookup_keys[ident]
+      raise Jamf::InvalidDataError, "No identifier :#{ident} for class #{self}" unless ident
+
+      list = cached_list ? cached_list : all(refresh, cnx: cnx)
+      mapped = list.map do |i|
+        [
+          i[ident],
+          i[to]
+        ]
+      end # do i
+
+      mapped.to_h
+    end
+
     # Return a hash of all objects of this subclass
     # in the JSS where the key is the id, and the value
-    # is some other key in the data items returned by the JSS::APIObject.all.
+    # is some other key in the data items returned by the Jamf::APIObject.all.
     #
     # If the other key doesn't exist in the API summary data from .all
-    # (eg :udid for JSS::Department) the values will be nil.
+    # (eg :udid for Jamf::Department) the values will be nil.
     #
     # Use this method to map ID numbers to other identifiers returned
     # by the API list resources. Invert its result to map the other
     # identfier to ids.
     #
     # @example
-    #   JSS::Computer.map_all_ids_to(:serial_number)
+    #   Jamf::Computer.map_all_ids_to(:serial_number)
     #
     #   # Returns, eg {2 => "C02YD3U8JHD3", 5 => "VMMz7xgg8lYZ"}
     #
-    #   JSS::Computer.map_all_ids_to(:serial_number).invert
+    #   Jamf::Computer.map_all_ids_to(:serial_number).invert
     #
     #   # Returns, eg {"C02YD3U8JHD3" => 2, "VMMz7xgg8lYZ" => 5}
     #
@@ -511,29 +606,33 @@ module JSS
     #
     # @param refresh[Boolean] should the data re-queried from the API?
     #
-    # @param api[JSS::APIConnection] an API connection to use for the query.
-    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    # @param cnx [Jamf::Connection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {Jamf::Connection}
     #
     # @return [Hash{Integer => Oject}] the associated ids and data
     #
-    def self.map_all_ids_to(other_key, refresh = false, api: JSS.api)
-      # we will accept any key, it'll just return nil if not in the
-      # .all hashes. However if we're given an alias of a lookup key
-      # we need to convert it to its real name.
-      other_key = lookup_keys[other_key] if lookup_keys[other_key]
-
-      cache_key = "#{self::RSRC_LIST_KEY}_map_#{other_key}".to_sym
-      cache = api.object_list_cache
-      cache[cache_key] = nil if refresh
-      return cache[cache_key] if cache[cache_key]
-
-      map = {}
-      all(refresh, api: api).each { |i| map[i[:id]] = i[other_key] }
-      cache[cache_key] = map
+    def self.map_all_ids_to(other_key, refresh = false, cached_list: nil, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
+      map_all :id, to: other_key, refresh: refresh, cnx: cnx, cached_list: cached_list
+
+      # # we will accept any key, it'll just return nil if not in the
+      # # .all hashes. However if we're given an alias of a lookup key
+      # # we need to convert it to its real name.
+      # other_key = lookup_keys[other_key] if lookup_keys[other_key]
+      #
+      # cache_key = "#{self::RSRC_LIST_KEY}_map_#{other_key}".to_sym
+      # cache = cnx.c_object_list_cache
+      # cache[cache_key] = nil if refresh
+      # return cache[cache_key] if cache[cache_key]
+      #
+      # map = {}
+      # all(refresh, cnx: cnx).each { |i| map[i[:id]] = i[other_key] }
+      # cache[cache_key] = map
     end
 
-    # Return an Array of JSS::APIObject subclass instances
-    # e.g when called on JSS::Package, return a hash of JSS::Package instancesa
+    # Return an Array of Jamf::APIObject subclass instances
+    # e.g when called on Jamf::Package, return a hash of Jamf::Package instancesa
     # for every package in the JSS.
     #
     # WARNING: This may be slow as it has to look up each object individually!
@@ -541,20 +640,23 @@ module JSS
     #
     # @param refresh[Boolean] should the data  re-queried from the API?
     #
-    # @param api[JSS::APIConnection] an API connection to use for the query.
-    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    # @param cnx [Jamf::Connection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {Jamf::Connection}
     #
     # @return [Array<APIObject>] the objects requested
     #
-    def self.all_objects(refresh = false, api: JSS.api)
+    def self.all_objects(refresh = false, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
       objects_cache_key ||= "#{self::RSRC_LIST_KEY}_objects".to_sym
-      api_cache = api.object_list_cache
+      api_cache = cnx.c_object_list_cache
       api_cache[objects_cache_key] = nil if refresh
 
       return api_cache[objects_cache_key] if api_cache[objects_cache_key]
-      all = all(refresh, api: api)
-      api_cache[objects_cache_key] = all.map do |o|
-        fetch id: o[:id], api: api, refresh: false
+
+      all_result = all(refresh, cnx: cnx)
+      api_cache[objects_cache_key] = all_result.map do |o|
+        fetch id: o[:id], cnx: cnx, refresh: false
       end
     end
 
@@ -576,24 +678,25 @@ module JSS
     #
     # @param refresh [Boolean] Should the data be re-read from the server
     #
-    # @param api[JSS::APIConnection] an API connection to use for the query.
-    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    # @param cnx [Jamf::Connection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {Jamf::Connection}
     #
     # @return [Integer, nil] the id of the matching object, or nil if it doesn't exist
     #
-    def self.valid_id(identifier, refresh = false, api: JSS.api)
+    def self.valid_id(identifier, refresh = false, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
 
       # refresh if needed
-      all(refresh, api: api) if refresh
+      all(refresh, cnx: cnx) if refresh
 
       # it its a valid id, return it
-      return identifier if all_ids(api: api).include? identifier
+      return identifier if all_ids(cnx: cnx).include? identifier
 
       keys_to_check = lookup_keys(no_aliases: true)
       keys_to_check.delete :id # we've already checked :id
 
       keys_to_check.each do |key|
-        mapped_ids = map_all_ids_to key, api: api
+        mapped_ids = map_all_ids_to key, cnx: cnx
         matches = mapped_ids.select { |_id, ident| ident.casecmp? identifier }
         # If exactly one match, return the id
         return matches.keys.first if matches.size == 1
@@ -609,11 +712,11 @@ module JSS
     #
     # @example
     #   # get the id for the computer with serialnum 'xyxyxyxy'
-    #   JSS::Computer.id_for_identifier :serial_number, 'xyxyxyxy'
+    #   Jamf::Computer.id_for_identifier :serial_number, 'xyxyxyxy'
     #
     #   # => the Integer id, or nil if no such serial number
     #
-    # Raises a JSS::Ambiguous error if there's more than one matching value
+    # Raises a Jamf::Ambiguous error if there's more than one matching value
     # for any key, which might be true of names for Computers and Devices
     #
     # This is similar to .valid_id, except only one key is searched
@@ -627,25 +730,27 @@ module JSS
     # @param refresh [Boolean] Should the cached summary data be re-read from
     #   the server first?
     #
-    # @param api[JSS::APIConnection] an API connection to use for the query.
-    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    # @param cnx [Jamf::Connection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {Jamf::Connection}
     #
     # @return [Integer, nil] the id of the matching object, or nil if it
     #   doesn't exist
     #
-    def self.id_for_identifier(key, val, refresh = false, api: JSS.api)
+    def self.id_for_identifier(key, val, refresh = false, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
       # refresh if needed
-      all(refresh, api: api) if refresh
+      all(refresh, cnx: cnx) if refresh
 
       # get the real key if an alias was used
       key = real_lookup_key key
 
       # do id's expicitly, they are integers
-      return all_ids.include?(val) ? val : nil if key == :id
+      return all_ids(cnx: cnx).include?(val) ? val : nil if key == :id
 
-      mapped_ids = map_all_ids_to key, api: api
+      mapped_ids = map_all_ids_to key, cnx: cnx
       matches = mapped_ids.select { |_id, map_val| val.casecmp? map_val }
-      raise JSS::AmbiguousError, "Key #{key}: value '#{val}' is not unique for #{self}" if matches.size > 1
+      raise Jamf::AmbiguousError, "Key #{key}: value '#{val}' is not unique for #{self}" if matches.size > 1
 
       return nil if matches.size.zero?
 
@@ -660,13 +765,15 @@ module JSS
     #
     # @param refresh [Boolean] Should the data be re-read from the server
     #
-    # @param api[JSS::APIConnection] an API connection to use for the query.
-    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    # @param cnx [Jamf::Connection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {Jamf::Connection}
     #
     # @return [Boolean] does an object with the given identifier exist?
     #
-    def self.exist?(identifier, refresh = false, api: JSS.api)
-      !valid_id(identifier, refresh, api: api).nil?
+    def self.exist?(identifier, refresh = false, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
+      !valid_id(identifier, refresh, cnx: cnx).nil?
     end
 
     # Convert an Array of Hashes of API object data to a
@@ -679,9 +786,9 @@ module JSS
     # with one <class> element per Hash member.
     #
     # @example
-    #   # for class JSS::Computer
+    #   # for class Jamf::Computer
     #   some_comps = [{:id=>2, :name=>"kimchi"},{:id=>5, :name=>"mantis"}]
-    #   xml_names = JSS::Computer.xml_list some_comps
+    #   xml_names = Jamf::Computer.xml_list some_comps
     #   puts xml_names  # output manually formatted for clarity, xml.to_s has no newlines between elements
     #
     #   <computers>
@@ -693,7 +800,7 @@ module JSS
     #     </computer>
     #   </computers>
     #
-    #   xml_ids = JSS::Computer.xml_list some_comps, :id
+    #   xml_ids = Jamf::Computer.xml_list some_comps, :id
     #   puts xml_names  # output manually formatted for clarity, xml.to_s has no newlines between elements
     #
     #   <computers>
@@ -756,10 +863,10 @@ module JSS
     #
     # @example
     #   # computer where 'xyxyxyxy'  is in any of the lookup key fields
-    #   JSS::Computer.fetch 'xyxyxyxy'
+    #   Jamf::Computer.fetch 'xyxyxyxy'
     #
     #   # computer where 'xyxyxyxy' is the serial number
-    #   JSS::Computer.fetch serial_number: 'xyxyxyxy'
+    #   Jamf::Computer.fetch serial_number: 'xyxyxyxy'
     #
     # Fetching is faster when specifying a lookup key, and that key has a
     # fetch_rsrc_key defined in its OTHER_LOOKUP_KEYS constant, as in the second
@@ -785,8 +892,8 @@ module JSS
     #   If no searchterm is provided, one of the args must be a valid
     #   lookup key and value to find in that key, e.g. `serial_number: '1234567'`
     #
-    # @option args api[JSS::APIConnection] an API connection to use for the query.
-    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    # @option args cnx[Jamf::Connection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {Jamf::Connection}
     #
     # @option args refresh[Boolean] should the summary list of all objects be
     #   reloaded from the API before being used to look for this object.
@@ -797,35 +904,34 @@ module JSS
       validate_not_metaclass(self)
 
       # which connection?
-      api = args.delete :api
-      api ||= JSS.api
+      cnx = args.delete :cnx
+      cnx ||= args.delete :api
+      cnx ||= Jamf.cnx
 
       # refresh the .all list if needed
       if args.delete(:refresh) || searchterm == :random
-        all(:refresh, api: api)
+        all(:refresh, cnx: cnx)
         just_refreshed = true
       else
         just_refreshed = false
       end
 
       # a random object?
-      if searchterm == :random
-        rnd_thing = all.sample
-        raise JSS::NoSuchItemError, "No #{self::RSRC_LIST_KEY} found" unless rnd_thing
+      if searchterm == :random || args[:random]
+        rnd_thing = all(cnx: cnx).sample
+        raise Jamf::NoSuchItemError, "No #{self::RSRC_LIST_KEY} found" unless rnd_thing
 
-        return new id: rnd_thing[:id], api: api
+        return new id: rnd_thing[:id], cnx: cnx
       end
 
       # get the lookup key and value, if given
       fetch_key, fetch_val = args.to_a.first
       fetch_rsrc_key = fetch_rsrc_key(fetch_key)
 
-      err_detail = "where #{fetch_key} = #{fetch_val}"
-
       # names should raise an error if more than one exists,
       # so we always have to do id_for_identifier, which will do so.
       if fetch_rsrc_key == :name
-        id = id_for_identifier fetch_key, fetch_val, !just_refreshed, api: api
+        id = id_for_identifier fetch_key, fetch_val, !just_refreshed, cnx: cnx
         fetch_rsrc = id ? "#{self::RSRC_BASE}/name/#{CGI.escape fetch_val.to_s}" : nil
 
       # if the fetch rsrc key exists, it can be used directly in an endpoint path
@@ -836,20 +942,19 @@ module JSS
       # it has an OTHER_LOOKUP_KEY but that key doesn't have a fetch_rsrc
       # so we look in the .map_all_ids_to_* hash for it.
       elsif fetch_key
-        id = id_for_identifier fetch_key, fetch_val, !just_refreshed, api: api
+        id = id_for_identifier fetch_key, fetch_val, !just_refreshed, cnx: cnx
         fetch_rsrc = id ? "#{self::RSRC_BASE}/id/#{id}" : nil
 
       # no fetch key was given in the args, so try a search term
       elsif searchterm
-        id = valid_id searchterm, api: api
+        id = valid_id searchterm, cnx: cnx
         fetch_rsrc = id ? "#{self::RSRC_BASE}/id/#{id}" : nil
-        err_detail = "matching #{searchterm}"
 
       else
         raise ArgumentError, 'Missing searchterm or fetch key'
       end
 
-      new fetch_rsrc: fetch_rsrc, api: api
+      new fetch_rsrc: fetch_rsrc, cnx: cnx
     end # fetch
 
     # Fetch the mostly- or fully-raw JSON or XML data for an object of this
@@ -869,7 +974,7 @@ module JSS
     # all the ruby goodness of a full instance, but just want a few values for
     # an object that aren't available in the `all` data
     #
-    # This is really just a wrapper around {APIConnection.get_rsrc} that
+    # This is really just a wrapper around {APIConnection.c_get} that
     # automatically fills in the RSRC::BASE value for you.
     #
     # @param id [Integer] the id of the object to fetch
@@ -879,18 +984,20 @@ module JSS
     # @param as_string[Boolean] return the raw JSON or XML string as it comes
     #   from the API, do not parse into a Hash or REXML::Document
     #
-    # @param api[JSS::APIConnection] the connection thru which to fetch this
-    #   object. Defaults to the deault API connection in JSS.api
+    # @param cnx [Jamf::Connection] the connection thru which to fetch this
+    #   object. Defaults to the deault API connection in Jamf.cnx
     #
     # @return [Hash, REXML::Document, String] the raw data for the object
     #
-    def self.get_raw(id, format: :json, as_string: false, api: JSS.api)
+    def self.get_raw(id, format: :json, as_string: false, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
       validate_not_metaclass(self)
       rsrc = "#{self::RSRC_BASE}/id/#{id}"
-      data = api.get_rsrc rsrc, format, raw_json: as_string
+      data = cnx.c_get rsrc, format, raw_json: as_string
       return data if format == :json || as_string
 
-      REXML::Document.new(data)
+      REXML::Document.new(**data)
     end
 
     # PUT some raw XML to the API for a given id in this subclass.
@@ -903,22 +1010,24 @@ module JSS
     # In some cases, where you're making simple changes to simple XML,
     # this can be faster than fetching a full instance and the re-saving it.
     #
-    # This is really just a wrapper around {APIConnection.put_rsrc} that
+    # This is really just a wrapper around {APIConnection.c_put} that
     # automatically fills in the RSRC::BASE value for you.
     #
     # @param id [Integer] the id of the object to PUT
     #
     # @param xml [String, #to_s] The XML to send
     #
-    # @param api[JSS::APIConnection] the connection thru which to fetch this
-    #   object. Defaults to the deault API connection in JSS.api
+    # @param cnx [Jamf::Connection] the connection thru which to fetch this
+    #   object. Defaults to the deault API connection in Jamf.cnx
     #
     # @return [REXML::Document] the XML response from the API
     #
-    def self.put_raw(id, xml, api: JSS.api)
+    def self.put_raw(id, xml, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
       validate_not_metaclass(self)
       rsrc = "#{self::RSRC_BASE}/id/#{id}"
-      REXML::Document.new(api.put_rsrc rsrc, xml.to_s)
+      REXML::Document.new(cnx.c_put rsrc, xml.to_s)
     end
 
     # POST some raw XML to the API for a given id in this subclass.
@@ -931,20 +1040,22 @@ module JSS
     # This probably isn't as much of a speed gain as get_raw or put_raw, as
     # opposed to instantiating a ruby object, but might still be useful.
     #
-    # This is really just a wrapper around {APIConnection.post_rsrc} that
+    # This is really just a wrapper around {APIConnection.c_post} that
     # automatically fills in the RSRC::BASE value for you.
     #
     # @param xml [String, #to_s] The XML to send
     #
-    # @param api[JSS::APIConnection] the connection thru which to fetch this
-    #   object. Defaults to the deault API connection in JSS.api
+    # @param cnx [Jamf::Connection] the connection thru which to fetch this
+    #   object. Defaults to the deault API connection in Jamf.cnx
     #
     # @return [REXML::Document] the XML response from the API
     #
-    def self.post_raw( xml, api: JSS.api)
+    def self.post_raw(xml, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
       validate_not_metaclass(self)
       rsrc = "#{self::RSRC_BASE}/id/-1"
-      REXML::Document.new(api.post_rsrc rsrc, xml.to_s)
+      REXML::Document.new(cnx.c_post rsrc, xml.to_s)
     end
 
     # Make a ruby instance of a not-yet-existing APIObject.
@@ -959,24 +1070,30 @@ module JSS
     #
     # @param name[String] The name of this object, generally must be uniqie
     #
-    # @param api[JSS::APIConnection] the connection thru which to make this
-    #   object. Defaults to the deault API connection in JSS.api
+    # @param cnx [Jamf::Connection] the connection thru which to make this
+    #   object. Defaults to the deault API connection in Jamf.cnx
     #
     # @param args[Hash] The data for creating an object, such as name:
     #  See {APIObject#initialize}
     #
     # @return [APIObject] The un-created ruby-instance of a JSS object
     #
-    def self.make(**args)
+    def self.create(**args)
       validate_not_metaclass(self)
       unless constants.include?(:CREATABLE)
-        raise JSS::UnsupportedError, "Creating #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows."
+        raise Jamf::UnsupportedError, "Creating #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows."
       end
       raise ArgumentError, "Use '#{self.class}.fetch id: xx' to retrieve existing JSS objects" if args[:id]
 
-      args[:api] ||= JSS.api
+      args[:api] ||= Jamf.cnx
       args[:id] = :new
-      new args
+      new **args
+    end
+
+    # backward compatability
+    # @deprecated use .create instead
+    def self.make(**args)
+      create **args
     end
 
     # Disallow direct use of ruby's .new class method for creating instances.
@@ -986,7 +1103,7 @@ module JSS
 
       calling_method = caller_locations(1..1).first.label
       unless OK_INSTANTIATORS.include? calling_method
-        raise JSS::UnsupportedError, 'Use .fetch or .make to instantiate APIObject classes'
+        raise Jamf::UnsupportedError, 'Use .fetch or .create to instantiate APIObject classes'
       end
 
       super
@@ -1000,16 +1117,18 @@ module JSS
     # @param victims[Integer,Array<Integer>] An object id or an array of them
     #   to be deleted
     #
-    # @param api[JSS::APIConnection] the API connection to use.
-    #   Defaults to the corrently active API. See {JSS::APIConnection}
+    # @param cnx [Jamf::Connection] the API connection to use.
+    #   Defaults to the corrently active API. See {Jamf::Connection}
     #
     # @return [Array<Integer>] The id's that didn't exist when we tried to
     #   delete them.
     #
-    def self.delete(victims, refresh = true, api: JSS.api)
+    def self.delete(victims, refresh = true, api: nil, cnx: Jamf.cnx)
+      cnx = api if api
+
       validate_not_metaclass(self)
 
-      raise JSS::InvalidDataError, 'Parameter must be an Integer ID or an Array of them' unless victims.is_a?(Integer) || victims.is_a?(Array)
+      raise Jamf::InvalidDataError, 'Parameter must be an Integer ID or an Array of them' unless victims.is_a?(Integer) || victims.is_a?(Array)
 
       case victims
       when Integer
@@ -1019,10 +1138,10 @@ module JSS
       end
 
       skipped = []
-      current_ids = all_ids refresh, api: api
+      current_ids = all_ids refresh, cnx: cnx
       victims.each do |vid|
         if current_ids.include? vid
-          api.delete_rsrc "#{self::RSRC_BASE}/id/#{vid}"
+          cnx.c_delete "#{self::RSRC_BASE}/id/#{vid}"
         else
           skipped << vid
         end # if current_ids include vid
@@ -1030,23 +1149,25 @@ module JSS
 
       # clear any cached all-lists or id-maps for this class
       # so they'll re-cache as needed
-      api.flushcache self::RSRC_LIST_KEY
-      # all :refresh, api: api
+      cnx.flushcache self::RSRC_LIST_KEY
+      # all :refresh, cnx: cnx
 
       skipped
     end # self.delete
 
     # Can't use APIObject directly.
     def self.validate_not_metaclass(klass)
-      raise JSS::UnsupportedError, 'JSS::APIObject is a metaclass. Do not use it directly' if klass == JSS::APIObject
+      raise Jamf::UnsupportedError, 'Jamf::APIObject is a metaclass. Do not use it directly' if klass == Jamf::APIObject
     end
 
     # Attributes
     #####################################
 
-    # @return [JSS::APIConnection] the API connection thru which we deal with
+    # @return [Jamf::Connection] the API connection thru which we deal with
     #   this object.
-    attr_reader :api
+    attr_reader :cnx
+    # @deprecated 'api' to refer to connection objects will be removed eventually
+    alias api cnx
 
     # @return the parsed JSON data retrieved from the API when this object was
     #    fetched
@@ -1074,9 +1195,9 @@ module JSS
 
     # The args hash must include :id, :name, or :data.
     # * :id or :name will be looked up via the API
-    # * * if the subclass includes JSS::Creatable, :id can be :new, to create a new object in the JSS.
+    # * * if the subclass includes Jamf::Creatable, :id can be :new, to create a new object in the JSS.
     #     and :name is required
-    # * :data must be the JSON output of a separate {JSS::APIConnection} query (a Hash of valid object data)
+    # * :data must be the JSON output of a separate {Jamf::Connection} query (a Hash of valid object data)
     #
     # Some subclasses can accept other options, by pasing their keys in a final Array
     #
@@ -1091,8 +1212,9 @@ module JSS
     #
     #
     def initialize(**args)
-      @api = args[:api]
-      @api ||= JSS.api
+      @cnx = args[:cnx]
+      @cnx ||= args[:api]
+      @cnx ||= Jamf.cnx
 
       # we're making a new one in the JSS
       if args[:id] == :new
@@ -1112,6 +1234,18 @@ module JSS
     # Public Instance Methods
     #####################################
 
+    # Ruby 3's default behavior when raising exceptions will include the output
+    # of #inspect, recursively for all data in an object.
+    # For many OAPIObjects, esp JPAPI Resources, this includes the embedded
+    # Connection object and all the caches is might hold, which might be
+    # thousands of lines.
+    # we override that here to prevent that. I've heard rumor this will be
+    # fixed in ruby 3.2
+    # def inspect
+    #   #<Jamf::Policy:0x0000000110138df8
+    #   "<#{self.class}:#{object_id}>"
+    # end
+
     # Either Create or Update this object in the JSS
     #
     # If this item is creatable or updatable, then
@@ -1121,83 +1255,93 @@ module JSS
     #
     def save
       if @in_jss
-        raise JSS::UnsupportedError, 'Updating this object in the JSS is currently not supported by ruby-jss' unless updatable?
+        raise Jamf::UnsupportedError, 'Updating this object in the JSS is currently not supported by ruby-jss' unless updatable?
 
-        update
+        update_in_jamf
       else
-        raise JSS::UnsupportedError, 'Creating this object in the JSS is currently not supported by ruby-jss' unless creatable?
+        raise Jamf::UnsupportedError, 'Creating this object in the JSS is currently not supported by ruby-jss' unless creatable?
 
-        create
+        create_in_jamf
       end
     end
 
+    # @deprecated, use #save
+    def create
+      save
+    end
+
+    # @deprecated, use #save
+    def update
+      save
+    end
+
     # Mix-in Modules.
     # Each module made for mixing in to APIObject subclasses
     # sets an appropriate constant to true.
     # These methods provide a simple way to programattically determine
     # if an object has one of the mixed-in modules available.
 
-    # @return [Boolean] See {JSS::Creatable}
+    # @return [Boolean] See {Jamf::Creatable}
     def creatable?
       defined? self.class::CREATABLE
     end
 
-    # @return [Boolean] See {JSS::Updatable}
+    # @return [Boolean] See {Jamf::Updatable}
     def updatable?
       defined? self.class::UPDATABLE
     end
 
-    # @return [Boolean] See {JSS::Categorizable}
+    # @return [Boolean] See {Jamf::Categorizable}
     def categorizable?
       defined? self.class::CATEGORIZABLE
     end
 
-    # @return [Boolean] See {JSS::VPPable}
+    # @return [Boolean] See {Jamf::VPPable}
     def vppable?
       defined? self.class::VPPABLE
     end
 
-    # @return [Boolean] See {JSS::SelfServable}
+    # @return [Boolean] See {Jamf::SelfServable}
     def self_servable?
       defined? self.class::SELF_SERVABLE
     end
 
-    # @return [Boolean] See {JSS::Criteriable}
+    # @return [Boolean] See {Jamf::Criteriable}
     def criterable?
       defined? self.class::CRITERIABLE
     end
 
-    # @return [Boolean] See {JSS::Sitable}
+    # @return [Boolean] See {Jamf::Sitable}
     def sitable?
       defined? self.class::SITABLE
     end
 
-    # @return [Boolean] See {JSS::extendable}
+    # @return [Boolean] See {Jamf::extendable}
     def extendable?
       defined? self.class::EXTENDABLE
     end
 
-    # @return [Boolean] See {JSS::Matchable}
+    # @return [Boolean] See {Jamf::Matchable}
     def matchable?
       defined? self.class::MATCHABLE
     end
 
-    # @return [Boolean] See {JSS::Locatable}
+    # @return [Boolean] See {Jamf::Locatable}
     def locatable?
       defined? self.class::LOCATABLE
     end
 
-    # @return [Boolean] See {JSS::Purchasable}
+    # @return [Boolean] See {Jamf::Purchasable}
     def purchasable?
       defined? self.class::PURCHASABLE
     end
 
-    # @return [Boolean] See {JSS::Scopable}
+    # @return [Boolean] See {Jamf::Scopable}
     def scopable?
       defined? self.class::SCOPABLE
     end
 
-    # @return [Boolean] See {JSS::Uploadable}
+    # @return [Boolean] See {Jamf::Uploadable}
     def uploadable?
       defined? self.class::UPLOADABLE
     end
@@ -1216,7 +1360,7 @@ module JSS
     def delete
       return unless @in_jss
 
-      @api.delete_rsrc @rest_rsrc
+      @cnx.c_delete @rest_rsrc
 
       @rest_rsrc = "#{self.class::RSRC_BASE}/name/#{CGI.escape @name.to_s}"
       @id = nil
@@ -1225,8 +1369,8 @@ module JSS
 
       # clear any cached all-lists or id-maps for this class
       # so they'll re-cache as needed
-      @api.flushcache self.class::RSRC_LIST_KEY
-      # self.class.all :refresh, api: @api
+      @cnx.flushcache self.class::RSRC_LIST_KEY
+      # self.class.all :refresh, cnx: @cnx
 
       :deleted
     end # delete
@@ -1236,7 +1380,7 @@ module JSS
     # @return [String]
     #
     def to_s
-      "#{self.class}, name: #{@name}, id: #{@id}"
+      "#{self.class}@#{cnx.host}, id: #{@id}"
     end
 
     # Remove the init_data and api object from
@@ -1247,7 +1391,7 @@ module JSS
     #
     def pretty_print_instance_variables
       vars = instance_variables.sort
-      vars.delete :@api
+      vars.delete :@cnx
       vars.delete :@init_data
       vars.delete :@main_subset
       vars
@@ -1259,7 +1403,7 @@ module JSS
     # object type in the OBJECT_HISTORY_TABLE in the database
     # (e.g. for computers, the object type is 1)
     #
-    # NOTE: Object history is not available via the API,
+    # NOTE: Object history is not available via the Classic API,
     #   so access is only available through direct MySQL
     #   connections
     #
@@ -1281,9 +1425,9 @@ module JSS
     def add_object_history_entry(user: nil, notes: nil, details: nil)
       validate_object_history_available
 
-      raise JSS::MissingDataError, 'A user: must be provided to make the entry' unless user
+      raise Jamf::MissingDataError, 'A user: must be provided to make the entry' unless user
 
-      raise JSS::MissingDataError, 'Either notes: must be provided to make the entry' unless notes
+      raise Jamf::MissingDataError, 'notes: must be provided to make the entry' unless notes
 
       user = "'#{Mysql.quote user.to_s}'"
       notes =  "'#{Mysql.quote notes.to_s}'"
@@ -1302,7 +1446,7 @@ module JSS
       VALUES
         (#{value_list})"
 
-      JSS::DB_CNX.db.query q
+      Jamf::DB_CNX.db.query q
     end
 
     # the object history for this object, an array of hashes
@@ -1324,7 +1468,7 @@ module JSS
       AND object_id = #{@id}
       ORDER BY object_history_id ASC"
 
-      result = JSS::DB_CNX.db.query q
+      result = Jamf::DB_CNX.db.query q
       history = []
       result.each do |entry|
         history << {
@@ -1362,11 +1506,11 @@ module JSS
     # @return [void]
     #
     def validate_object_history_available
-      raise JSS::NoSuchItemError, 'Object not yet created' unless @id && @in_jss
+      raise Jamf::NoSuchItemError, 'Object not yet created' unless @id && @in_jss
 
-      raise JSS::InvalidConnectionError, 'Not connected to MySQL' unless JSS::DB_CNX.connected?
+      raise Jamf::InvalidConnectionError, 'Not connected to MySQL' unless Jamf::DB_CNX.connected?
 
-      raise JSS::UnsupportedError, "Object History access is not supported for #{self.class} objects at this time" unless defined? self.class::OBJECT_HISTORY_OBJECT_TYPE
+      raise Jamf::UnsupportedError, "Object History access is not supported for #{self.class} objects at this time" unless defined? self.class::OBJECT_HISTORY_OBJECT_TYPE
     end
 
 
@@ -1382,15 +1526,15 @@ module JSS
     # @return [void]
     #
     def validate_init_for_creation(args)
-      raise JSS::UnsupportedError, "Creating #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless creatable?
+      raise Jamf::UnsupportedError, "Creating #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless creatable?
 
-      raise JSS::MissingDataError, "You must provide a :name to create a #{self.class::RSRC_OBJECT_KEY}." unless args[:name]
+      raise Jamf::MissingDataError, "You must provide a :name to create a #{self.class::RSRC_OBJECT_KEY}." unless args[:name]
 
       return if defined? self.class::NON_UNIQUE_NAMES
 
-      matches = self.class.all_names(:refresh, api: @api).select { |n| n.casecmp? args[:name] }
+      matches = self.class.all_names(:refresh, cnx: @cnx).select { |n| n.casecmp? args[:name] }
 
-      raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} already exists with the name '#{args[:name]}'" unless matches.empty?
+      raise Jamf::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} already exists with the name '#{args[:name]}'" unless matches.empty?
 
     end
 
@@ -1412,10 +1556,10 @@ module JSS
       raw_json =
         if defined? self.class::USE_XML_WORKAROUND
           # if we're here, the API JSON is borked, so use the XML
-          JSS::XMLWorkaround.data_via_xml rsrc, self.class::USE_XML_WORKAROUND, @api
+          Jamf::XMLWorkaround.data_via_xml rsrc, self.class::USE_XML_WORKAROUND, @cnx
         else
           # otherwise
-          @api.get_rsrc(rsrc)
+          @cnx.c_get(rsrc)
         end
 
       raw_json[args[:rsrc_object_key]]
@@ -1569,116 +1713,12 @@ module JSS
     # Most classes will redefine this method.
     #
     def rest_xml
-      doc = REXML::Document.new JSS::APIConnection::XML_HEADER
+      doc = REXML::Document.new Jamf::Connection::XML_HEADER
       tmpl = doc.add_element self.class::RSRC_OBJECT_KEY.to_s
       tmpl.add_element('name').text = @name
       doc.to_s
     end
 
-    # Meta Programming
-    ####################################################
-
-    # Loop through the defined lookup keys and make
-    # .all_<key>s methods for each one, with
-    # alises as needed.
-    #
-    # This is called automatically in api_object.rb
-    # after all subclasses are loaded.
-    #
-    def self.define_identifier_list_methods
-      return unless @subclasses
-
-      @subclasses.each do |subclass|
-        subclass.lookup_keys.each do |als, key|
-          meth_name = "all_#{key}s"
-
-          if als == key
-            # the all_ method - skip if defined in the class
-            next if subclass.instance_methods.include? meth_name
-
-            subclass.define_singleton_method meth_name do |refresh = false, api: JSS.api|
-              all(refresh, api: api).map { |i| i[key] }
-            end
-
-          else
-            # an alias - skip if defined in the class
-            als_name = "all_#{als}s"
-            next if subclass.instance_methods.include? als_name
-
-            subclass.define_singleton_method als_name do |refresh = false, api: JSS.api|
-              send meth_name, refresh, api: api
-            end
-          end # if
-        end # lookup_keys.each
-      end # @subclasses.each
-    end # self.define_identifier_list_methods
-
   end # class APIObject
 
-end # module JSS
-
-### Mix-in Sub Modules
-require 'jss/api_object/creatable'
-require 'jss/api_object/uploadable'
-require 'jss/api_object/locatable'
-require 'jss/api_object/matchable'
-require 'jss/api_object/purchasable'
-require 'jss/api_object/updatable'
-require 'jss/api_object/extendable'
-require 'jss/api_object/self_servable'
-require 'jss/api_object/categorizable'
-require 'jss/api_object/vppable'
-require 'jss/api_object/sitable'
-require 'jss/api_object/mdm'
-require 'jss/api_object/management_history'
-
-### Mix-in Sub Modules with Classes
-require 'jss/api_object/criteriable'
-require 'jss/api_object/scopable'
-
-### APIObject SubClasses with SubClasses
-require 'jss/api_object/advanced_search'
-require 'jss/api_object/configuration_profile'
-require 'jss/api_object/extension_attribute'
-require 'jss/api_object/group'
-require 'jss/api_object/patch_source'
-
-### APIObject SubClasses without SubClasses
-require 'jss/api_object/account'
-require 'jss/api_object/building'
-require 'jss/api_object/category'
-require 'jss/api_object/computer'
-require 'jss/api_object/computer_invitation'
-require 'jss/api_object/department'
-require 'jss/api_object/disk_encryption_configurations'
-require "jss/api_object/directory_binding_type"
-require 'jss/api_object/directory_binding'
-require 'jss/api_object/distribution_point'
-require 'jss/api_object/ebook'
-require 'jss/api_object/ibeacon'
-require 'jss/api_object/dock_item'
-require 'jss/api_object/ldap_server'
-require 'jss/api_object/mac_application'
-require 'jss/api_object/mobile_device'
-require 'jss/api_object/mobile_device_application'
-require 'jss/api_object/netboot_server'
-require 'jss/api_object/network_segment'
-require 'jss/api_object/package'
-require 'jss/api_object/patch_title'
-require 'jss/api_object/patch_policy'
-require 'jss/api_object/peripheral_type'
-require 'jss/api_object/peripheral'
-require 'jss/api_object/policy'
-require 'jss/api_object/removable_macaddr'
-require 'jss/api_object/restricted_software'
-require 'jss/api_object/script'
-require 'jss/api_object/site'
-require 'jss/api_object/software_update_server'
-require 'jss/api_object/user'
-require 'jss/api_object/webhook'
-require 'jss/api_object/printer'
-
-### Other
-require 'jss/api_object/app_store_country_codes'
-
-JSS::APIObject.define_identifier_list_methods
+end # module Jamf