Module: Windoo::Mixins::APICollection

Included in:
Capability, Component, ComponentCriterion, ExtensionAttribute, KillApp, Patch, Requirement, SoftwareTitle
Defined in:
lib/windoo/mixins/api_collection.rb

Overview

This should be included into The TitleEditor and Admin classes that represent API collections in their respective servers.

It defines core methods for dealing with such collections.

Defined Under Namespace

Modules: ClassMethods

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(includer) ⇒ Object

when this module is included, also extend our Class Methods



22
23
24
25
 
# File 'lib/windoo/mixins/api_collection.rb', line 22

def self.included(includer)
  Windoo.verbose_include includer, self
  includer.extend(ClassMethods)
end

Instance Method Details

#==(other) ⇒ Boolean

Returns Is this object the same as another, based on their primary_id.

Returns:

  • (Boolean) —

    Is this object the same as another, based on their primary_id



232
233
234
235
236
 
# File 'lib/windoo/mixins/api_collection.rb', line 232

def ==(other)
  return false unless self.class == other.class

  primary_id == other.primary_id
end

#cnx ⇒ Windoo::Connection

Returns The server connection for this object.

Returns:



263
264
265
 
# File 'lib/windoo/mixins/api_collection.rb', line 263

def cnx
  @cnx
end

#container ⇒ Windoo::APICollection

Returns If this object is contained within another, then here is the object that contains it.

Returns:

  • (Windoo::APICollection) —

    If this object is contained within another, then here is the object that contains it



257
258
259
 
# File 'lib/windoo/mixins/api_collection.rb', line 257

def container
  @container
end

#create_on_server(cnx: Windoo.cnx) ⇒ Integer

create a new object on the server from this instance

Parameters:

  • container_id (Integer, nil) —

    the id of the object that will contain the one we are creating. If nil, then we are creating a SoftwareTitle.

Returns:

  • (Integer) —

    The id of the newly created object



299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
 
# File 'lib/windoo/mixins/api_collection.rb', line 299

def create_on_server(cnx: Windoo.cnx)
  unless @creating
    raise Windoo::UnsupportedError,
          "Do not call 'create_on_server' directly - use the .create class method."
  end

  @cnx = cnx
  rsrc = creation_rsrc
  resp = cnx.post rsrc, to_json

  update_title_modify_time(resp)

  # the container method woull only return nil for
  # SoftwareTitle objects
  container_id = container&.primary_id

  new_id = handle_create_response(resp, container_id: container_id)

  # no longer creating, future saves are updates
  remove_instance_variable :@creating

  new_id
end

#delete ⇒ Integer

Delete this object

Returns:

  • (Integer) —

    The id of the object that was deleted



283
284
285
286
287
288
 
# File 'lib/windoo/mixins/api_collection.rb', line 283

def delete
  self.class.delete primary_id, cnx: cnx
  @deleted_id = primary_id
  instance_variable_set "@#{self.class.primary_id_key}", -1
  @deleted_id
end

#deleted_id ⇒ Integer

Returns our primary identifier value before we were deleted. Before deletion, this is nil.

Returns:

  • (Integer) —

    our primary identifier value before we were deleted. Before deletion, this is nil



242
243
244
 
# File 'lib/windoo/mixins/api_collection.rb', line 242

def deleted_id
  @deleted_id
end

#initialize(**init_data) ⇒ Object

Constructor



188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/windoo/mixins/api_collection.rb', line 188

def initialize(**init_data)
  fetching = init_data.delete :fetching
  @cnx = init_data.delete :cnx

  @container ||= init_data.delete :from_container

  # we save 'creating' in an inst. var so we know to create
  # rather than update later on when we #save
  @creating = true if init_data[:creating]

  unless fetching || @container || @creating
    raise Windoo::UnsupportedError, "#{self.class} can only be instantiated using .fetch or .create, not .new"
  end

  super
end

#pretty_print_instance_variables ⇒ Array

Remove the cnx object from the instance_variables used to create pretty-print (pp) output.

Returns:

  • (Array) —

    the desired instance_variables



366
367
368
369
370
371
 
# File 'lib/windoo/mixins/api_collection.rb', line 366

def pretty_print_instance_variables
  vars = instance_variables.sort
  vars.delete :@cnx
  vars.delete :@container
  vars
end

#primary_id ⇒ nil, Integer

Returns our primary identifier value, regardless of its attribute name. Before creation, this is nil. After deletion, this is -1.

Returns:

  • (nil, Integer) —

    our primary identifier value, regardless of its attribute name. Before creation, this is nil. After deletion, this is -1



225
226
227
 
# File 'lib/windoo/mixins/api_collection.rb', line 225

def primary_id
  send self.class.primary_id_key
end

#softwareTitle ⇒ Windoo::SoftwareTitle

Returns The SoftwareTitle object that ultimately contains this object.

Returns:



270
271
272
273
274
275
276
 
# File 'lib/windoo/mixins/api_collection.rb', line 270

def softwareTitle
  return self if is_a? Windoo::SoftwareTitle

  return container if container.is_a? Windoo::SoftwareTitle

  container.softwareTitle
end

#update_on_server(attr_name, new_value) ⇒ Integer

Update a single attribute on the server with the current value.

Parameters:

  • attr_name (Symbol) —

    The key from Class.json_attributes for the value we want to update

  • alt_value (Object) —

    A value to send that isn’t the actual data for the attribute. If provided, the attr_name need not appear as a key in .json_attributes, but that name and this value will be sent to the API. See CriteriaManager#update_criterion for an example

Returns:

  • (Integer) —

    the id of the updated item.



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
 
# File 'lib/windoo/mixins/api_collection.rb', line 336

def update_on_server(attr_name, new_value)
  # This may be nil if given an alt name for an alt value
  attr_def = self.class.json_attributes[attr_name]

  if attr_def&.dig attr_name, :do_not_send
    raise Windoo::UnsupportedError, "The value for #{attr_name} cannot be updated directly."
  end

  # convert the value, if needed, to API format
  value_to_send =
    if attr_def&.dig attr_name, :to_api
      Windoo::Converters.send attr_def[:to_api], new_value.dup
    else
      new_value
    end

  json_to_put = { attr_name => value_to_send }.to_json

  # should use our @cnx...
  resp = cnx.put "#{self.class::RSRC_PATH}/#{primary_id}", json_to_put
  update_title_modify_time(resp)
  handle_update_response(resp)
end