Class: Jamf::OAPIObject

Inherits:

Object

Object
Jamf::OAPIObject

show all

Includes:: Comparable

Defined in:: lib/jamf/api/jamf_pro/base_classes/oapi_object.rb

Overview

The parent class for all objects auto-generated in the Jamf::OAPISchemas module more docs to come

Direct Known Subclasses

Instance Attribute Summary collapse

#init_data ⇒ Hash readonly

the raw hash from which this object was constructed.

Class Method Summary collapse

.mutable? ⇒ Boolean

By default,OAPIObjects (as a whole) are mutable, although some attributes may not be (see OAPI_PROPERTIES in the JSONObject docs).
.oapi_properties_parsed? ⇒ Boolean

have we already parsed our OAPI_PROPERTIES? If so, we shoudn’t do it again, an this can be used to check.
.parse_oapi_properties ⇒ Object

create getters and setters for subclasses of APIObject based on their OAPI_PROPERTIES Hash.
.required_attributes ⇒ Object

An array of attribute names that are required when making new instances - they cannot be nil, but may be empty.
.validate_attr(attr_name, value) ⇒ Object

Used by auto-generated setters and .create to validate new values.

Instance Method Summary collapse

#<=>(other) ⇒ Object

Comparable by the sha1 hash of our properties.
#clear_unsaved_changes ⇒ Object
#initialize(data) ⇒ OAPIObject constructor

Make an instance.
#mutable? ⇒ Boolean

Are objects of this class mutable?.
#pretty_jamf_json ⇒ Object

Print the JSON version of the to_jamf outout mostly for debugging/troubleshooting.
#pretty_print_instance_variables ⇒ Array

Remove large cached items from the instance_variables used to create pretty-print (pp) output.
#sha1_hash ⇒ Object

The SHA1 hash of all the values of our properties as defined in the OAPI schema.
#to_jamf ⇒ Hash

The data to be sent to the API, as a Hash to be converted to JSON before sending to the JPAPI.
#to_json(*_args) ⇒ String

The JSON to be sent to the API for this object.
#unsaved_changes ⇒ Object

a hash of all unsaved changes.
#unsaved_changes? ⇒ Boolean

return true if we or any of our attributes have unsaved changes.

Constructor Details

#initialize(data) ⇒ `OAPIObject`

Make an instance. Data comes from the API

Parameters:

data (Hash) —

the data for constructing a new object.

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 350

def initialize(data)
  @init_data = data

  # creating a new one via ruby-jss, not fetching one from the API
  creating = data.delete :creating_from_create if data.is_a?(Hash)

  if creating
    self.class::OAPI_PROPERTIES.each_key do |attr_name|
      # we'll enforce required values when we save
      next unless data.key? attr_name

      # use our setters for each value so that they are validated, and
      # in the unsaved changes list
      send "#{attr_name}=", data[attr_name]
    end
    return
  end

  parse_init_data data
end

Instance Attribute Details

#init_data ⇒ `Hash` (readonly)

the raw hash from which this object was constructed

Returns:

(Hash)



341
342
343

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 341

def init_data
  @init_data
end

Class Method Details

.mutable? ⇒ `Boolean`

By default,OAPIObjects (as a whole) are mutable, although some attributes may not be (see OAPI_PROPERTIES in the JSONObject docs)

When an entire sublcass of OAPIObject is read-only/immutable, ‘extend Jamf::Immutable`, which will override this to return false. Doing so will prevent any setters from being created for the subclass and will cause Jamf::Resource.save to raise an error

Returns:

(Boolean)



50
51
52

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 50

def self.mutable?
  !singleton_class.ancestors.include? Jamf::Immutable
end

.oapi_properties_parsed? ⇒ `Boolean`

have we already parsed our OAPI_PROPERTIES? If so, we shoudn’t do it again, an this can be used to check

Returns:

(Boolean)



64
65
66

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 64

def self.oapi_properties_parsed?
  @oapi_properties_parsed
end

.parse_oapi_properties ⇒ `Object`

create getters and setters for subclasses of APIObject based on their OAPI_PROPERTIES Hash.

This method can’t be private, cuz we want to call it from a Zeitwerk callback when subclasses are loaded.

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 74

def self.parse_oapi_properties
  # only do this once
  return if @oapi_properties_parsed

  # only if this constant is defined
  return unless defined? self::OAPI_PROPERTIES

  # TODO: is the concept of 'primary' needed anymore?
  got_primary = false

  self::OAPI_PROPERTIES.each do |attr_name, attr_def|
    Jamf.load_msg "Creating getters and setters for attribute '#{attr_name}' of #{self}"

    # see above comment
    # don't make one for :id, that one's hard-coded into CollectionResource
    # create_list_methods(attr_name, attr_def) if need_list_methods && attr_def[:identifier] && attr_name != :id

    # there can be only one (primary ident)
    if attr_def[:identifier] == :primary
      raise Jamf::UnsupportedError, 'Two identifiers marked as :primary' if got_primary

      got_primary = true
    end

    # create getter unless the attr is write only
    create_getters attr_name, attr_def unless attr_def[:writeonly]

    # Don't crete setters for readonly attrs, or immutable objects
    next if attr_def[:readonly] || !mutable?

    create_setters attr_name, attr_def
  end #  do |attr_name, attr_def|

  @oapi_properties_parsed = true
end

.required_attributes ⇒ `Object`

An array of attribute names that are required when making new instances - they cannot be nil, but may be empty.

See the OAPI_PROPERTIES documentation in Jamf::OAPIObject



58
59
60

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 58

def self.required_attributes
  self::OAPI_PROPERTIES.select { |_attr, deets| deets[:required] }.keys
end

.validate_attr(attr_name, value) ⇒ `Object`

Used by auto-generated setters and .create to validate new values.

returns a valid value or raises an exception

This method only validates single values. When called from multi-value setters, it is used for each value individually.

Parameters:

attr_name (Symbol) —

, a top-level key from OAPI_PROPERTIES for this class
value (Object) —

the value to validate for that attribute.

Returns:

(Object) —

The validated, possibly converted, value.

Raises:

(ArgumentError)

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 324

def self.validate_attr(attr_name, value)
  attr_def = self::OAPI_PROPERTIES[attr_name]
  raise ArgumentError, "Unknown attribute: #{attr_name} for #{self} objects" unless attr_def

  # validate the value based on the OAPI definition.
  Jamf::Validate.oapi_attr value, attr_def: attr_def, attr_name: attr_name

  # if this is an identifier, it must be unique
  # TODO: move this to colloection resouce code
  # Jamf::Validate.doesnt_exist(value, self, attr_name, cnx: cnx) if attr_def[:identifier] && superclass == Jamf::CollectionResource
end

Instance Method Details

#<=>(other) ⇒ `Object`

Comparable by the sha1 hash of our properties. Subclasses or mixins may override this in ways that make sense for them



473
474
475

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 473

def <=>(other)
  sha1_hash <=> other.sha1_hash
end

#clear_unsaved_changes ⇒ `Object`

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 418

def clear_unsaved_changes
  return unless self.class.mutable?

  unsaved_changes.keys.each do |attr_name|
    attrib_val = instance_variable_get "@#{attr_name}"
    if self.class::OAPI_PROPERTIES[attr_name][:multi]
      attrib_val.each { |item| item.send :clear_unsaved_changes if item.respond_to? :clear_unsaved_changes }
    elsif attrib_val.respond_to? :clear_unsaved_changes
      attrib_val.send :clear_unsaved_changes
    end
  end
  ext_attrs_clear_unsaved_changes if self.class.include? Jamf::Extendable
  @unsaved_changes = {}
end

#mutable? ⇒ `Boolean`

Are objects of this class mutable?

Returns:

(Boolean)

#pretty_jamf_json ⇒ `Object`

Print the JSON version of the to_jamf outout mostly for debugging/troubleshooting



454
455
456

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 454

def pretty_jamf_json
  puts JSON.pretty_generate(to_jamf)
end

#pretty_print_instance_variables ⇒ `Array`

Remove large cached items from the instance_variables used to create pretty-print (pp) output.

Returns:

(Array) —

the desired instance_variables

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 464

def pretty_print_instance_variables
  vars = super.sort
  vars.delete :@init_data
  vars
end

#sha1_hash ⇒ `Object`

The SHA1 hash of all the values of our properties as defined in the OAPI schema



479
480
481

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 479

def sha1_hash
  Digest::SHA1.hexdigest(to_jamf.to_s)
end

#to_jamf ⇒ `Hash`

Returns The data to be sent to the API, as a Hash to be converted to JSON before sending to the JPAPI.

Returns:

(Hash) —

The data to be sent to the API, as a Hash to be converted to JSON before sending to the JPAPI

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 436

def to_jamf
  jamf_data = {}
  self.class::OAPI_PROPERTIES.each do |attr_name, attr_def|
    raw_value = instance_variable_get "@#{attr_name}"
    jamf_data[attr_name] = attr_def[:multi] ? multi_to_jamf(raw_value, attr_def) : single_to_jamf(raw_value, attr_def)
  end
  jamf_data
end

#to_json(*_args) ⇒ `String`

Returns the JSON to be sent to the API for this object.

Returns:

(String) —

the JSON to be sent to the API for this object



448
449
450

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 448

def to_json(*_args)
  to_jamf.to_json
end

#unsaved_changes ⇒ `Object`

a hash of all unsaved changes

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 382

def unsaved_changes
  return {} unless self.class.mutable?

  @unsaved_changes ||= {}

  changes = @unsaved_changes.dup

  self.class::OAPI_PROPERTIES.each do |attr_name, attr_def|
    # skip non-Class attrs
    next unless attr_def[:class].is_a? Class

    # the current value of the thing, e.g. a Location
    # which may have unsaved changes
    value = instance_variable_get "@#{attr_name}"

    # skip those that don't have any changes
    next unless value.respond_to? :unsaved_changes?

    attr_changes = value.unsaved_changes
    next if attr_changes.empty?

    # add the sub-changes to ours
    changes[attr_name] = attr_changes
  end
  changes[:ext_attrs] = ext_attrs_unsaved_changes if self.class.include? Jamf::Extendable
  changes
end

#unsaved_changes? ⇒ `Boolean`

return true if we or any of our attributes have unsaved changes

Returns:

(Boolean)

# File 'lib/jamf/api/jamf_pro/base_classes/oapi_object.rb', line 412

def unsaved_changes?
  return false unless self.class.mutable?

  !unsaved_changes.empty?
end

Class: Jamf::OAPIObject

Overview

Direct Known Subclasses

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data) ⇒ OAPIObject

Instance Attribute Details

#init_data ⇒ Hash (readonly)

Class Method Details

.mutable? ⇒ Boolean

.oapi_properties_parsed? ⇒ Boolean

.parse_oapi_properties ⇒ Object

.required_attributes ⇒ Object

.validate_attr(attr_name, value) ⇒ Object

Instance Method Details

#<=>(other) ⇒ Object

#clear_unsaved_changes ⇒ Object

#mutable? ⇒ Boolean

#pretty_jamf_json ⇒ Object

#pretty_print_instance_variables ⇒ Array

#sha1_hash ⇒ Object

#to_jamf ⇒ Hash

#to_json(*_args) ⇒ String

#unsaved_changes ⇒ Object

#unsaved_changes? ⇒ Boolean

#initialize(data) ⇒ `OAPIObject`

#init_data ⇒ `Hash` (readonly)

.mutable? ⇒ `Boolean`

.oapi_properties_parsed? ⇒ `Boolean`

.parse_oapi_properties ⇒ `Object`

.required_attributes ⇒ `Object`

.validate_attr(attr_name, value) ⇒ `Object`

#<=>(other) ⇒ `Object`

#clear_unsaved_changes ⇒ `Object`

#mutable? ⇒ `Boolean`

#pretty_jamf_json ⇒ `Object`

#pretty_print_instance_variables ⇒ `Array`

#sha1_hash ⇒ `Object`

#to_jamf ⇒ `Hash`

#to_json(*_args) ⇒ `String`

#unsaved_changes ⇒ `Object`

#unsaved_changes? ⇒ `Boolean`