ID | IEP-9 | ||||||||
Author | Pavel Tupitsyn | ||||||||
Sponsor | Pavel Tupitsyn | ||||||||
Created | 20-NOV-2017 | ||||||||
Status |
|
Table of Contents |
---|
Info |
---|
This page includes low-level protocol documentation that might be outdated and is not maintained. Refer to the official protocol documentation here: https://apacheignite.readme.io/docs/binary-client-protocol |
Implement thin Ignite client in any programming language / platform using a well-defined binary connectiona protocol.
...
Name | Type Code | Size (bytes) |
---|---|---|
byte | 1 | 1 |
short | 2 | 2 |
int | 3 | 4 |
long | 4 | 8 |
float | 5 | 4 |
double | 6 | 8 |
char | 7 | 2 |
bool | 8 | 1 |
string | 9 | 4 bytes length + length * 2Utf8 byte count + Utf8 bytes |
UUID (Guid) | 10 | 816 |
date | 11 | 8 (milliseconds from 1 Jan 1970) |
byte array | 12 | 4 bytes length + length |
short array | 13 | 4 bytes length + length * 2 |
int array | 14 | 4 bytes length + length * 4 |
long array | 15 | 4 bytes length + length * 8 |
float array | 16 | 4 bytes length + length * 4 |
double array | 17 | 4 bytes length + length * 8 |
char array | 18 | 4 bytes length + length * 2 |
bool array | 19 | 4 bytes length + length |
string array | 20 | 4 bytes length + variable length strings, see above. Nulls (byte 101) are allowed. |
UUID (Guid) array | 21 | 4 bytes length + length * 816. Nulls (byte 101) are allowed. |
date array | 22 | 4 bytes length + length * 8. Nulls (byte 101) are allowed. |
object array | 23 | 4 bytes length + 4 bytes element type id + variable size binary objects |
map | 25 | 4 bytes length + byte type (1 = HASH_MAP, 2 = LINKED_HASH_MAP) + length * (BinaryObject + BinaryObject) |
NULL | 101 | 0 |
...
Complex objects consist of a 24-byte header, set of fields (binary objects), and a set of fields (key-value pairsschema (field ids and positions).
Header | |
---|---|
byte | Object type code, always 103 |
byte | Version, always 1 |
short | Flags, USER_TYPE = 1, HAS_SCHEMA = 2 |
int | Type id, Java-style hash code of the type name |
int | Hash code, Java-style hash of contents without header, necessary for comparisons |
int | Length, including header |
int | Schema Id |
int | Schema offset from the header start, position where fields end |
BinaryObject * n | Fields |
(int + int) * n | Schema, fieldId (Java-style hash of field name) + offset (from header start) |
All messages, request and response, including handshake, start with int
message length (excluding these first 4 bytes). E.g. empty message would be represented by 4 zero bytes.
int | Length of Payload |
... | Payload |
Length is omitted in all message descriptions below for brevity.
Wrapped Binary Objects
One ore more binary objects can be wrapped in an array. This allows reading, storing, passing and writing objects efficiently without understanding their contents, performing simple byte copy.
All cache operations return complex objects inside a wrapper (but not primitives).
byte | Type code, always 27 |
int | Byte array size |
n bytes | Payload |
int | Offset of the object within array (array can contain an object graph, this offset points to the root object) |
All messages, request and response, including handshake, start with int
message length (excluding these first 4 bytes). E.g. empty message would be represented by 4 zero bytes.
int | Length of Payload |
... | Payload |
Length is omitted in all message descriptions below for brevity.
The first message upon connection establishment must be a handshake. Handshake ensures that client and server versions are compatible.
...
Response | |
BinaryObject | value |
OP_CACHE_GET_ALL = 1003
Cache flags
GET and all other cache operations include flags byte.
1 | KEEP_BINARY | Indicates wether IgniteCache.withKeepBinary should be called on the server side. This flag has effect only for OP_QUERY_SCAN when Java filter is used. Other operations ignore the flag and call withKeepBinary anyway. |
OP_CACHE_GET_ALL = 1003
Retrieves multiple values from cache given multiple keys.
...
Request | |
int | Cache ID: Java-style hash code of the cache name |
Response | |
CacheConfiguration | See below |
Cache configuration is sent and received by server in the following format:
name |
Response | |
CacheConfiguration | See below |
Cache configuration is sent by server in the following format:
CacheConfiguration | |||||||||||||||||||||||||||||||||||||||||||||||
int | Length of the configuration, in bytes | ||||||||||||||||||||||||||||||||||||||||||||||
int | CacheAtomicityMode, TRANSACTIONAL = 0, ATOMIC = 1 | ||||||||||||||||||||||||||||||||||||||||||||||
int | Backups | ||||||||||||||||||||||||||||||||||||||||||||||
int | CacheMode, LOCAL = 0, REPLICATED = 1, PARTITIONED = 2 | ||||||||||||||||||||||||||||||||||||||||||||||
bool | CopyOnRead | ||||||||||||||||||||||||||||||||||||||||||||||
string | DataRegionName | ||||||||||||||||||||||||||||||||||||||||||||||
bool | EagerTtl | ||||||||||||||||||||||||||||||||||||||||||||||
bool | StatisticsEnabled | ||||||||||||||||||||||||||||||||||||||||||||||
string | GroupName | ||||||||||||||||||||||||||||||||||||||||||||||
long | DefaultLockTimeout (milliseconds) | ||||||||||||||||||||||||||||||||||||||||||||||
int | MaxConcurrentAsyncOperations | ||||||||||||||||||||||||||||||||||||||||||||||
int | MaxQueryIterators | ||||||||||||||||||||||||||||||||||||||||||||||
string | Name | ||||||||||||||||||||||||||||||||||||||||||||||
bool | IsOnheapcacheEnabled | ||||||||||||||||||||||||||||||||||||||||||||||
int | PartitionLossPolicy, READ_ONLY_SAFE = 0, READ_ONLY_ALL = 1, READ_WRITE_SAFE = 2, READ_WRITE_ALL = 3, IGNORE = 4 | ||||||||||||||||||||||||||||||||||||||||||||||
int | QueryDetailMetricsSize | ||||||||||||||||||||||||||||||||||||||||||||||
int | QueryParallelism | ||||||||||||||||||||||||||||||||||||||||||||||
bool | ReadFromBackup | ||||||||||||||||||||||||||||||||||||||||||||||
int | RebalanceBatchSize | ||||||||||||||||||||||||||||||||||||||||||||||
long | RebalanceBatchesPrefetchCount | ||||||||||||||||||||||||||||||||||||||||||||||
long | RebalanceDelay (milliseconds) | ||||||||||||||||||||||||||||||||||||||||||||||
int | RebalanceMode, SYNC = 0, ASYNC = 1, NONE = 2 | ||||||||||||||||||||||||||||||||||||||||||||||
int | RebalanceOrder | ||||||||||||||||||||||||||||||||||||||||||||||
long | RebalanceThrottle (milliseconds) | ||||||||||||||||||||||||||||||||||||||||||||||
long | RebalanceTimeout (milliseconds) | ||||||||||||||||||||||||||||||||||||||||||||||
bool | SqlEscapeAll | ||||||||||||||||||||||||||||||||||||||||||||||
int | SqlIndexInlineMaxSize | ||||||||||||||||||||||||||||||||||||||||||||||
string | SqlSchema | ||||||||||||||||||||||||||||||||||||||||||||||
int | WriteSynchronizationMode, FULL_SYNC = 0, FULL_ASYNC = 1, PRIMARY_SYNC = 2 | ||||||||||||||||||||||||||||||||||||||||||||||
int | CacheKeyConfiguration count | ||||||||||||||||||||||||||||||||||||||||||||||
CacheKeyConfiguration * count |
| ||||||||||||||||||||||||||||||||||||||||||||||
int | QueryEntity count | ||||||||||||||||||||||||||||||||||||||||||||||
QueryEntity * count |
|
OP_CACHE_CREATE_WITH_CONFIGURATION = 1053
Creates cache with provided configuration. Throws an exception if the name is already in use.
Request | |
int | Length of the configuration, in bytes |
short | Number of configuration properties |
(short + ...) * n | Configuration property data |
Any number of configuration properties can be provided. Name is required.
Cache configuration data is specified in key-value form, where key is `short` property id and value is property-specific data. Table below describes all available properties.
Property code | Property type | Description | |||||||||||||||||||||||||||||||||||||||||||||||||
2 | int | ||||||||||||||||||||||||||||||||||||||||||||||||||
CacheConfiguration | |||||||||||||||||||||||||||||||||||||||||||||||||||
int | Length of the configuration, in bytes | ||||||||||||||||||||||||||||||||||||||||||||||||||
int | CacheAtomicityMode, TRANSACTIONAL = 0, ATOMIC = 1 | ||||||||||||||||||||||||||||||||||||||||||||||||||
3 | int | Backups | |||||||||||||||||||||||||||||||||||||||||||||||||
1 | int | CacheMode, LOCAL = 0, REPLICATED = 1, PARTITIONED = 2 | |||||||||||||||||||||||||||||||||||||||||||||||||
5 | bool | CopyOnRead | |||||||||||||||||||||||||||||||||||||||||||||||||
100 | string | DataRegionName | |||||||||||||||||||||||||||||||||||||||||||||||||
405 | bool | EagerTtl | |||||||||||||||||||||||||||||||||||||||||||||||||
406 | bool | StatisticsEnabled | |||||||||||||||||||||||||||||||||||||||||||||||||
400 | string | GroupName | bool | ||||||||||||||||||||||||||||||||||||||||||||||||
invalidate402 | long | DefaultLockTimeout (milliseconds) | |||||||||||||||||||||||||||||||||||||||||||||||||
403 | int | MaxConcurrentAsyncOperations | |||||||||||||||||||||||||||||||||||||||||||||||||
206 | int | MaxQueryIterators | |||||||||||||||||||||||||||||||||||||||||||||||||
0 | string | Name | |||||||||||||||||||||||||||||||||||||||||||||||||
101 | bool | IsOnheapcacheEnabled | |||||||||||||||||||||||||||||||||||||||||||||||||
404 | int | PartitionLossPolicy, READ_ONLY_SAFE = 0, READ_ONLY_ALL = 1, READ_WRITE_SAFE = 2, READ_WRITE_ALL = 3, IGNORE = 4 | |||||||||||||||||||||||||||||||||||||||||||||||||
202 | int | QueryDetailMetricsSize | |||||||||||||||||||||||||||||||||||||||||||||||||
201 | int | QueryParallelism | |||||||||||||||||||||||||||||||||||||||||||||||||
6 | bool | ReadFromBackup | |||||||||||||||||||||||||||||||||||||||||||||||||
303 | int | RebalanceBatchSize | |||||||||||||||||||||||||||||||||||||||||||||||||
304 | long | RebalanceBatchesPrefetchCount | |||||||||||||||||||||||||||||||||||||||||||||||||
301 | long | RebalanceDelay (milliseconds) | |||||||||||||||||||||||||||||||||||||||||||||||||
300 | int | RebalanceMode, SYNC = 0, ASYNC = 1, NONE = 2 | |||||||||||||||||||||||||||||||||||||||||||||||||
305 | int | RebalanceOrder | |||||||||||||||||||||||||||||||||||||||||||||||||
306 | long | RebalanceThrottle (milliseconds) | |||||||||||||||||||||||||||||||||||||||||||||||||
302 | long | RebalanceTimeout (milliseconds) | |||||||||||||||||||||||||||||||||||||||||||||||||
205 | bool | SqlEscapeAll | |||||||||||||||||||||||||||||||||||||||||||||||||
204 | int | SqlIndexInlineMaxSize | |||||||||||||||||||||||||||||||||||||||||||||||||
203 | string | SqlSchema | |||||||||||||||||||||||||||||||||||||||||||||||||
4 | int | WriteSynchronizationMode, FULL_SYNC = 0, FULL_ASYNC = 1, PRIMARY_SYNC = 2 | |||||||||||||||||||||||||||||||||||||||||||||||||
401 | int + CacheKeyConfiguration * count | CacheKeyConfiguration *count
| |||||||||||||||||||||||||||||||||||||||||||||||||
200 | int | QueryEntity count | + QueryEntity * count |
|
OP_CACHE_CREATE_WITH_CONFIGURATION = 1053
Creates cache with provided configuration. Throws an exception if the name is already in use.
| |||||||||
Request | |||||||||
CacheConfiguration | Cache config (see format above
|
Empty response.
OP_CACHE_GET_OR_CREATE_WITH_CONFIGURATION = 1054
Creates cache with provided configuration. Does nothing if the name is already in use.
Request | |
CacheConfiguration | Cache config (see format above) |
Same request format as above. Empty response.
OP_QUERY_SQL = 2002
Performs SQL query.
...
Gets the binary type information by id.id.
Request | |
int | Type id |
Response | |||||||||
bool | False: binary type does not exist, response end. True: binary type exists, response as follows. | ||||||||
Request | |||||||||
int | Type id | ||||||||
Response | |||||||||
int | Type id | ||||||||
string | Type name | ||||||||
string | Affinity key field name | ||||||||
int | BinaryField count | ||||||||
BinaryField * count |
| ||||||||
bool | Is enum | ||||||||
int (if isEnum) | Enum field count | ||||||||
(string + int) * count (if isEnum) | Enum values | ||||||||
int | Schema count | ||||||||
(int + int[](schema id) + int (field count) + int (field id) * n) * count | Binary schemas, set of (schemaId + fieldIds) pairs |
...
Request | |||||||||
int | Type id | ||||||||
string | Type name | ||||||||
string | Affinity key field name | ||||||||
int | BinaryField count | ||||||||
BinaryField * count |
| ||||||||
bool | Is enum | ||||||||
int (if isEnum) | Enum field count | ||||||||
(string + int) * count (if isEnum) | Enum values | ||||||||
int | Schema count | ||||||||
(int (schema id) + int (field count) + int [](field id) * n) * count | Binary schemas, set of (schemaId + fieldIds) pairs |
...
Request | |
int | Cache ID: Java-style hash code of the cache name |
BinaryObject | Filter object |
byte (if filter object is not null) | Filter platform, JAVA = 1, DOTNET = 2, CPP = 3 |
int | Cursor page size |
int | Partition to query (negative to query entire cache) |
bool | Local flag |
) | |
bool | Local flag |
Response | |
long | Cursor id |
int | Row count for the first page |
(Object + Object) * count | Cache entries, key + value |
bool | Indicates whether more results are available to be fetched with OP_QUERY_SCAN_CURSOR_GET_PAGE |
Response | |
long | Cursor id |
OP_QUERY_SCAN_CURSOR_GET_PAGE = 2001
...
Code Block |
---|
var socket = openSocket("127.0.0.1:10800"); // Message length socket.writeInt(8); // Handshake operation socket.writeByte(1); // Protocol version 1.0.0 socket.writeShort(1); socket.writeShort(0); socket.writeShort(0); // Client type: thin client socket.writeByte(2); // Receive result var resLen = socket.readInt(); assert resLen == 1; // Success message length is 1 var res = socket.readByte(); assert res == 1; // Success code // END HANDSHAKE // Perform OP_CACHE_GET // Message length socket.writeInt(20) // Op code = OP_CACHE_GET socket.writeShort(11000); // Request id (can be anything; does not matter for simple blocking socket IO) var reqId = 1; socket.writeLong(reqId); // Cache id var cacheName = "myCache"; var cacheId = javaHashCode(cacheName); socket.writeInt(cacheId); // Flags = none socket.writeByte(0); // Cache key socket.writeByte(3); // Integer type code socket.writeInt(1); // Our cache value // Read result var len = socket.readInt(); assert len == 17; // requestId (8) + status code (4) + int object (1 + 4) var resReqId = socket.readLong(); assert reqId == resReqId; var statusCode = socket.readInt(); assert statusCode == 0; // Success var resTypeCode = socket.readByte(); assert restypeCode == 3; // Integer var res = socket.readInt(); print(res); // Resulting cache value |
...
See "thin client" component in JIRA
...