| Hello, I tried to describe the complete Etch Binary Protocol in Extended Backus-Naur Form, to get a more detailed understanding of the protocol serialization. I would like to know whether the attached wiki style documentation is sufficient to complete the existing one (https://cwiki.apache.org/ETCH/etch-binary-protocol.html). Could you please have a look and check whether I have correctly interpreted the java source code and the existing documentation. Your feedback is highly appreciated. |
==Message== message = signatur, messageLength, version, call; signatur = 0xdeadbeef; messageLength = intValue ? number of bytes within message ?; version = 0x03;
==Basic==
===Structure===
structure = key, numberOfFields, {field}, NONE;
numberOfFields = intValue ? number of fields ?;
===Field===
field = fieldKey, fieldData;
fieldKey = key ? for respective field name ?;
fieldData = data ? of respective field ?;
===Key===
key = intKey | stringKey;
intKey = intData ? for hash of respective key name ?;
stringKey = stringData ? for respective key name?;
===Type Codes===
ANY = 0x96;
CUSTOM = 0x95;
STRING = 0x93;
EMPTY_STRING = 0x92;
ARRAY = 0x91;
BYTES = 0x8b;
DOUBLE = 0x89;
FLOAT = 0x88;
LONG = 0x87;
INT = 0x86;
SHORT = 0x85;
BYTE = 0x84;
NULL = 0x80;
NONE = 0x81;
BOOLEAN_FALSE = 0x82;
BOOLEAN_TRUE = 0x83;
==Call==
A function call is transferred as structured data (see above), where the key
value is derived from the function name. An additional "_messageId" field of
value type LONG is included as an unique identifier for every call message.
The call return message will be serialized just like that, but additionally
contains a "_inReplyTo" field, with the respective "_messageId" field value of
the call message and an optional "result" field with respective result data.
call = callKey, numberOfFields, (requestFields | responseFields),
NONE;
requestFields = messageIdField, {field};
responseFields = messageIdField, inReplyToField, [resultField];
callKey = key ? for respective function name ?;
messageIdField = messageIdKey, messageIdData;
messageIdKey = key ? for "_messageId" or 0x6306b468 ?;
messageIdData = longData ? unique message ID for this call ?;
inReplyToField = inReplyToKey, inReplyToData;
inReplyToKey = key ? for "_inReplyTo" or 0xeda8c9a6 ?;
inReplyToData = longData ? unique message ID value of the request message ?;
resultField = resultKey, resultData;
resultKey = key ? for "result" or 0x8104fdc2 ?;
resultData = data ? result data ?;
==Data==
All data are serialized as type - value pair.
data = customData | arrayData | nativeData | tinyInteger
| EMPTY_STRING | NULL
| BOOLEAN_FALSE | BOOLEAN_TRUE;
===Custom Data===
Custom data are structured data (see above) and will be tranferred just like
that. The custom content type is identified by the key derived from the
respective content type name.
customData = customType, numberOfFields, {field}, NONE;
customType = CUSTOM, customTypeNameKey;
customTypeNameKey = key ? for respective content type name ?;
===Array Data===
arrayData = ARRAY, arrayContentType, arrayDimension, arrayLength,
{data}, NONE;
arrayContentType = customType | BYTE | SHORT | INT | LONG | FLOAT | DOUBLE |
BYTES | STRING;
arrayDimension = intValue ? dimension of array ?;
arrayLength = intValue ? number of array elements ?;
===Native Data===
nativeData = byteData | shortData | intData | longData | floatData |
doubleData
| bytesData
| stringData;
byteData = BYTE, byteValue;
shortData = SHORT, shortValue;
intData = INT, intValue;
longData = LONG, longValue;
floatData = FLOAT, floatValue;
doubleData = DOUBLE, doubleValue;
bytesData = BYTES, bytesCount, {byteValue};
stringData = STRING, bytesCount, {characterValue};
bytesCount = intValue ? number of bytes ?;
byteValue = ? signed 8-bit quantity (-2^7 to 2^7-1) ?;
shortValue = ? signed 16-bit quantity (-2^15 to 2^15-1) ?;
intValue = ? signed 32-bit quantity (-2^31 to 2^31-1) ?;
longValue = ? signed 64-bit quantity (-2^63 to 2^63-1) ?;
floatValue = ? single precision IEEE floating point (max 3.4028235e38) ?;
doubleValue = ? double precision IEEE floating point (max
1.7976931348623157e308) ?;
characterValue = ? character (generally, Unicode) ?;
===Tiny Integer (Optimization)===
Integer values outside the range of the predefined type codes will be trenfer
Small integer values between:
MAX_TINY_INT = 0x7f ? = 127 ?;
MIN_TINY_INT = 0xc0 ? = -64 ?;
will be transferred directly with the 1-byte data type code and replacing it by
the original byte value.
tinyInteger = ? MIN_TINY_INT <= signed integer value <= MAX_TINY_INT ?;
Regards, Matthias Benesch |
