Module: Parse::Core::Actions

Included in:
Object
Defined in:
lib/parse/model/core/actions.rb

Overview

Defines some of the save, update and destroy operations for Parse objects.

Defined Under Namespace

Modules: ClassMethods

Instance Method Summary collapse

Instance Method Details

#_deleted? ⇒ Boolean

Returns true if this object has been fetched and found to be deleted from the server. Deleted objects cannot be saved.

Returns:

  • (Boolean) —

    true if the object is marked as deleted



1171
1172
1173
 
# File 'lib/parse/model/core/actions.rb', line 1171

def _deleted?
  @_deleted == true
end

#change_requests(force = false) ⇒ Array<Parse::Request>

Creates an array of all possible operations that need to be performed on this object. This includes all property and relational operation changes.

Parameters:

  • force (Boolean) (defaults to: false) —

    whether this object should be saved even if does not have pending changes.

Returns:



943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
 
# File 'lib/parse/model/core/actions.rb', line 943

def change_requests(force = false)
  requests = []
  # get the URI path for this object.
  uri = self.uri_path

  # generate the request to update the object (PUT)
  if attribute_changes? || force
    # if it's new, then we should call :post for creating the object.
    method = new? ? :post : :put
    r = Request.new(method, uri, body: attribute_updates)
    r.tag = object_id
    requests << r
  end

  # if the object is not new, then we can also add all the relational changes
  # we need to perform.
  if @id.present? && relation_changes?
    relation_change_operations.each do |ops|
      next if ops.empty?
      r = Request.new(:put, uri, body: ops)
      r.tag = object_id
      requests << r
    end
  end
  requests
end

#changes_applied! ⇒ Object

Clears changes information on all collections (array and relations) and all local attributes.



1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
 
# File 'lib/parse/model/core/actions.rb', line 1302

def changes_applied!
  # find all fields that are of type :array
  fields(:array) do |key, v|
    proxy = send(key)
    # clear changes
    proxy.changes_applied! if proxy.respond_to?(:changes_applied!)
  end

  # for all relational fields,
  relations.each do |key, v|
    proxy = send(key)
    # clear changes if they support the method.
    proxy.changes_applied! if proxy.respond_to?(:changes_applied!)
  end
  changes_applied
end

#changes_payload ⇒ Hash Also known as: update_payload

Returns a hash of the list of changes made to this instance.

Returns:

  • (Hash) —

    a hash of the list of changes made to this instance.



1210
1211
1212
1213
1214
1215
1216
1217
1218
 
# File 'lib/parse/model/core/actions.rb', line 1210

def changes_payload
  h = attribute_updates
  if relation_changes?
    r = relation_change_operations.select { |s| s.present? }.first
    h.merge!(r) if r.present?
  end
  #h.merge!(className: parse_class) unless h.empty?
  h.as_json
end

#create ⇒ Boolean

Save the object as a new record, running all callbacks.

Returns:

  • (Boolean) —

    true/false whether it was successful.



1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
 
# File 'lib/parse/model/core/actions.rb', line 1027

def create
  run_callbacks :create do
    body = attribute_updates
    # Forward a client-assigned objectId when a `before_create` callback
    # set it (e.g. `parse_reference precompute: true`). attribute_updates
    # excludes BASE_KEYS, so @id must be merged explicitly. Parse Server
    # accepts an objectId in the create POST body and rejects duplicates
    # with a typed error rather than silently overwriting.
    body[Parse::Model::OBJECT_ID] = @id if @id.present?
    res = client.create_object(parse_class, body, session_token: _session_token)
    # Retain the response so wrappers (e.g. synchronize_create) can
    # inspect the Parse error code on failure (notably 137 DuplicateValue).
    @_last_response = res
    unless res.error?
      result = res.result
      @id = result[Parse::Model::OBJECT_ID] || @id
      @created_at = result["createdAt"] || @created_at
      #if the object is created, updatedAt == createdAt
      @updated_at = result["updatedAt"] || result["createdAt"] || @updated_at
      # Because beforeSave hooks can change the fields we are saving, any items that were
      # changed, are returned to us and we should apply those locally to be in sync.
      set_attributes!(result)
    end
    puts "Error creating #{self.parse_class}: #{res.error}" if res.error?
    res.success?
  end
end

#destroy(session: nil) ⇒ Boolean

Delete this record from the Parse collection. Only valid if this object has an id. This will run all the destroy callbacks.

Parameters:

  • session (String) (defaults to: nil) —

    a session token if you want to apply ACLs for a user in this operation.

Returns:

  • (Boolean) —

    whether the operation was successful.

Raises:

  • ArgumentError if a non-nil value is passed to session that doesn't provide a session token string.



1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
 
# File 'lib/parse/model/core/actions.rb', line 1180

def destroy(session: nil)
  @_session_token = _validate_session_token! session, :destroy
  return false if new?
  success = false
  run_callbacks :destroy do
    res = client.delete_object parse_class, id, session_token: _session_token
    success = res.success?
    if success
      @id = nil
      changes_applied!
    elsif self.class.raise_on_save_failure
      raise Parse::RecordNotSaved.new(self), "Failed to create or save attributes. #{self.parse_class} was not saved."
    end
    # Your create action methods here
  end
  @_session_token = nil
  success
end

#destroy_request ⇒ Parse::Request

Returns a destroy_request for the current object.

Returns:



925
926
927
928
929
930
931
 
# File 'lib/parse/model/core/actions.rb', line 925

def destroy_request
  return nil unless @id.present?
  uri = self.uri_path
  r = Request.new(:delete, uri)
  r.tag = object_id
  r
end

#op_add!(field, objects) ⇒ Boolean

Perform an atomic add operation to the array field.

Parameters:

  • field (String) —

    the name of the field in the Parse collection.

  • objects (Array) —

    the set of items to add to this field.

Returns:

  • (Boolean) —

    whether it was successful

See Also:



831
832
833
 
# File 'lib/parse/model/core/actions.rb', line 831

def op_add!(field, objects)
  operate_field! field, { __op: :Add, objects: objects }
end

#op_add_relation!(field, objects = []) ⇒ Boolean

Perform an atomic add operation on this relational field.

Parameters:

  • field (String) —

    the name of the field in the Parse collection.

  • objects (Array<Parse::Object>) (defaults to: []) —

    the set of objects to add to this relational field.

Returns:

  • (Boolean) —

    whether it was successful

See Also:



881
882
883
884
885
886
 
# File 'lib/parse/model/core/actions.rb', line 881

def op_add_relation!(field, objects = [])
  objects = [objects] unless objects.is_a?(Array)
  return false if objects.empty?
  relation_action = Parse::RelationAction.new(field, polarity: true, objects: objects)
  operate_field! field, relation_action
end

#op_add_unique!(field, objects) ⇒ Boolean

Perform an atomic add unique operation to the array field. The objects will only be added if they don't already exists in the array for that particular field.

Parameters:

  • field (String) —

    the name of the field in the Parse collection.

  • objects (Array) —

    the set of items to add uniquely to this field.

Returns:

  • (Boolean) —

    whether it was successful

See Also:



841
842
843
 
# File 'lib/parse/model/core/actions.rb', line 841

def op_add_unique!(field, objects)
  operate_field! field, { __op: :AddUnique, objects: objects }
end

#op_destroy!(field) ⇒ Boolean

Perform an atomic delete operation on this field.

Parameters:

  • field (String) —

    the name of the field in the Parse collection.

Returns:

  • (Boolean) —

    whether it was successful

See Also:



858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
 
# File 'lib/parse/model/core/actions.rb', line 858

def op_destroy!(field)
  result = operate_field! field, { __op: :Delete }.freeze
  if result
    # Also update the local state to reflect the deletion
    field_sym = field.to_sym
    if self.class.fields[field_sym].present?
      set_attribute_method = "#{field}_set_attribute!"
      if respond_to?(set_attribute_method)
        send(set_attribute_method, nil, true) # Set to nil with dirty tracking
      else
        instance_variable_set(:"@#{field}", nil)
        send("#{field}_will_change!") if respond_to?("#{field}_will_change!")
      end
    end
  end
  result
end

#op_increment!(field, amount = 1) ⇒ Object

Atomically increment or decrement a specific field.

Parameters:

  • field (String) —

    the name of the field in the Parse collection.

  • amount (Integer) (defaults to: 1) —

    the amoun to increment. Use negative values to decrement.

See Also:



904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
 
# File 'lib/parse/model/core/actions.rb', line 904

def op_increment!(field, amount = 1)
  unless amount.is_a?(Numeric)
    raise ArgumentError, "Amount should be numeric"
  end
  result = operate_field! field, { __op: :Increment, amount: amount.to_i }.freeze
  if result
    # Also update the local state to reflect the increment
    field_sym = field.to_sym
    current_value = self[field_sym] || 0
    new_value = current_value + amount.to_i
    set_attribute_method = "#{field}_set_attribute!"
    if respond_to?(set_attribute_method)
      send(set_attribute_method, new_value, true) # Set new value with dirty tracking
    else
      self[field_sym] = new_value
    end
  end
  result
end

#op_remove!(field, objects) ⇒ Boolean

Perform an atomic remove operation to the array field.

Parameters:

  • field (String) —

    the name of the field in the Parse collection.

  • objects (Array) —

    the set of items to remove to this field.

Returns:

  • (Boolean) —

    whether it was successful

See Also:



850
851
852
 
# File 'lib/parse/model/core/actions.rb', line 850

def op_remove!(field, objects)
  operate_field! field, { __op: :Remove, objects: objects }
end

#op_remove_relation!(field, objects = []) ⇒ Boolean

Perform an atomic remove operation on this relational field.

Parameters:

  • field (String) —

    the name of the field in the Parse collection.

  • objects (Array<Parse::Object>) (defaults to: []) —

    the set of objects to remove to this relational field.

Returns:

  • (Boolean) —

    whether it was successful

See Also:



893
894
895
896
897
898
 
# File 'lib/parse/model/core/actions.rb', line 893

def op_remove_relation!(field, objects = [])
  objects = [objects] unless objects.is_a?(Array)
  return false if objects.empty?
  relation_action = Parse::RelationAction.new(field, polarity: false, objects: objects)
  operate_field! field, relation_action
end

#operate_field!(field, op_hash) ⇒ Boolean

Perform an atomic operation on this field. This operation is done on the Parse server which guarantees the atomicity of the operation. This is the low-level API on performing atomic operations on properties for classes. These methods do not update the current instance with any changes the server may have made to satisfy this operation.

Parameters:

  • field (String) —

    the name of the field in the Parse collection.

  • op_hash (Hash) —

    The operation hash. It may also be of type RelationAction.

Returns:

  • (Boolean) —

    whether the operation was successful.



806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
 
# File 'lib/parse/model/core/actions.rb', line 806

def operate_field!(field, op_hash)
  field = field.to_sym
  field = self.field_map[field] || field
  if op_hash.is_a?(Parse::RelationAction)
    op_hash = op_hash.as_json
  else
    op_hash = { field => op_hash }.as_json
  end

  # If the object hasn't been saved yet (no id), we can't make field operations
  # Return true to indicate the operation was "successful" locally
  return true if id.nil?

  response = client.update_object(parse_class, id, op_hash, session_token: _session_token)
  if response.error?
    puts "[#{parse_class}:#{field} Operation] #{response.error}"
  end
  response.success?
end

#prepare_save! ⇒ Boolean

Back-compat alias for Object#run_before_save_callbacks. The canonical name spells out exactly what runs (the before_save callbacks, before phase only) and is symmetric with run_after_save_callbacks / run_before_create_callbacks / run_after_create_callbacks. Retained so existing callers of prepare_save! keep working.

Returns:

  • (Boolean) —

    false if a before_save callback halted the chain, else true.



1205
1206
1207
 
# File 'lib/parse/model/core/actions.rb', line 1205

def prepare_save!
  run_before_save_callbacks
end

#relation_change_operations ⇒ Array

Generates an array with two entries for addition and removal operations. The first entry of the array will contain a hash of all the change operations regarding adding new relational objects. The second entry in the array is a hash of all the change operations regarding removing relation objects from this field.

Returns:

  • (Array) —

    an array with two hashes; the first is a hash of all the addition operations and the second hash, all the remove operations.



1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
 
# File 'lib/parse/model/core/actions.rb', line 1228

def relation_change_operations
  return [{}, {}] unless relation_changes?

  additions = []
  removals = []
  # go through all the additions of a collection and generate an action to add.
  relation_updates.each do |field, collection|
    if collection.additions.count > 0
      additions.push Parse::RelationAction.new(field, objects: collection.additions, polarity: true)
    end
    # go through all the additions of a collection and generate an action to remove.
    if collection.removals.count > 0
      removals.push Parse::RelationAction.new(field, objects: collection.removals, polarity: false)
    end
  end
  # merge all additions and removals into one large hash
  additions = additions.reduce({}) { |m, v| m.merge! v.as_json }
  removals = removals.reduce({}) { |m, v| m.merge! v.as_json }
  [additions, removals]
end

#save(session: nil, autoraise: false, force: false, validate: true) ⇒ Boolean

saves the object. If the object has not changed, it is a noop. If it is new, we will create the object. If the object has an id, we will update the record.

You may pass a session token to the session argument to perform this actions with the privileges of a certain user.

Callback order:

  1. before_validation / around_validation / after_validation
  2. before_save / around_save
  3. before_create or before_update / around_create or around_update
  4. [actual save operation]
  5. after_create or after_update
  6. after_save

You can define before and after :save callbacks autoraise: set to true will automatically raise an exception if the save fails

Parameters:

  • session (String) (defaults to: nil) —

    a session token in order to apply ACLs to this operation.

  • autoraise (Boolean) (defaults to: false) —

    whether to raise an exception if the save fails.

  • force (Boolean) (defaults to: false) —

    whether to run callbacks and send request even if there are no changes.

  • validate (Boolean) (defaults to: true) —

    whether to run validations (default: true).

Returns:

  • (Boolean) —

    whether the save was successful.

Raises:

  • (Parse::RecordNotSaved) —

    if the save fails

  • ArgumentError if a non-nil value is passed to session that doesn't provide a session token string.



1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
 
# File 'lib/parse/model/core/actions.rb', line 1094

def save(session: nil, autoraise: false, force: false, validate: true)
  # Prevent saving objects that have been fetched and found to be deleted
  if _deleted?
    error_msg = "Cannot save deleted object. Object with id '#{@id}' no longer exists on the server."
    raise Parse::Error::ProtocolError, error_msg
  end

  @_session_token = _validate_session_token! session, :save
  return true unless changed? || force

  # Run validations (validation callbacks are now triggered by valid? method)
  # Pass context so `on: :create` and `on: :update` options work with callbacks
  if validate
    validation_context = new? ? :create : :update
    validation_passed = valid?(validation_context)

    unless validation_passed
      if self.class.raise_on_save_failure || autoraise.present?
        raise Parse::RecordNotSaved.new(self), "Validation failed: #{errors.full_messages.join(", ")}"
      end
      return false
    end
  end

  success = false

  # Track if callbacks are halted by a before_save hook returning false
  callback_executed = false
  run_callbacks :save do
    callback_executed = true
    #first process the create/update action if any
    #then perform any relation changes that need to be performed
    success = new? ? create : perform_update(force: force)

    # if the save was successful and we have relational changes
    # let's update send those next.
    if success
      if relation_changes?
        # get the list of changed keys
        changed_attribute_keys = changed - relations.keys.map(&:to_s)
        clear_attribute_changes(changed_attribute_keys)
        success = update_relations
        if success
          changes_applied!
          clear_partial_fetch_state!
        elsif self.class.raise_on_save_failure || autoraise.present?
          raise Parse::RecordNotSaved.new(self), "Failed updating relations. #{self.parse_class} partially saved."
        end
      else
        changes_applied!
        clear_partial_fetch_state!
      end
    elsif self.class.raise_on_save_failure || autoraise.present?
      raise Parse::RecordNotSaved.new(self), "Failed to create or save attributes. #{self.parse_class} was not saved."
    end
  end #callbacks

  # If callbacks were halted (before_save returned false), return false
  return false unless callback_executed

  @_session_token = nil
  success
end

#save!(session: nil, force: false) ⇒ Boolean

Save this object and raise an exception if it fails.

Parameters:

  • session (String) (defaults to: nil) —

    a session token in order to apply ACLs to this operation.

  • force (Boolean) (defaults to: false) —

    whether to run callbacks and send request even if there are no changes.

Returns:

  • (Boolean) —

    whether the save was successful.

Raises:

  • (Parse::RecordNotSaved) —

    if the save fails

  • ArgumentError if a non-nil value is passed to session that doesn't provide a session token string.



1164
1165
1166
 
# File 'lib/parse/model/core/actions.rb', line 1164

def save!(session: nil, force: false)
  save(autoraise: true, session: session, force: force)
end

#set_attributes!(hash, dirty_track = false) ⇒ Hash

Performs mass assignment using a hash with the ability to modify dirty tracking. This is an internal method used to set properties on the object while controlling whether they are dirty tracked. Each defined property has a method defined with the suffix _set_attribute! that can will be called if it is contained in the hash.

Examples:

object.set_attributes!( {"myField" => value}, false)

# equivalent to calling the specific method.
object.myField_set_attribute!(value, false)

Parameters:

  • hash (Hash) —

    the hash containing all the attribute names and values.

  • dirty_track (Boolean) (defaults to: false) —

    whether the assignment should be tracked in the change tracking system.

Returns:



1291
1292
1293
1294
1295
1296
1297
1298
 
# File 'lib/parse/model/core/actions.rb', line 1291

def set_attributes!(hash, dirty_track = false)
  return unless hash.is_a?(Hash)
  hash.each do |k, v|
    next if k == Parse::Model::OBJECT_ID || k == Parse::Model::ID
    method = "#{k}_set_attribute!"
    send(method, v, dirty_track) if respond_to?(method)
  end
end

#update(force: false) ⇒ Boolean

Save all the changes related to this object.

Parameters:

  • force (Boolean) (defaults to: false) —

    whether to send the update even if there are no changes.

Returns:

  • (Boolean) —

    true/false whether it was successful.



1008
1009
1010
1011
 
# File 'lib/parse/model/core/actions.rb', line 1008

def update(force: false)
  return true unless attribute_changes? || force
  update!(force: force)
end

#update!(raw: false, force: false) ⇒ Boolean

This methods sends an update request for this object with the any change information based on its local attributes. The bang implies that it will send the request even though it is possible no changes were performed. This is useful in kicking-off an beforeSave / afterSave hooks Save the object regardless of whether there are changes. This would call any beforeSave and afterSave cloud code hooks you have registered for this class.

Returns:

  • (Boolean) —

    true/false whether it was successful.



977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
 
# File 'lib/parse/model/core/actions.rb', line 977

def update!(raw: false, force: false)
  if valid? == false
    errors.full_messages.each do |msg|
      warn "[#{parse_class}] warning: #{msg}"
    end
  end
  if force == true && attribute_changes?.blank? && !new?
    # if we are forcing an update, but there are no attribute changes,
    # we should still mark the updated_at field as changed so that
    # the server updates it.
    if self.class.fields[:updated_at].present?
      self.updated_at = Time.now.utc
      self.updated_at_will_change! if respond_to?(:updated_at_will_change!)
    end
  end
  response = client.update_object(parse_class, id, attribute_updates, session_token: _session_token)
  @_last_response = response
  if response.success?
    result = response.result
    # Because beforeSave hooks can change the fields we are saving, any items that were
    # changed, are returned to us and we should apply those locally to be in sync.
    set_attributes!(result)
  end
  puts "Error updating #{self.parse_class}: #{response.error}" if response.error?
  return response if raw
  response.success?
end

#update_relations ⇒ Boolean

Saves and updates all the relational changes for made to this object.

Returns:

  • (Boolean) —

    whether all the save or update requests were successful.



1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
 
# File 'lib/parse/model/core/actions.rb', line 1251

def update_relations
  # relational saves require an id
  return false unless @id.present?
  # verify we have relational changes before we do work.
  return true unless relation_changes?
  raise "Unable to update relations for a new object." if new?
  # get all the relational changes (both additions and removals)
  additions, removals = relation_change_operations

  responses = []
  # Send parallel Parse requests for each of the items to update.
  # since we will have multiple responses, we will track it in array
  [removals, additions].threaded_each do |ops|
    next if ops.empty? #if no operations to be performed, then we are done
    responses << client.update_object(parse_class, @id, ops, session_token: _session_token)
  end
  # check if any of them ended up in error
  has_error = responses.any? { |response| response.error? }
  # if everything was ok, find the last response to be returned and update
  #their fields in case beforeSave made any changes.
  unless has_error || responses.empty?
    result = responses.last.result #last result to come back
    set_attributes!(result)
  end #unless
  has_error == false
end

#uri_path ⇒ String

Returns the API uri path for this class.

Returns:

  • (String) —

    the API uri path for this class.



934
935
936
 
# File 'lib/parse/model/core/actions.rb', line 934

def uri_path
  self.client.url_prefix.path + Client.uri_path(self)
end