ruby-jss 0.9.2 → 0.10.0a1

data/lib/jss/server.rb

@@ -26,13 +26,14 @@
 ###
 module JSS
 
-  # A class representing the currently-connected JSS Server.
+  # A class representing the currently-connected JSS Server in a
+  # JSS::APIConnection instance.
   #
   # The {JSS::APIConnection} instance has a JSS::Server instance in its #server
   # attribute. It is created fresh every time {APIConnection#connect} is called.
   #
   # That's the only time it should be instantiated, and all access should be
-  # through {JSS.api_connection.server}
+  # through the #server attribute of the APIConnection instance.
   #
   class Server
 
@@ -66,6 +67,10 @@ module JSS
     #  @return [String]
     attr_reader :raw_version
 
+    # @return [JSS::APIConnection] The APIConnection object that contains this
+    #   instance of Server
+    attr_reader :api
+
     # Instance Methods
     #####################################
 
@@ -77,8 +82,12 @@ module JSS
     # However, it's marked as 'deprecated'. Hopefully jamf will
     # keep this basic level of info available for basic authentication
     # and JSS version checking.
-    def initialize(jss_data)
-
+    #
+    # The 'api' is a reference to the JSS::APIConnection instance
+    # which this JSS::Server instance is a part of.
+    #
+    def initialize(jss_data, api)
+      @api = api
       @license_type = jss_data[:license_type]
       @product = jss_data[:product]
       @raw_version = jss_data[:version]
@@ -91,16 +100,28 @@ module JSS
 
     # @return [String] the organization to which the server is licensed
     def organization
-      @act_code_data ||= JSS.api_connection.get_rsrc(ACTIVATION_CODE_RSRC)[ACTIVATION_CODE_KEY]
+      @act_code_data ||= @api.get_rsrc(ACTIVATION_CODE_RSRC)[ACTIVATION_CODE_KEY]
       @act_code_data[:organization_name]
     end
 
     # @return [String] the activation code for the server licence
     def activation_code
-      @act_code_data ||= JSS.api_connection.get_rsrc(ACTIVATION_CODE_RSRC)[ACTIVATION_CODE_KEY]
+      @act_code_data ||= @api.get_rsrc(ACTIVATION_CODE_RSRC)[ACTIVATION_CODE_KEY]
       @act_code_data[:code]
     end
 
+    # Remove the 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
+    end
+
     ##### Aliases
     alias institution organization
     alias product_name product

data/lib/jss/utility.rb

@@ -264,6 +264,50 @@ module JSS
     Time.at(epoch.to_i / 1000.0)
   end # parse_date
 
+  # Given a name, singular or plural, of a JSS::APIObject subclass as a String
+  # or Symbol (e.g. :computer/'computers'), return the class itself
+  # (e.g. JSS::Computer)
+  # The available names are the RSRC_LIST_KEY
+  # and RSRC_OBJECT_KEY values for each APIObject subclass.
+  #
+  # @seealso JSS.api_object_names
+  #
+  # @param name[String,Symbol] The name of a JSS::APIObject subclass, singluar
+  #   or plural
+  #
+  # @return [Class] The class
+  #
+  def self.api_object_class(name)
+    klass = api_object_names[name.downcase.to_sym]
+    raise JSS::InvalidDataError, "Unknown API Object Class: #{name}" unless klass
+    klass
+  end
+
+  # APIObject subclasses have singular names, and are, of course
+  # capitalized, e.g. 'Computer'
+  # But we often want to refer to them in the plural, or lowercase,
+  # e.g. 'computers'
+  # This method returns a Hash of the RSRC_LIST_KEY (a plural symbol)
+  # and the RSRC_OBJECT_KEY (a singular symbol) of each APIObject
+  # subclass, keyed to the class itself, such that both :computer
+  # and :computers are keys for JSS::Computer and both :policy and
+  # :policies are keys for JSS::Policy, and so on.
+  #
+  # @return [Hash] APIObject subclass names to Classes
+  #
+  def self.api_object_names
+    return @api_object_names if @api_object_names
+    @api_object_names ||= {}
+    JSS.constants.each do |const|
+      klass = JSS.const_get const
+      next unless klass.is_a? Class
+      next unless klass.ancestors.include? JSS::APIObject
+      @api_object_names[klass.const_get(:RSRC_LIST_KEY).to_sym] = klass if klass.constants.include? :RSRC_LIST_KEY
+      @api_object_names[klass.const_get(:RSRC_OBJECT_KEY).to_sym] = klass if klass.constants.include? :RSRC_OBJECT_KEY
+    end
+    @api_object_names
+  end
+
   # Given a string of xml element text, escape any characters that would make XML unhappy.
   #   * & => &
   #   * " => "

data/lib/jss/validate.rb

@@ -0,0 +1,85 @@
+# Copyright 2017 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 JSS
+
+  # A collection of methods for validating values. Mostly for
+  # ensuring the validity of data being set as attributes of APIObject
+  # subclass instances.
+  #
+  # Some of these methods can take multiple input types, such as a String
+  # or an Array.  All of them will either raise an exception
+  # if the value isn't valid, or will return a standardized form of the input
+  # (e.g. an Array, even if given a String)
+  #
+  module Validate
+
+    # The regular expression that matches a valid MAC address.
+    MAC_ADDR_RE = /^[a-f0-9]{2}(:[a-f0-9]{2}){5}$/i
+
+    # Validate the format and content of a MAC address
+    #
+    # @param val[String] The value to validate
+    #
+    # @return [String] The valid value
+    #
+    def self.mac_address(val)
+      raise JSS::InvalidDataError, "Not a valid MAC address: '#{val}'" unless val =~ MAC_ADDR_RE
+      val
+    end
+
+    # Validate the format and content of an IPv4 address
+    #
+    # @param val[String] The value to validate
+    #
+    # @return [String] The valid value
+    #
+    def self.ip_address(val)
+      ok = true
+      parts = val.strip.split '.'
+      ok = false unless parts.size == 4
+      parts.each { |p| ok = false unless p.jss_integer? && p.to_i < 256 }
+      raise JSS::InvalidDataError, "Not a valid IPv4 address: '#{val}'" unless ok
+      val
+    end
+
+    # Validate that a value doesn't already exist for a given identifier of a given class
+    #
+    # @param klass[JSS::APIObject] A subclass of JSS::APIObject, e.g. JSS::Computer
+    #
+    # @param identifier[Symbol] One of the keys of an Item of the class's #all Array
+    #
+    # @param val[Object] The value to check for uniqueness
+    #
+    # @return [Object] the validated unique value
+    #
+    def self.unique_identifier(klass, identifier, val)
+      raise JSS::AlreadyExistsError, "A #{klass} already exists with #{identifier} '#{val}'" if klass.all.map { |i| i[identifier] }.include? val
+      val
+    end
+
+  end # module validate
+
+end # module JSS

data/lib/jss/version.rb

@@ -27,6 +27,6 @@
 module JSS
 
   ### The version of the JSS ruby gem
-  VERSION = '0.9.2'.freeze
+  VERSION = '0.10.0a1'.freeze
 
 end # module

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-jss
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.10.0a1
 platform: ruby
 authors:
 - Chris Lasell
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-25 00:00:00.000000000 Z
+date: 2017-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: plist
@@ -181,6 +181,7 @@ files:
 - lib/jss/ruby_extensions/time.rb
 - lib/jss/server.rb
 - lib/jss/utility.rb
+- lib/jss/validate.rb
 - lib/jss/version.rb
 - lib/ruby-jss.rb
 homepage: http://pixaranimationstudios.github.io/ruby-jss/
@@ -203,9 +204,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.6.8