Skip to content

Commit 58773a9

Browse files
nickkkcccnickkkccc
authored
doc(call): add call examples (#38)
Add examples to interact with stored procedures from java Closes #37
1 parent 5be5b84 commit 58773a9

15 files changed

Lines changed: 316 additions & 23 deletions

‎documentation/doc-src/java/src/client/TarantoolCallCartridgeDriverExample.java‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
/*
2+
* Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
3+
* All Rights Reserved.
4+
*/
5+
6+
package client;
7+
8+
// --8<-- [start:all]
9+
10+
import java.net.InetSocketAddress;
11+
import java.util.Arrays;
12+
import java.util.List;
13+
import java.util.Map;
14+
15+
import org.junit.jupiter.api.Assertions;
16+
import org.junit.jupiter.api.Test;
17+
import testcontainers.utils.TarantoolSingleNodeConfigUtils;
18+
19+
import io.tarantool.driver.api.TarantoolClient;
20+
import io.tarantool.driver.api.TarantoolClientFactory;
21+
import io.tarantool.driver.api.TarantoolResult;
22+
import io.tarantool.driver.api.tuple.TarantoolTuple;
23+
24+
public class TarantoolCallCartridgeDriverExample extends TarantoolCallEvalAbstractExample {
25+
26+
@Test
27+
@SuppressWarnings("unchecked")
28+
void simpleCall() {
29+
try (TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> client = setupClient()) {
30+
loadFunctions();
31+
32+
final List<?> helloWorldReturns = client.call(HELLO_WORLD_FUNCTION).join();
33+
Assertions.assertEquals(1, helloWorldReturns.size());
34+
Assertions.assertEquals(HELLO_WORLD_FUNCTION_RETURNS, helloWorldReturns.get(0));
35+
36+
// convert returning lua map into Java pojo representing as map
37+
final String name = "Petya";
38+
final int age = 25;
39+
40+
final List<?> resultAsMap = client.call(SOME_MAP_FUNCTION, Arrays.asList(name, age)).join();
41+
42+
Assertions.assertEquals(1, resultAsMap.size());
43+
Assertions.assertInstanceOf(Map.class, resultAsMap.get(0));
44+
final Map<String, Object> castedResult = (Map<String, Object>) resultAsMap.get(0);
45+
Assertions.assertEquals(name, castedResult.get("name"));
46+
Assertions.assertEquals(age, castedResult.get("age"));
47+
48+
} catch (Exception e) {
49+
throw new RuntimeException(e);
50+
}
51+
}
52+
53+
private static TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> setupClient() {
54+
// Получаем адрес и порт из докера
55+
// Gets address and port from docker
56+
final InetSocketAddress nodeAddress = CONTAINER.mappedAddress();
57+
58+
return TarantoolClientFactory.createClient()
59+
.withAddress(nodeAddress.getHostName(), nodeAddress.getPort())
60+
.withCredentials(
61+
TarantoolSingleNodeConfigUtils.LOGIN, TarantoolSingleNodeConfigUtils.PWD.toString())
62+
.build();
63+
}
64+
}
65+
66+
// --8<-- [end:all]

‎documentation/doc-src/java/src/client/TarantoolCallEvalAbstractExample.java‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
/*
2+
* Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
3+
* All Rights Reserved.
4+
*/
5+
6+
package client;
7+
8+
// --8<-- [start:all]
9+
10+
import java.io.IOException;
11+
12+
import testcontainers.utils.TarantoolSingleNodeConfigUtils;
13+
14+
public abstract class TarantoolCallEvalAbstractExample
15+
extends TarantoolSingleInstanceConnectionAbstractExample {
16+
17+
protected static String HELLO_WORLD_FUNCTION = "hello_world_function";
18+
protected static String HELLO_WORLD_FUNCTION_RETURNS = "hello world";
19+
protected static String SOME_MAP_FUNCTION = "some_map_function";
20+
21+
protected static final String LUA_FUNCTION =
22+
String.format(
23+
"""
24+
%s = function()
25+
return '%s'
26+
end
27+
28+
%s = function(name, age)
29+
return {
30+
name = name,
31+
age = age
32+
}
33+
end
34+
""",
35+
HELLO_WORLD_FUNCTION, HELLO_WORLD_FUNCTION_RETURNS, SOME_MAP_FUNCTION);
36+
37+
protected void loadFunctions() throws IOException, InterruptedException {
38+
final String command =
39+
"echo \"%s\" | tt connect %s:%s@localhost:3301"
40+
.formatted(
41+
LUA_FUNCTION,
42+
TarantoolSingleNodeConfigUtils.LOGIN,
43+
TarantoolSingleNodeConfigUtils.PWD);
44+
CONTAINER.execInContainer("/bin/sh", "-c", command);
45+
}
46+
47+
protected record TestUser(String name, Integer age) {}
48+
}
49+
50+
// --8<-- [end:all]

‎documentation/doc-src/java/src/client/TarantoolCallTJSDKExample.java‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
/*
2+
* Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
3+
* All Rights Reserved.
4+
*/
5+
6+
package client;
7+
8+
// --8<-- [start:all]
9+
10+
import java.net.InetSocketAddress;
11+
import java.util.Arrays;
12+
import java.util.Collections;
13+
import java.util.List;
14+
import java.util.Map;
15+
16+
import com.fasterxml.jackson.core.type.TypeReference;
17+
import org.junit.jupiter.api.Assertions;
18+
import org.junit.jupiter.api.Test;
19+
import testcontainers.utils.TarantoolSingleNodeConfigUtils;
20+
21+
import io.tarantool.client.TarantoolClient;
22+
import io.tarantool.client.factory.TarantoolFactory;
23+
import io.tarantool.pool.InstanceConnectionGroup;
24+
25+
public class TarantoolCallTJSDKExample extends TarantoolCallEvalAbstractExample {
26+
27+
@Test
28+
void simpleCall() {
29+
try (TarantoolClient client = setupClient()) {
30+
loadFunctions();
31+
32+
final List<String> helloWorldReturns =
33+
client.call(HELLO_WORLD_FUNCTION, String.class).join().get();
34+
Assertions.assertEquals(1, helloWorldReturns.size());
35+
Assertions.assertEquals(HELLO_WORLD_FUNCTION_RETURNS, helloWorldReturns.get(0));
36+
37+
// convert returning lua map into Java pojo representing as map
38+
final String name = "Petya";
39+
final int age = 25;
40+
41+
final List<TestUser> resultAsPojo =
42+
client.call(SOME_MAP_FUNCTION, Arrays.asList(name, age), TestUser.class).join().get();
43+
44+
Assertions.assertEquals(1, resultAsPojo.size());
45+
Assertions.assertEquals(name, resultAsPojo.get(0).name());
46+
Assertions.assertEquals(age, resultAsPojo.get(0).age());
47+
48+
// convert returning lua map into java list of map via type reference
49+
// java map key type is string because lua map key type is string!
50+
final List<Map<String, Object>> objectObjectMap =
51+
client
52+
.call(
53+
SOME_MAP_FUNCTION,
54+
Arrays.asList(name, age),
55+
new TypeReference<List<Map<String, Object>>>() {})
56+
.join()
57+
.get();
58+
59+
} catch (Exception e) {
60+
throw new RuntimeException(e);
61+
}
62+
}
63+
64+
private static TarantoolClient setupClient() throws Exception {
65+
final InetSocketAddress address = CONTAINER.mappedAddress();
66+
67+
final InstanceConnectionGroup connectionGroup =
68+
InstanceConnectionGroup.builder()
69+
.withHost(address.getHostName())
70+
.withPort(address.getPort())
71+
.withUser(TarantoolSingleNodeConfigUtils.LOGIN)
72+
.withPassword(TarantoolSingleNodeConfigUtils.PWD.toString())
73+
.withSize(3)
74+
.build();
75+
76+
return TarantoolFactory.box().withGroups(Collections.singletonList(connectionGroup)).build();
77+
}
78+
}
79+
80+
// --8<-- [end:all]

‎documentation/doc-src/java/src/client/TarantoolSingleInstanceConnectionAbstractExample.java‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
package client;
77

8-
// --8<-- [start:tarantool-single-instance-abstract]
8+
// --8<-- [start:all]
99

1010
import java.io.IOException;
1111
import java.nio.file.Path;
@@ -40,12 +40,10 @@ static void afterAll() {
4040
CONTAINER.stop();
4141
}
4242

43-
protected abstract void simpleConnection();
44-
4543
protected static TarantoolContainer<Tarantool3Container> createSingleNodeContainer(Path tempPath)
4644
throws IOException {
4745
final Path pathToConfig = TarantoolSingleNodeConfigUtils.createConfig(tempPath);
4846
return new Tarantool3Container(image, "test-node").withConfigPath(pathToConfig);
4947
}
5048
}
51-
// --8<-- [end:tarantool-single-instance-abstract]
49+
// --8<-- [end:all]

‎documentation/doc-src/java/src/client/TarantoolSingleInstanceConnectionCartridgeDriverExample.java‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
package client;
77

8-
// --8<-- [start:tarantool-single-instance-cartridge-driver]
8+
// --8<-- [start:all]
99

1010
import java.net.InetSocketAddress;
1111
import java.util.List;
@@ -23,7 +23,6 @@ public class TarantoolSingleInstanceConnectionCartridgeDriverExample
2323
extends TarantoolSingleInstanceConnectionAbstractExample {
2424

2525
@Test
26-
@Override
2726
protected void simpleConnection() {
2827
try (TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> client = setupClient()) {
2928
final List<?> result = client.eval("return _TARANTOOL").join();
@@ -51,4 +50,4 @@ private static TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>>
5150
.build();
5251
}
5352
}
54-
// --8<-- [end:tarantool-single-instance-cartridge-driver]
53+
// --8<-- [end:all]

‎documentation/doc-src/java/src/client/TarantoolSingleInstanceConnectionTJSDKExample.java‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55

66
package client;
77

8-
// --8<-- [start:tarantool-single-instance-tjsdk]
8+
// --8<-- [start:all]
99

1010
import java.net.InetSocketAddress;
1111
import java.util.Collections;
@@ -25,7 +25,6 @@ public class TarantoolSingleInstanceConnectionTJSDKExample
2525
extends TarantoolSingleInstanceConnectionAbstractExample {
2626

2727
@Test
28-
@Override
2928
protected void simpleConnection() {
3029
// Получаем адрес и порт из докера
3130
// Gets address and port from docker
@@ -57,4 +56,4 @@ protected void simpleConnection() {
5756
}
5857
}
5958
}
60-
// --8<-- [end:tarantool-single-instance-tjsdk]
59+
// --8<-- [end:all]

‎documentation/doc-src/pages/client/examples/call/call.en.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
---
2+
title: Interacting with stored procedures
3+
---
4+
5+
The following example demonstrates interacting with stored procedures from java:
6+
7+
=== "tarantool-java-sdk"
8+
9+
```title="Interacting with stored procedures from java"
10+
--8<-- "client/TarantoolCallTJSDKExample.java:all"
11+
```
12+
13+
```title="Abstract class to create Tarantool container"
14+
--8<-- "client/TarantoolCallEvalAbstractExample.java:all"
15+
```
16+
17+
```title="Abstract class to create Tarantool container"
18+
--8<-- "client/TarantoolSingleInstanceConnectionAbstractExample.java:all"
19+
```
20+
21+
=== "cartridge-driver"
22+
23+
```title="Interacting with stored procedures from java"
24+
--8<-- "client/TarantoolCallCartridgeDriverExample.java:all"
25+
```
26+
27+
```title="Abstract class to create Tarantool container"
28+
--8<-- "client/TarantoolCallEvalAbstractExample.java:all"
29+
```
30+
31+
```title="Abstract class to create Tarantool container"
32+
--8<-- "client/TarantoolSingleInstanceConnectionAbstractExample.java:all"
33+
```
34+
35+
???+ note
36+
37+
`tarantool-java-sdk` allows you to convert stored procedure return values to pojos, which have
38+
fields with default types, automatically. In `cartridge-driver` for this requires implementing
39+
converters for each of the custom pojo types, and passing them to `#call(...)` methods .
40+

‎documentation/doc-src/pages/client/examples/call/call.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Работа с хранимыми процедурами
3+
---
4+
5+
Следующие пример демонстрируют работу с хранимыми процедурами из java:
6+
7+
=== "tarantool-java-sdk"
8+
9+
```title="Работа с хранимыми процедурами из java"
10+
--8<-- "client/TarantoolCallTJSDKExample.java:all"
11+
```
12+
13+
```title="Абстрактный класс для создания контейнера Tarantool"
14+
--8<-- "client/TarantoolCallEvalAbstractExample.java:all"
15+
```
16+
17+
```title="Абстрактный класс для создания контейнера Tarantool"
18+
--8<-- "client/TarantoolSingleInstanceConnectionAbstractExample.java:all"
19+
```
20+
21+
=== "cartridge-driver"
22+
23+
```title="Работа с хранимыми процедурами из java"
24+
--8<-- "client/TarantoolCallCartridgeDriverExample.java:all"
25+
```
26+
27+
```title="Абстрактный класс для создания контейнера Tarantool"
28+
--8<-- "client/TarantoolCallEvalAbstractExample.java:all"
29+
```
30+
31+
```title="Абстрактный класс для создания контейнера Tarantool"
32+
--8<-- "client/TarantoolSingleInstanceConnectionAbstractExample.java:all"
33+
```
34+
35+
???+ note "Заметка"
36+
37+
`tarantool-java-sdk` позволяет преобразовывать возвращаемые значения хранимых процедур в pojo,
38+
которые имеют поля с типами по умолчанию, автоматически. В `cartridge-driver` для этого
39+
требуется реализация конвертеров для каждого из пользовательских типов pojo, и передача их в
40+
методы `#call(...)`.
41+

‎documentation/doc-src/pages/client/examples/call/index.en.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: Interact with stored procedures
3+
hide:
4+
- toc
5+
---
6+
7+
This section provides examples of interacting with stored procedures from java using
8+
`tarantool-java-sdk`.

‎documentation/doc-src/pages/client/examples/call/index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: Работа с хранимыми процедурами
3+
hide:
4+
- toc
5+
---
6+
7+
В данном разделе приводятся примеры работы с хранимыми процедурами из java при помощи
8+
`tarantool-java-sdk`.

0 commit comments

Comments
 (0)