Class: Telnyx::TelnyxObject

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/telnyx/telnyx_object.rb

Direct Known Subclasses

APIResource, ListObject, Verification::Response

Constant Summary collapse

@@permanent_attributes = 
Set.new([:id])

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id = nil, opts = {}) ⇒ TelnyxObject

Returns a new instance of TelnyxObject.



73
74
75
76
77
78
79
80
81
82
83
 
# File 'lib/telnyx/telnyx_object.rb', line 73

def initialize(id = nil, opts = {})
  id, @retrieve_params = Util.normalize_id(id)
  @opts = Util.normalize_opts(opts)
  @original_values = {}
  @values = {}
  # This really belongs in APIResource, but not putting it there allows us
  # to have a unified inspect method
  @unsaved_values = Set.new
  @transient_values = Set.new
  @values[:id] = id if id
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args) ⇒ Object (protected) 



322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
 
# File 'lib/telnyx/telnyx_object.rb', line 322

def method_missing(name, *args)
  # TODO: only allow setting in updateable classes.
  if name.to_s.end_with?("=")
    attr = name.to_s[0...-1].to_sym

    # Pull out the assigned value. This is only used in the case of a
    # boolean value to add a question mark accessor (i.e. `foo?`) for
    # convenience.
    val = args.first

    # the second argument is only required when adding boolean accessors
    add_accessors([attr], attr => val)

    begin
      mth = method(name)
    rescue NameError
      raise NoMethodError, "Cannot set #{attr} on this object. HINT: you can't set: #{@@permanent_attributes.to_a.join(', ')}"
    end
    return mth.call(args[0])
  elsif @values.key?(name)
    return @values[name]
  end

  begin
    super
  rescue NoMethodError => e
    # If we notice the accessed name if our set of transient values we can
    # give the user a slightly more helpful error message. If not, just
    # raise right away.
    raise unless @transient_values.include?(name)

    raise NoMethodError, e.message + ".  HINT: The '#{name}' attribute was set in the past, however.  It was then wiped when refreshing the object with the result returned by Telnyx's API, probably as a result of a save().  The attributes currently available on this object are: #{@values.keys.join(', ')}"
  end
end

Class Method Details

.additive_object_param(name) ⇒ Object

Sets the given parameter name to one which is known to be an additive object.

Additive objects are subobjects in the API that don’t have the same semantics as most subobjects, which are fully replaced when they’re set. This is best illustrated by example. The ‘source` parameter sent when updating a subscription is not additive; if we set it:

source[object]=card&source[number]=123

We expect the old ‘source` object to have been overwritten completely. If the previous source had an `address_state` key associated with it and we didn’t send one this time, that value of ‘address_state` is gone.

By contrast, additive objects are those that will have new data added to them while keeping any existing data in place. The only known case of its use is for ‘metadata`, but it could in theory be more general. As an example, say we have a `metadata` object that looks like this on the server side:

metadata = { old: "old_value" }

If we update the object with ‘metadata=new_value`, the server side object now has both fields:

metadata = { old: "old_value", new: "new_value" }

This is okay in itself because usually users will want to treat it as additive:

obj.metadata[:new] = "new_value"
obj.save

However, in other cases, they may want to replace the entire existing contents:

obj.metadata = { new: "new_value" }
obj.save

This is where things get a little bit tricky because in order to clear any old keys that may have existed, we actually have to send an explicit empty string to the server. So the operation above would have to send this form to get the intended behavior:

metadata[old]=&metadata[new]=new_value

This method allows us to track which parameters are considered additive, and lets us behave correctly where appropriate when serializing parameters to be sent.



61
62
63
64
 
# File 'lib/telnyx/telnyx_object.rb', line 61

def self.additive_object_param(name)
  @additive_params ||= Set.new
  @additive_params << name
end

.additive_object_param?(name) ⇒ Boolean

Returns whether the given name is an additive object parameter. See ‘.additive_object_param` for details.

Returns:

  • (Boolean) 


68
69
70
71
 
# File 'lib/telnyx/telnyx_object.rb', line 68

def self.additive_object_param?(name)
  @additive_params ||= Set.new
  @additive_params.include?(name)
end

.construct_from(values, opts = {}) ⇒ Object 



85
86
87
88
89
90
 
# File 'lib/telnyx/telnyx_object.rb', line 85

def self.construct_from(values, opts = {})
  values = Telnyx::Util.symbolize_names(values)

  # work around protected #initialize_from for now
  new(values[:id]).send(:initialize_from, values, opts)
end

.protected_fields ⇒ Object

A protected field is one that doesn’t get an accessor assigned to it (i.e. ‘obj.public = …`) and one which is not allowed to be updated via the class level `Model.update(id, { … })`.



258
259
260
 
# File 'lib/telnyx/telnyx_object.rb', line 258

def self.protected_fields
  []
end

Instance Method Details

#==(other) ⇒ Object

Determines the equality of two Telnyx objects. Telnyx objects are considered to be equal if they have the same set of values and each one of those values is the same.



95
96
97
 
# File 'lib/telnyx/telnyx_object.rb', line 95

def ==(other)
  other.is_a?(TelnyxObject) && @values == other.instance_variable_get(:@values)
end

#[](k) ⇒ Object 



153
154
155
 
# File 'lib/telnyx/telnyx_object.rb', line 153

def [](k)
  @values[k.to_sym]
end

#[]=(k, v) ⇒ Object 



157
158
159
 
# File 'lib/telnyx/telnyx_object.rb', line 157

def []=(k, v)
  send(:"#{k}=", v)
end

#as_json(*a) ⇒ Object 



173
174
175
 
# File 'lib/telnyx/telnyx_object.rb', line 173

def as_json(*a)
  @values.as_json(*a)
end

#deleted? ⇒ Boolean

Indicates whether or not the resource has been deleted on the server. Note that some, but not all, resources can indicate whether they have been deleted.

Returns:

  • (Boolean) 


114
115
116
 
# File 'lib/telnyx/telnyx_object.rb', line 114

def deleted?
  @values.fetch(:deleted, false)
end

#dirty! ⇒ Object

Sets all keys within the TelnyxObject as unsaved so that they will be included with an update when #serialize_params is called. This method is also recursive, so any TelnyxObjects contained as values or which are values in a tenant array are also marked as dirty.



200
201
202
203
204
205
 
# File 'lib/telnyx/telnyx_object.rb', line 200

def dirty!
  @unsaved_values = Set.new(@values.keys)
  @values.each_value do |v|
    dirty_value!(v)
  end
end

#each(&blk) ⇒ Object 



192
193
194
 
# File 'lib/telnyx/telnyx_object.rb', line 192

def each(&blk)
  @values.each(&blk)
end

#eql?(other) ⇒ Boolean

Hash equality. As with ‘#==`, we consider two equivalent Telnyx objects equal.

Returns:

  • (Boolean) 


100
101
102
103
 
# File 'lib/telnyx/telnyx_object.rb', line 100

def eql?(other)
  # Defer to the implementation on `#==`.
  self == other
end

#hash ⇒ Object

As with equality in ‘#==` and `#eql?`, we hash two Telnyx objects to the same value if they’re equivalent objects.



107
108
109
 
# File 'lib/telnyx/telnyx_object.rb', line 107

def hash
  @values.hash
end

#inspect ⇒ Object 



122
123
124
125
 
# File 'lib/telnyx/telnyx_object.rb', line 122

def inspect
  id_string = respond_to?(:id) && !id.nil? ? " id=#{id}" : ""
  "#<#{self.class}:0x#{object_id.to_s(16)}#{id_string}> JSON: " + JSON.pretty_generate(@values)
end

#keys ⇒ Object 



161
162
163
 
# File 'lib/telnyx/telnyx_object.rb', line 161

def keys
  @values.keys
end

#marshal_dump ⇒ Object

Implements custom encoding for Ruby’s Marshal. The data produced by this method should be comprehendable by #marshal_load.

This allows us to remove certain features that cannot or should not be serialized.



212
213
214
215
216
217
218
219
 
# File 'lib/telnyx/telnyx_object.rb', line 212

def marshal_dump
  # The TelnyxClient instance in @opts is not serializable and is not
  # really a property of the TelnyxObject, so we exclude it when
  # dumping
  opts = @opts.clone
  opts.delete(:client)
  [@values, opts]
end

#marshal_load(data) ⇒ Object

Implements custom decoding for Ruby’s Marshal. Consumes data that’s produced by #marshal_dump.



223
224
225
226
227
 
# File 'lib/telnyx/telnyx_object.rb', line 223

def marshal_load(data)
  values, opts = data
  initialize(values[:id])
  initialize_from(values, opts)
end

#serialize_params(options = {}) ⇒ Object 



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
 
# File 'lib/telnyx/telnyx_object.rb', line 229

def serialize_params(options = {})
  update_hash = {}

  @values.each do |k, v|
    # There are a few reasons that we may want to add in a parameter for
    # update:
    #
    #   1. The `force` option has been set.
    #   2. We know that it was modified.
    #   3. Its value is a TelnyxObject. A TelnyxObject may contain modified
    #      values within in that its parent TelnyxObject doesn't know about.
    #
    unsaved = @unsaved_values.include?(k)
    if options[:force] || unsaved || v.is_a?(TelnyxObject)
      update_hash[k.to_sym] =
        serialize_params_value(@values[k], @original_values[k], unsaved, options[:force], key: k)
    end
  end

  # a `nil` that makes it out of `#serialize_params_value` signals an empty
  # value that we shouldn't appear in the serialized form of the object
  update_hash.reject! { |_, v| v.nil? }

  update_hash
end

#to_hash ⇒ Object 



177
178
179
180
181
182
183
184
185
186
187
188
189
190
 
# File 'lib/telnyx/telnyx_object.rb', line 177

def to_hash
  maybe_to_hash = lambda do |value|
    value && value.respond_to?(:to_hash) ? value.to_hash : value
  end

  @values.each_with_object({}) do |(key, value), acc|
    acc[key] = case value
               when Array
                 value.map(&maybe_to_hash)
               else
                 maybe_to_hash.call(value)
               end
  end
end

#to_json(*_a) ⇒ Object 



169
170
171
 
# File 'lib/telnyx/telnyx_object.rb', line 169

def to_json(*_a)
  JSON.generate(@values)
end

#to_s(*_args) ⇒ Object 



118
119
120
 
# File 'lib/telnyx/telnyx_object.rb', line 118

def to_s(*_args)
  JSON.pretty_generate(to_hash)
end

#update_attributes(values, opts = {}, dirty: true) ⇒ Object

Mass assigns attributes on the model.

This is a version of update_attributes that takes some extra options for internal use.

Attributes

  • values - Hash of values to use to update the current attributes of the object.

  • opts - Options for TelnyxObject like an API key that will be reused on subsequent API calls.

Options

  • :dirty - Whether values should be initiated as “dirty” (unsaved) and which applies only to new TelnyxObjects being initiated under this TelnyxObject. Defaults to true.



144
145
146
147
148
149
150
151
 
# File 'lib/telnyx/telnyx_object.rb', line 144

def update_attributes(values, opts = {}, dirty: true)
  values.each do |k, v|
    add_accessors([k], values) unless metaclass.method_defined?(k.to_sym)
    @values[k] = Util.convert_to_telnyx_object(v, opts)
    dirty_value!(@values[k]) if dirty
    @unsaved_values.add(k)
  end
end

#values ⇒ Object 



165
166
167
 
# File 'lib/telnyx/telnyx_object.rb', line 165

def values
  @values.values
end