Skip to content

Commit dd28fdb

Browse files
actions-useractions-user
committed
Deployed e6fc0da to dev with MkDocs 1.6.1 and mike 2.1.3
1 parent 85f7a21 commit dd28fdb

4 files changed

Lines changed: 609 additions & 81 deletions

File tree

‎dev/en/pages/client/arch/tuple_pojo_mapping/index.html‎

Lines changed: 264 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1268,6 +1268,78 @@
12681268
</span>
12691269
</a>
12701270

1271+
</li>
1272+
1273+
<li class="md-nav__item">
1274+
<a href="#supported-java-types-for-mapping" class="md-nav__link">
1275+
<span class="md-ellipsis">
1276+
1277+
Supported Java Types for Mapping
1278+
1279+
</span>
1280+
</a>
1281+
1282+
</li>
1283+
1284+
<li class="md-nav__item">
1285+
<a href="#jackson-msgpack-defaults-and-deserialization" class="md-nav__link">
1286+
<span class="md-ellipsis">
1287+
1288+
Jackson MsgPack: defaults and deserialization
1289+
1290+
</span>
1291+
</a>
1292+
1293+
<nav class="md-nav" aria-label="Jackson MsgPack: defaults and deserialization">
1294+
<ul class="md-nav__list">
1295+
1296+
<li class="md-nav__item">
1297+
<a href="#integers" class="md-nav__link">
1298+
<span class="md-ellipsis">
1299+
1300+
Integers
1301+
1302+
</span>
1303+
</a>
1304+
1305+
</li>
1306+
1307+
<li class="md-nav__item">
1308+
<a href="#deserialization-into-object-untyped" class="md-nav__link">
1309+
<span class="md-ellipsis">
1310+
1311+
Deserialization into Object (untyped)
1312+
1313+
</span>
1314+
</a>
1315+
1316+
</li>
1317+
1318+
<li class="md-nav__item">
1319+
<a href="#byte-and-string-bin-and-str-families" class="md-nav__link">
1320+
<span class="md-ellipsis">
1321+
1322+
byte[] and String (bin and str families)
1323+
1324+
</span>
1325+
</a>
1326+
1327+
</li>
1328+
1329+
<li class="md-nav__item">
1330+
<a href="#float-double-and-decimal" class="md-nav__link">
1331+
<span class="md-ellipsis">
1332+
1333+
float / double and decimal
1334+
1335+
</span>
1336+
</a>
1337+
1338+
</li>
1339+
1340+
</ul>
1341+
</nav>
1342+
12711343
</li>
12721344

12731345
<li class="md-nav__item">
@@ -2376,6 +2448,78 @@
23762448
</span>
23772449
</a>
23782450

2451+
</li>
2452+
2453+
<li class="md-nav__item">
2454+
<a href="#supported-java-types-for-mapping" class="md-nav__link">
2455+
<span class="md-ellipsis">
2456+
2457+
Supported Java Types for Mapping
2458+
2459+
</span>
2460+
</a>
2461+
2462+
</li>
2463+
2464+
<li class="md-nav__item">
2465+
<a href="#jackson-msgpack-defaults-and-deserialization" class="md-nav__link">
2466+
<span class="md-ellipsis">
2467+
2468+
Jackson MsgPack: defaults and deserialization
2469+
2470+
</span>
2471+
</a>
2472+
2473+
<nav class="md-nav" aria-label="Jackson MsgPack: defaults and deserialization">
2474+
<ul class="md-nav__list">
2475+
2476+
<li class="md-nav__item">
2477+
<a href="#integers" class="md-nav__link">
2478+
<span class="md-ellipsis">
2479+
2480+
Integers
2481+
2482+
</span>
2483+
</a>
2484+
2485+
</li>
2486+
2487+
<li class="md-nav__item">
2488+
<a href="#deserialization-into-object-untyped" class="md-nav__link">
2489+
<span class="md-ellipsis">
2490+
2491+
Deserialization into Object (untyped)
2492+
2493+
</span>
2494+
</a>
2495+
2496+
</li>
2497+
2498+
<li class="md-nav__item">
2499+
<a href="#byte-and-string-bin-and-str-families" class="md-nav__link">
2500+
<span class="md-ellipsis">
2501+
2502+
byte[] and String (bin and str families)
2503+
2504+
</span>
2505+
</a>
2506+
2507+
</li>
2508+
2509+
<li class="md-nav__item">
2510+
<a href="#float-double-and-decimal" class="md-nav__link">
2511+
<span class="md-ellipsis">
2512+
2513+
float / double and decimal
2514+
2515+
</span>
2516+
</a>
2517+
2518+
</li>
2519+
2520+
</ul>
2521+
</nav>
2522+
23792523
</li>
23802524

23812525
<li class="md-nav__item">
@@ -2690,6 +2834,126 @@ <h2 id="tarantool-java-pojo-field-mapping">Tarantool ⟷ Java POJO Field Mapping
26902834
guide, but will help you understand the principles of interaction. Mastering them will allow you to work
26912835
efficiently with the database in any scenarios, whether it's a cluster or a single instance, and with any POJO
26922836
objects.</p>
2837+
<h2 id="supported-java-types-for-mapping">Supported Java Types for Mapping</h2>
2838+
<p>The SDK uses <code>Jackson + jackson-dataformat-msgpack</code>, so:</p>
2839+
<ul>
2840+
<li>standard Java/Jackson types (primitives and wrappers, <code>String</code>, <code>byte[]</code>, <code>List</code>, <code>Map</code>, nested POJOs)
2841+
are supported by default;</li>
2842+
<li>Tarantool extension types are additionally supported.</li>
2843+
</ul>
2844+
<p>Below are the types that have explicit Tarantool extension-type mapping in the SDK:</p>
2845+
<table>
2846+
<thead>
2847+
<tr>
2848+
<th>Tarantool type</th>
2849+
<th>Java type</th>
2850+
<th>Comment</th>
2851+
</tr>
2852+
</thead>
2853+
<tbody>
2854+
<tr>
2855+
<td><code>decimal</code></td>
2856+
<td><code>java.math.BigDecimal</code></td>
2857+
<td>Uses MsgPack <code>decimal</code> extension; scale with absolute value up to and including <code>38</code> is supported.</td>
2858+
</tr>
2859+
<tr>
2860+
<td><code>uuid</code></td>
2861+
<td><code>java.util.UUID</code></td>
2862+
<td>Uses MsgPack <code>uuid</code> extension.</td>
2863+
</tr>
2864+
<tr>
2865+
<td><code>datetime</code></td>
2866+
<td><code>java.time.Instant</code>, <code>java.time.LocalDateTime</code>, <code>java.time.LocalDate</code>, <code>java.time.LocalTime</code>, <code>java.time.OffsetDateTime</code>, <code>java.time.ZonedDateTime</code></td>
2867+
<td>Uses MsgPack <code>datetime</code> extension.</td>
2868+
</tr>
2869+
<tr>
2870+
<td><code>interval</code></td>
2871+
<td><code>io.tarantool.mapping.Interval</code></td>
2872+
<td>Uses MsgPack <code>interval</code> extension.</td>
2873+
</tr>
2874+
<tr>
2875+
<td><code>tuple</code> (Tarantool 3.x, <code>TUPLE_EXT</code>)</td>
2876+
<td><code>io.tarantool.mapping.Tuple&lt;T&gt;</code></td>
2877+
<td>Uses MsgPack <code>tuple</code> extension; useful when tuple format is returned with tuple data.</td>
2878+
</tr>
2879+
</tbody>
2880+
</table>
2881+
<details class="note" open="open">
2882+
<summary>Note</summary>
2883+
<p>If you read data as <code>Object</code> (without an explicit target type), extension values are
2884+
deserialized to SDK Java objects automatically:
2885+
<code>decimal -&gt; BigDecimal</code>, <code>uuid -&gt; UUID</code>, <code>datetime -&gt; ZonedDateTime</code>,
2886+
<code>interval -&gt; Interval</code>, <code>tuple -&gt; Tuple&lt;?&gt;</code>.</p>
2887+
</details>
2888+
<h2 id="jackson-msgpack-defaults-and-deserialization">Jackson MsgPack: defaults and deserialization</h2>
2889+
<p>POJO mapping uses <strong>Jackson</strong> and the <a href="https://github.com/FasterXML/jackson-dataformats-binary/tree/2.18/msg-pack"><strong>jackson-dataformat-msgpack</strong></a> module.
2890+
Handling of <strong>missing properties</strong>, <strong>default values</strong>, and <strong>type coercion</strong> on deserialization is defined by Jackson configuration and API (<code>DeserializationFeature</code>, constructors, <code>@JsonCreator</code>, etc.) and by the actual MsgPack value type on the wire. Authoritative specification is in the <code>jackson-dataformat-msgpack</code> documentation and release notes for the Jackson line in use.</p>
2891+
<h3 id="integers">Integers</h3>
2892+
<p>MsgPack encodes integers with variable width (fixint, int8/16/32/64, uint<em>). The deserializer coerces them to the declared Java type (<code>int</code>, <code>long</code>, <code>Integer</code>, <code>BigInteger</code>, ...).
2893+
If the target type is </em><em>narrower</em>* than the wire value allows, deserialization may fail or lose precision; the Java field type must match the value range stored in Tarantool (including large <code>unsigned</code> values).</p>
2894+
<h3 id="deserialization-into-object-untyped">Deserialization into <code>Object</code> (untyped)</h3>
2895+
<p>If the target type is <code>java.lang.Object</code> (including elements of <code>List&lt;?&gt;</code>, values in <code>Map&lt;String, Object&gt;</code>, and raw <code>Object</code> fields), Jackson uses <code>UntypedObjectDeserializer</code> and, for numbers, <code>JsonParser.getNumberValue()</code>. The SDK depends on <strong><code>org.msgpack:jackson-dataformat-msgpack</code></strong>; scalar shapes are determined by its <code>MessagePackParser</code> (integers are <strong>not</strong> mapped to <code>Byte</code>/<code>Short</code> just because the wire encoding is small).</p>
2896+
<table>
2897+
<thead>
2898+
<tr>
2899+
<th>MsgPack on the wire</th>
2900+
<th>Java type when binding to <code>Object</code> (default <code>ObjectMapper</code> in the SDK)</th>
2901+
</tr>
2902+
</thead>
2903+
<tbody>
2904+
<tr>
2905+
<td><strong>Signed</strong> integer (fixint, int8, int16, int32, int64)</td>
2906+
<td><code>Integer</code> if the value fits in <code>int</code>; otherwise <code>Long</code></td>
2907+
</tr>
2908+
<tr>
2909+
<td><strong>uint64</strong></td>
2910+
<td><code>Long</code> if the value fits in signed <code>long</code>; otherwise <code>BigInteger</code></td>
2911+
</tr>
2912+
<tr>
2913+
<td><strong>float32</strong> / <strong>float64</strong></td>
2914+
<td><code>Double</code> (both are read as double-precision)</td>
2915+
</tr>
2916+
<tr>
2917+
<td><strong>nil</strong></td>
2918+
<td><code>null</code></td>
2919+
</tr>
2920+
<tr>
2921+
<td><strong>boolean</strong></td>
2922+
<td><code>Boolean</code></td>
2923+
</tr>
2924+
<tr>
2925+
<td><strong>binary</strong> (<code>bin</code>)</td>
2926+
<td><code>byte[]</code></td>
2927+
</tr>
2928+
<tr>
2929+
<td><strong>string</strong> (<code>str</code>)</td>
2930+
<td><code>String</code></td>
2931+
</tr>
2932+
<tr>
2933+
<td><strong>map</strong></td>
2934+
<td><code>LinkedHashMap&lt;String, Object&gt;</code></td>
2935+
</tr>
2936+
<tr>
2937+
<td><strong>array</strong></td>
2938+
<td><code>ArrayList&lt;Object&gt;</code></td>
2939+
</tr>
2940+
<tr>
2941+
<td>Tarantool/SDK <strong>extensions</strong> (<code>decimal</code>, <code>uuid</code>, <code>datetime</code>, …)</td>
2942+
<td><code>BigDecimal</code>, <code>UUID</code>, <code>ZonedDateTime</code>, <code>Interval</code>, <code>Tuple&lt;?&gt;</code>, … (see the Tarantool/SDK type table and the <code>Object</code> note at the start of the POJO section)</td>
2943+
</tr>
2944+
</tbody>
2945+
</table>
2946+
<p>With <code>DeserializationFeature.USE_BIG_INTEGER_FOR_INTS</code> enabled on the <code>ObjectMapper</code>, untyped integers may always deserialize as <code>BigInteger</code> — see Jackson Javadoc. <code>BaseTarantoolJacksonMapping</code> does <strong>not</strong> enable this flag.</p>
2947+
<h3 id="byte-and-string-bin-and-str-families"><code>byte[]</code> and <code>String</code> (<code>bin</code> and <code>str</code> families)</h3>
2948+
<p>In MsgPack, <strong>binary</strong> (<code>bin</code> family) and <strong>string</strong> (<code>str</code> family) are distinct. Default mapping:</p>
2949+
<ul>
2950+
<li><strong><code>byte[]</code></strong> — <strong>binary</strong> payload;</li>
2951+
<li><strong><code>String</code></strong> — <strong>string</strong> payload (UTF-8).</li>
2952+
</ul>
2953+
<p>A mismatch between the MsgPack format and the Java field type (for example, <strong>string</strong> on the wire and <strong><code>byte[]</code></strong> in the POJO) does not guarantee successful deserialization with the module defaults. Alternatives: aligned storage schema and POJO types, an intermediate type with conversion, <strong><code>@JsonDeserialize</code></strong>, or a custom <code>JsonDeserializer</code> (see <code>jackson-dataformat-msgpack</code> documentation).</p>
2954+
<h3 id="float-double-and-decimal"><code>float</code> / <code>double</code> and <code>decimal</code></h3>
2955+
<p>Non-extension floating-point values in MsgPack are <strong>float32</strong> / <strong>float64</strong>. Tarantool <strong><code>decimal</code></strong> is transmitted as a <strong>MsgPack extension</strong> in this SDK and maps to <strong><code>java.math.BigDecimal</code></strong> (table above).</p>
2956+
<p>Pairing <strong>float32/float64</strong> on the wire with a <strong><code>BigDecimal</code></strong> field, or a <strong>decimal extension</strong> with <strong><code>float</code></strong> / <strong><code>double</code></strong>, follows Jackson type-coercion rules and the module version; an explicit field type or a boundary deserializer may be required.</p>
26932957
<h2 id="efficient-mapping-flatten-input-flatten-output">Efficient Mapping (Flatten input, Flatten output)</h2>
26942958
<p>By default, field mapping in any of the clients (CrudClient, BoxClient) is performed in the most
26952959
efficient way — by the field's ordinal number.</p>

0 commit comments

Comments
 (0)