ruby-jss 0.9.2 → 0.10.0a1

data/lib/jss/api_object.rb

@@ -142,22 +142,29 @@ module JSS
     # class methods for accessing those other values as mapped Arrays,
     # e.g. JSS::Computer.all_udids
     #
-    # The results of the first query for each subclass is stored in JSS.api.object_list_cache
-    # and returned at every future call, so as to not requery the server every time.
+    # The results of the first query for each subclass is stored in the .object_list_cache
+    # of the given JSS::APIConnection and returned at every future call, so as
+    # to not requery the server every time.
     #
     # To force requerying to get updated data, provided a non-false argument.
     # I usually use :refresh, so that it's obvious what I'm doing, but true, 1,
     # or anything besides false or nil will work.
     #
+    # To query an APIConnection other than the currently active one,
+    # provide one via the api: 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}
+    #
     # @return [Array<Hash{:name=>String, :id=> Integer}>]
     #
-    def self.all(refresh = false)
+    def self.all(refresh = false, api: JSS.api)
       raise JSS::UnsupportedError, '.all can only be called on subclasses of JSS::APIObject' if self == JSS::APIObject
-      JSS.api.object_list_cache[self::RSRC_LIST_KEY] = nil if refresh
-      return JSS.api.object_list_cache[self::RSRC_LIST_KEY] if JSS.api.object_list_cache[self::RSRC_LIST_KEY]
-      JSS.api.object_list_cache[self::RSRC_LIST_KEY] = JSS.api.get_rsrc(self::RSRC_BASE)[self::RSRC_LIST_KEY]
+      api.object_list_cache[self::RSRC_LIST_KEY] = nil if refresh
+      return api.object_list_cache[self::RSRC_LIST_KEY] if api.object_list_cache[self::RSRC_LIST_KEY]
+      api.object_list_cache[self::RSRC_LIST_KEY] = api.get_rsrc(self::RSRC_BASE)[self::RSRC_LIST_KEY]
     end
 
     # Returns an Array of the JSS id numbers of all the members
@@ -168,10 +175,13 @@ module JSS
     #
     # @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}
+    #
     # @return [Array<Integer>] the ids of all it1ems of this subclass in the JSS
     #
-    def self.all_ids(refresh = false)
-      all(refresh).map { |i| i[:id] }
+    def self.all_ids(refresh = false, api: JSS.api)
+      all(refresh, api: api).map { |i| i[:id] }
     end
 
     # Returns an Array of the JSS names of all the members
@@ -182,10 +192,13 @@ module JSS
     #
     # @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}
+    #
     # @return [Array<String>] the names of all item of this subclass in the JSS
     #
-    def self.all_names(refresh = false)
-      all(refresh).map { |i| i[:name] }
+    def self.all_names(refresh = false, api: JSS.api)
+      all(refresh, api: api).map { |i| i[:name] }
     end
 
     # Return a hash of all objects of this subclass
@@ -212,11 +225,14 @@ 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}
+    #
     # @return [Hash{Integer => Oject}] the associated ids and data
     #
-    def self.map_all_ids_to(other_key, refresh = false)
+    def self.map_all_ids_to(other_key, refresh = false, api: JSS.api)
       h = {}
-      all(refresh).each { |i| h[i[:id]] = i[other_key] }
+      all(refresh, api: api).each { |i| h[i[:id]] = i[other_key] }
       h
     end
 
@@ -229,55 +245,56 @@ 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}
+    #
     # @return [Hash{Integer => Object}] the objects requested
-    def self.all_objects(refresh = false)
+    #
+    def self.all_objects(refresh = false, api: JSS.api)
       objects_key = "#{self::RSRC_LIST_KEY}_objects".to_sym
-      JSS.api.object_list_cache[objects_key] = nil if refresh
-      return JSS.api.object_list_cache[objects_key] if JSS.api.object_list_cache[objects_key]
-      JSS.api.object_list_cache[objects_key] = all(refresh).map { |o| new id: o[:id] }
+      return api.object_list_cache[objects_key] unless refresh || api.object_list_cache[objects_key].nil?
+      api.object_list_cache[objects_key] = all(refresh, api: api).map { |o| fetch id: o[:id], api: api }
     end
 
     # Return true or false if an object of this subclass
-    # with the given name or id exists on the server
+    # with the given Identifier exists on the server
     #
-    # @param identfier [String,Integer] The name or id of object to check for
+    # @param identfier [String,Integer] An identifier for an object, a value for
+    # one of the available lookup_keys
     #
     # @param refresh [Boolean] Should the data be re-read from the server
     #
-    # @return [Boolean] does an object with the given name or id exist?
+    # @param api[JSS::APIConnection] an API connection to use for the query.
+    #   Defaults to the corrently active API. See {JSS::APIConnection}
     #
-    def self.exist?(identfier, refresh = false)
-      case identfier
-      when Integer
-        all_ids(refresh).include? identfier
-      when String
-        all_names(refresh).include? identfier
-      else
-        raise ArgumentError, 'Identifier must be a name (String) or id (Integer)'
-      end
+    # @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?
     end
 
     # Return an id or nil if an object of this subclass
     # with the given name or id exists on the server
     #
-    # Subclasses may want to override this method to support more
-    # identifiers than name and id.
-    #
-    # @param identfier [String,Integer] The name or id of object to check for
+    # @param identfier [String,Integer] An identifier for an object, a value for
+    # one of the available lookup_keys
     #
     # @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}
+    #
     # @return [Integer, nil] the id of the matching object, or nil if it doesn't exist
     #
-    def self.valid_id(identfier, refresh = false)
-      case identfier
-      when Integer
-        return identfier if all_ids(refresh).include? identfier
-      when String
-        return map_all_ids_to(:name).invert[identfier] if all_names(refresh).include? identfier
-      else
-        raise ArgumentError, 'Identifier must be a name (String) or id (Integer)'
-      end
+    def self.valid_id(identifier, refresh = false, api: JSS.api)
+      return identifier if all_ids(refresh, api: api).include? identifier
+      id = nil
+      all_lookup_keys.keys.each do |key|
+        next if key == :id
+        id = map_all_ids_to(key).invert[identifier]
+        return id if id
+      end # do key
+      id
     end
 
     # Convert an Array of Hashes of API object data to a
@@ -377,26 +394,32 @@ module JSS
     #
     def self.rsrc_keys
       hash = {}
-      all_keys = if defined?(self::OTHER_LOOKUP_KEYS)
-                   DEFAULT_LOOKUP_KEYS.merge self::OTHER_LOOKUP_KEYS
-                 else
-                   DEFAULT_LOOKUP_KEYS
-                 end
-      all_keys.each { |key, deets| hash[key] = deets[:rsrc_key]}
+      all_lookup_keys.each { |key, deets| hash[key] = deets[:rsrc_key] }
       hash
     end
 
+    # the available list methods for an APIObject sublcass
+    #
+    # @return [Array<Symbol>] The list methods (e.g. .all_serial_numbers) for
+    # this APIObject subclass
+    #
+
+    # The combined DEFAULT_LOOKUP_KEYS and OTHER_LOOKUP_KEYS
+    # (which may be defined in subclasses)
+    #
+    # @return [Hash] See DEFAULT_LOOKUP_KEYS constant
+    #
+    def self.all_lookup_keys
+      return DEFAULT_LOOKUP_KEYS.merge(self::OTHER_LOOKUP_KEYS) if defined? self::OTHER_LOOKUP_KEYS
+      DEFAULT_LOOKUP_KEYS
+    end
+
     # @return [Hash] the available lookup keys mapped to the appropriate
     #  list class method (e.g. id: :all_ids )
     #
     def self.lookup_key_list_methods
       hash = {}
-      all_keys = if defined?(self::OTHER_LOOKUP_KEYS)
-                   DEFAULT_LOOKUP_KEYS.merge self::OTHER_LOOKUP_KEYS
-                 else
-                   DEFAULT_LOOKUP_KEYS
-                 end
-      all_keys.each { |key, deets| hash[key] = deets[:list]}
+      all_lookup_keys.each { |key, deets| hash[key] = deets[:list] }
       hash
     end
 
@@ -414,13 +437,14 @@ module JSS
     #
     # @return [APIObject] The ruby-instance of a JSS object
     #
-    def self.fetch(arg)
+    def self.fetch(arg, api: JSS.api)
       raise JSS::UnsupportedError, 'JSS::APIObject cannot be instantiated' if self.class == JSS::APIObject
 
       # if given a hash (or a colletion of named params)
       # pass to .new
       if arg.is_a? Hash
-        raise ArgumentError, 'Use .create to create new JSS objects' if arg[:id] == :new
+        raise ArgumentError, 'Use .make to create new JSS objects' if arg[:id] == :new
+        api = arg[:api] if arg[:api]
         return new arg
       end
 
@@ -428,7 +452,7 @@ module JSS
       # and if it's result includes the desired value,
       # the pass they key and arg to .new
       lookup_key_list_methods.each do |key, method_name|
-        return new({key => arg}) if self.send(method_name).include? arg
+        return new ({ key => arg, :api => api }) if method_name && send(method_name).include?(arg)
       end # each key
 
       # if we're here, we couldn't find a matching object
@@ -451,7 +475,8 @@ module JSS
     #
     # @return [APIObject] The un-created ruby-instance of a JSS object
     #
-    def self.make(args = {})
+    def self.make(**args)
+      args[:api] ||= JSS.api
       raise JSS::UnsupportedError, 'JSS::APIObject cannot be instantiated' if self.class == JSS::APIObject
       raise ArgumentError, "Use '#{self.class}.fetch id: xx' to retrieve existing JSS objects" if args[:id]
       args[:id] = :new
@@ -464,7 +489,7 @@ module JSS
     # These Symbols are added to VALID_DATA_KEYS for performing the
     # :data validity test described above.
     #
-    REQUIRED_DATA_KEYS = [:id, :name].freeze
+    REQUIRED_DATA_KEYS = %i[id name].freeze
 
     # All API objects have an id and a name. As such By these keys are available
     # for object lookups.
@@ -473,6 +498,7 @@ module JSS
     # which has the same format, described here:
     #
     # The merged Hashes DEFAULT_LOOKUP_KEYS and OTHER_LOOKUP_KEYS
+    # (as provided by the .all_lookup_keys Class method)
     # define what unique identifiers can be passed as parameters to the
     # fetch method for retrieving an object from the API.
     # They also define the class methods that return a list (Array) of all such
@@ -494,13 +520,21 @@ module JSS
     # }
     #
     DEFAULT_LOOKUP_KEYS = {
-      id: {rsrc_key: :id, list: :all_ids},
-      name: {rsrc_key: :name, list: :all_names}
+      id: { rsrc_key: :id, list: :all_ids },
+      name: { rsrc_key: :name, list: :all_names }
     }.freeze
 
     # Attributes
     #####################################
 
+    # @return [JSS::APIConnection] the API connection thru which we deal with
+    #   this object.
+    attr_reader :api
+
+    # @return the parsed JSON data retrieved from the API when this object was
+    #    fetched
+    attr_reader :init_data
+
     # @return [Integer] the JSS id number
     attr_reader :id
 
@@ -535,7 +569,8 @@ module JSS
     #
     #
     def initialize(args = {})
-
+      args[:api] ||= JSS.api
+      @api = args[:api]
       raise JSS::UnsupportedError, 'JSS::APIObject cannot be instantiated' if self.class == JSS::APIObject
 
       ####### Previously looked-up JSON data
@@ -559,7 +594,6 @@ module JSS
         @init_data = look_up_object_data(args)
       end ## end arg parsing
 
-
       parse_init_data
       @need_to_update = false
     end # init
@@ -652,6 +686,9 @@ module JSS
 
     # Delete this item from the JSS.
     #
+    # TODO: Make a class method for mass deletion
+    # without instantiating, then call it from this method.
+    #
     # Subclasses may want to redefine this method,
     # first calling super, then setting other attributes to
     # nil, false, empty, etc..
@@ -660,7 +697,7 @@ module JSS
     #
     def delete
       return nil unless @in_jss
-      JSS.api.delete_rsrc @rest_rsrc
+      @api.delete_rsrc @rest_rsrc
       @rest_rsrc = "#{self.class::RSRC_BASE}/name/#{CGI.escape @name}"
       @id = nil
       @in_jss = false
@@ -676,6 +713,19 @@ module JSS
       "#{self.class}, name: #{@name}, id: #{@id}"
     end
 
+    # Remove the init_data and api object from
+    # the instance_variables used to create
+    # pretty-print (pp) output.
+    #
+    # @return [Array] the desired instance_variables
+    #
+    def pretty_print_instance_variables
+      vars = instance_variables.sort
+      vars.delete :@api
+      vars.delete :@init_data
+      vars
+    end
+
     # Private Instance Methods
     #####################################
     private
@@ -702,7 +752,7 @@ module JSS
       end
       # and the id must be in the jss
       raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} with JSS id: #{@init_data[:id]}" unless \
-        self.class.all_ids.include? hash_to_check[:id]
+        self.class.all_ids(api: @api).include? hash_to_check[:id]
     end # validate_init_data
 
     # If we're making a new object in the JSS, make sure we were given
@@ -719,9 +769,9 @@ module JSS
     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 JSS::MissingDataError, "You must provide a :name to create a #{self.class::RSRC_OBJECT_KEY}."  unless args[:name]
+      raise JSS::MissingDataError, "You must provide a :name to create a #{self.class::RSRC_OBJECT_KEY}." unless args[:name]
 
-      raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} already exists with the name '#{args[:name]}'" if self.class.all_names.include? args[:name]
+      raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} already exists with the name '#{args[:name]}'" if self.class.all_names(api: @api).include? args[:name]
     end
 
     # Given initialization args, perform an API lookup for an object.
@@ -743,7 +793,7 @@ module JSS
       # e.g. User when loookup is by email.
       rsrc_object_key = args[:rsrc_object_key] ? args[:rsrc_object_key] : self.class::RSRC_OBJECT_KEY
 
-      return JSS.api.get_rsrc(rsrc)[rsrc_object_key]
+      return @api.get_rsrc(rsrc)[rsrc_object_key]
     rescue RestClient::ResourceNotFound
       raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} found matching: #{rsrc_key}/#{args[lookup_key]}"
     end
@@ -767,6 +817,7 @@ module JSS
 
       # many things have  a :site
       # TODO: Implement a Sitable mixin module
+      #
       @site = JSS::APIObject.get_name(@main_subset[:site]) if @main_subset[:site]
 
       ##### Handle Mix-ins
@@ -792,7 +843,7 @@ module JSS
     def find_main_subset
       return @init_data if @init_data[:id] && @init_data[:name]
       return @init_data[:general] if @init_data[:general] && @init_data[:general][:id] && @init_data[:general][:name]
-      @init_data.each do |key, value|
+      @init_data.each do |_key, value|
         next unless value.is_a? Hash
         return value if value.keys.include?(:id) && value.keys.include?(:name)
       end

data/lib/jss/api_object/account.rb

@@ -72,33 +72,33 @@ module JSS
     #####################################
 
     # @return [Array<Hash>] all JSS account users
-    def self.all_users(refresh = false)
-      all(refresh)[:users]
+    def self.all_users(refresh = false, api: JSS.api)
+      all(refresh, api: api)[:users]
     end
 
     # @return [Array<Hash>] all JSS account user ids
-    def self.all_user_ids(refresh = false)
-      all(refresh)[:users].map { |i| i[:id] }
+    def self.all_user_ids(refresh = false, api: JSS.api)
+      all(refresh, api: api)[:users].map { |i| i[:id] }
     end
 
     # @return [Array<Hash>] all JSS account user names
-    def self.all_user_names(refresh = false)
-      all(refresh)[:users].map { |i| i[:name] }
+    def self.all_user_names(refresh = false, api: JSS.api)
+      all(refresh, api: api)[:users].map { |i| i[:name] }
     end
 
     # @return [Array<Hash>] all JSS account groups
-    def self.all_groups(refresh = false)
-      all(refresh)[:groups]
+    def self.all_groups(refresh = false, api: JSS.api)
+      all(refresh, api: api)[:groups]
     end
 
     # @return [Array<Hash>] all JSS account group ids
-    def self.all_group_ids(refresh = false)
-      all(refresh)[:groups].map { |i| i[:id] }
+    def self.all_group_ids(refresh = false, api: JSS.api)
+      all(refresh, api: api)[:groups].map { |i| i[:id] }
     end
 
     # @return [Array<Hash>] all JSS account group names
-    def self.all_group_names(refresh = false)
-      all(refresh)[:groups].map { |i| i[:name] }
+    def self.all_group_names(refresh = false, api: JSS.api)
+      all(refresh, api: api)[:groups].map { |i| i[:name] }
     end
 
     # Attributes

data/lib/jss/api_object/advanced_search.rb

@@ -167,11 +167,11 @@ module JSS
       raise JSS::InvalidDataError, 'JSS::Criteriable::Criteria instance required' unless @criteria.is_a? JSS::Criteriable::Criteria
       raise JSS::InvalidDataError, 'display_fields must be an Array.' unless @display_fields.is_a? Array
 
-      orig_timeout = JSS.api_connection.cnx.options[:timeout]
-      JSS.api_connection.timeout = 1800
+      orig_timeout = @api.cnx.options[:timeout]
+      @api.timeout = 1800
       super()
       requery_search_results if get_results
-      JSS.api_connection.timeout = orig_timeout
+      @api.timeout = orig_timeout
 
       @id # remember to return the id
     end
@@ -185,11 +185,11 @@ module JSS
     # @return [Integer] the id of the updated search
     #
     def update(get_results = false)
-      orig_timeout = JSS.api_connection.cnx.options[:timeout]
-      JSS.api_connection.timeout = 1800
+      orig_timeout = @api.cnx.options[:timeout]
+      @api.timeout = 1800
       super()
       requery_search_results if get_results
-      JSS.api_connection.timeout = orig_timeout
+      @api.timeout = orig_timeout
 
       @id # remember to return the id
     end
@@ -201,17 +201,17 @@ module JSS
     # @return [Array<Hash>] the new search results
     #
     def requery_search_results
-      orig_open_timeout = JSS.api_connection.cnx.options[:open_timeout]
-      orig_timeout = JSS.api_connection.cnx.options[:timeout]
-      JSS.api_connection.timeout = 1800
-      JSS.api_connection.open_timeout = 1800
+      orig_open_timeout = @api.cnx.options[:open_timeout]
+      orig_timeout = @api.cnx.options[:timeout]
+      @api.timeout = 1800
+      @api.open_timeout = 1800
       begin
         requery = self.class.new(id: @id)
         @search_results = requery.search_results
         @result_display_keys = requery.result_display_keys
       ensure
-        JSS.api_connection.timeout = orig_timeout
-        JSS.api_connection.open_timeout = orig_open_timeout
+        @api.timeout = orig_timeout
+        @api.open_timeout = orig_open_timeout
       end
     end