This topic describes the PUT command in VMware Tanzu GemFire to update (compare-and-set) value-having key with a new value if and only if the @old
value sent matches the current value-having key in the region.
http://<hostname_or_http-service-bind-address>:<http-service-port>/gemfire-api/v1/{region}/{key}?op=CAS
http://<hostname_or_http-service-bind-address>:<http-service-port>/gemfire-api/v1/{region}/{key1},{key2},...{keyN}?op=CAS
Parameter | Description | Example Values |
---|---|---|
op | URL parameter. When you specify CAS for this parameter, data is only updated if the @old value specified in the request body matches the existing value in the region. | CAS |
@type | Specified in the response body for both the old and new value. Use this to declare the domain object type of the entry's value. | com.mycompany.ObjectName |
@old | Compare this value to the existing value in the region. |
|
@new | If @old value matches existing value, use this value to replace the existing value. |
|
Request Payload: application/json
PUT /gemfire-api/v1/orders/2?op=CAS
Accept: application/json
Content-Type: application/json
{
"@old": {
"@type": "org.apache.geode.web.rest.domain.Order",
"purchaseOrderNo": 1121,
"customerId": 1012,
"description": "Order for XYZ Corp",
"orderDate": "02/10/2020",
"deliveryDate": "02/20/2020",
"contact": "Jelly Bean",
"email": "[email protected]",
"phone": "01-2048096",
"items": [
{
"itemNo": 1,
"description": "Product-100",
"quantity": 12,
"unitPrice": 5,
"totalPrice": 60
}
],
"totalPrice": 225
},
"@new ": {
"@type": "org.apache.geode.web.rest.domain.Order",
"purchaseOrderNo": 1121,
"customerId": 1013,
"description": "Order for New Corp",
"orderDate": "02/10/2020",
"deliveryDate": "02/25/2020",
"contact": "Vanilla Bean",
"email": "[email protected]",
"phone": "01-2048096",
"items": [
{
"itemNo": 12345,
"description": "part 123",
"quantity": 12,
"unitPrice": 29.99,
"totalPrice": 149.95
}
],
"totalPrice": 149.95
}
}
Response Payload: null
200 OK
Status Code | Description |
---|---|
400 BAD REQUEST | Returned if the supplied key is not present in the region. |
404 NOT FOUND | Returned if the region is not found. |
409 CONFLICT | Returned if the provided @old value of the key does not match the current value of the key. |
500 INTERNAL SERVER ERROR | Error encountered at Tanzu GemFire server. Check the HTTP response body for a stack trace of the exception. |
Response-payload: application/json
409 Conflict
Content-Type: application/json
{
"purchaseOrderNo": 1121,
"customerId": 1012,
"description": "Order for XYZ Corp",
"orderDate": "02/10/2020",
"deliveryDate": "02/20/2020",
"contact": "Jelly Bean",
"email": "[email protected]",
"phone": "01-2048096",
"items": [
{
"itemNo": 1,
"description": "Product-100",
"quantity": 12,
"unitPrice": 5,
"totalPrice": 60
}
],
"totalPrice": 225
}
If the “@old” value sent by the client in the HTTP request, along with the “@new” value, does not match the existing value having key in region, then a 409 - CONFLICT error is returned indicating the mismatch in expected state. The “@old” and current value must match in order for the key to be assigned the “@new” value.
If a “CONFLICT” occurs, it is a simple matter for the client to issue a HTTP GET request for the Key (GET /gemfire-api/v1/orders/222) to get a updated copy of the value. CAS is similar to optimistic locking (as opposed to optimistic locking assuming the value will change between the time a client requests a value and subsequently updates the value) in that it assumes the client’s state is up-to-date when the client tries to update, but if not then fail, hence the 409 - CONFLICT.