Introduction
Geode is a reliable distributed data management tool. There is a demand to access Geode from various programming languages. But the existing client-server protocol is too complex to understand, and it’s not even documented. That establishes the need for a new client-server protocol.
Protocol Terms
Any binary protocol will require following things
Version: This indicates the API version.
Request Type: This indicates API needs to invoke.
Correlation Id: This helps to relate request-response.
Object Type: What is the type of serialized object.
Response Type: It indicates whether resposne is partial or complete.
Error Handling: It indicates the problem with API invocation.
Streaming support: To support the large response or continuous response.
Command Format: Api request and response.
Byte Order(Big Endian)
Connect
The new protocol will be integrated with current Geode server. The new client driver can connect with Geode server by sending byte “110”.
Request Type
Following table contains the request type and its corresponding id. RequestTypeId would recognize the API, which client want to invoke on the server. The request format will contain the 2-bytes(int16) for request type id. It will be marked as requestTypeId in request format.
RequestType | RequestTypeId |
---|---|
MetaDataConfigRequestType | 1 |
AuthenticationRequestType | 2 |
PutRequestType | 3 |
GetRequestType | 4 |
PutAllRequestType | 5 |
GetAllRequestType | 6 |
FunctionRequestType | 7 |
CreateRequestType | 8 |
InvalidateRequestType | 9 |
DestroyRequestType | 10 |
KeySetRequestType | 11 |
ValuesRequestType | 12 |
EntrySetRequestType | 13 |
ContainsValueForKeyRequestType | 14 |
ContainsKeyRequestType | 15 |
ContainsValueRequestType | 16 |
RemoveAllRequestType | 17 |
SizeRequestType | 18 |
PutIfAbsentRequestType | 19 |
RemoveIfValueIsSameRequestType | 20 |
ReplaceIfValueIsSameRequestType | 21 |
ReplaceIfValueExistType | 22 |
Correlation Id
The purpose of correlation id to match the request and its corresponding response. The request format will contain the 4-bytes(int32) for correlation Id. It will be marked as correlationId in request format.
Object Type
We will support all the object types which Geode understands. This would include all the java primitive types, an array of primitive types, collections, java serialization, data serializable, pdx serialization and custom user data serializers. For the purpose of the request format, we would distinguish key type and value type.
ObjectKeyType
Geode supports only few object types as the region Key. In the request format key will be marked as KeyObject.
ObjectValueType
All the supported Geode types can be defined as the region value. In the request format value will be marked as ValueObject. Value object will be preceded by ValueHeader. This will represent the size of the serialized bytes of ValueObject. It will consume 5-byte in request format. And it will be marked as ValueHeader in the request format.
ResponseType
ReponseType will indicate that whether the response is partial or complete. In the case of the partial response, a client would see the stream of response which it can process as it receives. The response format will contain the 2-bytes(int16) for response type. It will be marked as FullResponse or PartialResponse in request format.
ResponseType | ResponseTypeId |
---|---|
FullResponse | 1 |
PartialResponse | 2 |
Error Codes
Error codes indicate the issue with the invocation of API at the server. We have following error code for various issues at the server. The response format will contain the 2-bytes(int16) for error codes. It will be marked as ErrorCode in the response format.
Exception Type | ErrorCode |
---|---|
AUTHENICATION_REQUIRED_EXCEPTION | 1 |
AUTHORIZATION_FAILED_EXCEPTION | 2 |
AUTHETICATIONFAILED_EXCEPTION | 3 |
BUCKET_MOVED_EXCEPTION | 4 |
SERIALIZATION_EXCEPTION | 5 |
INTERRUPTED_EXCEPTION | 6 |
ILLEGAL_ARGUMNET_EXCEPTION | 7 |
ILLEGAL_STATE_EXCEPTION | 8 |
TIMEOUT_EXCEPTION | 9 |
CACHE_WRITER_EXCEPTION | 10 |
REGION_EXIST_EXCEPTION | 11 |
REGION_NOT_EXIST_EXCEPTION | 12 |
LEASE_EXPIRED_EXCEPTION | 13 |
CACHE_LOADER_EXCEPTION | 14 |
REGION_DESTROYED_EXCEPTION | 15 |
ENTRY_DESTROYED_EXCEPTION | 16 |
ENTRY_NOT_FOUND_EXCEPTION | 17 |
FUNCTION_NOT_FOUND_EXCEPTION | 18 |
FUNCTION_ATTRIBUTE_MISMATCH_EXCEPTION | 19 |
FUNCTION_EXECUTION_EXCEPTION | 20 |
CONCURRENT_MODIFICATION_EXCEPTION | 21 |
UNKNOWN_EXCEPTION | 22 |
CLASS_CAST_EXCEPTION | 23 |
GEODE_IO_EXCEPTION | 24 |
NULL_POINTER_EXCEPTION | 25 |
ENTRY_EXIST_EXCEPTION | 26 |
DISK_ACCESS_EXCEPTION | 27 |
QUERY_EXCEPTION | 28 |
CACHE_CLOSED_EXCEPTION | 29 |
MESSAGE_FORMAT_EXCEPTION | 30 |
CACHE_LISTENER_EXCEPTION | 31 |
CQ_EXCEPTION | 32 |
CQ_CLOSED_EXCEPTION | 33 |
CQ_QUERY_EXCEPTION | 34 |
CQ_EXIST_EXCEPTION | 35 |
CQ_INVALID_EXCEPTION | 36 |
INVALID_DELTA_EXCEPTION | 37 |
TRANSACTION_EXCEPTION | 38 |
TRANSACTION_DATA_NODE_DEPARTED_EXCEPTION | 39 |
TRANSACTION_REBALANCED_EXCEPTION | 40 |
COMMIT_CONFLICT_EXCEPTION | 41 |
PUTALL_PARTIAL_RESULT_EXCEPTION | 42 |
Streaming
Request Format