PUT /gemfire-api/v1/{region}/{key}?op=CAS

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 region.

Resource URL

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

Parameters

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.	{ "@type": "com.gemstone.gemfire.web.rest.domain.Order", "purchaseOrderNo": 1121, "customerId": 1012, "description": "Order for XYZ Corp", "orderDate": "02/10/2014", "deliveryDate": "02/20/2014", "contact": "Jelly Bean", "email": "jelly.bean@vmware.com", "phone": "01-2048096", "items": [ { "itemNo": 1, "description": "Product-100", "quantity": 12, "unitPrice": 5, "totalPrice": 60 } ], "totalPrice": 225 }
@new	If @old value matches existing value, use this value to replace the existing value.	{ "@type": "com.gemstone.gemfire.web.rest.domain.Order", "purchaseOrderNo": 1121, "customerId": 1013, "description": "Order for New Corp", "orderDate": "02/10/2014", "deliveryDate": "02/25/2014", "contact": "Vanilla Bean", "email": "vanilla.bean@newcorp.com", "phone": "01-2048096", "items": [ { "itemNo": 12345, "description": "part 123", "quantity": 12, "unitPrice": 29.99, "totalPrice": 149.95 } ], "totalPrice": 149.95 }

Example Request

Request Payload: application/json

PUT /gemfire-api/v1/orders/2?op=CAS

Accept: application/json
Content-Type: application/json
{
    "@old": {
         "@type":  "com.gemstone.gemfire.web.rest.domain.Order",
         "purchaseOrderNo": 1121,
         "customerId": 1012,
         "description":  "Order for  XYZ Corp",
         "orderDate":  "02/10/2014",
         "deliveryDate":  "02/20/2014",
         "contact":  "Jelly Bean",
         "email":  "jelly.bean@vmware.com",
         "phone":  "01-2048096",
         "items": [
            {
                 "itemNo": 1,
                 "description":  "Product-100",
                 "quantity": 12,
                 "unitPrice": 5,
                 "totalPrice": 60
            }
        ],
         "totalPrice": 225
    },
     "@new ": {
         "@type":  "com.gemstone.gemfire.web.rest.domain.Order",
         "purchaseOrderNo": 1121,
         "customerId": 1013,
         "description":  "Order for  New Corp",
         "orderDate":  "02/10/2014",
         "deliveryDate":  "02/25/2014",
         "contact":  "Vanilla Bean",
         "email":  "vanillabean@newcorp.com",
         "phone":  "01-2048096",
         "items": [
            {
                 "itemNo": 12345,
                 "description":  "part 123",
                 "quantity": 12,
                 "unitPrice": 29.99,
                 "totalPrice": 149.95
            }
        ],
         "totalPrice": 149.95
    }
}

Example Success Response

Response Payload: null

200 OK

Error Codes

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 GemFire server. Check the HTTP response body for a stack trace of the exception.

Example Error Response

Response-payload: application/json

409 Conflict
Content-Type: application/json
{
     "purchaseOrderNo": 1121,
     "customerId": 1012,
     "description":  "Order for  XYZ Corp",
     "orderDate":  "02/10/2014",
     "deliveryDate":  "02/20/2014",
     "contact":  "Jelly Bean",
     "email":  "jelly.bean@vmware.com",
     "phone":  "01-2048096",
     "items": [
        {
             "itemNo": 1,
             "description":  "Product-100",
             "quantity": 12,
             "unitPrice": 5,
             "totalPrice": 60
        }
    ],
     "totalPrice": 225
}

Implementation Notes

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.