Skip to content

Commit 5bf4a0a

Browse files
nickkkcccnickkkccc
committed
doc(snippets): add simple example
Add example how to connect single-node Tarantool from `tarantool-java-sdk` and `cartridge-java`
1 parent d9fd514 commit 5bf4a0a

10 files changed

Lines changed: 313 additions & 0 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,4 @@ workbench.xmi
2323
.factorypath
2424
documentation/venv
2525
documentation/site
26+
documentation/target

‎documentation/docs/documentation/client/examples/connection/index.md‎

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

‎documentation/docs/documentation/client/examples/connection/single-node.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Подключение к одиночному узлу
3+
---
4+
5+
Для того чтобы подключиться к одиночному узлу необходимо выполнить следующий код:
6+
7+
=== "tarantool-java-sdk"
8+
9+
```java title="Подключение к одному узлу Tarantool"
10+
--8<-- "src/client/simple/connection/SingleNodeConnectionNewConnector.java:new-simple-connection"
11+
```
12+
13+
```java title="Родительский класс с созданием контейнера"
14+
--8<-- "src/client/simple/connection/SingleNodeConnection.java:single-node-connection"
15+
```
16+
17+
```java title="Класс, который создает контейнер"
18+
--8<-- "src/testcontainers/single/CreateSingleNode.java:create-single-node"
19+
```
20+
21+
=== "cartridge-java"
22+
23+
```java title="Подключение к одному узлу Tarantool"
24+
--8<-- "src/client/simple/connection/SingleNodeConnectionCartridgeJava.java:old-simple-connection"
25+
```
26+
27+
```java title="Родительский класс с созданием контейнера"
28+
--8<-- "src/client/simple/connection/SingleNodeConnection.java:single-node-connection"
29+
```
30+
31+
```java title="Класс, который создает контейнер"
32+
--8<-- "src/testcontainers/single/CreateSingleNode.java:create-single-node"
33+
```
34+

‎documentation/docs/documentation/client/examples/index.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
title: Примеры использования
3+
hide:
4+
- toc
5+
---
6+
7+
В разделе приводятся примеры использования `tarantool-java-sdk`.
8+
9+
???+ note "Заметка"
10+
11+
Где это возможно, производится сравнение кода с
12+
[cartridge-java](https://github.com/tarantool/cartridge-java)

‎documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnection.java‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
/*
2+
* Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
3+
* All Rights Reserved.
4+
*/
5+
6+
package client.simple.connection;
7+
8+
// --8<-- [start:single-node-connection]
9+
10+
import java.io.IOException;
11+
import java.nio.file.Path;
12+
13+
import org.junit.jupiter.api.BeforeAll;
14+
import org.junit.jupiter.api.io.TempDir;
15+
import org.testcontainers.containers.tarantool.Tarantool3Container;
16+
import org.testcontainers.containers.tarantool.TarantoolContainer;
17+
import org.testcontainers.utility.DockerImageName;
18+
import testcontainers.single.CreateSingleNode;
19+
20+
public abstract class SingleNodeConnection {
21+
22+
@TempDir protected static Path TEMP_DIR;
23+
24+
private static final DockerImageName image = DockerImageName.parse("tarantool/tarantool:3.4.1");
25+
26+
protected static TarantoolContainer<Tarantool3Container> CONTAINER;
27+
28+
@BeforeAll
29+
static void beforeAll() throws IOException {
30+
CONTAINER = createSingleNodeContainer(TEMP_DIR);
31+
CONTAINER.start();
32+
}
33+
34+
protected abstract void simpleConnection();
35+
36+
protected static TarantoolContainer<Tarantool3Container> createSingleNodeContainer(Path tempPath)
37+
throws IOException {
38+
final Path pathToConfig = CreateSingleNode.createSingleNodeConfig(tempPath);
39+
return new Tarantool3Container(image, "test-node").withConfigPath(pathToConfig);
40+
}
41+
}
42+
// --8<-- [end:single-node-connection]

‎documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnectionCartridgeJava.java‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
/*
2+
* Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
3+
* All Rights Reserved.
4+
*/
5+
6+
package client.simple.connection;
7+
8+
// --8<-- [start:old-simple-connection]
9+
10+
import java.net.InetSocketAddress;
11+
import java.util.List;
12+
13+
import org.junit.jupiter.api.Assertions;
14+
import org.junit.jupiter.api.Test;
15+
import testcontainers.single.CreateSingleNode;
16+
17+
import io.tarantool.driver.api.TarantoolClient;
18+
import io.tarantool.driver.api.TarantoolClientFactory;
19+
import io.tarantool.driver.api.TarantoolResult;
20+
import io.tarantool.driver.api.tuple.TarantoolTuple;
21+
22+
public class SingleNodeConnectionCartridgeJava extends SingleNodeConnection {
23+
24+
@Test
25+
@Override
26+
protected void simpleConnection() {
27+
try (TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> client = setupClient()) {
28+
final List<?> result = client.eval("return _TARANTOOL").join();
29+
30+
Assertions.assertEquals(1, result.size());
31+
32+
final Object object = result.get(0);
33+
34+
Assertions.assertInstanceOf(String.class, object);
35+
Assertions.assertTrue(((String) object).contains("3.4.1"));
36+
} catch (Exception e) {
37+
throw new RuntimeException(e);
38+
}
39+
}
40+
41+
private static TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> setupClient() {
42+
// Получаем адрес и порт из докера
43+
final InetSocketAddress nodeAddress = CONTAINER.mappedAddress();
44+
45+
return TarantoolClientFactory.createClient()
46+
.withAddress(nodeAddress.getHostName(), nodeAddress.getPort())
47+
.withCredentials(CreateSingleNode.LOGIN, CreateSingleNode.PWD.toString())
48+
.build();
49+
}
50+
}
51+
// --8<-- [end:old-simple-connection]

‎documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnectionNewConnector.java‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
/*
2+
* Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
3+
* All Rights Reserved.
4+
*/
5+
6+
package client.simple.connection;
7+
8+
// --8<-- [start:new-simple-connection]
9+
10+
import java.net.InetSocketAddress;
11+
import java.util.Collections;
12+
import java.util.List;
13+
14+
import org.junit.jupiter.api.Assertions;
15+
import org.junit.jupiter.api.Test;
16+
import testcontainers.single.CreateSingleNode;
17+
18+
import io.tarantool.client.box.TarantoolBoxClient;
19+
import io.tarantool.client.factory.TarantoolBoxClientBuilder;
20+
import io.tarantool.client.factory.TarantoolFactory;
21+
import io.tarantool.mapping.TarantoolResponse;
22+
import io.tarantool.pool.InstanceConnectionGroup;
23+
24+
public class SingleNodeConnectionNewConnector extends SingleNodeConnection {
25+
26+
@Test
27+
@Override
28+
protected void simpleConnection() {
29+
// Получаем адрес и порт из докера
30+
final InetSocketAddress nodeAddress = CONTAINER.mappedAddress();
31+
32+
// Настраиваем группу подключения
33+
final InstanceConnectionGroup connectionGroup =
34+
InstanceConnectionGroup.builder()
35+
.withHost(nodeAddress.getHostName())
36+
.withPort(nodeAddress.getPort())
37+
.withUser(CreateSingleNode.LOGIN)
38+
.withPassword(CreateSingleNode.PWD.toString())
39+
.build();
40+
41+
final TarantoolBoxClientBuilder clientBuilder =
42+
TarantoolFactory.box().withGroups(Collections.singletonList(connectionGroup));
43+
44+
try (final TarantoolBoxClient singleNodeClient = clientBuilder.build()) {
45+
46+
final TarantoolResponse<List<String>> response =
47+
singleNodeClient.eval("return _TARANTOOL", String.class).join();
48+
final List<String> results = response.get();
49+
50+
Assertions.assertEquals(1, results.size());
51+
Assertions.assertTrue(results.get(0).contains("3.4.1"));
52+
} catch (Exception e) {
53+
throw new RuntimeException(e);
54+
}
55+
}
56+
}
57+
// --8<-- [end:new-simple-connection]

‎documentation/docs/documentation/examples/src/testcontainers/single/CreateSingleNode.java‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
/*
2+
* Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
3+
* All Rights Reserved.
4+
*/
5+
6+
package testcontainers.single;
7+
8+
// --8<-- [start:create-single-node]
9+
10+
import java.io.IOException;
11+
import java.nio.file.Files;
12+
import java.nio.file.Path;
13+
import java.util.Collections;
14+
15+
import org.testcontainers.containers.tarantool.config.ConfigurationUtils;
16+
17+
import io.tarantool.autogen.Tarantool3Configuration;
18+
import io.tarantool.autogen.credentials.Credentials;
19+
import io.tarantool.autogen.credentials.users.Users;
20+
import io.tarantool.autogen.credentials.users.usersProperty.UsersProperty;
21+
import io.tarantool.autogen.groups.Groups;
22+
import io.tarantool.autogen.groups.groupsProperty.GroupsProperty;
23+
import io.tarantool.autogen.groups.groupsProperty.replicasets.Replicasets;
24+
import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.ReplicasetsProperty;
25+
import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.Instances;
26+
import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.instancesProperty.InstancesProperty;
27+
import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.instancesProperty.iproto.Iproto;
28+
import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.instancesProperty.iproto.listen.Listen;
29+
30+
public class CreateSingleNode {
31+
32+
public static final String NODE = "test-node";
33+
34+
public static final CharSequence PWD = "secret";
35+
36+
public static final String LOGIN = "test-user";
37+
38+
/*
39+
Создает конфигурацию вида:
40+
---
41+
credentials:
42+
users:
43+
test-user:
44+
password: "secret"
45+
roles:
46+
- "super"
47+
groups:
48+
test-group:
49+
replicasets:
50+
test-rs:
51+
instances:
52+
test-node:
53+
iproto:
54+
listen:
55+
- uri: "0.0.0.0:3301"
56+
*/
57+
public static Path createSingleNodeConfig(Path tempDir) throws IOException {
58+
final Path pathToConfigFile = Files.createFile(tempDir.resolve("config.yaml"));
59+
60+
final Credentials credentials =
61+
Credentials.builder()
62+
.withUsers(
63+
Users.builder()
64+
.withAdditionalProperty(
65+
LOGIN,
66+
UsersProperty.builder()
67+
.withRoles(Collections.singletonList("super"))
68+
.withPassword(PWD.toString())
69+
.build())
70+
.build())
71+
.build();
72+
73+
final Iproto iproto =
74+
Iproto.builder()
75+
.withListen(Collections.singletonList(Listen.builder().withUri("0.0.0.0:3301").build()))
76+
.build();
77+
78+
final InstancesProperty instance = InstancesProperty.builder().withIproto(iproto).build();
79+
80+
final ReplicasetsProperty replicaset =
81+
ReplicasetsProperty.builder()
82+
.withInstances(Instances.builder().withAdditionalProperty(NODE, instance).build())
83+
.build();
84+
85+
final GroupsProperty group =
86+
GroupsProperty.builder()
87+
.withReplicasets(
88+
Replicasets.builder().withAdditionalProperty("test-rs", replicaset).build())
89+
.build();
90+
91+
final Tarantool3Configuration configuration =
92+
Tarantool3Configuration.builder()
93+
.withGroups(Groups.builder().withAdditionalProperty("test-group", group).build())
94+
.withCredentials(credentials)
95+
.build();
96+
97+
ConfigurationUtils.writeToFile(configuration, pathToConfigFile);
98+
return pathToConfigFile;
99+
}
100+
}
101+
102+
// --8<-- [end:create-single-node]

‎documentation/mkdocs.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,11 @@ nav:
9494
- documentation/client/arch/connection-to-multiple-nodes.md
9595
- documentation/client/arch/call.md
9696
- documentation/client/arch/tuple_pojo_mapping.md
97+
- Примеры использования:
98+
- documentation/client/examples/index.md
99+
- Подключение к узлам:
100+
- documentation/client/examples/connection/index.md
101+
- documentation/client/examples/connection/single-node.md
97102
- Tarantool Testcontainers:
98103
- documentation/testcontainers/index.md
99104
- Одиночный узел:

‎documentation/pom.xml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,12 +26,14 @@
2626
<artifactId>tarantool-client</artifactId>
2727
<version>2.0.0-SNAPSHOT</version>
2828
<scope>import</scope>
29+
<type>pom</type>
2930
</dependency>
3031
<dependency>
3132
<groupId>io.tarantool</groupId>
3233
<artifactId>testcontainers</artifactId>
3334
<version>2.0.0-SNAPSHOT</version>
3435
<scope>import</scope>
36+
<type>pom</type>
3537
</dependency>
3638
<dependency>
3739
<groupId>org.junit</groupId>

0 commit comments

Comments
 (0)