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



1117
1118
1119
 
# File 'lib/parse/model/core/actions.rb', line 1117

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:



889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
 
# File 'lib/parse/model/core/actions.rb', line 889

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.



1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
 
# File 'lib/parse/model/core/actions.rb', line 1250

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.



1158
1159
1160
1161
1162
1163
1164
1165
1166
 
# File 'lib/parse/model/core/actions.rb', line 1158

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.



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

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.



1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
 
# File 'lib/parse/model/core/actions.rb', line 1126

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:



871
872
873
874
875
876
877
 
# File 'lib/parse/model/core/actions.rb', line 871

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:



777
778
779
 
# File 'lib/parse/model/core/actions.rb', line 777

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:



827
828
829
830
831
832
 
# File 'lib/parse/model/core/actions.rb', line 827

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:



787
788
789
 
# File 'lib/parse/model/core/actions.rb', line 787

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:



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

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:



850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
 
# File 'lib/parse/model/core/actions.rb', line 850

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:



796
797
798
 
# File 'lib/parse/model/core/actions.rb', line 796

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:



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

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.



752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
 
# File 'lib/parse/model/core/actions.rb', line 752

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! ⇒ Object

Runs all the registered ‘before_save` related callbacks.



1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
 
# File 'lib/parse/model/core/actions.rb', line 1146

def prepare_save!
  # With terminator configured, run_callbacks will return false if any callback returns false
  # We track if the block executes to know if callbacks were halted
  callback_success = false
  run_callbacks(:save) do
    callback_success = true
    true
  end
  callback_success
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.



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

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.



1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
 
# File 'lib/parse/model/core/actions.rb', line 1040

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.



1110
1111
1112
 
# File 'lib/parse/model/core/actions.rb', line 1110

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:



1239
1240
1241
1242
1243
1244
1245
1246
 
# File 'lib/parse/model/core/actions.rb', line 1239

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.



954
955
956
957
 
# File 'lib/parse/model/core/actions.rb', line 954

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.



923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
 
# File 'lib/parse/model/core/actions.rb', line 923

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.



1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
 
# File 'lib/parse/model/core/actions.rb', line 1199

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.



880
881
882
 
# File 'lib/parse/model/core/actions.rb', line 880

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