Error Response
Description
This response type is returned when an error occurs with any command type.
Response
| 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 |
Possible Errors
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 |
|---|---|---|
| LOW_MEMORY | Server does not have enough free memory to complete the operation | |
| 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 | |
| ENCODING_ERROR | There was an error whilst encoding a data entry (key / value) | |
| DECODING_ERROR | There was an error whilst decoding a data entry (key / value) |
Get
Description
Gets the value associated with a particular key in a particular region.
Request
| 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 |
Response
| GetResponse | |||
| Field Name | Data type | Description | Mandatory? |
|---|---|---|---|
| result | EncodedValue | The value matching the looked-up key | Y |
Expected behavior
If key is not found in the region, the result will not be populated.
For valid key, return value as EncodedValue
- If there is no region matching the regionName, a REGION_NOT_FOUND ErrorResponse will be returned
- If the provided key does not match the configured key-constraint on the region, a CONSTRAINT_VIOLATION ErrorResponse will be returned
Errors
| Error Code | Error Definition | Error Description |
|---|---|---|
| REGION_NOT_FOUND | No Region exists for the name provided | |
| CONSTRAINT_VIOLATION | The key-constraint on the region has been violated and incompatible |
Put
Description
Adds a (key, value) pair to a region, replacing any existing entry for the key.
Request fields
| 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 |
Response
None - returns an empty put response message indicating success.
Behavior Notes
If an error is returned, any existing entry is left unmodified.
Errors
REGION_NOT_FOUND - no region with the provided regionName exists.
CONSTRAINT_VIOLATION - the type of value provided for the key or entry doesn’t match the region’s constraints.
Query
Description
Pass an OQL query to the server, which will execute it and return the result.
Request fields
query
Type: string
Description: OQL describing the query to run
timeoutInMillis
Type: int
Optional (defaults to 0).
Description: a timeout in milliseconds after which the query will terminate. If less than or equal to 0, no user-defined timeout is imposed.
parameters
Type: repeated EncodedValue
Must match the number of parameters expected for the query. Can be absent if no parameters are needed.
Description: must match any parameters specified in OQL
Response fields
queryResults
Type: repeated string
Description: One JSON formatted string per response (see AbstractBaseController.processQueryResponse)
Behavior notes
The query will timeout on the shorter of the provided timeout or the cache’s timeout (configured in gemfire.Cache.MAX_QUERY_EXECUTION_TIME).
Errors
CONSTRAINT_VIOLATION - Bind parameter is not of the expected type
BAD_QUERY - Name in the query cannot be resolved!
BAD_QUERY - Query cannot be parsed.
PARAMETER_MISMATCH - The number of bound parameters does not match the number of placeholders!
OPERATION_NOT_PERMITTED - Query is not permitted on this type of region!
OPERATION_TIMEOUT - Query execution time has exceeded max query execution time (gemfire.Cache.MAX_QUERY_EXECUTION_TIME) configured!
OPERATION_TIMEOUT - Query execution time has exceeded provided timeout
GetRegion
Description
Get a structure containing information about a region.
Request fields
regionName
Type: string
Description: the name of the region to get information on.
Response fields
region
Type: Region
Description: A structure containing information on the region.
Errors
REGION_NOT_FOUND - if the region doesn’t exist.
GetServers
Description
Returns a list of available servers in the cluster.
Request fields
None.
Response fields
servers
type: repeated Server
description: a list of servers available in the cluster.
Errors
None specific to this operation.
GetRegionNames
Description
Returns a list of regions available through this server.
Request fields
None.
Response fields
regions
Type: repeated string
Description: a list of the names of the regions that are available on the server.
Behavior notes
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.
Errors
None specific to this operation.
Remove
Description
Remove an entry from a region.
Request fields
regionName
Type: string
Description: the name of the region to remove an entry from.
key
Type: EncodedValue
Description: the key of the entry to be removed.
Response fields
None.
Behavior notes
If the key is not present in the region, this operation will make no changes to the region and return success.
Errors
REGION_NOT_FOUND - no region with the provided regionName exists.
CONSTRAINT_VIOLATION - the type of value provided for the key doesn’t match the region’s constraints.
RemoveAll
Description
Removes all of a list of entries from a region.
Request fields
regionName
Type: string
Description: the name of the region to remove an entry from.
keys
Type: repeated EncodedValue
Description: a list of keys whose entries should be removed.
Response fields
None.
Behavior notes
If a key is not present in the region, this operation will ignore it and continue with the others.
If an error is returned, no guarantees are made as to whether any or all of the keys have been removed.
Errors
REGION_NOT_FOUND - no region with the provided regionName exists.
CONSTRAINT_VIOLATION - the type of key provided doesn’t match the region’s constraints.
PutAll
Description
Put a collection of Entries into a region.
Request fields
regionName
Type: string
Description: The name of the region to put entries into.
entries
Type: repeated Entry
Description: the entries to put into the region.
Response fields
failedKeys
Type: repeated KeyedErrorResponse
Description: A list of keys which we failed to put values for, along with the error for each failed put.
Behavior notes
If an error is returned none of the puts succeeded.
If a PutAllResponse is returned, any keys not in the responses failedKeys were successfully set.
If two Entries share equal keys, a successful operation will result in one of the Entries being present in the region. Which one is undefined.
Errors
REGION_NOT_FOUND - no region with the provided regionName exists.
CONSTRAINT_VIOLATION - the type of value provided for a key or value doesn’t match the region’s constraints.
GetAll
Description
Get a series of values from a region.
Request fields
regionName
Type: string
Description: The name of the region to get entries from.
keys
Type: repeated EncodedValue
Description: the keys to look up in the region.
Response fields
entries
Type: repeated Entry
Description: the entries corresponding to keys that were present.
errors
Type: repeated ErrorEntry
Description: any keys that encountered an error will be returned here instead of in entries.
Behavior notes
An error for any key will return an error.
Any key not found in the region will return an Entry with that key and a null value.
Errors
REGION_NOT_FOUND - no region with the provided regionName exists.
CONSTRAINT_VIOLATION - the type of value provided for a key doesn’t match the region’s constraints.
VALUE_ENCODING_ERROR - if a value stored on the server cannot be encoded and sent to the client.