windoo 1.0.1

data/lib/windoo/base_classes/array_manager.rb

@@ -0,0 +1,335 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+# main module
+module Windoo
+
+  module BaseClasses
+
+    # The common code for dealing with a managed array of objects in
+    # Software Titles.
+    #
+    # Array Managers manage an Array of instances of API objects, preventing
+    # direct access to the Array, but providing methods for adding, removing,
+    # updating, and moving array members, while appropriatly interacting with the
+    # API and maintaining consistency between the local Array and the server.
+    #
+    # This base class provides management of the actual Array, and doesn't
+    # intentionally communicate with the server at all. However, it
+    # may cause server interaction when calling methods on the objects held
+    # in the Array.
+    #
+    # Instances of subclasses of this class are held by API objects instead
+    # of the raw Array.
+    #
+    # For example, SoftwareTitles have a #patches method, which is a list
+    # of all the patches for the title. In the raw API data Hash, the :patches
+    # key contains an array of hashes of patch data.
+    #
+    # However, the SoftwareTitle#patches method does not return an Array.
+    # Intead it returns an instance of Windoo::PatchManager, a subclass of this class,
+    # which provides ways to add, update, and delete patches from the title.
+    #
+    # CAUTION: Do not instantiate (with .create) or delete members of the Array
+    # directly, use the `add_*` and `delete_` methods of the Array Manager, so
+    # that the local array automatically stays in sync with the server.
+    #
+    # TODO: Prevent instantiation of those objects outside of approved methods.
+    #
+    # Subclasses MUST define the constant MEMBER_CLASS to indicate the class of
+    # the items we are managing
+    #
+    class ArrayManager
+
+      # Constants
+      ##################################
+      ##################################
+
+      PP_OMITTED_INST_VARS = %i[@container].freeze
+
+      # Attributes
+      ##################################
+      ##################################
+
+      # @return [APICollection] the API object that contains this manager
+      attr_reader :container
+
+      # Constructor
+      ##################################
+      ##################################
+
+      # @param data [Array<Hash>] A JSON array of hashes from the API
+      #   containing data the to construct one of these manager objects.
+      #
+      # @param container [Object] the object that contains this managed
+      #   array of criteria
+      #
+      def initialize(data, container:)
+        @container = container
+        @managed_array = []
+        return unless data
+
+        @managed_array = data.map do |member_data|
+          self.class::MEMBER_CLASS.instantiate_from_container(container: container, **member_data)
+        end
+      end
+
+      # Public Instance Methods
+      ##################################
+      ##################################
+
+      # Only selected items are displayed with prettyprint
+      # otherwise its too much data in irb.
+      #
+      # @return [Array] the desired instance_variables
+      #
+      ###########################
+      def pretty_print_instance_variables
+        instance_variables - PP_OMITTED_INST_VARS
+      end
+
+      # @return [Array<Windoo::BaseClasses::Criterion>] A dup'd and frozen copy of
+      #  the array of criteria maintained by this class
+      ###########################
+      def to_a
+        @managed_array.dup.freeze
+      end
+
+      # Some convenience wrappers for common array methods
+      # For other array methods, use #to_a to get the
+      # actual (readonly dup of) the array.
+      #####
+
+      # @return [Object]
+      ###########################
+      def [](idx)
+        @managed_array[idx]
+      end
+
+      # @return [Object]
+      ###########################
+      def first
+        @managed_array.first
+      end
+
+      # @return [Object]
+      ###########################
+      def last
+        @managed_array.last
+      end
+
+      # @return [Boolean]
+      ###########################
+      def empty?
+        @managed_array.empty?
+      end
+
+      # @return [Integer]
+      ###########################
+      def size
+        @managed_array.size
+      end
+      alias count size
+      alias length size
+
+      # Iterators - they have to use the
+      # frozen dup from to_a, since they
+      # might try to modify items as they
+      # iterate.
+      ###########################
+
+      # @return [Array]
+      ###########################
+      def each(&block)
+        to_a.each(&block)
+      end
+
+      # @return [Object, nil]
+      ###########################
+      def find(if_none = nil, &block)
+        to_a.find if_none, &block
+      end
+
+      # @return [Object, nil]
+      ###########################
+      def find_by_attr(attr_name, value)
+        return if empty?
+        return unless @managed_array.first.respond_to? attr_name
+
+        @managed_array.find { |i| i.send(attr_name) == value }
+      end
+
+      # @return [Integer, nil]
+      ###########################
+      def index(obj = nil, &block)
+        return to_a.index(obj) if obj
+
+        to_a.index(&block)
+      end
+
+      # Private Instance Methods
+      ##################################
+      ##################################
+      private
+
+      # Add a member to the array at a given position.
+      #
+      # Subclasses must define a related method to create the new member
+      # object, then call this method to add it to the array, then do any
+      # other processing needed after, e.g. returning some attribute of
+      # the object.
+      #
+      # NOTE: This method does not communicate with the server. You must add
+      # the object to the server in whatever method calls this one, preferably
+      # before calling this one, so that any server errors are raised before
+      # we insert the object into the array.
+      #
+      # @param new_member [Object] the object to be added to the array
+      #
+      # @param index [Integer] The array index at which to add the object.
+      #   Defaults to -1 (the end of the array)
+      #
+      # @return [Object] the object that was added
+      #
+      ###########################
+      def add_member(new_member, index: -1)
+        @managed_array.insert index, new_member
+        new_member
+      end
+
+      # Update the details of an existing array member
+      #
+      # Subclasses should define a related method to do any kind of non-standard
+      # processing if needed, then call this method, perhaps after modifying the
+      # given attribs hash.
+      #
+      # This method will then call the matching setter method for each attrib
+      # provided, if available, passing in the new value.
+      #
+      # Those setters may or may not update the server immediately.
+      #
+      # @param id [Integer] The primary ID of the object to update.
+      #   For an array of Windoo::Requirement, you would provide a value that is a
+      #   'requirementId', for an array of Windoo::Patch, the value would
+      #    be a 'patchId'.
+      #
+      # @param attribs [Hash] Key=>value pairs for attributes to be updated
+      #   and the new values to be applied.
+      #   Each key will be transformed into a setter method and sent to the
+      #   object with the value as input to the setter.
+      #
+      #   If any special handling of an attrib is needed, the calling
+      #   method should deal with that and modify the attribs hash
+      #   before passing them into this method via #super.
+      #
+      #   NOTE: Explicit nils are sent!
+      #
+      #
+      # @return [Object] the object that was updated
+      #
+      ###########################
+      def update_member(id, **attribs)
+        member = member_by_id(id)
+
+        attribs.each do |attr_name, new_val|
+          setter = "#{attr_name}="
+          member.send setter, new_val if member.respond_to? setter
+        end
+
+        member
+      end
+
+      # Move a member to a new location in the array. This
+      # does not talk to the server
+      #
+      # @param member [Object] the member to move
+      #
+      # @param index [Integer] the new index for the member
+      #
+      # @return [void]
+      ###########################
+      def move_member(member, index:)
+        curr_idx = @managed_array.index { |m| m == member }
+
+        @managed_array.insert index, @managed_array.delete_at(curr_idx)
+      end
+
+      # Delete a member of the array.
+      #
+      # This method will call the object's #delete method, if it has one,
+      # which may delete it from the server. It will then delete it from
+      # the local array
+      #
+      # Subclasses should define a related method that calls this one, doing
+      # any processing before or after
+      #
+      # @param id [Integer] The primary ID of the object to delete.
+      #   For an array of Windoo::Requirement, you would provide a value that is a
+      #   'requirementId', for an array of Windoo::Patch, the value would
+      #    be a 'patchId'.
+      #
+      # @return [Object] The object that was removed from the array
+      #
+      ###########################
+      def delete_member(id)
+        member = member_by_id(id)
+
+        # call its delete method, which may delete it from the server
+        member.delete if member.respond_to? :delete
+
+        # delete from the array
+        @managed_array.delete member
+
+        member
+      end
+
+      # Delete all members of the array
+      #
+      # Subclasses should override, or define a related method that calls this one,
+      # doing any processing before or after
+      #
+      # @return [void]
+      #
+      ###########################
+      def delete_all_members
+        @managed_array.each { |member| member.delete if member.respond_to? :delete }
+        @managed_array = []
+      end
+
+      # Return a member of the array by searching for its 'primary_id'
+      #
+      # @param id [Integer] The primary ID of the object to return.
+      #   For an array of Windoo::Requirement, you would provide a value that is a
+      #   'requirementId', for an array of Windoo::Patch, the value would
+      #    be a 'patchId'.
+      #
+      # @return [Object] The object with the given id
+      #
+      ###########################
+      def member_by_id(id)
+        member = @managed_array.find { |m| m.send(primary_id_key) == id }
+        return member if member
+
+        raise Windoo::NoSuchItemError, "No matching #{self.class::MEMBER_CLASS} with #{primary_id_key} #{id} found"
+      end
+
+      # The primary
+      ###########################
+      def primary_id_key
+        @primary_id_key ||= self.class::MEMBER_CLASS.primary_id_key
+      end
+
+      ###########################
+      def container_primary_id_key
+        @container_primary_id_key ||= @container.class.primary_id_key
+      end
+
+    end # class Criterion
+
+  end # module BaseClasses
+
+end # module Windoo

data/lib/windoo/base_classes/criteria_manager.rb

@@ -0,0 +1,327 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+
+# frozen_string_literal: true
+
+# main module
+module Windoo
+
+  module BaseClasses
+
+    # The common code for dealing with a group of criteria-based objects
+    # in Software Titles.
+    #
+    # This class manages an array of instances of subclasses of
+    # {Windoo::BaseClasses::Criterion}
+    #
+    # See also: {Windoo::BaseClasses::ArrayManager}
+    # for info about managed Arrays.
+    #
+    # This class should be the superclass of classes representing
+    # the three ways Criteria are used in a {SoftwareTitle}.
+    #
+    # - SoftwareTitles have 'requirements'
+    #   - These are criteria defining which computers have any version of the title installed.
+    # - {Patch Patches} within SoftwareTitles have 'capabilities'
+    #   - These are criteria defining which computers are capable of installing/running the patch.
+    # - A Patch's '{Component component}' has a set of 'criteria'
+    #   - These are criteria defining which comptuers have _this_ version of the title installed.
+    #
+    # Here's how that looks for requirements:
+    #
+    #   - {Windoo::RequirementManager Windoo::RequirementManager} should be a subclass of this class, and must define<br/>
+    #     the constant `MEMBER_CLASS = Windoo::Requirement` indicating that it should manage an array of...
+    #   - {Windoo::Requirement Windoo::Requirement} objects which is a subclass of {Windoo::BaseClasses::Criterion}
+    #   - {Windoo::SoftwareTitle#requirements} should return a single {Windoo::RequirementManager Windoo::RequirementManager} object
+    #
+    # Here's how to use a {Windoo::RequirementManager Windoo::RequirementManager}:
+    #
+    #     title = Windoo::SoftwareTitle.fetch 'mytitle'
+    #     title.requirements.to_a
+    #     # => the readonly Array of Windoo::Requirement objects
+    #
+    #     title.requirements.add_criterion(options: here)
+    #     # => add a new Windoo::Requirement to the Array
+    #
+    #     title.requirements.replace_criterion(victim_id, options: here)
+    #     # => replace an existing Windoo::Requirement in the Array
+    #
+    #     title.requirements.delete_criterion(victim_id)
+    #     # => delete an existing Windoo::Requirement from the Array
+    #
+    # The other CriteriaManagers work the same way, they are just located in their respective places:
+    #
+    #     # Patch Capabilities
+    #
+    #     patch = title.patches.first
+    #     # => a single patch
+    #
+    #     patch.capabilities.to_a
+    #     # => the readonly Array of Windoo::Capability objects
+    #
+    #     patch.capabilities.add_criterion(options: here)
+    #     # => add a new Windoo::Capability to the patch
+    #
+    #     patch.capabilities.replace_criterion(victim_id, options: here)
+    #     # => replace an existing Windoo::Capability in the patch
+    #
+    #     patch.capabilities.delete_criterion(victim_id)
+    #     # => delete an existing Windoo::Capability from the patch
+    #
+    #     # Patch Component Criteria
+    #
+    #     component = patch.component
+    #     # => the component of a patch
+    #
+    #     component.criteria.to_a
+    #     # => the readonly Array of Windoo::ComponentCriterion objects
+    #
+    #     component.criteria.add_criterion(options: here)
+    #     # => add a new Windoo::ComponentCriterion to the component
+    #
+    #     component.criteria.replace_criterion(victim_id, options: here)
+    #     # => replace an existing Windoo::ComponentCriterion in the component
+    #
+    #     component.criteria.delete_criterion(victim_id)
+    #     # => delete an existing Windoo::ComponentCriterion from the component
+    #
+    #
+    # Subclasses MUST define the constant MEMBER_CLASS to indicate the class of the items we are managing
+    #
+    class CriteriaManager < Windoo::BaseClasses::ArrayManager
+
+      # Class Methods
+      ######################
+
+      # @return [Array<String>] The names of all available recon criteria names
+      #####
+      def self.available_names(cnx: Windoo.cnx)
+        cnx.get 'valuelists/criteria/names'
+      end
+
+      # @return [Array<String>] The possible criteria types
+      #####
+      def self.available_types(cnx: Windoo.cnx)
+        cnx.get 'valuelists/criteria/types'
+      end
+
+      # Find out the available critrion operators for a given criterion.
+      # e.g. for the criterion 'Application Title' the operators are:
+      #    ["is", "is not", "has", "does not have"]
+      #
+      # for the criterion 'Application Bundle ID' the operators are:
+      #    ["is", "is not", "like", "not like", "matches regex", "does not match regex"]
+      #
+      # for the criterion 'Computer Group' the operators are:
+      #    ["member of", "not member of"]
+      #
+      # ...and so on.
+      #
+      # @param name [String] The criterion for which to get the operators
+      #
+      # @return [Array<String>] The possible operators for a given criterion name
+      #
+      #####
+      def self.operators_for(name, cnx: Windoo.cnx)
+        cnx.post 'valuelists/criteria/operators', { name: name }
+      end
+
+      # Public Instance Methods
+      ####################################
+
+      # Add a criterion to the end of this array.
+      #
+      # @param name [String] The name of the criterion
+      #   To ask the server for an Array of all possible criteria names,
+      #   use
+      #     Windoo::BaseClasses::CriteriaManager.available_names
+      #
+      # @param operator [String] The operator to use for
+      #   comparing the value given here with the value for
+      #   a computer.
+      #   To ask the server for an Array of all operators available for some
+      #   criterion, use
+      #     Windoo::BaseClasses::CriteriaManager.operators_for criterion_name
+      #
+      # @param value [String, integer] The value that will be
+      #   compared with that on a computer, using the operator.
+      #
+      # @param type [String] how does Jamf Pro get this
+      #   value for a computer? 'recon' means its a normal value
+      #   gathered by a recon. 'extensionAttribute' means the value
+      #   is generated by the extensionAttribute associated with
+      #   this SoftwareTitle. Defaults to 'recon'.
+      #
+      # @param and_or [Symbol] :and or :or. Defines how this
+      #   criterion is joined with the previous one in a chain of
+      #   boolean logic. Default is :and
+      #
+      # @param absoluteOrderId [Integer] The zero-based position of this criterion
+      #   among all the others in the array. By default, this criterion will be added
+      #   at '-1', the end of the array
+      #
+      # @return [Integer] The id of the new criterion
+      #
+      def add_criterion(name:, operator:, value:, type: 'recon', and_or: :and, absoluteOrderId: nil)
+        absoluteOrderId ||= @managed_array.size
+
+        new_criterion = self.class::MEMBER_CLASS.create(
+          cnx: container.cnx,
+          container: container,
+          and_or: and_or,
+          name: name,
+          operator: operator,
+          value: value,
+          type: type.to_s,
+          absoluteOrderId: absoluteOrderId
+        )
+
+        # call the method from our superclass to add it to the array
+        add_member new_criterion, index: absoluteOrderId
+        update_local_absoluteOrderIds
+        new_criterion.primary_id
+      end
+
+      # Create a new criterion from the provided attributes and use it
+      # to replace the one with the given id.
+      #
+      # @param id [Integer] The primary ID of the criterion to update.
+      #   So for an array of Windoo::Requirement, you would provide a 'requirementId'
+      #
+      # @param name [String] The name of the criterion
+      #   To get an Array of all possible criteria names, use
+      #   Windoo::BaseClasses::CriteriaManager.available_names
+      #
+      # @param operator [String] The operator to use for
+      #   comparing the value given here with the value for
+      #   a computer.
+      #   To get an Array of all operators available for some criterion,
+      #   use Windoo::BaseClasses::CriteriaManager.operators_for criterion_name
+      #
+      # @param value [String, integer] The value that will be
+      #   compared with that on a computer, using the operator.
+      #
+      # @param type [String] how does Jamf Pro get this
+      #   value for a computer? 'recon' means its a normal value
+      #   gathered by a recon. 'extensionAttribute' means the value
+      #   is generated by the extensionAttribute associated with
+      #   this SoftwareTitle. Defaults to 'recon'.
+      #
+      # @param and_or [Symbol] :and or :or. Defines how this
+      #   criterion is joined with the previous one in a chain of
+      #   boolean logic. Default is :and
+      #
+      # @return [Integer] The id of the new criterion
+      #
+      def replace_criterion(id, name:, operator:, value:, type: 'recon', and_or: :and)
+        victim = delete_member(id)
+
+        add_criterion(
+          and_or: and_or,
+          name: name,
+          operator: operator,
+          value: value,
+          type: type.to_s,
+          absoluteOrderId: victim.absoluteOrderId
+        )
+      # no need to run update_local_absoluteOrderIds, we haven't changed the order,
+      # and it was called by add_criterion
+
+      # Windoo::ConnectionError should only come from the Add operation,
+      # usually when one of the attributes given was a problem.
+      #
+      # The delete should give a Windoo::NoSuchItemError if the id doesn't
+      # exist on the server.
+      rescue Windoo::ConnectionError
+        # make sure the victim was really removed from the array
+        # It should have been by the delete_member call above,
+        @managed_array.delete_if { |c| c.primary_id == victim.primary_id }
+
+        # then re-add the victim in the same position
+        add_criterion(
+          and_or: victim.and_or,
+          name: victim.name,
+          operator: victim.operator,
+          value: victim.value,
+          type: victim.type.to_s,
+          absoluteOrderId: victim.absoluteOrderId
+        )
+        # and re-raise the error
+        raise
+      end
+
+      # Change the position of an existing criterion in the array
+      #
+      # @param id [Integer] The primary ID of the criterion to update.
+      #   So for an array of Windoo::Requirement, you would provide a 'requirementId'
+      #
+      # @param absoluteOrderId [Integer] The zero-based position to which you want to
+      #   move the criterion. So if you want to make it the third criterion
+      #   in the list, use 2.
+      #
+      # @return [Integer] the new absoluteOrderId
+      #
+      def move_criterion(id, absoluteOrderId:)
+        # Can't move it beyond the end of the array....
+        max_idx = @managed_array.size - 1
+        absoluteOrderId = max_idx if absoluteOrderId > max_idx
+
+        # ... or before the beginning
+        absoluteOrderId = 0 if absoluteOrderId.negative?
+
+        # do it on the server first, to raise potential errs before
+        # modifying the array
+        criterion = update_member id, absoluteOrderId: absoluteOrderId
+
+        # now modify the array
+        move_member criterion, index: absoluteOrderId
+        update_local_absoluteOrderIds
+
+        absoluteOrderId
+      end
+
+      # Delete a criterion by its id
+      #
+      # @param id [Integer] The primary ID of the criterion to delete.
+      #   So for an array of Windoo::Requirement, you would provide a 'requirementId'
+      #
+      # @return [Integer] The id of the deleted criterion
+      #
+      def delete_criterion(id)
+        delid = delete_member(id).deleted_id
+        update_local_absoluteOrderIds
+        delid
+      end
+
+      # Delete all the criteria
+      #
+      # @return [void]
+      #
+      def delete_all_criteria
+        delete_all_members
+      end
+
+      # Private Instance Methods
+      ####################################
+      private
+
+      # Update the local absoluteOrderId of Array members
+      # to match their array index, without updating the server
+      # cuz the server should have done it automatically
+      #
+      # @return [void]
+      def update_local_absoluteOrderIds
+        @managed_array.each_with_index do |criterion, index|
+          next unless criterion
+
+          criterion.local_absoluteOrderId = index
+        end
+      end
+
+    end # class Criterion
+
+  end # module BaseClasses
+
+end # module Windoo