Updating a single object

Important

This operation updates a single object in the database. To update more than one object, use the bulkUpdate operation documented in the Updating multiple objects chapter of this guide.

To add this operation to a Unit Of Work instance, use the following methods:

The methods are organized by how the object to be updated is specified in the API. As you can see below, there are several ways to reference the object which will be updated in the database: explicit object reference, which is either using a Dictionary or a custom class or by using a result of a previous operation:

Objective-CSwift

DictionaryCustom ClassOperation Result

// Saves the object represented by the "objectToSave" argument in the database
// The object must have a server assigned value for the objectId property.
// The object will be saved in a data table with the "tableName" name.
// Values in the "objectToSave" map will overwrite the ones in the database.
-(OpResult *)[unitOfWorkInstance updateWithTableName:(NSString * _Nonnull)
                                        objectToSave:(NSDictionary<NSString *,id> * _Nonnull)];

// Saves the object represented by the "objectToSave" argument in
// the database. The YourCustomClass class must have either
// the get/set methods for the objectId property or a public
// string field called objectId. The object must exist in a
// data table which corresponds to the YourCustomClass class.
// For example, if YourCustomClass is called Person, then the
// objectToSave must be stored in the Person table.
-(OpResult *)[unitOfWorkInstance updateWithObjectToSave:YourCustomClass];

// Update an object represented by the "result" argument. The argument
// is a result of a previous operation in the same transaction.
// Since this operation expects a single object, the "result"
// argument must represent a single object as well. This means it
// can be a result from any of the following previous operations:
//   - saving a single object
//   - updating a single object
// The "changes" argument is a key/value dictionary of changes which will
// be updated in the object represented by "result". The keys in
// "changes" correspond to the columns in the data table where
// the updated object is stored.
-(OpResult *)[unitOfWorkInstance
              updateWithResult:(OpResult * _Nonnull)
              changes:(NSDictionary<NSString *,id> * _Nonnull)];

// Same as the above, but instead of a collection/map of "changes",
// this method accepts only one key/value pair in the form of
// propertyName and propertyValue. The propertyName argument
// is a property name in the object to be updated that will be
// updated with the value in the propertyValue argument.
-(OpResult *)[unitOfWorkInstance
              updateWithResult:(OpResult * _Nonnull)
              propertyName:(NSString * _Nonnull)
              propertyValue:(id _Nonnull)];

// Update an object represented by the "result" argument. The argument
// is a reference to an object from a result of a previous operation
// in the same transaction. Since this operation expects a single object,
// the "result" argument must represent a single object as well.
//  This means it can be obtained from any of the following previous
// operations:
//   - saving multiple objects
//   - retrieving objects
// The "changes" argument is a key/value dictionary of changes which will
// be updated in the object represented by "result". The keys in
// "changes" correspond to the columns in the data table where
// the updated object is stored.
-(OpResult *)[unitOfWorkInstance
              updateWithValueReference:(OpResultValueReference * _Nonnull)
              changes:(NSDictionary<NSString *,id> * _Nonnull)];

// Same as the above, but instead of a dictionary of "changes",
// this method accepts only one key/value pair in the form of
// propertyName and propertyValue. The propertyName argument
// is a property name in the object to be updated that will be
// updated with the value in the propertyValue argument.
-(OpResult *)[unitOfWorkInstance
              updateWithValueReference:(OpResultValueReference * _Nonnull)
              propertyName:(NSString * _Nonnull)
              propertyValue:(id _Nonnull)];

DictionaryCustom ClassOperation Result

// Saves the object represented by the "objectToSave" argument in the database
// The object must have a server assigned value for the objectId property.
// The object will be saved in a data table with the "tableName" name.
// Values in the "objectToSave" dictionary will overwrite the ones in the database.
unitOfWorkInstance.update(tableName: String, objectToSave: [String : Any]) -> OpResult

// Saves the object represented by the "objectToSave" argument in
// the database. The YourCustomClass class must have a public string
// field called objectId. The object must exist in a
// data table which corresponds to the YourCustomClass class.
// For example if YourCustomClass is called Person, then the
// objectToSave must be stored in the Person table.
unitOfWorkInstance.update(objectToSave: YourCustomClass) -> OpResult

// Update an object represented by the "result" argument. The argument
// is a result of a previous operation in the same transaction.
// Since this operation expects a single object, the "result"
// argument must represent a single object as well. This means it
// can be a result from any of the following previous operations:
//   - saving a single object
//   - updating a single object
// The "changes" argument is a key/value dictionary of changes which will
// be updated in the object represented by "result". The keys in
// "changes" correspond to the columns in the data table where
// the updated object is stored.
unitOfWorkInstance.update(result: OpResult,
                          changes: [String : Any]) -> OpResult

// Same as the above, but instead of a collection/map of "changes",
// this method accepts only one key/value pair in the form of
// propertyName and propertyValue. The propertyName argument
// is a property name in the object to be updated that will be
// updated with the value in the propertyValue argument.
unitOfWorkInstance.update(result: OpResult,
                          propertyName: String,
                          propertyValue: Any) -> OpResult

// Update an object represented by the "result" argument. The argument
// is a reference to an object from a result of a previous operation
// in the same transaction. Since this operation expects a single object,
// the "result" argument must represent a single object as well.
//  This means it can be obtained from any of the following previous
// operations:
//   - saving multiple objects
//   - retrieving objects
// The "changes" argument is a key/value map of changes which will
// be updated in the object represented by "result". The keys in
// "changes" correspond to the columns in the data table where
// the updated object is stored.
unitOfWorkInstance.update(valueReference: OpResultValueReference,
                          changes: [String : Any]) -> OpResult

// Same as the above, but instead of a collection/map of "changes",
// this method accepts only one key/value pair in the form of
// propertyName and propertyValue. The propertyName argument
// is a property name in the object to be updated that will be
// updated with the value in the propertyValue argument.
unitOfWorkInstance.update(valueReference: OpResultValueReference,
                          propertyName: String,
                          propertyValue: Any) -> OpResult

Return Value

All methods listed above return an instance of the OpResult class which represents the updated object in the database. The OpResult object can be used as an argument in other operations in the same transaction (same UnitOfWork instance). For more information see the Operation Result chapter of this guide.

Example

The examples below demonstrate the usage of the operation for all possible ways to reference the object that should be updated. This is the what the data table looks like before the transaction runs:

Objective-CSwift

DictionaryCustom ClassOperation Result

UnitOfWork *unitOfWork = [UnitOfWork new];

NSDateFormatter *formatter = [NSDateFormatter new];
formatter.dateFormat = @"dd/MM/yyyy";

NSMutableDictionary *changes = [NSMutableDictionary new];
changes[@"objectId"] = @"37ADFFA8-39E2-73A5-FF44-651EF5C4E900";
changes[@"orderStatus"] = @"complete";
changes[@"deliveryDate"] = [formatter dateFromString:@"20/03/2020"];

[unitOfWork updateWithTableName:@"Order" objectToSave:changes];

// run the transaction
[unitOfWork executeWithResponseHandler:^(UnitOfWorkResult *result) {
    NSLog(@"Transaction complete - %@", result);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

UnitOfWork *unitOfWork = [UnitOfWork new];

NSDateFormatter *formatter = [NSDateFormatter new];
formatter.dateFormat = @"dd/MM/yyyy";

Order *orderInstance = [Order new];
orderInstance.objectId = @"37ADFFA8-39E2-73A5-FF44-651EF5C4E900";
orderInstance.orderStatus = @"complete";
orderInstance.deliveryDate = [formatter dateFromString:@"20/03/2020"];

[unitOfWork updateWithObjectToSave:orderInstance];

// run the transaction
[unitOfWork executeWithResponseHandler:^(UnitOfWorkResult *result) {
    NSLog(@"Transaction complete - %@", result);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

Order class:

@interface Order : NSObject

@property (strong, nonatomic) NSString *objectId;
@property (strong, nonatomic) NSDate *deliveryDate;
@property (strong, nonatomic) NSString *orderStatus;

@end

UnitOfWork *unitOfWork = [UnitOfWork new];

// compose query builder
DataQueryBuilder *queryBuilder = [DataQueryBuilder new];

// set the query condition
queryBuilder.whereClause = @"orderId = '031820-CV1'";

// we need only one object, this will help to speed it up
queryBuilder.pageSize = 1;

// add the find operation to the transaction
OpResult *findResult = [unitOfWork findWithTableName:@"Order" queryBuilder:queryBuilder];

// get a reference to the first object (order) from the result
OpResultValueReference *orderObjectRef = [findResult resolveToResultIndex:0];

// compose a map of changes - notice the objectId is not needed there
NSDateFormatter *formatter = [NSDateFormatter new];
formatter.dateFormat = @"dd/MM/yyyy";

NSMutableDictionary *changes = [NSMutableDictionary new];
changes[@"orderStatus"] = @"complete";
changes[@"deliveryDate"] = [formatter dateFromString:@"20/03/2020"];

// add the update operation to the transaction
[unitOfWork updateWithValueReference:orderObjectRef changes:changes];

// run the transaction
[unitOfWork executeWithResponseHandler:^(UnitOfWorkResult *result) {
    NSLog(@"Transaction complete - %@", result);
} errorHandler:^(Fault *fault) {
    NSLog(@"Error: %@", fault.message);
}];

DictionaryCustom ClassOperation Result

let unitOfWork = UnitOfWork()

let formatter = DateFormatter()
formatter.dateFormat = "dd/MM/yyyy"

var changes = [String : Any]()
changes["objectId"] = "37ADFFA8-39E2-73A5-FF44-651EF5C4E900"
changes["orderStatus"] = "complete"
changes["deliveryDate"] = formatter.date(from: "20/03/2020")

let _ = unitOfWork.update(tableName: "Order", objectToSave: changes)

// run the transaction
unitOfWork.execute(responseHandler: { result in
    print("Transaction complete - \(result)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

@objcMembers class Order: NSObject {
    public var objectId: String?
    public var deliveryDate: Date?
    public var orderStatus: String?
}

let unitOfWork = UnitOfWork()

let formatter = DateFormatter()
formatter.dateFormat = "dd/MM/yyyy"

let orderInstance = Order()
orderInstance.objectId = "37ADFFA8-39E2-73A5-FF44-651EF5C4E900"
orderInstance.orderStatus = "complete"
orderInstance.deliveryDate = formatter.date(from: "20/03/2020")

let _ = unitOfWork.update(objectToSave: orderInstance)        

// run the transaction     
unitOfWork.execute(responseHandler: { result in
    print("Transaction complete - \(result)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

let unitOfWork = UnitOfWork()

// compose query builder
let queryBuilder = DataQueryBuilder()

// set the query condition
queryBuilder.whereClause = "orderId = '031820-CV1'"

// we need only one object, this will help to speed it up
queryBuilder.pageSize = 1

// add the find operation to the transaction
let findResult = unitOfWork.find(tableName: "Order", queryBuilder: queryBuilder)

// get a reference to the first object (order) from the result
let orderObjectRef = findResult.resolveTo(resultIndex: 0)

// compose a map of changes - notice the objectId is not needed there
let formatter = DateFormatter()
formatter.dateFormat = "dd/MM/yyyy"

var changes = [String : Any]()
changes["orderStatus"] = "complete"
changes["deliveryDate"] = formatter.date(from: "20/03/2020")

// add the update operation to the transaction
let _ = unitOfWork.update(valueReference: orderObjectRef, changes: changes)

// run the transaction
unitOfWork.execute(responseHandler: { result in
    print("Transaction complete - \(result)")
}, errorHandler: { fault in
    print("Error: \(fault.message ?? "")")
})

This is what the same object in the data table looks like after the transaction runs: