diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d87c6e2..7bc12d4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -34,7 +34,7 @@ jobs: - name: Publish to Maven Central run: | - ./mvnw -B clean deploy -PsonatypeRelease -DskipTests -pl '!jacoco-coverage-aggregate-report' + ./mvnw -B clean deploy -PsonatypeRelease -DskipTests -pl '!jacoco-coverage-aggregate-report,!documentation' env: MAVEN_USERNAME: ${{ secrets.MAVEN_CENTRAL_USER }} MAVEN_TOKEN: ${{ secrets.MAVEN_CENTRAL_TOKEN }} diff --git a/.github/workflows/snapshot.yml b/.github/workflows/snapshot.yml index c4a59e2..a27838b 100644 --- a/.github/workflows/snapshot.yml +++ b/.github/workflows/snapshot.yml @@ -27,7 +27,7 @@ jobs: - name: Publish Snapshot to Maven Central run: | - ./mvnw -B clean deploy -PsonatypeSnapshot -DskipTests -pl '!jacoco-coverage-aggregate-report' + ./mvnw -B clean deploy -PsonatypeSnapshot -DskipTests -pl '!jacoco-coverage-aggregate-report,!documentation' env: MAVEN_USERNAME: ${{ secrets.MAVEN_CENTRAL_USER }} MAVEN_TOKEN: ${{ secrets.MAVEN_CENTRAL_TOKEN }} diff --git a/.gitignore b/.gitignore index 3b1e9ee..3ce9a8a 100644 --- a/.gitignore +++ b/.gitignore @@ -23,3 +23,4 @@ workbench.xmi .factorypath documentation/venv documentation/site +documentation/target diff --git a/documentation/README.md b/documentation/README.md index a97dd2e..77e2f16 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -32,3 +32,8 @@ markdown сошлитесь на схему как на обычную markdown- ```markdown ![](../../../../assets//schema.drawio) ``` + +### Code Snippets + +Сейчас документация настроена на то, что пути snippet файлов обрабатываются относительно директории +`docs/documentation/examples` diff --git a/documentation/docs/documentation/client/examples/connection/index.md b/documentation/docs/documentation/client/examples/connection/index.md new file mode 100644 index 0000000..dabe45d --- /dev/null +++ b/documentation/docs/documentation/client/examples/connection/index.md @@ -0,0 +1,7 @@ +--- +title: Подключение к узлам +hide: + - toc +--- + +В данном разделе приводятся примеры подключения к Tarantool с помощью `tarantool-java-sdk`. diff --git a/documentation/docs/documentation/client/examples/connection/single-node.md b/documentation/docs/documentation/client/examples/connection/single-node.md new file mode 100644 index 0000000..64b7961 --- /dev/null +++ b/documentation/docs/documentation/client/examples/connection/single-node.md @@ -0,0 +1,34 @@ +--- +title: Подключение к одиночному узлу +--- + +Для того чтобы подключиться к одиночному узлу необходимо выполнить следующий код: + +=== "tarantool-java-sdk" + + ```java title="Подключение к одному узлу Tarantool" + --8<-- "src/client/simple/connection/SingleNodeConnectionNewConnector.java:new-simple-connection" + ``` + + ```java title="Родительский класс с созданием контейнера" + --8<-- "src/client/simple/connection/SingleNodeConnection.java:single-node-connection" + ``` + + ```java title="Класс, который создает контейнер" + --8<-- "src/testcontainers/single/CreateSingleNode.java:create-single-node" + ``` + +=== "cartridge-java" + + ```java title="Подключение к одному узлу Tarantool" + --8<-- "src/client/simple/connection/SingleNodeConnectionCartridgeJava.java:old-simple-connection" + ``` + + ```java title="Родительский класс с созданием контейнера" + --8<-- "src/client/simple/connection/SingleNodeConnection.java:single-node-connection" + ``` + + ```java title="Класс, который создает контейнер" + --8<-- "src/testcontainers/single/CreateSingleNode.java:create-single-node" + ``` + \ No newline at end of file diff --git a/documentation/docs/documentation/client/examples/index.md b/documentation/docs/documentation/client/examples/index.md new file mode 100644 index 0000000..72d969f --- /dev/null +++ b/documentation/docs/documentation/client/examples/index.md @@ -0,0 +1,12 @@ +--- +title: Примеры использования +hide: + - toc +--- + +В разделе приводятся примеры использования `tarantool-java-sdk`. + +???+ note "Заметка" + + Где это возможно, производится сравнение кода с + [cartridge-java](https://github.com/tarantool/cartridge-java) diff --git a/documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnection.java b/documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnection.java new file mode 100644 index 0000000..939c0cc --- /dev/null +++ b/documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnection.java @@ -0,0 +1,42 @@ +/* + * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY + * All Rights Reserved. + */ + +package client.simple.connection; + +// --8<-- [start:single-node-connection] + +import java.io.IOException; +import java.nio.file.Path; + +import org.junit.jupiter.api.BeforeAll; +import org.junit.jupiter.api.io.TempDir; +import org.testcontainers.containers.tarantool.Tarantool3Container; +import org.testcontainers.containers.tarantool.TarantoolContainer; +import org.testcontainers.utility.DockerImageName; +import testcontainers.single.CreateSingleNode; + +public abstract class SingleNodeConnection { + + @TempDir protected static Path TEMP_DIR; + + private static final DockerImageName image = DockerImageName.parse("tarantool/tarantool:3.4.1"); + + protected static TarantoolContainer CONTAINER; + + @BeforeAll + static void beforeAll() throws IOException { + CONTAINER = createSingleNodeContainer(TEMP_DIR); + CONTAINER.start(); + } + + protected abstract void simpleConnection(); + + protected static TarantoolContainer createSingleNodeContainer(Path tempPath) + throws IOException { + final Path pathToConfig = CreateSingleNode.createSingleNodeConfig(tempPath); + return new Tarantool3Container(image, "test-node").withConfigPath(pathToConfig); + } +} +// --8<-- [end:single-node-connection] diff --git a/documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnectionCartridgeJava.java b/documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnectionCartridgeJava.java new file mode 100644 index 0000000..e2d8694 --- /dev/null +++ b/documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnectionCartridgeJava.java @@ -0,0 +1,51 @@ +/* + * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY + * All Rights Reserved. + */ + +package client.simple.connection; + +// --8<-- [start:old-simple-connection] + +import java.net.InetSocketAddress; +import java.util.List; + +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.Test; +import testcontainers.single.CreateSingleNode; + +import io.tarantool.driver.api.TarantoolClient; +import io.tarantool.driver.api.TarantoolClientFactory; +import io.tarantool.driver.api.TarantoolResult; +import io.tarantool.driver.api.tuple.TarantoolTuple; + +public class SingleNodeConnectionCartridgeJava extends SingleNodeConnection { + + @Test + @Override + protected void simpleConnection() { + try (TarantoolClient> client = setupClient()) { + final List result = client.eval("return _TARANTOOL").join(); + + Assertions.assertEquals(1, result.size()); + + final Object object = result.get(0); + + Assertions.assertInstanceOf(String.class, object); + Assertions.assertTrue(((String) object).contains("3.4.1")); + } catch (Exception e) { + throw new RuntimeException(e); + } + } + + private static TarantoolClient> setupClient() { + // Получаем адрес и порт из докера + final InetSocketAddress nodeAddress = CONTAINER.mappedAddress(); + + return TarantoolClientFactory.createClient() + .withAddress(nodeAddress.getHostName(), nodeAddress.getPort()) + .withCredentials(CreateSingleNode.LOGIN, CreateSingleNode.PWD.toString()) + .build(); + } +} +// --8<-- [end:old-simple-connection] diff --git a/documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnectionNewConnector.java b/documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnectionNewConnector.java new file mode 100644 index 0000000..dd601c9 --- /dev/null +++ b/documentation/docs/documentation/examples/src/client/simple/connection/SingleNodeConnectionNewConnector.java @@ -0,0 +1,57 @@ +/* + * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY + * All Rights Reserved. + */ + +package client.simple.connection; + +// --8<-- [start:new-simple-connection] + +import java.net.InetSocketAddress; +import java.util.Collections; +import java.util.List; + +import org.junit.jupiter.api.Assertions; +import org.junit.jupiter.api.Test; +import testcontainers.single.CreateSingleNode; + +import io.tarantool.client.box.TarantoolBoxClient; +import io.tarantool.client.factory.TarantoolBoxClientBuilder; +import io.tarantool.client.factory.TarantoolFactory; +import io.tarantool.mapping.TarantoolResponse; +import io.tarantool.pool.InstanceConnectionGroup; + +public class SingleNodeConnectionNewConnector extends SingleNodeConnection { + + @Test + @Override + protected void simpleConnection() { + // Получаем адрес и порт из докера + final InetSocketAddress nodeAddress = CONTAINER.mappedAddress(); + + // Настраиваем группу подключения + final InstanceConnectionGroup connectionGroup = + InstanceConnectionGroup.builder() + .withHost(nodeAddress.getHostName()) + .withPort(nodeAddress.getPort()) + .withUser(CreateSingleNode.LOGIN) + .withPassword(CreateSingleNode.PWD.toString()) + .build(); + + final TarantoolBoxClientBuilder clientBuilder = + TarantoolFactory.box().withGroups(Collections.singletonList(connectionGroup)); + + try (final TarantoolBoxClient singleNodeClient = clientBuilder.build()) { + + final TarantoolResponse> response = + singleNodeClient.eval("return _TARANTOOL", String.class).join(); + final List results = response.get(); + + Assertions.assertEquals(1, results.size()); + Assertions.assertTrue(results.get(0).contains("3.4.1")); + } catch (Exception e) { + throw new RuntimeException(e); + } + } +} +// --8<-- [end:new-simple-connection] diff --git a/documentation/docs/documentation/examples/src/testcontainers/single/CreateSingleNode.java b/documentation/docs/documentation/examples/src/testcontainers/single/CreateSingleNode.java new file mode 100644 index 0000000..a5fe259 --- /dev/null +++ b/documentation/docs/documentation/examples/src/testcontainers/single/CreateSingleNode.java @@ -0,0 +1,102 @@ +/* + * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY + * All Rights Reserved. + */ + +package testcontainers.single; + +// --8<-- [start:create-single-node] + +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; +import java.util.Collections; + +import org.testcontainers.containers.tarantool.config.ConfigurationUtils; + +import io.tarantool.autogen.Tarantool3Configuration; +import io.tarantool.autogen.credentials.Credentials; +import io.tarantool.autogen.credentials.users.Users; +import io.tarantool.autogen.credentials.users.usersProperty.UsersProperty; +import io.tarantool.autogen.groups.Groups; +import io.tarantool.autogen.groups.groupsProperty.GroupsProperty; +import io.tarantool.autogen.groups.groupsProperty.replicasets.Replicasets; +import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.ReplicasetsProperty; +import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.Instances; +import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.instancesProperty.InstancesProperty; +import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.instancesProperty.iproto.Iproto; +import io.tarantool.autogen.groups.groupsProperty.replicasets.replicasetsProperty.instances.instancesProperty.iproto.listen.Listen; + +public class CreateSingleNode { + + public static final String NODE = "test-node"; + + public static final CharSequence PWD = "secret"; + + public static final String LOGIN = "test-user"; + + /* + Создает конфигурацию вида: + --- + credentials: + users: + test-user: + password: "secret" + roles: + - "super" + groups: + test-group: + replicasets: + test-rs: + instances: + test-node: + iproto: + listen: + - uri: "0.0.0.0:3301" + */ + public static Path createSingleNodeConfig(Path tempDir) throws IOException { + final Path pathToConfigFile = Files.createFile(tempDir.resolve("config.yaml")); + + final Credentials credentials = + Credentials.builder() + .withUsers( + Users.builder() + .withAdditionalProperty( + LOGIN, + UsersProperty.builder() + .withRoles(Collections.singletonList("super")) + .withPassword(PWD.toString()) + .build()) + .build()) + .build(); + + final Iproto iproto = + Iproto.builder() + .withListen(Collections.singletonList(Listen.builder().withUri("0.0.0.0:3301").build())) + .build(); + + final InstancesProperty instance = InstancesProperty.builder().withIproto(iproto).build(); + + final ReplicasetsProperty replicaset = + ReplicasetsProperty.builder() + .withInstances(Instances.builder().withAdditionalProperty(NODE, instance).build()) + .build(); + + final GroupsProperty group = + GroupsProperty.builder() + .withReplicasets( + Replicasets.builder().withAdditionalProperty("test-rs", replicaset).build()) + .build(); + + final Tarantool3Configuration configuration = + Tarantool3Configuration.builder() + .withGroups(Groups.builder().withAdditionalProperty("test-group", group).build()) + .withCredentials(credentials) + .build(); + + ConfigurationUtils.writeToFile(configuration, pathToConfigFile); + return pathToConfigFile; + } +} + +// --8<-- [end:create-single-node] diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index 8e03af5..dd31fa2 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -94,6 +94,11 @@ nav: - documentation/client/arch/connection-to-multiple-nodes.md - documentation/client/arch/call.md - documentation/client/arch/tuple_pojo_mapping.md + - Примеры использования: + - documentation/client/examples/index.md + - Подключение к узлам: + - documentation/client/examples/connection/index.md + - documentation/client/examples/connection/single-node.md - Tarantool Testcontainers: - documentation/testcontainers/index.md - Одиночный узел: @@ -130,7 +135,9 @@ markdown_extensions: line_spans: __spanz pygments_lang_class: true - pymdownx.inlinehilite - - pymdownx.snippets + - pymdownx.snippets: + check_paths: true + base_path: docs/documentation/examples - def_list - pymdownx.tasklist: custom_checkbox: true diff --git a/documentation/pom.xml b/documentation/pom.xml new file mode 100644 index 0000000..174786e --- /dev/null +++ b/documentation/pom.xml @@ -0,0 +1,90 @@ + + + 4.0.0 + + io.tarantool + tarantool-java-sdk + 2.0.0-SNAPSHOT + + + documentation + + + 0.13.0 + 5.14.0 + 17 + 17 + ${project.parent.basedir}/LICENSE_HEADER.txt + + + + + + io.tarantool + tarantool-client + 2.0.0-SNAPSHOT + import + pom + + + io.tarantool + testcontainers + 2.0.0-SNAPSHOT + import + pom + + + org.junit + junit-bom + ${junit.version} + import + pom + + + io.tarantool + cartridge-driver + ${cartridge-java.version} + import + + + + + + + io.tarantool + tarantool-client + test + + + io.tarantool + testcontainers + test + + + org.junit.jupiter + junit-jupiter + test + + + ch.qos.logback + logback-classic + test + + + io.tarantool + cartridge-driver + test + + + + + docs/documentation/examples/src + + + docs/documentation/examples/resources + + + + diff --git a/pom.xml b/pom.xml index 44d92b5..29d1540 100644 --- a/pom.xml +++ b/pom.xml @@ -642,5 +642,6 @@ testcontainers jacoco-coverage-aggregate-report testcontainers-autogen + documentation