[ 
https://issues.apache.org/jira/browse/IGNITE-8039?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16430474#comment-16430474
 ] 

Vladimir Ozerov edited comment on IGNITE-8039 at 4/9/18 12:48 PM:
------------------------------------------------------------------

[~alexey.kosenchuk], answering your questions:

1) >>> what is Object array (type code 23) ? What is the difference between it 
and Objects Wrapped In Array (type code 27) ?
 Type code 23 stands for array of objects. Type code 27 stands for "binary 
object", which is completely different concept. Consider the following Java 
class:
{code:java}
class Person {
    private String name;
    private Address address;
}
{code}
When serialized, we will get a graph of objects in plain form: {{[103 ... [103 
...] ... ]}}, where first "103" stands for serialized person, second - 
serialized address inside serialized person. Binary object format allows us to 
wrap serialized object graph and address specific object inside it. E.g. 
consider that total length of serialized person is 200 bytes and address is 
located on the position 100. Then wrapped person would look like this (bytes 
1-4 is total length, last four bytes is person offset inside aforementioned 
data array which is zero):
 {{[27, 200, 0, 0, 0, [data], 0, 0, 0, 0}}
 But wrapped address would look like this (notice changed offset in the end):
 {{[27, 200, 0, 0, 0, [data], 100, 0, 0, 0}}
 Essentially, data type 27 maps to our {{BinaryObjectImpl}} (see 
{{org.apache.ignite.internal.binary.BinaryObjectImpl}} in Java code, fields 
{{arr}} and {{offset}}). We will improve our docs.

2) what is Collection USER_SET?
 This is arbitrary set passed from user code. Maps to {{java.util.HashSet}} on 
deserialization.

3) what is Collection USER_COL?
 Arbitrary collection passed from user code. Maps to {{java.util.ArrayList}}.

4) what is Collection SINGLETON_LIST?
 Java-specific singleton list. Not relevant to public protocol.

5) what is Decimal?
 Standard decimal data type. Maps to {{java.lang.Decimal}} in Java and 
{{decimal}} in .NET. The most complex part is {{byte array}}, please refer to 
{{java.math.BigInteger.toByteArray}} in Java to undestand how it should be 
formed. Docs will be improved soon.

6) what is Timestamp ?
 Essentially - date + additional nanosecond precision. Please refer to 
{{java.util.Timestamp}} to understand how "nano" component is formed.

7) what is Time?
 JDBC-specific data type, see {{java.util.Time}}. Essentially - a date, where 
date component is set to 1 Jan 1970 and is ignored, only time component could 
be accessed.

8) what does flag USER_TYPE mean?
 Is used to distinguish between user and internal system types. In the context 
of thin client, should always be {{true}}.

9) is it mandated that the number of fields in the Schema must be equal to the 
number of fields in the Data Object?
 Yes


was (Author: vozerov):
[~alexey.kosenchuk], answering your questions:

1) >>> what is Object array (type code 23) ? What is the difference between it 
and Objects Wrapped In​ Array (type code 27) ?
Type code 23 stands for array of objects. Type code 27 stands for "binary 
object", which is completely different concept. Consider the following Java 
class:
{code}
class Person {
    private String name;
    private Address address;
}
{code}
When serialized, we will get a graph of objects in plain form: {{[103 ... \[103 
...\] ... ]}}, where first "103" stands for serialized person, second - 
serialized address inside serialized person. Binary object format allows us to 
wrap serialized object graph and address specific object inside it. E.g. 
consider that total length of serialized person is 200 bytes and address is 
located on the position 100. Then wrapped person would look like this (bytes 
1-4 is total length, last four bytes is person offset inside aforementioned 
data array which is zero):
{{[27, 200, 0, 0, 0, \[data\], 0, 0, 0, 0}}
But wrapped address would look like this (notice changed offset in the end):
{{[27, 200, 0, 0, 0, \[data\], 100, 0, 0, 0}}
Essentially, data type 27 maps to our {{BinaryObjectImpl}} (see 
{{org.apache.ignite.internal.binary.BinaryObjectImpl}} in Java code, fields 
{{arr}} and {{offset}}). We will improve our docs.

2) what is Collection USER_SET?
This is arbitrary set passed from user code. Maps to {{java.util.HashSet}} on 
deserialization.

3) what is Collection USER_COL?
Arbitrary collection passed from user code. Maps to {{java.util.ArrayList}}.

4) what is Collection SINGLETON_LIST?
Java-specific singleton list. Not relevant to public protocol.

5) what is Decimal?
Standard decimal data type. Maps to {{java.lang.Decimal}} in Java and 
{{decimal}} in .NET. The most complex part is {{byte array}}, please refer to 
{{java.math.BigInteger.toByteArray}} in Java to undestand how it should be 
formed. Docs will be improved soon.

6) what is Timestamp ?
Essentially - date + additional nanosecond precision. Please refer to 
{{java.util.Timestamp}} to understand how "nano" component is formed.

7) what is Time?
JDBC-specific data type, see {{java.util.Time}}. Essentially - a date, where 
date component is set to 1 Jan 1970 and is ignored, only time component could 
be accessed.

8) what does flag USER_TYPE mean?
Is used to distinguish between user and internal system types. In the context 
of thin client, should always be {{true}}.

9) is it mandated that the number of fields in the Schema must be equal to the 
number of fields in the Data Object?
Yes

> Binary Client Protocol spec: data types/format clarifications
> -------------------------------------------------------------
>
>                 Key: IGNITE-8039
>                 URL: https://issues.apache.org/jira/browse/IGNITE-8039
>             Project: Ignite
>          Issue Type: Bug
>          Components: documentation, thin client
>    Affects Versions: 2.4
>            Reporter: Alexey Kosenchuk
>            Assignee: Vladimir Ozerov
>            Priority: Major
>             Fix For: 2.5
>
>
> Assuming the Binary Client Protocol spec should be detalized enough to allow 
> a client development basing on the spec only, w/o looking at other client 
> implementations and asking additional questions...
> The following should be clarified / corrected in the Binary Client Protocol 
> spec (v.2.4) 
> (https://apacheignite.readme.io/v2.4/docs/binary-client-protocol#section-data-format):
> Type Codes table:
> -----------------
> - UUID (Guid) size: should be 16 bytes, not 8 (?) 
> - what is Object array (type code 23) ? What is the difference between it and 
> Objects Wrapped In​ Array (type code 27) ?
> - what is Collection USER_SET ?
> - what is Collection USER_COL ?
> - what is Collection SINGLETON_LIST ?
> - Collection: misprint: should be "... + length ..."
> - what is Decimal ?
> - what is Timestamp ?
> - what is Time ?
> Complex Objects:
> ----------------
> - what does flag USER_TYPE mean ?
> - Schema "field Id; Java-style hash code of field" -> should be "... of field 
> name".
> - "Repeat for as many times as the total number of schemas you have" -> 
> should be "... total number of fields you have".
> - is it mandated that the number of fields in the Schema must be equal to the 
> number of fields in the Data Object ?
> Objects Wrapped In​ Array
> ------------------------
> - may binary objects with different type codes be in the same array ?
> - may complex objects with different type ids be in the same array ?
> - "All cache operations return complex objects inside a wrapper (but not 
> primitives)." -> does it mean that in general a complex object (103) must 
> always be sent via the Binary Protocol in a wrapper (27)? 
> - "Byte array size" -> "Payload size" or "Size of the whole array with 
> header" ?
> - Offset. What is "object graph" here ? The Binary Protocol nowhere describes 
> any relations ("graph") between data objects in the protocol.
> Terminology
> -----------
> Not critical but would be really convenient to define and use the same terms 
> along the whole spec. For example:
> - "binary object" is always the same as "data object" of any type (?). Can be 
> "standard/predefined type object" or "complex object".
> - "cluster" or "server" ?
> - "cluster member" or "server nodes" ?



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

Reply via email to