doc(call): add call examples (#38)

Add examples to interact with stored procedures from java

Closes #37

Author: nickkkccc

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

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
+ * All Rights Reserved.
+ */
+
+package client;
+
+// --8<-- [start:all]
+
+import java.net.InetSocketAddress;
+import java.util.Arrays;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import testcontainers.utils.TarantoolSingleNodeConfigUtils;
+
+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 TarantoolCallCartridgeDriverExample extends TarantoolCallEvalAbstractExample {
+
+  @Test
+  @SuppressWarnings("unchecked")
+  void simpleCall() {
+    try (TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> client = setupClient()) {
+      loadFunctions();
+
+      final List<?> helloWorldReturns = client.call(HELLO_WORLD_FUNCTION).join();
+      Assertions.assertEquals(1, helloWorldReturns.size());
+      Assertions.assertEquals(HELLO_WORLD_FUNCTION_RETURNS, helloWorldReturns.get(0));
+
+      // convert returning lua map into Java pojo representing as map
+      final String name = "Petya";
+      final int age = 25;
+
+      final List<?> resultAsMap = client.call(SOME_MAP_FUNCTION, Arrays.asList(name, age)).join();
+
+      Assertions.assertEquals(1, resultAsMap.size());
+      Assertions.assertInstanceOf(Map.class, resultAsMap.get(0));
+      final Map<String, Object> castedResult = (Map<String, Object>) resultAsMap.get(0);
+      Assertions.assertEquals(name, castedResult.get("name"));
+      Assertions.assertEquals(age, castedResult.get("age"));
+
+    } catch (Exception e) {
+      throw new RuntimeException(e);
+    }
+  }
+
+  private static TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> setupClient() {
+    // Получаем адрес и порт из докера
+    // Gets address and port from docker
+    final InetSocketAddress nodeAddress = CONTAINER.mappedAddress();
+
+    return TarantoolClientFactory.createClient()
+        .withAddress(nodeAddress.getHostName(), nodeAddress.getPort())
+        .withCredentials(
+            TarantoolSingleNodeConfigUtils.LOGIN, TarantoolSingleNodeConfigUtils.PWD.toString())
+        .build();
+  }
+}
+
+// --8<-- [end:all]

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

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
+ * All Rights Reserved.
+ */
+
+package client;
+
+// --8<-- [start:all]
+
+import java.io.IOException;
+
+import testcontainers.utils.TarantoolSingleNodeConfigUtils;
+
+public abstract class TarantoolCallEvalAbstractExample
+    extends TarantoolSingleInstanceConnectionAbstractExample {
+
+  protected static String HELLO_WORLD_FUNCTION = "hello_world_function";
+  protected static String HELLO_WORLD_FUNCTION_RETURNS = "hello world";
+  protected static String SOME_MAP_FUNCTION = "some_map_function";
+
+  protected static final String LUA_FUNCTION =
+      String.format(
+          """
+          %s = function()
+            return '%s'
+          end
+
+          %s = function(name, age)
+            return {
+                name = name,
+                age = age
+            }
+          end
+          """,
+          HELLO_WORLD_FUNCTION, HELLO_WORLD_FUNCTION_RETURNS, SOME_MAP_FUNCTION);
+
+  protected void loadFunctions() throws IOException, InterruptedException {
+    final String command =
+        "echo \"%s\" | tt connect %s:%s@localhost:3301"
+            .formatted(
+                LUA_FUNCTION,
+                TarantoolSingleNodeConfigUtils.LOGIN,
+                TarantoolSingleNodeConfigUtils.PWD);
+    CONTAINER.execInContainer("/bin/sh", "-c", command);
+  }
+
+  protected record TestUser(String name, Integer age) {}
+}
+
+// --8<-- [end:all]

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

@@ -0,0 +1,80 @@
+/*
+ * Copyright (c) 2025 VK DIGITAL TECHNOLOGIES LIMITED LIABILITY COMPANY
+ * All Rights Reserved.
+ */
+
+package client;
+
+// --8<-- [start:all]
+
+import java.net.InetSocketAddress;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import testcontainers.utils.TarantoolSingleNodeConfigUtils;
+
+import io.tarantool.client.TarantoolClient;
+import io.tarantool.client.factory.TarantoolFactory;
+import io.tarantool.pool.InstanceConnectionGroup;
+
+public class TarantoolCallTJSDKExample extends TarantoolCallEvalAbstractExample {
+
+  @Test
+  void simpleCall() {
+    try (TarantoolClient client = setupClient()) {
+      loadFunctions();
+
+      final List<String> helloWorldReturns =
+          client.call(HELLO_WORLD_FUNCTION, String.class).join().get();
+      Assertions.assertEquals(1, helloWorldReturns.size());
+      Assertions.assertEquals(HELLO_WORLD_FUNCTION_RETURNS, helloWorldReturns.get(0));
+
+      // convert returning lua map into Java pojo representing as map
+      final String name = "Petya";
+      final int age = 25;
+
+      final List<TestUser> resultAsPojo =
+          client.call(SOME_MAP_FUNCTION, Arrays.asList(name, age), TestUser.class).join().get();
+
+      Assertions.assertEquals(1, resultAsPojo.size());
+      Assertions.assertEquals(name, resultAsPojo.get(0).name());
+      Assertions.assertEquals(age, resultAsPojo.get(0).age());
+
+      // convert returning lua map into java list of map via type reference
+      // java map key type is string because lua map key type is string!
+      final List<Map<String, Object>> objectObjectMap =
+          client
+              .call(
+                  SOME_MAP_FUNCTION,
+                  Arrays.asList(name, age),
+                  new TypeReference<List<Map<String, Object>>>() {})
+              .join()
+              .get();
+
+    } catch (Exception e) {
+      throw new RuntimeException(e);
+    }
+  }
+
+  private static TarantoolClient setupClient() throws Exception {
+    final InetSocketAddress address = CONTAINER.mappedAddress();
+
+    final InstanceConnectionGroup connectionGroup =
+        InstanceConnectionGroup.builder()
+            .withHost(address.getHostName())
+            .withPort(address.getPort())
+            .withUser(TarantoolSingleNodeConfigUtils.LOGIN)
+            .withPassword(TarantoolSingleNodeConfigUtils.PWD.toString())
+            .withSize(3)
+            .build();
+
+    return TarantoolFactory.box().withGroups(Collections.singletonList(connectionGroup)).build();
+  }
+}
+
+// --8<-- [end:all]

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

@@ -5,7 +5,7 @@
 
 package client;
 
-// --8<-- [start:tarantool-single-instance-abstract]
+// --8<-- [start:all]
 
 import java.io.IOException;
 import java.nio.file.Path;
@@ -40,12 +40,10 @@ static void afterAll() {
     CONTAINER.stop();
   }
 
-  protected abstract void simpleConnection();
-
   protected static TarantoolContainer<Tarantool3Container> createSingleNodeContainer(Path tempPath)
       throws IOException {
     final Path pathToConfig = TarantoolSingleNodeConfigUtils.createConfig(tempPath);
     return new Tarantool3Container(image, "test-node").withConfigPath(pathToConfig);
   }
 }
-// --8<-- [end:tarantool-single-instance-abstract]
+// --8<-- [end:all]

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

@@ -5,7 +5,7 @@
 
 package client;
 
-// --8<-- [start:tarantool-single-instance-cartridge-driver]
+// --8<-- [start:all]
 
 import java.net.InetSocketAddress;
 import java.util.List;
@@ -23,7 +23,6 @@ public class TarantoolSingleInstanceConnectionCartridgeDriverExample
     extends TarantoolSingleInstanceConnectionAbstractExample {
 
   @Test
-  @Override
   protected void simpleConnection() {
     try (TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>> client = setupClient()) {
       final List<?> result = client.eval("return _TARANTOOL").join();
@@ -51,4 +50,4 @@ private static TarantoolClient<TarantoolTuple, TarantoolResult<TarantoolTuple>>
         .build();
   }
 }
-// --8<-- [end:tarantool-single-instance-cartridge-driver]
+// --8<-- [end:all]

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

@@ -5,7 +5,7 @@
 
 package client;
 
-// --8<-- [start:tarantool-single-instance-tjsdk]
+// --8<-- [start:all]
 
 import java.net.InetSocketAddress;
 import java.util.Collections;
@@ -25,7 +25,6 @@ public class TarantoolSingleInstanceConnectionTJSDKExample
     extends TarantoolSingleInstanceConnectionAbstractExample {
 
   @Test
-  @Override
   protected void simpleConnection() {
     // Получаем адрес и порт из докера
     // Gets address and port from docker
@@ -57,4 +56,4 @@ protected void simpleConnection() {
     }
   }
 }
-// --8<-- [end:tarantool-single-instance-tjsdk]
+// --8<-- [end:all]

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

@@ -0,0 +1,40 @@
+---
+title: Interacting with stored procedures
+---
+
+The following example demonstrates interacting with stored procedures from java:
+
+=== "tarantool-java-sdk"
+
+    ```title="Interacting with stored procedures from java"
+    --8<-- "client/TarantoolCallTJSDKExample.java:all"
+    ```
+
+    ```title="Abstract class to create Tarantool container"
+    --8<-- "client/TarantoolCallEvalAbstractExample.java:all"
+    ```
+
+    ```title="Abstract class to create Tarantool container"
+    --8<-- "client/TarantoolSingleInstanceConnectionAbstractExample.java:all"
+    ```
+
+=== "cartridge-driver"
+
+    ```title="Interacting with stored procedures from java"
+    --8<-- "client/TarantoolCallCartridgeDriverExample.java:all"
+    ```
+
+    ```title="Abstract class to create Tarantool container"
+    --8<-- "client/TarantoolCallEvalAbstractExample.java:all"
+    ```
+
+    ```title="Abstract class to create Tarantool container"
+    --8<-- "client/TarantoolSingleInstanceConnectionAbstractExample.java:all"
+    ```
+
+???+ note
+
+    `tarantool-java-sdk` allows you to convert stored procedure return values to pojos, which have 
+    fields with default types, automatically. In `cartridge-driver` for this requires implementing 
+    converters for each of the custom pojo types, and passing them to `#call(...)` methods .
+

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

@@ -0,0 +1,41 @@
+---
+title: Работа с хранимыми процедурами
+---
+
+Следующие пример демонстрируют работу с хранимыми процедурами из java:
+
+=== "tarantool-java-sdk"
+
+    ```title="Работа с хранимыми процедурами из java"
+    --8<-- "client/TarantoolCallTJSDKExample.java:all"
+    ```
+
+    ```title="Абстрактный класс для создания контейнера Tarantool"
+    --8<-- "client/TarantoolCallEvalAbstractExample.java:all"
+    ```
+
+    ```title="Абстрактный класс для создания контейнера Tarantool"
+    --8<-- "client/TarantoolSingleInstanceConnectionAbstractExample.java:all"
+    ```
+
+=== "cartridge-driver"
+
+    ```title="Работа с хранимыми процедурами из java"
+    --8<-- "client/TarantoolCallCartridgeDriverExample.java:all"
+    ```
+
+    ```title="Абстрактный класс для создания контейнера Tarantool"
+    --8<-- "client/TarantoolCallEvalAbstractExample.java:all"
+    ```
+
+    ```title="Абстрактный класс для создания контейнера Tarantool"
+    --8<-- "client/TarantoolSingleInstanceConnectionAbstractExample.java:all"
+    ```
+
+???+ note "Заметка"
+
+    `tarantool-java-sdk` позволяет преобразовывать возвращаемые значения хранимых процедур в pojo, 
+    которые имеют поля с типами по умолчанию, автоматически. В `cartridge-driver` для этого 
+    требуется реализация конвертеров для каждого из пользовательских типов pojo, и передача их в 
+    методы `#call(...)`.
+

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

@@ -0,0 +1,8 @@
+---
+title: Interact with stored procedures
+hide:
+  - toc
+---
+
+This section provides examples of interacting with stored procedures from java using
+`tarantool-java-sdk`.

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

@@ -0,0 +1,8 @@
+---
+title: Работа с хранимыми процедурами
+hide:
+  - toc
+---
+
+В данном разделе приводятся примеры работы с хранимыми процедурами из java при помощи
+`tarantool-java-sdk`.