ruby-jss 1.2.3 → 1.2.4a1

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

@@ -0,0 +1,39 @@
+# Copyright 2019 Pixar
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+module Jamf
+
+  # This mixin overrides JSONObject.mutable? to return false,
+  # meaning that no setters are ever defined, and if the
+  # object is a Jamf::Resource, #save will raise an error
+  #
+  module Immutable
+
+    def mutable?
+      false
+    end
+
+  end # Lockable
+
+end # Jamf

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

@@ -0,0 +1,124 @@
+# Copyright 2019 Pixar
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+module Jamf
+
+  # Classes mixing this in have a Jamf::Location instance in their :location
+  # attribute.
+  #
+  # See the Jamf::JSONObject docs for OBJECT_MODEL for defining the
+  # :location attribute. It should always be marked `readonly: true`,
+  # since attempting to set the location as a whole will raise an error.
+  #
+  # Instead of setting it as a whole, you must use the Jamf::Location object
+  # stored in the :location attribute to access it's values, like so:
+  #
+  #   mycomputer.location.department # => 'Muggle Studies'
+  #   mycomputer.location.room = 'Great Hall'
+  #
+  # All location attributes can be set that way, but building, room, department,
+  # & phoneNumber are more related to the physical location, so must be used
+  # that way.
+  #
+  # The other attributes, username, realName, position, and emailAddress, are
+  # more related to the assinged user than the physical location, and are also
+  # acessible via the #user method, which returns a simple wrapper for those
+  # attributes, like this:
+  #
+  #   mycomputer.user.name  # => 'adumble'   user.username works too
+  #   mycomputer.user.realName = 'Albus Dumbledore'
+  #   mycomputer.user.position = 'Headmaster'
+  #   mycomputer.user.emailAddress = 'adumble@hogwarts.edu.uk'
+  #
+  # are more related to the machine and its physical location
+  # than to the user responsible for the machine.
+  #
+  module Locatable
+
+    def location=(_loc)
+      raise Jamf::UnsupportedError, 'Location cannot be set as a whole, set its attributes individually'
+    end
+
+    def user
+      @location_user ||= Jamf::Locatable::User.new(self)
+    end
+
+    # a class for user-specific data in a Location object
+    class User
+
+      def initialize(assigned_object)
+        @assigned_object = assigned_object
+      end
+
+      def username
+        @assigned_object.location.username
+      end
+      alias name username
+
+      def username=(val)
+        @assigned_object.location.username = val
+      end
+      alias name= username=
+
+      def realName
+        @assigned_object.location.realName
+      end
+
+      def realName=(val)
+        @assigned_object.location.realName = val
+      end
+
+      def emailAddress
+        @assigned_object.location.emailAddress
+      end
+
+      def emailAddress=(val)
+        @assigned_object.location.emailAddress = val
+      end
+
+      def position
+        @assigned_object.location.position
+      end
+
+      def position=(val)
+        @assigned_object.location.position = val
+      end
+
+      # Remove large cached items 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 :@assigned_object
+        vars
+      end
+
+    end # class user
+
+  end # locatable
+
+end # Jamf

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

@@ -0,0 +1,48 @@
+# Copyright 2019 Pixar
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+module Jamf
+
+  # Classes mixing this in have a 'versionLock' attribute and implement
+  # 'Optimistic Locking'
+  #  https://stackoverflow.com/questions/129329/optimistic-vs-pessimistic-locking/129397#129397
+  #
+  # When the object is saved, the versionLock is sent back with the data
+  # and if it doesn't match whats on the server, then the object has been updated
+  # from elsewhere since we fetched it, and a 409 Conflict error is raised with
+  # the reason OPTIMISTIC_LOCK_FAILED.
+  #
+  # If that happens, the save doesnt happen, the object is re-fetched,
+  # and the user can try again.
+  #
+  module Lockable
+
+    def initialize(data, cnx: Jamf.cnx)
+      @versionLock = data[:versionLock]
+      super
+    end
+
+  end # Lockable
+
+end # Jamf

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

@@ -0,0 +1,92 @@
+# Copyright 2019 Pixar
+
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+module Jamf
+
+  # CollectionResource Class instances with this module mixed-in can be
+  # referred to in other classes.
+  #
+  # Doing so dynamically defines a new 'Reference' class, which is a
+  # subclass of {Jamf::GenericReference}
+  #
+  # Examples:
+  #
+  # 1) A Policy can have a category assigned to it, and the policy's API data
+  # will contain a reference to a category.
+  #
+  # Jamf::Policy instances have a :category attribute, which contains an
+  # instance of Jamf::Category::Reference
+  #
+  # Mixing Referable into Jamf::Category automatically creates the class
+  # Jamf::Category::Reference
+  #
+  # 2) The API data for a Jamf::ComputerGroup contains a an Array of references
+  # to member Jamf::Computers. That Array arrives in JSON like this:
+  #
+  #  computers: [
+  #    { id: 234, name: 'foobar' },
+  #    { id: 698, name: 'barfoo' }
+  #  ]
+  #
+  # Mixing Referable into Jamf::Computer defines the class
+  # Jamf::Computer::Reference and allows Jamf::ComputerGroups to maintain an
+  # array of Jamf::Computer::Reference objects representing that list.
+  # When needed to send to the API, it will send this:
+  #
+  #  computers: [
+  #    { id: 234 },
+  #    { id: 698 }
+  #  ]
+  #
+  # Parsing the API data into Reference instances, and converting them back for
+  # the API is handled by the Reference class.
+  #
+  # TODO: Handle if any references contain keys other than :id and :name.
+  #
+  module Referable
+
+    # this will hopefully autoload generic_reference
+    GENREF = Jamf::GenericReference
+
+    # This is run when Referable is included in some class 'referent'
+    # It creates class referent::Reference as a subclass of
+    # GenericReference, and sets the REFERENT_CLASS constant of
+    # referent::Reference to referent.
+    #
+    def self.included(referent)
+      raise JSS::InvalidDataError, "'#{referent}' is not a subclass of Jamf::CollectionResource, can't include 'Referable'" unless referent.ancestors.include? Jamf::CollectionResource
+      referent.const_set :Reference, Class.new(GENREF)
+      referent::Reference.const_set :REFERENT_CLASS, referent
+    end
+
+    # @return [self.class::GenericReference] A reference to this object.
+    #
+    def reference
+      @reference ||= self.class::Reference.new self
+    end
+
+  end # module Referable
+
+end # module

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

@@ -0,0 +1,202 @@
+# Copyright 2019 Pixar
+
+#
+#    Licensed under the Apache License, Version 2.0 (the "Apache License")
+#    with the following modification; you may not use this file except in
+#    compliance with the Apache License and the following modification to it:
+#    Section 6. Trademarks. is deleted and replaced with:
+#
+#    6. Trademarks. This License does not grant permission to use the trade
+#       names, trademarks, service marks, or product names of the Licensor
+#       and its affiliates, except as required to comply with Section 4(c) of
+#       the License and to reproduce the content of the NOTICE file.
+#
+#    You may obtain a copy of the Apache License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the Apache License with the above modification is
+#    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#    KIND, either express or implied. See the Apache License for the specific
+#    language governing permissions and limitations under the Apache License.
+#
+#
+
+module Jamf
+
+  # Code for CollectionResources that have a .../searchObjects resource.
+  # These resources provide for basic searching as will as sorting and paging of
+  # the found set.
+  #
+  # NOTE: This module provides class methods, not instance methods, and
+  # therefore must be mixed in with `extend` and not `include`
+  #
+  # Classes extended with this module *must* define:
+  #
+  #   SEARCH_RSRC [String] the resource to which the search is POSTed.
+  #
+  #
+  # Classes including this module *may* define:
+  #
+  #   SEARCH_FIELDS [Hash{Symbol: Symbol}]
+  #
+  # The hash keys are the names of searchable fields, e.g. 'name', or 'udid'
+  # and the values are the class expected for the field, one of:
+  # :string, :integer, or :boolean
+  #
+  # Without defining search fields, every search returns all objects, but
+  # the sorting and paging options are honored.
+  #
+  # If search fields are provided, then they can be specified when performing
+  # a search. If more than one is specified, they are AND'ed together.
+  #
+  # To Search:
+  #
+  # 1) Set result sort order
+  #
+  # If you want sorted results, first set the sort order with a combination of
+  # `MyClass.search_result_order = field, dir` where field is the name of the
+  # sort fiend and dir is :asc or :desc
+  #
+  # If you want a multi-level sort, set the first sort field as above,
+  # then use `MyClass.search_result_order_append field, dir` to add
+  # subsequent sort fields
+  #
+  # To clear them out and start over, call `MyClass.clear_search_result_order`
+  #
+  # 2) Set page size
+  #
+  #  If you want paged results then call `MyClass.search_result_page_size = X`
+  #  before starting your seacch
+  #
+  # 3) Do the search:
+  #   MyClass.search
+  #
+  module Searchable
+
+    SORT_DIRECTIONS = {
+      asc: 'ASC',
+      desc: 'DESC'
+    }.freeze
+
+    def search_result_page_size
+      @search_result_page_size ||= 0
+    end
+
+    def search_result_page_size=(size)
+      raise 'Size must be a non-negative integer' unless size.is_a?(Integer) && size >= 0
+      @search_result_page_size = size
+    end
+
+    def search_result_order
+      @search_result_order ||= []
+    end
+
+    def search_result_order=(fieldname, dir = :asc)
+      raise 'direction must be either :asc, or :desc' unless SORT_DIRECTIONS.key? dir
+      @search_result_order = [{ field: fieldname, direction: SORT_DIRECTIONS[dir] }]
+    end
+
+    def search_result_order_append(fieldname, dir = :asc)
+      raise 'direction must be either :asc, or :desc' unless SORT_DIRECTIONS.key? dir
+      search_result_order << { field: fieldname, direction: SORT_DIRECTIONS[dir] }
+    end
+
+    def clear_search_result_order
+      @search_result_order = []
+    end
+
+    # TODO: occasional excludedIds array
+    def search(pageNumber: 0, cnx: Jamf.cnx, load_all: true, **terms)
+      raise "#{self} is not searchable in the API" unless defined? self::SEARCH_RSRC
+
+      search_body = {
+        pageNumber: pageNumber,
+        pageSize: @search_result_page_size,
+        isLoadToEnd: load_all,
+        orderBy: @search_result_order
+      }
+
+      if defined? self::SEARCH_FIELDS
+        terms.each do |fld, val|
+          next unless self::SEARCH_FIELDS.key? fld
+
+          case self::SEARCH_FIELDS[fld]
+          when :integer
+            val = Jamf::Validate.integer val, "Search value for #{fld} must be an Integer"
+          when :string
+            val = Jamf::Validate.string val, "Search value for #{fld} must be a String"
+          when :boolean
+            val = Jamf::Validate.boolean val, "Search value for #{fld} must be a boolean"
+          end # case
+
+          search_body[fld] = val
+        end # terms.each
+      end # if defined? self::SEARCH_FIELDS
+
+      cnx.post self::SEARCH_RSRC, search_body
+
+    end # def search
+
+    class OrderBy < Jamf::JSONObject
+
+      SORT_DIRECTIONS = {
+        asc: 'ASC',
+        desc: 'DESC'
+      }.freeze
+
+      OBJECT_MODEL = {
+
+        # @!attribute field
+        #   @return [String]
+        field: {
+          class: :string
+        },
+
+        # @!attribute direction
+        #   @return [String]
+        direction: {
+          class: :string,
+          enum: SORT_DIRECTIONS
+        }
+      }.freeze
+
+    end # class Orderby
+
+    class SeachParams < Jamf::JSONObject
+
+      OBJECT_MODEL = {
+
+        # @!attribute pageSize
+        #   @return [Integer]
+        pageSize: {
+          class: :integer
+        },
+
+        # @!attribute pageNumber
+        #   @return [Integer]
+        pageNumber: {
+          class: :integer
+        },
+
+        # @!attribute isLoadToEnd
+        #   @return [Boolean]
+        isLoadToEnd: {
+          class: :boolean
+        },
+
+        # @!attribute orderBy
+        #   @return [Boolean]
+        orderBy: {
+          class: Jamf::Searchable::OrderBy,
+          multi: true
+        }
+
+      }.freeze
+
+    end # class SearchParams
+
+  end # module searchable
+
+end # module