Alpha

These pages are built from turborel-java’s main, turborel 0.0.0. Anything may change from one build to the next: SQL, API, protocol and files alike.

Values

NAME

The values of the low-level client: the codec's data types, values and JSON items.

SYNOPSIS

package com.turborel.jdbc.internal.codec;

public sealed interface DataType { ... }
public sealed interface Value { void encode(Writer w) throws TurborelException; ... }
public sealed interface JsonItem { ... }
public final class TypeCodec { public static DataType read(Reader r) throws TurborelException; }
public final class ValueCodec { public static Value read(Reader r) throws TurborelException; }

DESCRIPTION

Every data type and value of the native protocol has a Java record of its own, which Appendix A lists with its bounds. TypeCodec reads a column's or a parameter's type, and ValueCodec a value, as the server writes them. Each value writes itself, as a program's parameter or a row of a copy. Nothing a value holds is converted on its way: an exact number keeps every unit and scale, an approximate number its bits, a plug-in's value its type's name, text and bytes, and a JSON value its stored form, checked whole as it is read.

A JSON value is made of an item, or of JSON text by Json.ofText, the text parsed as Turborel parses it, a decimal keeping the scale it was written with; its item() gives it back, and JsonText.of an item's text. An XML value is its serialization as CONTENT, of which nodes() parses its nodes; a parameter of an XML type is made of its text. A UUID is made of its 16 octets by Value.Uuid.ofOctets, or of its text by Value.Uuid.parse, read as CAST reads it; octets() and text() give them back, whatever types the program registered.

The package is the driver's own and the module does not export it. A program reaches values through JDBC (ResultSet and Metadata); this page describes what is beneath them.

ERRORS

SQLSTATE SQLCODE When
08006 -919 A value or a type received is malformed: a tag of none, a body cut short, a flag neither 0 nor 1, a string not UTF-8, parts nested too deep. The connection fails.
TB916 -916 A value or a type received that the client cannot take, its frame whole: a truth byte other than 0 or 1, a length's units neither 0 nor 1, a JSON value damaged, a condition of a Complete malformed, a value of tag 18 or 19. Its request fails alone, the rest of its replies read past; the connection goes on.
0A000 -900 A JSON value received past Turborel's limits: its request fails alone, and the connection goes on.
22003 -301 A value given cannot be carried: a number past its field, a DECFLOAT of more than 34 digits or past its exponents. Nothing is sent.
22021 -301 A string given is not Unicode: it holds a lone surrogate. Nothing is sent.
TB916 -916 A JSON value's stored form given is damaged.
TB910 -910 A JSON item's scalar is of no SQL/JSON scalar's kind.
22009 -301 A displacement given past -12:59 to +14:00, refused before it is sent with the code Turborel gives it.
0A000 -900 A JSON item nests deeper than 128, or its stored form passes 256 MiB.
22032 -301 A JSON item with no JSON text, as a datetime or an approximate number not finite, asked for its text; a string that is no JSON text, made a JSON value.
22037 -301 Two members of one key in JSON text parsed with keys to be unique.
2200N -301 An XML value's text that is not well-formed XML content, asked for its nodes.
2200W -301 An XML value the server cannot serialize, as an attribute alone, fails the fetch.
TB910 -910 A UUID made of octets not 16.

EXAMPLES

A UUID, an XML value and a JSON value made of its text, sent and read back:

Statements statements = conn.statements();
statements.query("CREATE TABLE ORDERS (ID UUID, BODY XML, EXTRA JSON)");
Statement insert = statements.prepare("INSERT INTO ORDERS VALUES (?, ?, ?)");
statements.execute(insert, List.of(
        Value.Uuid.parse("919108f7-52d1-4320-9bac-f847db4148a8"),
        new Value.Xml("<order no=\"18\"><item>jam</item></order>"),
        OctetValue.Json.ofText("{\"rush\": true, \"price\": 1.50}")));
List<Value> row = ((Outcome.Rows) statements.query("SELECT ID, BODY, EXTRA FROM ORDERS")).rows().get(0);
Value.Uuid id = (Value.Uuid) row.get(0);
Value.Xml body = (Value.Xml) row.get(1);
OctetValue.Json extra = (OctetValue.Json) row.get(2);
System.out.println(id.text() + ", " + id.octets().length + " octets");
System.out.println(body.serialization() + ", its first node " + body.nodes().getFirstChild().getNodeName());
System.out.println(JsonText.of(extra.item()));
919108f7-52d1-4320-9bac-f847db4148a8, 16 octets
<order no="18"><item>jam</item></order>, its first node order
{"rush":true,"price":1.50}

STANDARD

[PROTOCOL Data types], [PROTOCOL Values], [PROTOCOL JSON values], [PROTOCOL Composite fields], [CLIENT XML values], [CLIENT UUIDs], and Turborel's RULES.md D89, the JSON value's stored form, and D184, the UUID's tag.

SEE ALSO

Appendix A: Types, Errors.