Skip to content

Commit

Permalink
types: ResultSet API for TarantoolClient
Browse files Browse the repository at this point in the history
This commit introduces a new API to handle TarantoolClient result. The
concept is similar to the JDBC ResultSet in terms of a getting the data
using rows ans columns. Instead of a guessing-style processing the
result via List<?>, TarantoolResultSet offers set of typed methods to
retrieve the data or get an error if the result cannot be represented as
the designated type.

Latter case requires to declare formal rules of a casting between the
types. In scope of this commit it is supported 11 standard types and
conversions between each other. These types are byte, short, int, long,
float, double, boolean, BigInteger, BigDecimal, String, and byte[].

Closes: #211
  • Loading branch information
nicktorwald committed Dec 16, 2019
1 parent 45e4b39 commit 416a303
Show file tree
Hide file tree
Showing 14 changed files with 3,136 additions and 0 deletions.
75 changes: 75 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ To get the Java connector for Tarantool 1.6.9, visit
* [Spring NamedParameterJdbcTemplate usage example](#spring-namedparameterjdbctemplate-usage-example)
* [JDBC](#JDBC)
* [Cluster support](#cluster-support)
* [Getting a result](#getting-a-result)
* [Logging](#logging)
* [Building](#building)
* [Where to get help](#where-to-get-help)
Expand Down Expand Up @@ -418,6 +419,80 @@ against its integer IDs.
3. The client guarantees an order of synchronous requests per thread. Other cases such
as asynchronous or multi-threaded requests may be out of order before the execution.

## Getting a result

Traditionally, when a response is parsed by the internal MsgPack implementation the client
will return it as a heterogeneous list of objects `List` that in most cases is inconvenient
for users to use. It requires a type guessing as well as a writing more boilerplate code to work
with typed data. Most of the methods which are provided by `TarantoolClientOps` (i.e. `select`)
return raw de-serialized data via `List`.

Consider a small example how it is usually used:

```java
// get an untyped array of tuples
List<?> result = client.syncOps().execute(Requests.selectRequest("space", "pk"));
for (int i = 0; i < result.size(); i++) {
// get the first tuple (also untyped)
List<?> row = result.get(i);
// try to cast the first tuple as a couple of values
int id = (int) row.get(0);
String text = (String) row.get(1);
processEntry(id, text);
}
```

There is an additional way to work with data using `TarantoolClient.executeRequest(TarantoolRequestConvertible)`
method. This method returns a result wrapper over original data that allows to extract in a more
typed manner rather than it is directly provided by MsgPack serialization. The `executeRequest`
returns the `TarantoolResultSet` which provides a bunch of methods to get data. Inside the result
set the data is represented as a list of rows (tuples) where each row has columns (fields).
In general, it is possible that different rows have different size of their columns in scope of
the same result.

```java
TarantoolResultSet result = client.executeRequest(Requests.selectRequest("space", "pk"));
while (result.next()) {
long id = result.getLong(0);
String text = result.getString(1);
processEntry(id, text);
}
```

The `TarantoolResultSet` provides an implicit conversation between types if it's possible.

Numeric types internally can represent each other if a type range allows to do it. For example,
byte 100 can be represented as a short, int and other types wider than byte. But 200 integer
cannot be narrowed to a byte because of overflow (byte range is [-128..127]). If a floating
point number is converted to a integer then the fraction part will be omitted. It is also
possible to convert a valid string to a number.

Boolean type can be obtained from numeric types such as byte, short, int, long, BigInteger,
float and double where 1 (1.0) means true and 0 (0.0) means false. Or it can be got from
a string using well-known patterns such as "1", "t|true", "y|yes", "on" for true and
"0", "f|false", "n|no", "off" for false respectively.

String type can be converted from a byte array and any numeric types. In case of `byte[]`
all bytes will be interpreted as a UTF-8 sequence.

There is a special method called `getObject(int, Map)` where a user can provide its own
mapping functions to be applied if a designated type matches a value one.

For instance, using the following map each strings will be transformed to an upper case and
boolean values will be represented as strings "yes" or "no":

```java
Map<Class<?>, Function<Object, Object>> mappers = new HashMap<>();
mappers.put(
String.class,
v -> ((String) v).toUpperCase()
);
mappers.put(
Boolean.class,
v -> (boolean) v ? "yes" : "no"
);
```

## Spring NamedParameterJdbcTemplate usage example

The JDBC driver uses `TarantoolClient` implementation to provide a communication with server.
Expand Down
197 changes: 197 additions & 0 deletions src/main/java/org/tarantool/InMemoryResultSet.java
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
package org.tarantool;

import org.tarantool.conversion.ConverterRegistry;
import org.tarantool.conversion.NotConvertibleValueException;

import java.math.BigInteger;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

/**
* Simple implementation of {@link TarantoolResultSet}
* that contains all tuples in local memory.
*/
class InMemoryResultSet implements TarantoolResultSet {

private final ConverterRegistry converterRegistry;
private final List<Object> results;

private int currentIndex;
private List<Object> currentTuple;

InMemoryResultSet(List<Object> rawResult, boolean asSingleResult, ConverterRegistry converterRegistry) {
currentIndex = -1;
this.converterRegistry = converterRegistry;

results = new ArrayList<>();
ArrayList<Object> copiedResult = new ArrayList<>(rawResult);
if (asSingleResult) {
results.add(copiedResult);
} else {
results.addAll(copiedResult);
}
}

@Override
public boolean next() {
if ((currentIndex + 1) < results.size()) {
currentTuple = getAsTuple(++currentIndex);
return true;
}
return false;
}

@Override
public boolean previous() {
if ((currentIndex - 1) >= 0) {
currentTuple = getAsTuple(--currentIndex);
return true;
}
return false;
}

@Override
public byte getByte(int columnIndex) {
return getTypedValue(columnIndex, Byte.class, (byte) 0);
}

@Override
public short getShort(int columnIndex) {
return getTypedValue(columnIndex, Short.class, (short) 0);
}

@Override
public int getInt(int columnIndex) {
return getTypedValue(columnIndex, Integer.class, 0);
}

@Override
public long getLong(int columnIndex) {
return getTypedValue(columnIndex, Long.class, 0L);
}

@Override
public float getFloat(int columnIndex) {
return getTypedValue(columnIndex, Float.class, 0.0f);
}

@Override
public double getDouble(int columnIndex) {
return getTypedValue(columnIndex, Double.class, 0.0d);
}

@Override
public boolean getBoolean(int columnIndex) {
return getTypedValue(columnIndex, Boolean.class, false);
}

@Override
public byte[] getBytes(int columnIndex) {
return getTypedValue(columnIndex, byte[].class, null);
}

@Override
public String getString(int columnIndex) {
return getTypedValue(columnIndex, String.class, null);
}

@Override
public Object getObject(int columnIndex) {
return requireInRange(columnIndex);
}

@Override
public BigInteger getBigInteger(int columnIndex) {
return getTypedValue(columnIndex, BigInteger.class, null);
}

@Override
@SuppressWarnings("unchecked")
public List<Object> getList(int columnIndex) {
Object value = requireInRange(columnIndex);
if (value == null) {
return null;
}
if (value instanceof List<?>) {
return (List<Object>) value;
}
throw new NotConvertibleValueException(value.getClass(), List.class);
}

@Override
@SuppressWarnings("unchecked")
public Map<Object, Object> getMap(int columnIndex) {
Object value = requireInRange(columnIndex);;
if (value == null) {
return null;
}
if (value instanceof Map<?, ?>) {
return (Map<Object, Object>) value;
}
throw new NotConvertibleValueException(value.getClass(), Map.class);
}

@Override
public boolean isNull(int columnIndex) {
Object value = requireInRange(columnIndex);
return value == null;
}

@Override
public TarantoolTuple getTuple(int size) {
requireInRow();
int capacity = size == 0 ? currentTuple.size() : size;
return new TarantoolTuple(currentTuple, capacity);
}

@Override
public int getRowSize() {
return (currentTuple != null) ? currentTuple.size() : -1;
}

@Override
public boolean isEmpty() {
return results.isEmpty();
}

@Override
public void close() {
results.clear();
currentTuple = null;
currentIndex = -1;
}

@SuppressWarnings("unchecked")
private <R> R getTypedValue(int columnIndex, Class<R> type, R defaultValue) {
Object value = requireInRange(columnIndex);
if (value == null) {
return defaultValue;
}
if (type.isInstance(value)) {
return (R) value;
}
return converterRegistry.convert(value, type);
}

@SuppressWarnings("unchecked")
private List<Object> getAsTuple(int index) {
Object row = results.get(index);
return (List<Object>) row;
}

private Object requireInRange(int index) {
requireInRow();
if (index < 1 || index > currentTuple.size()) {
throw new IndexOutOfBoundsException("Index out of range: " + index);
}
return currentTuple.get(index - 1);
}

private void requireInRow() {
if (currentIndex == -1) {
throw new IllegalArgumentException("Result set out of row position. Try call next() before.");
}
}

}
2 changes: 2 additions & 0 deletions src/main/java/org/tarantool/TarantoolClient.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
package org.tarantool;

import org.tarantool.dsl.TarantoolRequestSpec;
import org.tarantool.schema.TarantoolSchemaMeta;

import java.util.List;
Expand Down Expand Up @@ -33,4 +34,5 @@ public interface TarantoolClient {

TarantoolSchemaMeta getSchemaMeta();

TarantoolResultSet executeRequest(TarantoolRequestSpec requestSpec);
}
16 changes: 16 additions & 0 deletions src/main/java/org/tarantool/TarantoolClientImpl.java
Original file line number Diff line number Diff line change
@@ -1,5 +1,8 @@
package org.tarantool;

import org.tarantool.conversion.ConverterRegistry;
import org.tarantool.conversion.DefaultConverterRegistry;
import org.tarantool.dsl.TarantoolRequestSpec;
import org.tarantool.logging.Logger;
import org.tarantool.logging.LoggerFactory;
import org.tarantool.protocol.ProtoConstants;
Expand Down Expand Up @@ -92,6 +95,7 @@ public class TarantoolClientImpl extends TarantoolBase<Future<?>> implements Tar
protected Thread writer;

protected TarantoolSchemaMeta schemaMeta = new TarantoolMetaSpacesCache(this);
protected ConverterRegistry converterRegistry = new DefaultConverterRegistry();

protected Thread connector = new Thread(new Runnable() {
@Override
Expand Down Expand Up @@ -279,6 +283,18 @@ public TarantoolSchemaMeta getSchemaMeta() {
return schemaMeta;
}

@Override
@SuppressWarnings("unchecked")
public TarantoolResultSet executeRequest(TarantoolRequestSpec requestSpec) {
TarantoolRequest request = requestSpec.toTarantoolRequest(getSchemaMeta());
List<Object> result = (List<Object>) syncGet(exec(request));
return new InMemoryResultSet(result, isSingleResultRow(request.getCode()), converterRegistry);
}

private boolean isSingleResultRow(Code code) {
return code == Code.EVAL || code == Code.CALL || code == Code.OLD_CALL;
}

/**
* Executes an operation with default timeout.
*
Expand Down
Loading

0 comments on commit 416a303

Please sign in to comment.