Accessing optimistic concurrency features in Azure Mobile Services client SDKs

發行項
12/02/2013

In my last post I talked about the new features in the tables inside Azure Mobile Services. One of those features is the ability to do conditional retrieval and updates of items, which can be used to implement optimistic concurrency in such tables. The scenario is that many clients can perform updates to the items in the server, but those updates will only work if the version the clients are updating actually match the version of the item in the server, to avoid a case where an update done by one client is lost because of an update done by a different client.

Another feature added to the tables were some new system properties, which provide useful information about the items (creation and update time, in addition to the version, used for optimistic concurrency). As those properties cannot be sent by the clients, and are only returned if explicitly asked for, they also require a special handling in the client.

At this moment, the managed (Windows Store / Windows Phone / Full .NET 4.5) version of the SDK has built-in support for those features, with the support for other platforms planned to arrive soon. But if you want to start using those features in the other platforms now, you can do so by using special filters, which is what I’ll show in this post (once the support in those platforms is there I’ll likely make another post with more information).

Quick recap

In order to request that the server send the system properties in its CRUD responses, the clients need to send the ‘__systemProperties’ query parameter, informing which of those special columns it wants to receive. So If a client is interested in the creation time and the version of the items it receives in a query, it can send ‘__systemProperties=createdAt,version’ in its request, like the following example (some headers omitted for brevity):

GET /tables/Person? __systemproperties=__createdAt%2C__version HTTP/1.1
X-ZUMO-APPLICATION: your-app-key
Accept: application/json
Host: your-service.azure-mobile.net

And the server would respond with them (some headers omitted, JSON response pretty-printed):

HTTP/1.1 200 OK
Content-Length: 565
Content-Type: application/json
Server: Microsoft-IIS/8.0
x-zumo-version: Zumo.Main.0.1.6.4247.Runtime
Date: Thu, 28 Nov 2013 20:54:40 GMT

[{"id":"A3EDC179-462E-4266-8691-1A1610CAE121","__createdAt":"2013-11-28T20:54:13.604Z","__version":"AAAAAAAAB+c=","name":"John Doe","age":33},{"id":"AF4E2B0B-625B-44F3-876B-BB65BB40BD78","__createdAt":"2013-11-28T20:54:13.901Z","__version":"AAAAAAAAB+k=","name":"Jane Roe","age":32}]

That’s it for system properties – if the client requests them (like in the example above, ‘__createdAt’ and ‘__version’), the server will include them in the response; if the client doesn’t (in the example above, ‘__updatedAt’), the response will not have it.

Conditional retrieval is done by using the value of the ‘__version’ property and using it as the item ETag (it’s also returned as the ETag HTTP response header in insert and update operations, and when querying for single items), and using it in the ‘If-None-Match’ request header. For the items above, if the client wants to check whether there have been any changes:

GET /tables/Person/A3EDC179-462E-4266-8691-1A1610CAE121?__systemProperties=version HTTP/1.1
X-ZUMO-APPLICATION: your-app-key
Accept: application/json
If-None-Match: "AAAAAAAAB+c="
Host: your-service.azure-mobile.net

If the item had not been updated, the server will just return with a 304 response. Otherwise, it will return the item as it normally would.

Conditional updates is also done via the item version mapped to the ETag of the server resource. For all PATCH requests, if the client wants the server only to update the item if the version on the server is the same version on the client, then it needs to send the ‘If-Match’ request header with the version as the ETag:

PATCH /tables/Person/A3EDC179-462E-4266-8691-1A1610CAE121?__systemProperties=version HTTP/1.1
X-ZUMO-APPLICATION: your-app-key
Content-Type: application/json
If-Match: "AAAAAAAAB+c="
Host: your-service.azure-mobile.net
Content-Length: 54

{"age":34,"id":"A3EDC179-462E-4266-8691-1A1610CAE121"}

If the server version matched that version, the update will happen as expected. However, if the item in the server had been updated (and its version changed), the server would respond with a 412 (Precondition Failed) response, including the current version of the item in the server in its response body. With the item in the response of the failed update, the client can look at both versions (its own and the server one) and decide what to do – a few examples are ignoring the client changes and take the server version; override the server version (by resubmitting the PATCH request, but with the version from the server item) or applying some custom merge policy and retrying the update.

Now let’s see how to access those features from the client side. Since each platform has a different behavior, let’s look at each one individually.

Managed clients

The managed client currently has full support for the table system properties, and it will do the “right” thing when sending / receiving data to / from the service. As described in the previous post, the service will only return those properties if explicitly asked for. The support is different depending on whether the calls are done for typed tables (i.e., IMobileServiceTable<T>) or untyped tables (i.e., IMobileServiceTable), so let’s look at them separately.

Untyped tables

Untyped tables are those in which all operations are done with JSON objects (represented by the classes in the Newtonsoft.Json.Linq namespace, usually with the classes JToken, JObject, JArray and JValue. Those tables are represented by the interface IMobileServiceTable, and returned by calls to MobileServiceClient.GetTable(string)). With the latest update (NuGet 1.1.0) there’s a new property, ‘SystemProperties’, in which you can set to determine which values will be requested by all CRUD operations made in that object. For example, in the code below the data returned by the service will have, in addition to the “regular” columns stored in the ‘Person’ table, the values of the columns ‘__createdAt’ and ‘__version’ from the first 5 items in that table.

var table = MobileService.GetTable("Person");
table.SystemProperties = MobileServiceSystemProperties.CreatedAt | MobileServiceSystemProperties.Version;
var data = await table.ReadAsync("$top=5");

Notice that by setting the ‘SystemProperties’ in the table object, it doesn’t only add the ‘__systemProperties’ parameter in read operations – it will add them in all of the table operations. This is important so that you can get those properties when creating or updating an item, for example. Take the code below:

var table = MobileService.GetTable("Person");
table.SystemProperties = MobileServiceSystemProperties.CreatedAt |
MobileServiceSystemProperties.Version;
var item = new JObject(new JProperty("name", "John Doe"), new JProperty("age", 33));
var inserted = (JObject)(await table.InsertAsync(item));
inserted["age"] = 34;
var updated = await table.UpdateAsync(inserted);
AddToDebug("Updated: {0}", updated);

When executed, the insert (POST) call will add the query parameter, so that the response will have the requested values:

POST /tables/Person? __systemproperties=__createdAt%2C__version HTTP/1.1
X-ZUMO-APPLICATION: your-app-key
Accept: application/json
Content-Type: application/json; charset=utf-8
Host: your-service.azure-mobile.net
Content-Length: 28

{"name":"John Doe","age":33}

HTTP/1.1 201 Created
Content-Length: 140
Content-Type: application/json
ETag: "AAAAAAAAB/U="
Location: https://your-service.azure-mobile.net/tables/Person/6DD0F0A1-EF4E-4F40-A03C-91C7F528F57E
Server: Microsoft-IIS/8.0
x-zumo-version: Zumo.Main.0.1.6.4247.Runtime
Date: Fri, 29 Nov 2013 15:38:35 GMT

{"name":"John Doe","age":33,"id":"6DD0F0A1-EF4E-4F40-A03C-91C7F528F57E", "__createdAt":"2013-11-29T15:38:35.618Z","__version":"AAAAAAAAB/U=" }

Notice that the inserted object version is also mapped to the ETag header – we’re being good HTTP citizens here, using the appropriate header to “tag” the resource which has just been created in the server.

The UpdateAsync call is more interesting. The object had both a ‘__createdAt’ and a ‘__version’ property, but those system properties cannot be send by the client – so the client SDK will actually remove those prior to sending the request over the wire. Also, since the object being updated has a ‘__version’ property, it will be “lifted” into the request’s If-Match header, thus making it a conditional update. The simple presence of that property enables the optimistic concurrency scenario, as can be seen below (the request / response for that call).

PATCH /tables/Person/6DD0F0A1-EF4E-4F40-A03C-91C7F528F57E? __systemproperties=__createdAt%2C__version HTTP/1.1
If-Match: "AAAAAAAAB/U="
X-ZUMO-APPLICATION: your-app-key
Accept: application/json
Content-Type: application/json; charset=utf-8
Host: your-service.azure-mobile.net
Content-Length: 72

{"name":"John Doe","age":34,"id":"6DD0F0A1-EF4E-4F40-A03C-91C7F528F57E"}

HTTP/1.1 200 OK
Content-Length: 140
Content-Type: application/json
ETag: "AAAAAAAAB/c="
Server: Microsoft-IIS/8.0
x-zumo-version: Zumo.Main.0.1.6.4247.Runtime
Date: Fri, 29 Nov 2013 15:38:35 GMT

{"name":"John Doe","age":34,"id":"6DD0F0A1-EF4E-4F40-A03C-91C7F528F57E", "__version":"AAAAAAAAB/c=","__createdAt":"2013-11-29T15:38:35.618Z" }

So in the success case it works as expected. But what if another client had updated the same item? In this case, the version we have in the client would be incorrect, and the server would return a 412 (Precondition Failed) response. The client SDK actually catches that response, and throws a special exception (MobileServicePreconditionFailedException, a subclass of MobileServiceInvalidOperationException), which contains the server item returned by the server. The client can then retrieve that item, and decide what to do (i.e., its merge policy).

var item = new JObject(new JProperty("name", "John Doe"), new JProperty("age", 33));
var inserted = (JObject)(await table.InsertAsync(item));
inserted["age"] = 34;
try
{
// Invalid version, simulate another client making an update prior to this one
inserted["__version"] = "incorrect";
var updated = await table.UpdateAsync(inserted);
AddToDebug("Updated: {0}", updated);
}
catch (MobileServicePreconditionFailedException ex)
{
var serverVersion = ex.Value;
AddToDebug("The value of the item in the server: {0}", serverVersion);
}

Typed tables

Those are the types of tables which are bound to a specific user type. For example, the code below defines a table which can only be used to work (insert / query / update / delete) objects of type Person¹:

var table = MobileService.GetTable<Person>();
var person = new Person { Name = "John Doe", Age = 33 };
await table.InsertAsync(person);

To access the system properties in those tables, you can also use the ‘SystemProperties’ property in the table object. However, since in this case the SDK knows which objects the requests will be bound to, it can infer the properties you want based on the type itself. As long as the type has properties which map to the system columns, the ‘SystemProperties’ property will be set with the appropriate value. The can be accomplished in two ways. The first is by naming the property the name of the system column (‘__createdAt’, ‘__updatedAt’, ‘__version’) either directly or using the [JsonProperty] annotation, as shown below (created / updated using the attribute, version defined directly).

public class Person
{
public string Id { get; set; }
[JsonProperty("name")]
public string Name { get; set; }
[JsonProperty("age")]
public int Age { get; set; }
[JsonProperty("__createdAt")]
public DateTime CreatedAt { get; set; }
[JsonProperty("__updatedAt")]
public DateTime UpdatedAt { get; set; }
public string __version { get; set; }
}

The second option is to use the special attributes (introduced in the version 1.1.0 of the NuGet package for the Mobile Services SDK) that declare that those fields will be mapped to the corresponding special property. Those attributes are [CreatedAt], [UpdatedAt] and [Version], all from the Microsoft.WindowsAzure.MobileServices namespace (as of the time of this post, the documentation has yet to be updated to account for those attributes). This is the same class, defined with those attributes:

public class Person
{
public string Id { get; set; }
[JsonProperty("name")]
public string Name { get; set; }
[JsonProperty("age")]
public int Age { get; set; }
[CreatedAt]
public DateTime CreatedAt { get; set; }
[UpdatedAt]
public DateTime UpdatedAt { get; set; }
[Version]
public string Version { get; set; }
}

When a table has the items shown above, you don’t need to set the value of the ‘SystemProperties’ member in the table, as it will be done when the table object is being created by the MobileServiceClient.GetTable<T> call. Assuming that the type Person is defined as above, the code below will print the id of the newly inserted object and the creation time (based on the server clock), and the updated time will show (roughly) 5 seconds after the creation time after the call to UpdateAsync.

var table = MobileService.GetTable<Person>();
var item = new Person { Name = "John Doe", Age = 33 };
await table.InsertAsync(item);
AddToDebug("Person {0} was created at {1}", item.Id, item.CreatedAt);
await Task.Delay(5000);
item.Age = 34;
await table.UpdateAsync(item);
AddToDebug("Person was last updated at {0}", item.UpdatedAt);

Like in the case with untyped tables, the SDK will map the ETag header in the server responses to the property corresponding to the ‘__version’ column in the client – and on update requests, that property will be mapped to the If-Match HTTP header. The update call shown above will only succeed if no changes had been made to the item in the 5 seconds which elapsed between its creation time and the update call.

If the update call fail because of a version mismatch, the UpdateAsync operation will throw a MobileServicePreconditionFailedException<T> (subclass of the non-generic MobileServicePreconditionFailedException class), where T is the type bound to the table. In this case, the exception will have a property containing the (typed) item which reflects the value of the resource in the server, as can be seen below.

var item = new Person { Name = "John Doe", Age = 33 };
await table.InsertAsync(item);
AddToDebug("Person {0} was created at {1}", item.Id, item.CreatedAt);
try
{
// Invalid version, simulate another client making an update prior to this one
item.Version = "invalid";
item.Age = 34;
await table.UpdateAsync(item);
}
catch (MobileServicePreconditionFailedException<Person> ex)
{
Person serverItem = ex.Item;
AddToDebug("Update failed, server item: {0}-{1}", serverItem.Name, serverItem.Age);
}

One last thing about typed tables and the new features: if you call the method IMobileServiceTable<T>.RefreshAsync in an object which has a ‘__version’ property, that call will be made as a condition GET: the __version property will be “lifted” into the If-None-Match request header, and the server will only return a response (instead of a 304 Not Modified) if the version in the table is different than the one passed in that header.

¹ to be more precise, it can also use the untyped notation, by inserting / reading / etc. data of type JToken and its derived classes; but I mean that it cannot work with objects of type ‘Order’ or ‘Product’, for example.

JavaScript

If you want to access system properties and use optimistic concurrency in the managed client, it does almost all of it for you, by requesting the appropriate fields and mapping the version property to the proper HTTP ETag in request and responses. But for other platforms, this support isn’t there (at least not as of the writing of this post; it should come in the near future). So let’s see how we can use the filters to enable that support. First: JavaScript (both for WinStore applications and for HTML/JS apps)

If you take an existing code like the one below, it will run and the response will not have any of the system properties.

var table = client.getTable('person');
var item = { name: 'John Doe', age: 33 };
table.insert(item).then(function (inserted) {
document.getElementById('result').innerText = 'Inserted: ' + JSON.stringify(inserted);
}, function (err) {
document.getElementById('result').innerText = 'Error: ' + JSON.stringify(err);
});

We can use the additional parameter to the ‘insert’ method, and that would actually work. In the code below the inserted item (passed to the success callback) will have not only the name, age and id properties, but also the ‘__createdAt’ and ‘__version’ ones as requested.

var table = client.getTable('person');
var item = { name: 'John Doe', age: 33 };
table.insert(item, { __systemProperties: 'createdAt,version' }).then(function (inserted) {
document.getElementById('result').innerText = 'Inserted: ' + JSON.stringify(inserted);
}, function (err) {
document.getElementById('result').innerText = 'Error: ' + JSON.stringify(err);
});

That works for requesting the properties, but then you’ll need to pass those parameters in all requests for that table. A better alternative is to use a filter which will do it for all operations, like in the example below:

function createSystemPropertiesFilter(properties) {
properties = properties || '*'; // all properties if none specified
return function (req, next, callback) {
var url = req.url;
url = addSystemProperties(url);
req.url = url;
next(req, callback);
function addSystemProperties(url) {
var queryIndex = url.indexOf('?');
var query, urlNoQuery;
if (queryIndex >= 0) {
urlNoQuery = url.substring(0, queryIndex);
query = url.substring(queryIndex + 1) + '&';
} else {
urlNoQuery = url;
query = '';
}
query = query + '__systemProperties=' + properties;
return urlNoQuery + '?' + query;
}
};
}
client = client.withFilter(createSystemPropertiesFilter('createdAt,version'));
var table = client.getTable('person');
var item = { name: 'John Doe', age: 33 };
table.insert(item).then(function (inserted) {
document.getElementById('result').innerText = 'Inserted: ' + JSON.stringify(inserted);
}, function (err) {
document.getElementById('result').innerText = 'Error: ' + JSON.stringify(err);
});

Now let’s try an update call. After we succeed inserting an item, we’ll try to update that item using the code below.

client = client.withFilter(createSystemPropertiesFilter('createdAt,version'));
var table = client.getTable('person');
var item = { name: 'John Doe', age: 33 };
table.insert(item).then(function (inserted) {
document.getElementById('result').innerText = 'Inserted: ' + JSON.stringify(inserted);
// Let's now update the item...
inserted.age = 34;
table.update(item).done(function (updated) {
document.getElementById('result').innerText += '\nUpdated: ' + JSON.stringify(updated);
}, function (err) {
document.getElementById('result').innerText += '\nError updating: ' + JSON.stringify(err);
});
});

Unfortunately the update call fails with the message “Error: The property '__createdAt' can not be set. Properties that begin with a '__' are considered system properties.” We need then to update our filter to remove such properties on update calls (since they cannot be set from the client, as I mentioned before).

function createSystemPropertiesFilter(properties) {
properties = properties || '*'; // all properties if none specified
return function (req, next, callback) {
var url = req.url;
url = addSystemProperties(url);
req.url = url;
removeSystemPropertiesFromBody(req);
next(req, callback);
function removeSystemPropertiesFromBody(request) {
var method = request.type;
var data = request.data;
if (method === 'PATCH' || method === 'PUT') {
var body = JSON.parse(data);
if (typeof body === 'object') {
var toRemove = [];
for (var k in body) {
if (k.indexOf('__') === 0) {
toRemove.push(k);
}
}
if (toRemove.length) {
for (var i = 0; i < toRemove.length; i++) {
delete body[toRemove[i]];
}
req.data = JSON.stringify(body);
}
}
}
}
function addSystemProperties(url) {
// Same as previous...
}
};
}

Now the insert-then-update code which failed before works fine, and if all you want is to access system properties then we’re done. But let’s complete the picture – lifting the __version property into the If-Match request header for update calls. This can be done by changing the ‘removeSystemPropertiesFromBody’ function. Below is the full code for the filter-generating function, which can be used for optimistic concurrency scenarios.

function createSystemPropertiesFilter(properties) {
properties = properties || '*'; // all properties if none specified
return function (req, next, callback) {
var url = req.url;
url = addSystemProperties(url);
req.url = url;
removeSystemPropertiesFromBody(req);
next(req, callback);
function removeSystemPropertiesFromBody(request) {
var method = request.type;
var data = request.data;
if (method === 'PATCH' || method === 'PUT') {
var body = JSON.parse(data);
if (typeof body === 'object') {
var toRemove = [];
for (var k in body) {
if (k.indexOf('__') === 0) {
toRemove.push(k);
if (k === '__version') {
var etag = '\"' + body[k] + '\"';
request.headers['If-Match'] = etag;
}
}
}
if (toRemove.length) {
for (var i = 0; i < toRemove.length; i++) {
delete body[toRemove[i]];
}
req.data = JSON.stringify(body);
}
}
}
}
function addSystemProperties(url) {
var queryIndex = url.indexOf('?');
var query, urlNoQuery;
if (queryIndex >= 0) {
urlNoQuery = url.substring(0, queryIndex);
query = url.substring(queryIndex + 1) + '&';
} else {
urlNoQuery = url;
query = '';
}
query = query + '__systemProperties=' + properties;
return urlNoQuery + '?' + query;
}
};
}

With this filter you should be able to get your feet wet with the new features in JavaScript while the official support doesn’t arrive.

iOS

iOS is fairly similar to JavaScript in a way that both languages only deal with “untyped” data (objects, arrays and primitives on JavaScript; NSDictionary, NSArray, NSNumber, NSString, NSDate and NSNull in iOS), so the filter implementation is pretty much the same, translated into Objective-C. Without further ado, this is a filter which can be used in iOS to consume system properties and perform conditional updates.

@interface SystemPropertiesFilter : NSObject<MSFilter>
{
NSString *_properties;
}
@end

@implementation SystemPropertiesFilter

- (id)init {
self = [super init];
if (self) {
// Default to all properties
self->_properties = @"*";
}
return self;
}

- (id)initWithProperties:(NSString *)properties {
self = [super init];
if (self) {
self->_properties = properties;
}
return self;
}

- (void)handleRequest:(NSURLRequest *)request next:(MSFilterNextBlock)onNext response:(MSFilterResponseBlock)onResponse {
// Append __systemProperties to the query string
NSString *url = [[request URL] absoluteString];
NSString *query, *urlWithoutQuery;
NSRange indexOfQuery = [url rangeOfString:@"?"];
if (indexOfQuery.location == NSNotFound) {
query = @"";
urlWithoutQuery = url;
} else {
query = [url substringFromIndex:(indexOfQuery.location + 1)];
query = [query stringByAppendingString:@"&"];
urlWithoutQuery = [url substringToIndex:indexOfQuery.location];
}
urlWithoutQuery = [urlWithoutQuery stringByAppendingString:@"?"];
query = [query stringByAppendingString:@"__systemProperties="];
query = [query stringByAppendingString:self->_properties];
url = [urlWithoutQuery stringByAppendingString:query];

    // Clone the request and headers
NSMutableURLRequest *newRequest = [[NSMutableURLRequest alloc] initWithURL:[NSURL URLWithString:url]];
NSString *HTTPMethod = [request HTTPMethod];
[newRequest setHTTPMethod:HTTPMethod];
NSDictionary *requestHeaders = [request allHTTPHeaderFields];
for (NSString *headerName in [requestHeaders keyEnumerator]) {
NSString *headerValue = [requestHeaders objectForKey:headerName];
[newRequest setValue:headerValue forHTTPHeaderField:headerName];
}
[newRequest setHTTPBody:[request HTTPBody]];

    // Remove the system properties from the request
if ([HTTPMethod isEqualToString:@"PUT"] || [HTTPMethod isEqualToString:@"PATCH"]) {
NSError *error;
NSData *requestBody = [request HTTPBody];
id body = [NSJSONSerialization JSONObjectWithData:requestBody options:0 error:&error];
if (error) {
onResponse(nil, nil, error);
return;
}
if ([body isKindOfClass:[NSDictionary class]]) {
NSDictionary *item = body;
NSString *version = nil;
NSMutableDictionary *newItem = [[NSMutableDictionary alloc] init];
BOOL propertyRemoved = NO;
for (NSString *key in [item allKeys]) {
if ([key hasPrefix:@"__"]) {
propertyRemoved = YES;
if ([key isEqualToString:@"__version"]) {
version = [item objectForKey:key];
}
} else {
[newItem setValue:[item objectForKey:key] forKey:key];
}
}

            if (version) {
NSString *etag = [NSString stringWithFormat:@"\"%@\"", version];
[newRequest setValue:etag forHTTPHeaderField:@"If-Match"];
}

            if (propertyRemoved) {
NSData *newBody = [NSJSONSerialization dataWithJSONObject:newItem options:0 error:&error];
if (error) {
onResponse(nil, nil, error);
return;
}
[newRequest setHTTPBody:newBody];
}
}
}

    // Now send the updated request
onNext(newRequest, onResponse);
}

@end

The filter can be used by calling the clientWithFilter: selector in the MSClient class to create a new client object which uses that filter.

MSClient *client = [MSClient clientWithApplicationURLString:@"https://my-service.azure-mobile.net/"
applicationKey:@"my-application-key"];
SystemPropertiesFilter *filter = [[SystemPropertiesFilter alloc]
initWithPropreties:@"createdAt,version"];
client = [client clientWithFilter:filter];
MSTable *table = [client tableWithName:@"Person"];
NSDictionary *item = @{@"name":@"John Doe",@"age":@33};
[table insert:item completion:^(NSDictionary *inserted, NSError *error) {
if (error) {
NSLog(@"Error: %@", error);
return;
}
NSLog(@"Inserted: %@", inserted);
NSMutableDictionary *toUpdate = [[NSMutableDictionary alloc] initWithDictionary:inserted];
[toUpdate setValue:@34 forKey:@"age"];
[table update:toUpdate completion:^(NSDictionary *updated, NSError *error) {
if (error) {
NSLog(@"Error: %@", error);
return;
}
NSLog(@"Updated: %@", updated);
}];
}];

And that’s it for iOS.

Android

Android is more similar to the managed SDK, since it has both a typed (using user-defined types) and untyped (using the com.google.gson types). For the untyped case, we’re at the same boat as both JavaScript and iOS, so we can define a filter with the same behavior (this time, in Java):

class SystemPropertiesFilter implements ServiceFilter {
private String systemProperties;
public SystemPropertiesFilter() {
this.systemProperties = "*";
}
public SystemPropertiesFilter(String properties) {
this.systemProperties = properties;
}
@Override
public void handleRequest(ServiceFilterRequest req,
NextServiceFilterCallback next,
ServiceFilterResponseCallback callback) {
String url = req.getUrl();
url = addSystemPropertiesToQuery(url);
try {
req.setUrl(url);
} catch (URISyntaxException e) {
e.printStackTrace();
}
removeSystemPropertiesFromBody(req);
next.onNext(req, callback);
}
private void removeSystemPropertiesFromBody(ServiceFilterRequest req) {
String method = req.getMethod();
if (method.equalsIgnoreCase("PUT") || method.equalsIgnoreCase("PATCH")) {
// Remove system properties from update calls
String body = req.getContent();
JsonElement json = new JsonParser().parse(body);
if (json.isJsonObject()) {
JsonObject obj = json.getAsJsonObject();
List<String> toRemove = new ArrayList<String>();
for (Entry<String, JsonElement> entry : obj.entrySet()) {
String key = entry.getKey();
if (key.startsWith("__")) {
toRemove.add(key);
if (key.equals("__version")) {
String version = entry.getValue().getAsString();
req.addHeader("If-Match", "\"" + version + "\"");
}
}
}
if (!toRemove.isEmpty()) {
for (String prop : toRemove) {
obj.remove(prop);
}
try {
req.setContent(obj.toString());
} catch (Exception e) {
e.printStackTrace();
}
}
}
}
}
private String addSystemPropertiesToQuery(String url) {
int queryIndex = url.indexOf('?');
String query;
String urlNoQuery;
if (queryIndex >= 0) {
urlNoQuery = url.substring(0, queryIndex);
query = url.substring(queryIndex + 1) + "&";
} else {
query = "";
urlNoQuery = url;
}
query = query + "__systemProperties=" + this.systemProperties;
return urlNoQuery + "?" + query;
}
}

And we can then use it if we’re talking to an untyped table (i.e., one represented by the MobileServiceJsonTable class), we can use this filter:

final MobileServiceClient spClient = mClient.withFilter(new SystemPropertiesFilter("createdAt,version"));
final MobileServiceJsonTable table = spClient.getTable("person");
JsonObject jo = new JsonObject();
jo.addProperty("name", "John Doe");
jo.addProperty("age", 33);
table.insert(jo, new TableJsonOperationCallback() {
@Override
public void onCompleted(JsonObject inserted, Exception error,
ServiceFilterResponse response) {
if (error != null) {
tv.setText("Error: " + error.toString());
} else {
tv.setText("Inserted: " + inserted.toString());
inserted.remove("age");
inserted.addProperty("age", 34);
table.update(inserted, new TableJsonOperationCallback() {
@Override
public void onCompleted(JsonObject updated,
Exception error,
ServiceFilterResponse response) {
String text = (String) tv.getText();
if (error != null) {
text = text + "\nError: " + error.toString();
} else {
text = text + "\nUpdated: " + updated.toString();
}
tv.setText(text);
}
});
}
}
});

But what if we’re using typed tables (i.e., MobileServiceTable<E>)? Let’s try it. So let’s define our type with the properties we want:

public class Person {
@SerializedName("id")
private String mId;
@SerializedName("name")
private String mName;
@SerializedName("age")
private int mAge;
@SerializedName("__createdAt")
private Date mCreatedAt;
@SerializedName("__version")
private String mVersion;
public String getId() { return mId; }
public void setId(String id) { mId = id; }
public String getName() { return mName; }
public void setName(String name) { mName = name; }
public int getAge() { return mAge; }
public void setAge(int age) { mAge = age; }
public Date getCreatedAt() { return mCreatedAt; }
public String getVersion() { return mVersion; }
@Override
public String toString() {
StringBuilder sb = new StringBuilder();
sb.append("Person[Name=" + this.getName());
sb.append(",Age=" + this.getAge());
sb.append(",CreatedAt=" + this.getCreatedAt());
sb.append(",Id=" + this.getId());
sb.append(",Version=" + this.getVersion() + "]");
return sb.toString();
}
}

And now try to use it:

final MobileServiceTable<Person> table = spClient.getTable(Person.class);
Person p = new Person();
p.setName("John Doe");
p.setAge(33);
table.insert(p, new TableOperationCallback<Person>() {
@Override
public void onCompleted(Person inserted, Exception error,
ServiceFilterResponse response) {
if (error != null) {
tv.setText("Error: " + error.toString());
Throwable t = error.getCause();
while (t != null) {
tv.setText((String)tv.getText() + "\n Cause: " + t.toString());
t = t.getCause();
}
} else {
tv.setText("Inserted: " + inserted.toString());
inserted.setAge(34);
table.update(inserted, new TableOperationCallback<Person>() {
@Override
public void onCompleted(Person updated,
Exception error,
ServiceFilterResponse response) {
String text = (String) tv.getText();
if (error != null) {
text = text + "\nError: " + error.toString();
} else {
text = text + "\nUpdated: " + updated.toString();
}
tv.setText(text);
}
});
}
}
});

When we run it, we get an error, though. The server responds saying that the client cannot send an item with properties starting with ‘__’. The problem here is that in the insert operation, the value of the mCreatedAt and mVersion properties are being serialized (as ‘null’), and the server rejects it. Maybe there’s a way to change the Gson serializer to avoid that, but for now I’ll take the simple route and change the filter itself. It now needs to remove system properties from the request body on botu updates and insert operations. It also needs to account for possible null values in the ‘__version’ field (which is the case for inserts). Here’s the updated definition of the ‘removeSystemPropertiesFromBody’ method:

private void removeSystemPropertiesFromBody(ServiceFilterRequest req) {
String method = req.getMethod();
if (method.equalsIgnoreCase("PUT") || method.equalsIgnoreCase("PATCH") || method.equalsIgnoreCase("POST")) {
// Remove system properties from insert / update calls
String body = req.getContent();
JsonElement json = new JsonParser().parse(body);
if (json.isJsonObject()) {
JsonObject obj = json.getAsJsonObject();
List<String> toRemove = new ArrayList<String>();
for (Entry<String, JsonElement> entry : obj.entrySet()) {
String key = entry.getKey();
if (key.startsWith("__")) {
toRemove.add(key);
if (key.equals("__version")) {
JsonElement versionJson = entry.getValue();
if (versionJson != null && versionJson.isJsonPrimitive()) {
String version = versionJson.getAsString();
if (version != null) {
req.addHeader("If-Match", "\"" + version + "\"");
}
}
}
}
}
if (!toRemove.isEmpty()) {
for (String prop : toRemove) {
obj.remove(prop);
}
try {
req.setContent(obj.toString());
} catch (Exception e) {
e.printStackTrace();
}
}
}
}
}

After those changes, the code should run fine.

Wrapping up

Hopefully this post explained how you can use the new system properties / optimistic concurrency features for all supported client SDKs. For those where the official support isn’t there yet what I showed here is mostly a workaround until the “real” support arrives.

共用方式為