ID

IEP-9

Author

Sponsor

Created

20-NOV-2017

Status


colour	GreyGreen
title	DRAFTCOMPLETED

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

Motivation

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

Complex objects consist of a 24-byte header and a , set of fields (key-value pairs)binary objects), and a schema (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)

Message format

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)

Message format

All messages, request and response, including handshake, start with int message length (excluding these first 4 bytes). E.g. 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.

...

Operation codes and request ids are omitted everywhere below for brevity.

OP_CACHE_GET = 11000

Retrieves a value from cache by key.

...

Response
BinaryObject	value

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 = 1003OP_CACHE_GET_ALL = 12

Retrieves multiple values from cache given multiple keys.

...

Response
int	result count
(BinaryObject + BinaryObject) * count	Resulting key-value pairs. Keys that are not present in the cache are not included.

OP_CACHE_PUT = 4 1001

Puts a value with a given key to cache (overwriting existing value if any).

...

Empy response.

OP_CACHE_PUT_ALL = 201004

Puts multiple key-value pairs to cache (overwriting existing associations if any).

...

Empy response.

OP_CACHE_CONTAINS_KEY = 101011

Returns a value indicating whether given key is present in cache.

...

OP_CACHE_CONTAINS_KEYS = 111012

Returns a value indicating whether all given keys are present in cache.

...

Response
bool	True when keys are present, false otherwise

OP_CACHE_GET_AND_PUT = 131005

Puts a value with a given key to cache, returning previous value for that key.

...

OP_CACHE_GET_AND_REPLACE = 14 1006

Puts a value with a given key to cache, returning previous value for that key, if and only if there is a value currently mapped for that key.

...

OP_CACHE_GET_AND_REMOVE = 151007

Removes the cache entry with specified key, returning the value.

...

OP_CACHE_PUT_IF_ABSENT = 16 1002

Puts a value with a given key to cache only if the key does not already exist.

...

OP_CACHE_GET_AND_PUT_IF_ABSENT = 171008

Puts a value with a given key to cache only if the key does not already exist.

...

Response
BinaryObject	Previously contained value regardless of whether put happened or not.

OP_CACHE_REPLACE = 18 1009

Puts a value with a given key to cache only if the key already exists.

...

OP_CACHE_REPLACE_IF_EQUALS = 19 1010

Puts a value with a given key to cache only if the key already exists and value equals provided value.

...

Response
bool	value indicating whether replace happened

OP_CACHE_CLEAR = 211013

Clears the cache without notifying listeners or cache writers.

...

Empy response.

OP_CACHE_CLEAR_KEY = 221014

Clears the cache key without notifying listeners or cache writers.

...

Empy response.

OP_CACHE_CLEAR_KEYS = 23 1015

Clears the cache keys without notifying listeners or cache writers.

...

Empy response.

OP_CACHE_REMOVE_KEY = 241016

Removes an entry with a given key, notifying listeners and cache writers.

...

OP_CACHE_REMOVE_IF_EQUALS = 25 1017

Removes an entry with a given key if provided value is equal to actual value, notifying listeners and cache writers.

...

Response
bool	value indicating whether remove happened

OP_CACHE_GET_SIZE = 26 1020

Gets the cache size.

Request
int	Cache ID: Java-style hash code of the cache name
byte	flags
int	Peek mode count. Can be 0, which means ALL.
byte * count	Peek modes. ALL = 0, NEAR = 1, PRIMARY = 2, BACKUP = 3

Response
long	Cache size

OP_CACHE_REMOVE_KEYS = 271018

Removes entries with given keys, notifying listeners and cache writers.

...

Empty response.

OP_CACHE_REMOVE_ALL = 28 1019

Removes all entries from cache, notifying listeners and cache writers.

...

OP_CACHE_CREATE_WITH_NAME = 291051

Creates a cache with a given name. Cache template can be applied if there is '*' in the cache name. Throws exception if a cache with specified name already exists.

Request
string	Cache name

Empty response.

OP_CACHE_GET_OR_CREATE_WITH_NAME = 301052

Creates a cache with a given name. Cache template can be applied if there is '*' in the cache name. Does nothing if the cache exists.

...

Empty response.

OP_CACHE_DESTROY = 311056

Destroys cache with a given name.

...

Empty response.

OP_CACHE_GET_NAMES = 321050

Gets existing cache names.

...

OP_CACHE_GET_CONFIGURATION = 331055

Gets cache configuration

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

CacheKeyConfiguration
string	Type name
string	Affinity key field name

int

QueryEntity count

QueryEntity * count

QueryEntity

string

Key type name

string

Value type name

string

Table name

string

Key field name

string

Value field name

int

QueryField count

QueryField * count

QueryField
string	Name
string	Type name
bool	Is key field
bool	Is NotNull constraint field

int

Alias count

(string + string) * count

Field name aliases

int

QueryIndex count

QueryIndex * count

QueryIndex
string	Index name
byte	Index type, SORTED = 0, FULLTEXT = 1, GEOSPATIAL = 2
int	Inline size
int	Field count
(string + bool) * count	Fields (name + IsDescensing)

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

CacheKeyConfiguration
string	Type name
string	Affinity key field name

200

int

QueryEntity count

+ QueryEntity * count

count

QueryEntity

string

Key type name

string

Value type name

string

Table name

string

Key field name

string

Value field name

int

QueryField count

QueryField * count

QueryField
string	Name
string	Type name
bool	Is key field
bool	Is NotNull constraint field

int

Alias count

(string + string) * count

Field name aliases

int

QueryIndex count

QueryIndex * count

QueryIndex
string	Index name
byte	Index type, SORTED = 0, FULLTEXT = 1, GEOSPATIAL = 2
int	Inline size
int	Field

(string + bool) *

count

Fields (name + IsDescensing)

OP_CACHE_CREATE_WITH_CONFIGURATION = 34

Creates cache with provided configuration. Throws an exception if the name is already in use.


(string + bool) * count	Fields (name + IsDescensing

Request

CacheConfiguration

Cache config (see format above

)

Empty response.

OP_CACHE_GET_OR_CREATE_WITH_CONFIGURATION = 35 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 = 36 2002

Performs SQL query.

Request
int	Cache ID: Java-style hash code of the cache name
string	Query entity type name
string	SQL
int	Argument count
BinaryObject * count	Arguments
bool	Distributed joins
bool	Local query
bool	Replicated only
int	Cursor page size
long	Timeout (milliseconds)

...

OP_QUERY_SQL_CURSOR_GET_PAGE = 37 2003

Retrieves next SQL query cursor page by cursor id from OP_QUERY_SQL.

...

Response
long	Cursor id
int	Row count
(Object + Object) * count	Cache entries, key + value
bool	Indicates whether more results are available to be fetched with OP_QUERY_SQL_CURSOR_GET_PAGE. When true, query cursor is closed automatically.

OP_RESOURCE_CLOSE = 90

Closes a resource, such as query cursor.

...

Empty response.

OP_QUERY_SQL_FIELDS = 382004

Performs SQL fields query

...

OP_QUERY_SQL_FIELDS_CURSOR_GET_PAGE = 392005

Retrieves next query page.

...

OP_GET_BINARY_TYPE_NAME = 23000

Gets the platform-specific full binary type name by id. For example, .NET and Java can map to the same type Foo, but classes will be Apache.Ignite.Foo in .NET and org.apache.ignite.Foo in Java.

...

Response
string	Binary type name

OP_GET_BINARY_TYPE = 33002

Gets the binary type information by id.

Response

Request
int	Type id	id

Response

bool

False: binary type does not exist, response end.

True: binary type exists, response as follows.

int

Type id

string

Type name

string

Affinity key field name

int

BinaryField count

BinaryField * count

BinaryField
string	Field name
int	Type id
int	Field id

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

...

OP_REGISTER_BINARY_TYPE_NAME = 53001

Registers the platform-specific full binary type name by id. For example, .NET and Java can map to the same type Foo, but classes will be Apache.Ignite.Foo in .NET and org.apache.ignite.Foo in Java.

...

Empty response.

OP_PUT_BINARY_TYPE = 63003

Registers binary type information in cluster.

Request

int

Type id

string

Type name

string

Affinity key field name

int

BinaryField count

BinaryField * count

BinaryField
string	Field name
int	Type id
int	Field id

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

Empty response.

OP_QUERY_SCAN = 72000

Performs scan query.

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

Response
long	Cursor id

)
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

OP_QUERY_SCAN_CURSOR_GET_PAGE = 82001

Retrieves next SQL query cursor page by cursor id from OP_QUERY_SCAN.

...

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

...

Tickets

See "thin client" component in JIRA

...

Page tree

Versions Compared

Old Version 47

New Version Current

Key

Motivation

Message format

Message format

Tickets

Page tree

Page History

Versions Compared

Old Version 47

New Version Current

Key

Motivation

Message format

Message format

Tickets