This response type is returned when an error occurs with any command type.
| ErrorResponse | |||
| Field Name | Data type | Description | Mandatory? |
|---|---|---|---|
| errorCode | Int | An Integer representing the error code for a specific error | Y |
| errorMessage | String | A description of the error. | N |
While each operation describes some errors particular to its execution, the following errors are fairly generic and can be seen in a wide variety of operations. This list is a possible super-set of errors that can be thrown and are applicable to all operations.
| Error Code | Error Definition | Error Description |
|---|---|---|
| 1000 | UNCLASSIFIED_FAILURE | This error will be thrown as a last resort if an exception cannot be classified. This error will then have to be investigated and correctly classified |
| 1100 | VALUE_ENCODING_ERROR | There was an error whilst encoding a data entry (key / value) |
| 1102 | UNSUPPORTED_OPERATION | The request isn't a valid server operation |
| 1201 | AUTHORIZATION_FAILED | The client doesn't have sufficient access rights to perform this operation |
| 1300 | LOW_MEMORY | Server does not have enough free memory to complete the operation |
Gets the value associated with a particular key in a particular region.
| GetRequest | |||
| Field Name | Data type | Description | Mandatory? |
|---|---|---|---|
| regionName | String | The name of the region which is to be targeted | Y |
| key | EncodedValue | The key that is to be looked up | Y |
| GetResponse | |||
| Field Name | Data type | Description | Mandatory? |
|---|---|---|---|
| result | EncodedValue | The value matching the looked-up key | Y |
If key is not found in the region, the result will not be populated.
For valid key, return value as EncodedValue
| Error Code | Error Definition | Error Description |
|---|---|---|
| 2100 | REGION_NOT_FOUND | No Region exists for the name provided |
| 2000 | CONSTRAINT_VIOLATION | The key-constraint on the region has been violated and incompatible |
Adds a (key, value) pair to a region, replacing any existing entry for the key.
| PutRequest | |||
| Field Name | Data type | Description | Mandatory? |
|---|---|---|---|
| regionName | String | The name of the region which is to be targeted | Y |
| entry | Entry | A type containing (key, value) pair to be inserted into the region. | Y |
A successful Put operaration will result in an empty PutResponse message. This is because there is no data that needs to be sent back, but a message is needed to indicate a complete operation.
| PutResponse | |||
| Field Name | Data type | Description | Mandatory? |
|---|---|---|---|
| Error Code | Error Definition | Error Description |
|---|---|---|
| 2100 | REGION_NOT_FOUND | No Region exists for the name provided |
| 2000 | CONSTRAINT_VIOLATION | The key-constraint on the region has been violated and incompatible |
Get a structure containing information about a region.
| GetRegionRequest | |||
| Field Name | Data type | Description | Mandatory? |
|---|---|---|---|
| regionName | String | The name of the region to get information on | Y |
| GetRegionResponse | |||
| Field Name | Data type | Description | Mandatory? |
|---|---|---|---|
| region | Region | A structure containing information on the region | Y |
If there is no region matching the regionName, a REGION_NOT_FOUND ErrorResponse will be returned
| Error Code | Error Definition | Error Description |
|---|---|---|
| 2100 | REGION_NOT_FOUND | No Region exists for the name provided |
Returns a list of regions available through this server.
A GetRegionNamesRequest contains no extra data fields.
| GetRegionNamesRequest | |||
| Field Name | Data type | Description | Mandatory? |
|---|---|---|---|
| GetRegionNamesResponse | ||||
| Field Name | Data type | Description | Mandatory? | Repeated |
|---|---|---|---|---|
| regions | String | A list of the names of the regions that are available on the server. | Y | Y |
This only gets the regions present on the target server. This may not be the set of all regions in the cluster, depending on how the servers are configured.
There are no errors particular to this operation.
| Error Code | Error Definition | Error Description |
|---|---|---|
Remove an entry from a region.
| RemoveRequest | |||
| Field Name | Data type | Description | Mandatory? |
|---|---|---|---|
| regionName | String | The name of the region to remove an entry from. | Y |
| key | EncodedValue | The key of the entry to be removed. | Y |
The presence of a remove response indicates the entry is not longer present in the region. The response contains no additional data fields.
| RemoveResponse | ||||
| Field Name | Data type | Description | Mandatory? | Repeated |
|---|---|---|---|---|
If the key is not present in the region, this operation will make no changes to the region. It will still return a RemoveResponse in this case.
| Error Code | Error Definition | Error Description |
|---|---|---|
| 2100 | REGION_NOT_FOUND | No region with the provided regionName exists. |
| 2000 | CONSTRAINT_VIOLATION | The type of value provided for the key doesn’t match the region’s constraints. |
Removes all of a list of entries from a region.
| RemoveAllRequest | ||||
| Field Name | Data type | Description | Mandatory? | Repeated? |
|---|---|---|---|---|
| regionName | String | The name of the region to remove entries from. | Y | N |
| key | EncodedValue | A list of keys who's entries should be removed. | Y | Y |
| RemoveAllResponse | ||||
| Field Name | Data type | Description | Mandatory? | Repeated |
|---|---|---|---|---|
| failedKeys | KeyedErrorResponse | A list of keys that were not removed. | N | Y |
If a key is not present in the region, this operation will ignore it and continue with the others.
If a RemoveAllResponse is returned with a list of failedKeys, any keys from the request not present in the response have been removed. If an empty list is returned, all keys were removed.
Any keys present in failedKeys will have their entry remain in the same state they were in prior to this operation.
If an error response is returned by this operation (instead of a RemoveAllResponse), all entries remain in the same state as prior to this operation.
| Error Code | Error Definition | Error Description |
|---|---|---|
| 2100 | REGION_NOT_FOUND | No region with the provided regionName exists. |
Put a collection of Entries into a region.
| PutAllRequest | ||||
| Field Name | Data type | Description | Mandatory? | Repeated? |
|---|---|---|---|---|
| regionName | String | The name of the region to put entries into. | Y | N |
| entries | Entry | A list of entries to add to the region. | Y | Y |
| PutAllResponse | ||||
| Field Name | Data type | Description | Mandatory? | Repeated |
|---|---|---|---|---|
| failedKeys | KeyedErrorResponse | A list of keys that were not added. | N | Y |
If a PutAllResponse is returned with a list of failedKeys, any keys from the request not present in the response were successfully added/updated.
Any keys present in failedKeys will have their entry remain in the same state they were in prior to this operation.
If an error response is returned by this operation (instead of a RemoveAllResponse), all entries remain in the same state as prior to this operation.
| Error Code | Error Definition | Error Description |
|---|---|---|
| 2100 | REGION_NOT_FOUND | No region with the provided regionName exists. |
Get a series of values from a region.
| GetAllRequest | ||||
| Field Name | Data type | Description | Mandatory? | Repeated? |
|---|---|---|---|---|
| regionName | String | The name of the region to get entries from. | Y | N |
| keys | EncodedValue | A list of keys to fetch values for. | Y | Y |
| GetAllResponse | ||||
| Field Name | Data type | Description | Mandatory? | Repeated |
|---|---|---|---|---|
| entries | Entry | A list of looked up entries. | Y | Y |
| failedKeys | KeyedErrorResponse | A list of keys which generated errors on lookup. | N | Y |
If a GetAllResponse is returned and no entry is returned for a particular key, and that key is not present in the failedKeys, then no entry exists for that key in the region.
| Error Code | Error Definition | Error Description |
|---|---|---|
| 2100 | REGION_NOT_FOUND | No region with the provided regionName exists. |