Update Java SDK documentation KIKIMR-14232

Add Java SDK retry recipe
Add Java SDK logging recipt
Add auth recipes for Java SDK
Fix broken link
Update simple project example

ref:5c1845b01395960d0b76d2e37825269d3703c5eb

14 files changed, 247 insertions, 0 deletions

diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/access_token.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/access_token.md
index 89ddec8b24..b371b3079a 100644
--- a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/access_token.md
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/access_token.md
@@ -11,4 +11,9 @@
 
   {% include [go.md](access_token/go.md) %}
 
+- Java
+
+
+  {% include [java.md](access_token/java.md) %}
+
 {% endlist %}
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/access_token/java.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/access_token/java.md
new file mode 100644
index 0000000000..ae48d716db
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/access_token/java.md
@@ -0,0 +1,21 @@
+```java
+public void work(String connectionString, String accessToken) {
+    AuthProvider authProvider = CloudAuthProvider.newAuthProvider(
+        IamTokenCredentialProvider.builder()
+            .token(accessToken)
+            .build()
+    );
+
+    GrpcTransport transport = GrpcTransport.forConnectionString(connectionString)
+            .withAuthProvider(authProvider)
+            .build();
+
+    TableClient tableClient = TableClient
+        .newClient(GrpcTableRpc.ownTransport(transport))
+        .build());
+
+    doWork(tableClient);
+
+    tableClient.close();
+}
+```
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/anonymous.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/anonymous.md
index fb7085864b..78203438a5 100644
--- a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/anonymous.md
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/anonymous.md
@@ -12,4 +12,9 @@
   {% include [go.md](anonymous/go.md) %}
 
 
+- Java
+
+
+  {% include [java.md](anonymous/java.md) %}
+
 {% endlist %}
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/anonymous/java.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/anonymous/java.md
new file mode 100644
index 0000000000..b795713ddf
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/anonymous/java.md
@@ -0,0 +1,17 @@
+```java
+public void work(String connectionString) {
+    AuthProvider authProvider = NopAuthProvider.INSTANCE;
+
+    GrpcTransport transport = GrpcTransport.forConnectionString(connectionString)
+            .withAuthProvider(authProvider)
+            .build();
+
+    TableClient tableClient = TableClient
+        .newClient(GrpcTableRpc.ownTransport(transport))
+        .build());
+
+    doWork(tableClient);
+
+    tableClient.close();
+}
+```
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/env.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/env.md
index b1772d1300..0fcc99c52e 100644
--- a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/env.md
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/env.md
@@ -20,5 +20,9 @@
 
   {% include [go.md](env/go.md) %}
 
+- Java
+
+
+  {% include [java.md](env/java.md) %}
 
 {% endlist %}
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/env/java.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/env/java.md
new file mode 100644
index 0000000000..cfff5c1a83
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/env/java.md
@@ -0,0 +1,17 @@
+```java
+public void work(String connectionString) {
+    AuthProvider authProvider = CloudAuthHelper.getAuthProviderFromEnviron();
+
+    GrpcTransport transport = GrpcTransport.forConnectionString(connectionString)
+            .withAuthProvider(authProvider)
+            .build();
+
+    TableClient tableClient = TableClient
+        .newClient(GrpcTableRpc.ownTransport(transport))
+        .build());
+
+    doWork(tableClient);
+
+    tableClient.close();
+}
+```
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/metadata.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/metadata.md
index f0502f89a8..f6e5ac104b 100644
--- a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/metadata.md
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/metadata.md
@@ -11,5 +11,9 @@
 
   {% include [go.md](metadata/go.md) %}
 
+- Java
+
+
+  {% include [java.md](metadata/java.md) %}
 
 {% endlist %}
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/metadata/java.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/metadata/java.md
new file mode 100644
index 0000000000..ceb04396fa
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/metadata/java.md
@@ -0,0 +1,20 @@
+```java
+public void work(String connectionString) {
+    AuthProvider authProvider = CloudAuthProvider.newAuthProvider(
+        ComputeEngineCredentialProvider.builder()
+            .build()
+    );
+
+    GrpcTransport transport = GrpcTransport.forConnectionString(connectionString)
+            .withAuthProvider(authProvider)
+            .build();
+
+    TableClient tableClient = TableClient
+        .newClient(GrpcTableRpc.ownTransport(transport))
+        .build());
+
+    doWork(tableClient);
+
+    tableClient.close();
+}
+```
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/service_account.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/service_account.md
index ab98a99d6d..59e06312a6 100644
--- a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/service_account.md
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/service_account.md
@@ -11,5 +11,9 @@
 
   {% include [go.md](service_account/go.md) %}
 
+- Java
+
+
+  {% include [java.md](service_account/java.md) %}
 
 {% endlist %}
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/service_account/java.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/service_account/java.md
new file mode 100644
index 0000000000..a75034440c
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/auth/_includes/service_account/java.md
@@ -0,0 +1,21 @@
+```java
+public void work(String connectionString, Path saKeyPath) {
+    AuthProvider authProvider = CloudAuthProvider.newAuthProvider(
+        ApiKeyCredentialProvider.builder()
+            .fromFile(saKeyPath)
+            .build()
+    );
+
+    GrpcTransport transport = GrpcTransport.forConnectionString(connectionString)
+            .withAuthProvider(authProvider)
+            .build();
+
+    TableClient tableClient = TableClient
+        .newClient(GrpcTableRpc.ownTransport(transport))
+        .build());
+
+    doWork(tableClient);
+
+    tableClient.close();
+}
+```
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/debug/_includes/logs.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/debug/_includes/logs.md
index 48c306591d..ebd53ad379 100644
--- a/ydb/docs/ru/core/reference/ydb-sdk/recipes/debug/_includes/logs.md
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/debug/_includes/logs.md
@@ -11,5 +11,9 @@
 
   {% include [go.md](logs/go.md) %}
 
+- Java
+
+
+  {% include [java.md](logs/java.md) %}
 
 {% endlist %}
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/debug/_includes/logs/java.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/debug/_includes/logs/java.md
new file mode 100644
index 0000000000..29d7708be2
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/debug/_includes/logs/java.md
@@ -0,0 +1,50 @@
+В {{ ydb-short-name }} Java SDK для логирования используется библиотека slf4j, которая позволяет использовать различные уровни логирования (`error`, `warn`, `info`, `debug`, `trace`) для одного или нескольких логгеров. В текущей реализации доступны следующие логгеры:
+
+* Логгер `com.yandex.ydb.core.grpc` предоставляет информацию о внутренней реализации grpc протокола 
+  * уровень `debug` логирует все операции по протоколу grpc, рекомедуется использовать только для отладки
+  * уровень `info` рекомендуется использовать по умолчанию
+
+* Логгер `com.yandex.ydb.table.impl` на уровне `debug` позволяет отслеживать внутреннее состояние драйвера ydb, в частности работу пула сессий.
+
+* Логгер `com.yandex.ydb.table.SessionRetryContext` на уровне `debug` будет информировать о количестве ретраев, результатах выполненных запросов, времени выполнения отдельных ретраев и общем времени выполнения всей операции
+
+* Логгер `com.yandex.ydb.table.Session` на уровне `debug` предоставляет информацию о тексте запроса, статусе ответа и времени выполнения для различных операций сессии
+
+
+Включение и настройка логгеров Java SDK зависит от используемой реализации `slf4j-api`.
+Здесь приведен пример конфигурации `log4j2` для библиотеки `log4j-slf4j-impl`
+
+```xml
+<Configuration status="WARN">
+    <Appenders>
+        <Console name="Console" target="SYSTEM_OUT">
+            <PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %logger{36} - %msg%n"/>
+        </Console>
+    </Appenders>
+
+    <Loggers>
+        <Logger name="io.netty" level="warn" additivity="false">
+            <AppenderRef ref="Console"/>
+        </Logger>
+        <Logger name="io.grpc.netty" level="warn" additivity="false">
+            <AppenderRef ref="Console"/>
+        </Logger>
+        <Logger name="com.yandex.ydb.core.grpc" level="info" additivity="false">
+            <AppenderRef ref="Console"/>
+        </Logger>
+        <Logger name="com.yandex.ydb.table.impl" level="info" additivity="false">
+            <AppenderRef ref="Console"/>
+        </Logger>
+        <Logger name="com.yandex.ydb.table.SessionRetryContext" level="debug" additivity="false">
+            <AppenderRef ref="Console"/>
+        </Logger>
+        <Logger name="com.yandex.ydb.table.Session" level="debug" additivity="false">
+            <AppenderRef ref="Console"/>
+        </Logger>
+
+        <Root level="debug" >
+            <AppenderRef ref="Console"/>
+        </Root>
+    </Loggers>
+</Configuration>
+```
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/retry/_includes/java.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/retry/_includes/java.md
new file mode 100644
index 0000000000..cd455281f1
--- /dev/null
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/retry/_includes/java.md
@@ -0,0 +1,71 @@
+В {{ ydb-short-name }} Java SDK механизм повторных запросов реализован в виде класс хелпера `com.yandex.ydb.table.SessionRetryContext`. Данный класс конструируется с помощью метода `SessionRetryContext.create` в который требуется передать реализацию интерфейса `SessionSupplier` - как правило это экземпляр класса `TableClient`.
+Дополнительно пользователь может задавать некоторые другие опции
+* `maxRetries(int maxRetries)` - максимальное количество повторов операции, не включает в себя первое выполение. Значение по умолчанию `10`
+* `retryNotFound(boolean retryNotFound)` - опция повтора операций, вернувших статус `NOT_FOUND`. По умолчанию включено.
+* `idempotent(boolean idempotent)` - признак идемпотентности операций. Идемпотентные операции будут повторяться для более широкого списка ошибок. По умолчанию отключено.
+
+Для запуска операций с ретраями класс `SessionRetryContext` предоставляет два метода
+* `CompletableFuture<Status> supplyStatus` - выполнение операции, возвращающей статус. В качестве аргумента принимает лямбду `Function<Session, CompletableFuture<Status>> fn`
+* `CompletableFuture<Result<T>> supplyResult` - выполнение операции, возвращающей данные. В качестве аргумента принимает лямбду `Function<Session, CompletableFuture<Result<T>>> fn` 
+
+При использовании класса `SessionRetryContext` нужно учитывать, что повторое исполнение операции будут выполнятся в следующих случаях
+* Лямбда вернула [retryable](../../../error_handling.md) код ошибки
+* В рамках исполнения лямбды была вызвано `UnexpectedResultException` c [retryable](../../../error_handling.md) кодом ошибки
+
+
+
+  {% cut "Пример кода, использующего SessionRetryContext.supplyStatus:" %}
+
+    ```java
+    private void createTable(TableClient tableClient, String database, String tableName) {
+        SessionRetryContext retryCtx = SessionRetryContext.create(tableClient).build();
+        TableDescription pets = TableDescription.newBuilder()
+                .addNullableColumn("species", PrimitiveType.utf8())
+                .addNullableColumn("name", PrimitiveType.utf8())
+                .addNullableColumn("color", PrimitiveType.utf8())
+                .addNullableColumn("price", PrimitiveType.float32())
+                .setPrimaryKeys("species", "name")
+                .build();
+
+        String tablePath = database + "/" + tableName;
+        retryCtx.supplyStatus(session -> session.createTable(tablePath, pets))
+                .join().expect("ok");
+    }
+    ```
+
+  {% endcut %}
+
+  {% cut "Пример кода, использующего SessionRetryContext.supplyResult:" %}
+
+    ```java
+    private void selectData(TableClient tableClient, String tableName) {
+        SessionRetryContext retryCtx = SessionRetryContext.create(tableClient).build();
+        String selectQuery
+                = "DECLARE $species AS Utf8;"
+                + "DECLARE $name AS Utf8;"
+                + "SELECT * FROM " + tableName + " "
+                + "WHERE species = $species AND name = $name;";
+
+        Params params = Params.of(
+                "$species", PrimitiveValue.utf8("cat"),
+                "$name", PrimitiveValue.utf8("Tom")
+        );
+
+        DataQueryResult data = retryCtx
+                .supplyResult(session -> session.executeDataQuery(selectQuery, TxControl.onlineRo(), params))
+                .join().expect("ok");
+
+        ResultSetReader rsReader = data.getResultSet(0);
+        logger.info("Result of select query:");
+        while (rsReader.next()) {
+            logger.info("  species: {}, name: {}, color: {}, price: {}",
+                    rsReader.getColumn("species").getUtf8(),
+                    rsReader.getColumn("name").getUtf8(),
+                    rsReader.getColumn("color").getUtf8(),
+                    rsReader.getColumn("price").getFloat32()
+            );
+        }
+    }
+    ```
+
+  {% endcut %}
diff --git a/ydb/docs/ru/core/reference/ydb-sdk/recipes/retry/index.md b/ydb/docs/ru/core/reference/ydb-sdk/recipes/retry/index.md
index b7dcdd0159..c7a297f050 100644
--- a/ydb/docs/ru/core/reference/ydb-sdk/recipes/retry/index.md
+++ b/ydb/docs/ru/core/reference/ydb-sdk/recipes/retry/index.md
@@ -18,5 +18,9 @@
 
   {% include [go.md](_includes/go.md) %}
 
+- Java
+
+
+  {% include [java.md](_includes/java.md) %}
 
 {% endlist %}