Overview
The ISpaceProxy.Change
and the ChangeSet
allows updating existing objects in Space, by specifying only the required change instead of passing the entire updated object. Thus reducing required network traffic between the client and the space, and the network traffic generated from replicating the changes between the space instances (e.g between the primary space instance and its backup).
Moreover, using this API also can prevent the need of reading the existing object prior to the change operation because the change operation can specify how to change the existing property without knowing its current value. For instance, implementing atomic counters can be done by increasing a counter property of an integer property by some delta. Another example would be to add a value to a collection and so on. The change API supports transactions in the same way the other space operation supports it.
Example
The following example demonstrates how to increment the property ‘Count’ of an object of type ‘WordCount’ with id ‘myID’ by one.
ISpaceProxy space = // ... obtain a space reference
String id = "myID";
IdQuery<WordCount> idQuery = new IdQuery<WordCount>(id, routing);
space.Change(idQuery, new ChangeSet().Increment("Count", 1));
The Query Template
The change operation may receive any query template for matching a single or multiple objects that needs to be changed by the operation.
The Change Set
The change operation requires a ChangeSet
which described the changes that needs to be done once locating the object specified by the query template.
The ChangeSet
contains a predefined set of operations that can be invoked to alter the object, the set may contain one or more changes that will be applied sequentially to the object.
Each specified change may operate on any level of properties of the specified object, this is defined by specifying the path to the property that needs to be changed where ‘.’ in the path specifies
that this change is done on a nested property. For instance:
[SpaceClass]
public class Account
{
...
[SpaceID]
Guid Id {get; set;}
Balance Balance {get; set;}
}
public class Balance
{
...
public double Euro {get; set;}
public double UsDollar {get; set;}
}
ISpaceProxy space = // ... obtain a space reference
Guid id = ...;
IdQuery<Account> idQuery = new IdQuery<Account>(id, routing);
space.Change(idQuery, new ChangeSet().Increment("Balance.Euro", 5.2D));
Change Path Specification
Each operation in the change set acts on a specified string path. This path points to the property that needs to be changed and it has the following semantic:
- First level property - A path with no ‘.’ character in it points to a first level property, If the property specified by this path is not part of the Object it will be treated as a dynamic property (see Dynamic Properties) if the object does not support dynamic properties, an exception will be generated.
- Nested property - A path that contains ‘.’ character is considered a path to a nested property, the location process of the final property which needs to be changed is done recursively by activating the properties, specified by the split of the path using the ‘.’ character, one at a time until reaching the targeted end property.
- Nested Dictionary property - A path that contains ‘.’ may also point to keys inside a dictionary as, meaning the following path - ‘Attributes.Color’ will look for key named ‘Color’ if the property named ‘Attribute’ in the object is actually a dictionary. This affects nested properties as well.
The following demonstrates how the path works with a dictionary property instead of concrete properties:
[SpaceClass]
public class Account
{
...
[SpaceID]
Guid getId {get; set;}
IDictionary<String, double> Balance {get; set;}
}
ISpaceProxy space = // ... obtain a space reference
Guid id = ...;
IdQuery<Account> idQuery = new IdQuery<Account>(id, routing);
space.Change(idQuery, new ChangeSet().Increment("Balance.Euro", 5.2D));
In this case the key euro inside the dictionary behind the balance will be increased by 5.2.
Available Change Set Operations
Operation Name | Description | Semantics |
---|---|---|
Set | sets a property value | sets value of the given property |
Unset | unsets a property value | If the property is a fixed property, it will be set with null (null value for primitives), if it is a dynamic property it will be removed from the dynamic properties, note that for dynamic properties this is not equivalent to the set operation with null value |
Increment | increase a numeric property by the given delta | This change may operate on a numeric property only (byte,short,int,long,float,double or their corresponding Boxed variation), if the property does not exists, the delta will be set as its initial state |
Decrement | decrease a numeric property by the given delta | This change may operate on a numeric property only (byte,short,int,long,float,double or their corresponding Boxed variation), if the property does not exists, the -delta will be set as its initial state |
AddToCollection | adds an item to a collection property | if the property do not exists an exception will be thrown |
AddRangeToCollection | adds a list of items to a collection property | if the property do not exists an exception will be thrown |
RemoveFromCollection | removes an item from a collection property | if the property do not exists an exception will be thrown |
SetInDictionary | Sets a key value pair in a dictionary property | if the property do not exists an exception will be thrown |
RemoveFromDictionary | removes a key and its associated value from a dictionary property | if the property do not exists an exception will be thrown |
Using Change with the Embedded model
With the embedded model, updating (as well adding or removing) a nested collection with large number of elements must use the change API since the default behavior would be to replicate the entire space object and its nested collection elements from the primary to the backup (or other replica primary copies when using the sync-replicate or the async-replicated cluster schema). The Change API reduces the CPU utilization at the primary side, reduce the serialization overhead and reduce the garbage collection activity both at the primary and backup. This improves the overall system stability significantly.
Change Result
The change operations returns a IChangeResult
object that provides information regarding the change operation affect.
public interface IChangeResult<T>
{
ICollection<IChangedEntryDetails<T>> Results { get;}
int NumberOfChangedEntries { get; }
}
ISpaceProxy space = // ... obtain a space reference
Guid id = ...;
IdQuery<Account> idQuery = new IdQuery<Account>(id, routing);
IChangeResult<Account> changeResult = space.Change(idQuery, new ChangeSet().Increment("Balance.Euro", 5.2D));
if (changeResult.NumberOfChangedEntries == 0)
{
// ... handle no entry found for change
}
The IChangeResult
contains the NumberOfChangedEntries
which specifies how many objects where changed by this operation where 0 means none were changed. The Results
property gives further details about the objects that were actually changes by providing a collection which gives details for each of the objects that were changed, such as their id and version after the change took affect. By default, in order to reduce network overhead, calling the Results will throw NotSupportedException
. In order to get the more detailed result, the ChangeModifiers.ReturnDetailedResults
should be passed to the Change
operation.
For more information please refer to Change API Advanced
ChangeException
Upon any error a ChangeException
will be thrown containing the following details:
public class ChangeException
{
public ICollection<Exception> Errors {get;}
public ICollection<IFailedChangedEntryDetails> FailedChanges {get;}
public ICollection<IChangedEntryDetails<object>> SuccessfulChanges {get;}
public int NumOfSuccessfulChanges {get;}
}
The NumSuccesfullChanges
property contains the number of entries that were successfully changed.
The SuccesfullChanges
property contains details for objects that were successfully changed just like the IChangeResult.Results
property. This property can only be used if the change operation was executed using the ChangeModifiers.ReturnDetailedResults
modifier.
The FailedChanges
property contains details for objects that failed being changed, the details contains information about id, version and the actual cause for failure.
The Errors
property contains general failure reason for executing the change operation which do not apply to a specific object, such as not being able to access the space.
Multiple Changes in One Operation
One may apply multiple changes in one Change
operation by setting up multiple operation in the change set, this is done simply by chaining changes as follows:
ISpaceProxy space = // ... obtain a space reference
IdQuery<MyObject> idQuery = new IdQuery<MyObject>(id, routing);
space.Change(idQuery, new ChangeSet().Increment("SomeIntProperty", 1)
.Set("SomeStringProperty", "NewStringValue)
.SetInDictionary("SomeNestedProperty.SomeDictionaryProperty", "MyKey", 2));
The changes will applied to the object sequentially (and atomically) keeping the order applied on the ChangeSet
.
Changing the Object’s Lease
By default, the change operation will not modify the existing remaining lease of the changed entries. In order to change the lease, the new lease should be specified on the ChangeSet
using the lease
operation.
ISpaceProxy space = // ... obtain a space reference
space.Change(idQuery, new ChangeSet().Lease(1000)...);
The lease can be changed as part of other changes applied to the object, as well as having the ChangeSet
include only the lease modification without any property changes.
The lease time specified will override the existing lease with the new value relative to the current time while ignoring the current lease.
The above example will set the lease of the changed object to be one second from the time the change operation took affect.
Change with Timeout
A timeout can be passed to the change
operation, this timeout will only be used if any of the objects that needs to be changed is locked under a transaction which is not from the
current thread context. In that case, all objects which are not locked will be changed and the operation will block until either one of the two happens, which ever comes first:
- the transaction lock is released - in that case the the change operation will be applied on the objects that were locked but now available.
- the timeout elapsed - the change operation will return with an exception. Like all other failures, the exception will be a
ChangeException
which will contain the successful changes, and all the objects that remained locked when the timeout elapsed will be part of theFailedChanges
property of the exception, each with a failure reason ofOperationTimeoutException
.
If there were no matching objects for the specified template, the operation will return immediately without waiting for the timeout to elapse. This is similar to the (Read/Take)IfExists
operation semantic.
ISpaceProxy space = // ... obtain a space reference
Guid id = ...;
IdQuery<Account> idQuery = new IdQuery<Account>(id, routing);
long timeout = 1000; //1 seconds
try
{
space.Change(idQuery, new ChangeSet().Increment("Balance.Euro", 5.2D), timeout);
}
catch(ChangeException e)
{
if (e.FailedChanges.Count > 0))
{
foreach(IFailedChangedEntryDetails failedChangedEntry in e.FailedChanges)
{
if (id.Equals(failedChangedEntry.Id) && failedChangedEntry.Error is OperationTimeoutException)
{
//.. Indicate the object is still locked under a transaction, maybe retry the operation?
}
}
}
}
Change and Optimistic Locking
The Change
operation has the same semantics as regular space Update
operation when it comes to Optimistic Locking. It will increase the version of the changed object and the expected version can be specified in the id query when optimistic locking is needed.
ISpaceProxy space = // ... obtain a space reference
Guid id = ...;
Object routing = id; // In our case the space routing property is the space id property.
int version = 2; // We only want to change the object if the object's version in the space is 2.
IdQuery<Account> idQuery = new IdQuery<Account>(id, routing, version);
try
{
space.Change(idQuery, new ChangeSet().Increment("Balance.Euro", 5.2D), timeout);
}
catch(ChangeException e)
{
if (e.FailedChanges.Count > 0))
{
foreach(IFailedChangedEntryDetails failedChangedEntry in e.FailedChanges)
{
if (id.Equals(failedChangedEntry.Id) && failedChangedEntry.Error is EntryVersionConflictException)
{
//.. Indicate optimistic locking failure, get the updated version for instance and maybe read updated object and retry?
int updatedVersion = failedChangedEntry.Version;
}
}
}
}
In order to prevent constructor overload ambiguity, when using id query with version, the space routing property needs to be specified as well. If the object has no space routing then its space id property is the routing property and it should be used as shown in the previous example.
Change and Notifications
Change will be delivered as a regular update notification, with the state of the object after the change was applied.
Change Modifiers
The following modifiers can be used with the change operation
ChangeModifiers.ReturnDetailedResults
- Provide details change result containing more information about the objects that were changed, requires more network traffic.ChangeModifiers.OneWay
- Change is executed in one way mode, which means the operation will not wait for the change operation to reach the server, the result will always be null and there is no guarantee whether the operation succeeded or not as this mode does not guarantee any exceptions upon failure. The only guarantee is that the operation was successfully written to the local network buffer.ChangeModifiers.MemoryOnlySearch
- Search for matching entries in cache memory only (do not use the underlying external data source). However, any changes done on the matches entries will propagate to the underlying external data source.
Considerations
- When replicated to a gateway and a conflict occurs, change operation only supports the built in
abort
resolution asoverride
in change case may result with an inconsistent state of the object. - The change operation is converted to a regular update when delegated to a data source.