THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
...
Message Definition
A message is a series of bytes which contains the request or response. If the message is large, then we will have provision to divide the message into small messages. In that case, client/server needs to collect all messages to parse the request/response.
The message will be sent in following way. A client can send the multiple messages on the connection and the server will respond to those messages in same order.
Message definition grammar
In order to consistently define messages the Extended Backus–Naur form grammar will be used.
| Usage | Notation |
|---|---|
| definition | = |
| alteration | | |
| optional | [ ... ] |
| repetition | { ... } |
Generic Message definition
Every message will adhere to the following generic message definition.
| Message => MessageHeader (Request | Response) | |
|---|---|
| MessageHeader => defined below | |
| Request => defined below | |
| variable size, type = MessageHeader | |
| Request | variable size, type = Request |
| Response | variable size, type = ResponseResponse => defined below |
Protocol Terminology
Any binary protocol requires the following things:
Version: This indicates the API version.
Correlation Id: This should be different per request sent. It allows correlation of request and response.
Object Type: The type of a serialized object.
Response Type: It indicates whether a response is partial or complete.
ErrorCodes: It indicates the problem with API invocation.
Chunk Response: Send large response in multiple chunks.
Continuous Response: Client can register(Observer pattern) for events and then server notify the client if those events occur.
Request: It indicates client's message
Response: It indicates server's message.
Request Format: Format of request API and its parameters, which client wants to invoke.
Response Format: Format for API return value, which client invoked.
Message: Set of bytes which contain the Message Header and Request/Response.
Serialized Byte Order: Big Endian
...
- If a message is sent in multiple sub-messages, then it will be used for combining the whole message.
- It will be used for correlating the request to its response.
| MessageHeader => Size CorrelationId isPartialMessage hasMetaData | Description | |
|---|---|---|
| Size => | fixedSize = 4 bytes, type = int32 | Size of request or response |
| CorrelationId=> | fixedSize = 4 bytes, type = int32 | The correlationID used to track a request/response |
| isPartialMessage => | fixedSize = 1 byte, type = boolean | Is this a partial message |
| hasMetaData | => fixedSize = 1 byte, type = boolean | Does the message have meta data associated with it |
...
The request would contain the fixed size request header, optional metadata and request API parameters.
| Request => RequestHeader [MetaData] RequestAPI | |
|---|---|
| RequestHeader => defined below | |
| MetaData => optional | |
| variable size, type = RequestHeader | |
| MetaData | optional, variable size, type = MetaData |
RequestAPI | variable size, type = RequestTypes RequestAPI => (PutRequest | GetRequest | PutAllRequest | GetAllRequest |ServerConfigRequest | ClientConfigRequest | AuthRequest) |
RequestHeader
The request header contains the ApiId, ApiVersion, and hasMetaData flag to indicate whether the request contains some metadata.
| RequestHeader => ApiId apiVersion | Description | |
|---|---|---|
| ApiId => | fixedSize = 2 bytes, type = int16 | |
| apiVersion=> | fixedSize = 1 byte, type = int8 | |
| Anchor | ||||
|---|---|---|---|---|
|
Response
The response would contain the fixed size response header, optional metadata and return values.
| Response => ResponseHeader [MetaData] APIResponse | |
|---|---|
| ResponseHeader=> defined below | |
| MetaData => Optional | |
| variable size, type = ResponseHeader | |
| MetaData | optional, variable size, type = MetaData |
| APIResponse | variable size, type = ResponseTypes APIResponse => (PutResponse | GetResponse | PutAllResponse | GetAllResponse | ServerConfigResposne | ClientConfigResponse | AuthResponse | ErrorResponse) |
ResponseHeader
The response header will have resposneType, which indicates its partial response, full response or error. A hasMetaData flag indicates whether the response contains some metadata.
| ResponseHeader => ResponseTypeId | ErrorCode | Description | |
|---|---|---|
| ResponseTypeId=> | fixedSize = 2 bytes, type = int16 | |
| ErrorCode | => fixedSize = 2 bytes, type = int16 | When there is error response will have error message(String) for it |
...
The server will raise the error when it failed to execute API request from the client. The error code and message should help the client to diagnose the issue.
| ErrorResponse => errorMessage | |
|---|---|
| errorMessage | => (variable size, type = String) |
Value
The Value is serialized bytes for the Geode region value. It contains value header and series of bytes. Using value header, we can send a big serialized object in more than one chunk.
...