windoo 1.0.1

data/lib/windoo/objects/kill_app_manager.rb

@@ -0,0 +1,89 @@
+# 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
+
+module Windoo
+
+  # An {Windoo::BaseClasses::ArrayManager ArrayManager} for dealing with the
+  # {Windoo::KillApp KillApps} of a {Windoo::Patch Patch}
+  #
+  # An instance of this is returned by {Patch#killApps}
+  class KillAppManager < Windoo::BaseClasses::ArrayManager
+
+    # Constants
+    ##################################
+
+    MEMBER_CLASS = Windoo::KillApp
+
+    # Public Instance Methods
+    ####################################
+
+    # Add a killApp to this patch
+    #
+    # A killApp idetifies apps that cannot be running while this patch
+    # is installed. If the user is voluntarily applying the patch, they
+    # will be asked to quit the killApp. If the patch is being applied
+    # automatically, it will be killed automatically.
+    #
+    # @param appName [String] The name of the application that
+    #   cannot be running to install this patch. e.g. Safari.app
+    #
+    # @param bundleId [String] The bundle id of the application
+    #   that cannot be running to install this patch,
+    #   e.g. com.apple.Safari
+    #
+    # @return [Integer] The id of the new killApp
+    #
+    def add_killApp(appName:, bundleId:)
+      new_ka = Windoo::KillApp.create(
+        cnx: container.cnx,
+        container: container,
+        appName: appName,
+        bundleId: bundleId
+      )
+
+      # call the method from our superclass to add it to the array
+      add_member new_ka
+      new_ka.primary_id
+    end
+
+    # Update the details of an existing killApp
+    #
+    # Values not set in the params are left unchanged
+    #
+    # @param id [Integer] The killAppId of the desired killApp in the array
+    #
+    # @param attribs [Hash] The attribute(s) to update. See #add_killApp
+    #
+    # @return [Integer] The id of the updated killApp
+    #
+    def update_killApp(id, **attribs)
+      ka = update_member(id, **attribs)
+      ka.killAppId
+    end
+
+    # Delete a killApp
+    #
+    # @param id [Integer] The killAppId of the desired killApp in the array
+    #
+    # @return [Integer] The id of the deleted killApp
+    #
+    def delete_killApp(id)
+      delete_member(id).deleted_id
+    end
+
+    # Delete all the killApps
+    #
+    # @return [void]
+    #
+    def delete_all_killApps
+      delete_all_members
+    end
+
+  end # module KillAppManager
+
+end # module Windoo

data/lib/windoo/objects/patch.rb

@@ -0,0 +1,235 @@
+# 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
+
+module Windoo
+
+  # A patch represents a specific version of a Software Title.
+  class Patch < Windoo::BaseClasses::JSONObject
+
+    # Mixins
+    ######################
+
+    include Windoo::Mixins::APICollection
+    include Windoo::Mixins::Patch::Component
+
+    # Constants
+    ######################
+
+    RSRC_PATH = 'patches'
+
+    CONTAINER_CLASS = Windoo::SoftwareTitle
+
+    # Attributes
+    ######################
+
+    JSON_ATTRIBUTES = {
+
+      # @!attribute patchId
+      # @return [Integer] The id number of this patch
+      patchId: {
+        class: :Integer,
+        identifier: :primary,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute softwareTitleId
+      # @return [Integer] The id number of the title which uses this patch
+      softwareTitleId: {
+        class: :Integer,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute absoluteOrderId
+      # @return [Integer] The zero-based position of this patch among
+      #   all those used by the title. Should be identical to the Array index
+      #   of this patch in the #patches attribute of the SoftwareTitle
+      #   instance that uses this patch.
+      #   NOTE: This can only be changed via methods called on the
+      #   PatchManager that contains the patch.
+      absoluteOrderId: {
+        class: :Integer,
+        readonly: true
+      },
+
+      # @!attribute enabled
+      # @return [Boolean] Is this patch enabled?
+      enabled: {
+        class: :Boolean
+      },
+
+      # @!attribute version
+      # @return [String] The version on the title installed by this patch
+      version: {
+        class: :String,
+        required: true
+      },
+
+      # @!attribute releaseDate
+      # @return [Time] When this patch was released
+      releaseDate: {
+        class: :Time,
+        required: true,
+        to_ruby: :to_time,
+        to_api: :time_to_api
+      },
+
+      # @!attribute standalone
+      # @return [Boolean] Can this patch be installed as an initial installation?
+      #   If not, it must be applied to an already-installed version of this title.
+      #   NOTE: This is for reporting only, it is not used in patch policies
+      standalone: {
+        class: :Boolean
+      },
+
+      # @!attribute minimumOperatingSystem
+      # @return [String] The lowest version of the OS that can run this patch
+      #   NOTE: This is for reporting only. If there is a minimumOperatingSystem
+      #   You'll still need to specify it in the capabilities for this patch.
+      minimumOperatingSystem: {
+        class: :String,
+        required: true
+      },
+
+      # @!attribute reboot
+      # @return [Boolean] Does the patch require a reboot after installation?
+      reboot: {
+        class: :Boolean
+      },
+
+      # @!attribute killApps
+      # @return [Array<Windoo::KillApp>] The apps that must be quit before
+      #   installing this patch
+      killApps: {
+        class: Windoo::KillAppManager,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute components
+      # @return [Array<Windoo::Component>] The components of this patch.
+      #   NOTE: there can be only one!
+      component: {
+        class: Windoo::Component,
+        do_not_send: true,
+        readonly: true
+      },
+
+      # @!attribute capabilities
+      # @return [Array<Windoo::CapabilityManager>] The criteria which identify
+      #   computers capable of running, and thus installing, this patch.
+      capabilities: {
+        class: Windoo::CapabilityManager,
+        do_not_send: true,
+        readonly: true
+      }
+
+    }.freeze
+
+    # Constructor
+    ######################
+
+    def initialize(**init_data)
+      super
+      @capabilities = Windoo::CapabilityManager.new @capabilities, container: self
+      @killApps = Windoo::KillAppManager.new @killApps, container: self
+    end
+
+    # Public Instance Methods
+    ##########################################
+
+    # Enable this Patch
+    def enable
+      return if enabled?
+
+      if capabilities.empty? || component.nil? || component.criteria.empty?
+        raise Windoo::MissingDataError,
+              'Patches must have at least one capability, and a component with at least one criterion, before they can be enabled'
+      end
+
+      self.enabled = true
+
+      # Update the currentVersion of our title to this version if this patch is the
+      # newest enabled patch
+      container.currentVersion = version if container.patches.all_enabled.first == self
+
+      :enabled
+    end
+
+    # Disable this Patch
+    def disable
+      return unless enabled?
+
+      self.enabled = false
+      :disabled
+    end
+
+    # Allow array managers to change the absoluteOrderId.
+    #
+    # @todo Only allow this to be called from a PatchManager.
+    #
+    # @param new_index [Integer] The new, zero-based index for this
+    #   criterion.
+    #
+    # @return [Integer] the id of the updated criterion
+    #
+    def absoluteOrderId=(new_index)
+      new_value = validate_attr :absoluteOrderId, new_index
+      return if new_value == @absoluteOrderId
+
+      update_on_server :absoluteOrderId, new_value
+      @absoluteOrderId = new_value
+    end
+
+    # Update the local absoluteOrderId without updating it on
+    # the server.
+    #
+    # Why??
+    #
+    # Because changing the value on the server for one criterion
+    # using #absoluteOrderId=  will automatically change it on the
+    # server for all the others.
+    #
+    # After changing one on the server and updating that one in the
+    # local array, the ArrayManager will use this, without
+    # updating the server, to change the value for all others in the
+    # array to match their array index.
+    #
+    # @todo Only allow this to be called from a PatchManager.
+    #
+    # @return [void]
+    def local_absoluteOrderId=(new_index)
+      @absoluteOrderId = new_index
+    end
+
+    # Private Instance Methods
+    ##########################################
+    private
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_create_response(post_response, container_id: nil)
+      @patchId = post_response[:patchId]
+      @absoluteOrderId = post_response[:absoluteOrderId]
+
+      @softwareTitleId = container_id
+
+      @patchId
+    end
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_update_response(put_response)
+      @absoluteOrderId = put_response[:absoluteOrderId]
+
+      @patchId
+    end
+
+  end # class Patch
+
+end # module Windoo

data/lib/windoo/objects/patch_manager.rb

@@ -0,0 +1,240 @@
+# 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
+
+module Windoo
+
+  # An {Windoo::BaseClasses::ArrayManager ArrayManager} for dealing with the
+  # {Windoo::Patch Patches} of a {Windoo::SoftwareTitle SoftwareTitle}
+  #
+  # An instance of this is returned by {SoftwareTitle#patches}
+  #
+  class PatchManager < Windoo::BaseClasses::ArrayManager
+
+    # Constants
+    ####################################
+
+    MEMBER_CLASS = Windoo::Patch
+
+    # Public Instance Methods
+    ####################################
+
+    # @return [Array<Windoo::Patch] An array of the currently enabled patches
+    ############################
+    def all_enabled
+      @managed_array.select(&:enabled?)
+    end
+
+    # @return [Hash {Integer => String}] The Patch IDs => Version installed
+    #   by the patch.
+    ############################
+    def patchIds_to_versions
+      @managed_array.map { |p| [p.patchId, p.version] }.to_h
+    end
+
+    # @return [Hash {Integer => String}] The Versions => Patch ID installed
+    #   by the patch.
+    ############################
+    def versions_to_patchIds
+      @managed_array.map { |p| [p.version, p.patchId] }.to_h
+    end
+
+    # @return [Hash {Integer => String}] The Versions for this title
+    #
+    ##################################
+    def all_versions
+      @managed_array.map(&:version)
+    end
+
+    # get a patch by id or version
+    #
+    # @param ident [Integer, String] the patchId or version to return
+    #
+    # @return [Windoo::Patch] the patch object for the ident
+    ###########################
+    def patch(ident)
+      case ident
+      when Integer
+        find_by_attr(:patchId, ident)
+      when String
+        find_by_attr(:version, ident)
+      else
+        raise ArgumentError, 'ident must be an Integer patchId, or a String Version'
+      end
+    end
+
+    # Add a Patch to this SoftwareTitle. NOTE: patches cannot be
+    # enabled when added, you must call 'enable' on them after creating
+    # any necessary sub-objects.
+    #
+    # Patches must be ordered from newest to oldest, and are indexed zero-based,
+    # like Ruby Arrays.
+    #
+    # By default, patches are added at the front, index 0,meaning the are the newest.
+    #
+    # To make the new patch appear later in the order, provide a zero-based
+    # integer as 'absoluteOrderId' (0, the first in the order, is the default).
+    # So to add this new patch as older than the first and second, use
+    #    absoluteOrderId: 2
+    # All others will be adjusted automatically.
+    #
+    #
+    # @param version [String] The version of the title that is installed
+    #   by this patch. Required.
+    #
+    # @param minimumOperatingSystem [String] The lowest OS version that
+    #   this patch will run on. Required.
+    #
+    # @param releaseDate [Time, String] The date and time this patch
+    #   became available. Will be stored as a UTC timestampe in ISO8601 format.
+    #
+    # @param reboot [Boolean] Does this patch require a reboot after installation?
+    #
+    # @param standalone [Boolean] Can this patch be installed as the initial
+    #   install of this SoftwareTitle? If not, a previous version must already
+    #   be installed before this one can be.
+    #
+    # @param absoluteOrderId [Integer] The zero-based position of this patch among
+    #   all the others for this title. Ordered from newest to oldest. By default,
+    #   this patch will be added at '0'  the newest, first in the Array.
+    #
+    # @return [Integer] The id of the new Patch
+    ############################
+    def add_patch(version:, minimumOperatingSystem:, releaseDate: nil, reboot: nil, standalone: nil, absoluteOrderId: 0)
+      new_patch = Windoo::Patch.create(
+        cnx: container.cnx,
+        container: container,
+        version: version,
+        minimumOperatingSystem: minimumOperatingSystem,
+        releaseDate: releaseDate,
+        reboot: reboot,
+        standalone: standalone,
+        absoluteOrderId: absoluteOrderId
+      )
+
+      # call the method from our superclass to add it to the array
+      add_member new_patch, index: absoluteOrderId
+      update_local_absoluteOrderIds
+      new_patch.patchId
+    end
+
+    # TODO: implement cloning? The clone resource
+    # just creates a bare one with no killApps, component or
+    # capabilities. So not sure its much of a win
+    # over doing it in ruby.
+    #
+    # def clone_patch(_patchId, new_version:)
+    #   source_id = title.patches[-1].patchId
+    #   new_version = '0.0.1a1'
+    #   clone_url = "#{Windoo::Patch::RSRC_PATH}/#{source_id}/clone"
+    #   data = Windoo.cnx.post clone_url, {version: new_version }.to_json
+    #   newpatch = Windoo::Patch.new **data
+    # end
+
+    # Update a Patch in this SoftwareTitle.
+    # Do not use this to update absoluteOrderId, instead
+    # use #move_patch
+    #
+    # @param patchId [Integer] the id of the Patch to be updated.
+    #
+    # @param attribs [Hash] The attribute(s) to update. See #add_patch
+    #
+    # @return [Integer] The id of the updated Patch
+    ############################
+    def update_patch(patchId, **attribs)
+      # TODO: use this to undo if we changed
+      # the absoluteOrderId but something about the
+      # API transaction failed
+      @managed_array.index { |p| p.patchId == patchId }
+
+      patch = update_member(patchId, **attribs)
+
+      if attribs[:absoluteOrderId]
+        move_member patch, index: patch.absoluteOrderId
+        update_local_absoluteOrderIds
+      end
+
+      patch.patchId
+    end
+
+    # Change the position of an existing patch in the array
+    # This just calls update_patch, with absoluteOrderId as
+    # the only attribute.
+    #
+    # @param patchId [Integer] The patchId of the patch to update.
+    #
+    # @param absoluteOrderId [Integer] The zero-based position to which you want to
+    #   move the patch. So if you want to make it the third patch
+    #   in the list, use 2.
+    #
+    # @return [Integer] the new absoluteOrderId
+    ############################
+    def move_patch(patchId, 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?
+
+      update_patch patchId, absoluteOrderId: absoluteOrderId
+      absoluteOrderId
+    end
+
+    # Delete a Patch from this SoftwareTitle
+    #
+    # When deleting a Patch via this method, it is deleted
+    # from the server immediately, there is no need to #save
+    # the SoftwareTitle
+    #
+    # @param patchId [Integer] the id of the Patch to be updated.
+    #
+    #
+    # @return [Integer] The id of the deleted Patch
+    ############################
+    def delete_patch(patchId)
+      patch = delete_member(patchId)
+
+      # titles without a patch are not valid
+      # so must be disabled
+      patch.softwareTitle.disable if empty?
+
+      update_local_absoluteOrderIds
+
+      patchId
+    end
+
+    # Delete all the patches
+    #
+    # @return [void]
+    ############################
+    def delete_all_patches
+      delete_all_members
+      # titles without a patch are not valid
+      # so must be disabled
+      @container.disable
+    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 |patch, index|
+        patch.local_absoluteOrderId = index
+      end
+    end
+
+  end # class PatcheManager
+
+end # module Windoo

data/lib/windoo/objects/requirement.rb

@@ -0,0 +1,85 @@
+# 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
+
+module Windoo
+
+  # The class for dealing with Software Title Requirements in the
+  # TitleEditor
+  #
+  # A requirement is one criterion, a group of which define which computers
+  # have the title installed, regardless of version.
+  class Requirement < Windoo::BaseClasses::Criterion
+
+    # Mixins
+    ######################
+
+    include Windoo::Mixins::APICollection
+
+    # Constants
+    ######################
+
+    RSRC_PATH = 'requirements'
+
+    CONTAINER_CLASS = Windoo::SoftwareTitle
+
+    # Attributes
+    ######################
+
+    JSON_ATTRIBUTES = {
+
+      # @!attribute requirementId
+      # @return [Integer] The id number of this requirement in the Title Editor
+      requirementId: {
+        class: :Integer,
+        identifier: :primary,
+        readonly: true
+      },
+
+      # @!attribute softwareTitleId
+      # @return [Integer] The id number of the title which uses this requirement
+      softwareTitleId: {
+        class: :Integer,
+        readonly: true
+      }
+
+    }.freeze
+
+    # Public Class Methods
+    ######################
+
+    ####
+    def self.fetch(*_args)
+      raise Windoo::UnsupportedError, 'Requirements are fetched as part of the SoftwareTitle that contains them'
+    end
+
+    # Private Instance Methods
+    ##########################################
+    private
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_create_response(post_response, container_id: nil)
+      @requirementId = post_response[:requirementId]
+      @absoluteOrderId = post_response[:absoluteOrderId]
+      @softwareTitleId = container_id
+
+      @requirementId
+    end
+
+    # See the section 'REQUIRED ITEMS WHEN MIXING IN'
+    # in the APICollection mixin.
+    def handle_update_response(put_response)
+      @and_or = put_response[:and] == false ? :or : :and
+      @absoluteOrderId = put_response[:absoluteOrderId]
+
+      @requirementId
+    end
+
+  end # class Requirement
+
+end # Module Windoo

data/lib/windoo/objects/requirement_manager.rb

@@ -0,0 +1,52 @@
+# 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
+
+module Windoo
+
+  # A {Windoo::BaseClasses::CriteriaManager CriteriaManager} for dealing with the
+  # {Windoo::Requirement Requirements} of a {Windoo::SoftwareTitle SoftwareTitle}
+  #
+  # An instance of this is returned by {SoftwareTitle#requirements}
+  #
+  class RequirementManager < Windoo::BaseClasses::CriteriaManager
+
+    # Constants
+    ######################
+
+    MEMBER_CLASS = Windoo::Requirement
+
+    # Public Instance Methods
+    #################################
+
+    # Override this method to disable the containing patch
+    # if there are no more capabilities.
+    #
+    def delete_criterion(id)
+      deleted_id = super
+
+      # Titles without a requirement are not valid
+      # so must be disabled
+      @container.disable if @managed_array.empty?
+
+      deleted_id
+    end
+
+    # Delete all the criteria
+    #
+    # @return [void]
+    #
+    def delete_all_criteria
+      delete_all_members
+      # titles without a requirement are not valid
+      # so must be disabled
+      @container.disable
+    end
+
+  end # class RequirementManager
+
+end # Module Windoo