[docs-java-client] Client V2 Configuration Docs #2707

chernser · 2024-10-16T19:10:48Z

Summary

Added list of all JAVA Client V2 configuration parameters
Added documentation for authentication method.

Checklist

Delete items not relevant to your PR
URL changes should add a redirect to the old URL via https://github.com/ClickHouse/clickhouse-docs/blob/main/docusaurus.config.js
If adding a new integration page, also add an entry to the integrations list here: https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/en/integrations/index.mdx

…t V2

mshustov · 2024-11-02T10:29:12Z

docs/en/integrations/language-clients/java/client-v2.md

+| httpHeader(String key, Collection values) | - `key` - HTTP header key.<br /> - `values` - list of string values. | Sets values for a single HTTP header. Previous value is overriden.|
+| httpHeaders(Map headers) | - `header` - map with HTTP headers and their values. | Sets multiple HTTP header values at a time. |
+| serverSetting(String name, String value) | - `name` - name of a query level setting.<br /> - `value` - string value of the setting. | Sets query level setting to be sent along with every request. Operation settings may override it. See [Query Level Settings](/docs/en/operations/settings/query-level) for more information. | 
+| serverSetting(String name,  Collection values) | - `name` - name of a query level setting.<br /> - `values` - string values of the setting. | Sets query level setting values to be sent along with every request. Operation settings may be override it. This method is useful to set settings with multiple values, for example [roles](/docs/en/interfaces/http#setting-role-with-query-parameters) |


name of a query level setting.

Does it set the server setting? I'd rephrase it something like clickhouse setting set for each query

mshustov · 2024-11-02T10:29:51Z

docs/en/integrations/language-clients/java/client-v2.md

+| useAsyncRequests(boolean async) | `async` - flag that indicates if the option should be enabled. | Sets if client should execute request in a separate thread. Disabled by default because application knows better how to organize multithreaded tasks and running tasks in separate thread do not help with performance. | 
+| setSharedOperationExecutor(ExecutorService executorService) | `executorService` - instance of executor service. | Sets executor service for operation tasks. | 
+| setClientNetworkBufferSize(int size) | - `size` - size in bytes | Sets size of a buffer in application memory space that is used to copy data back-and-forth between socket and application. Greater reduces system calls to TCP stack, but affects how much memory is spent on every connection. This buffer is also subject for GC because connections are shortlive. Also keep in mind that allocating big continious block of memory might be a problem. |
+| retryOnFailures(ClientFaultCause ...causes) | - `causes` - array of causes that causes retry | Set if client should retry on certain faults. This option is useful to avoid some infrequent problems like staled connection. | 


it's unclear how causes looks like. can we add a link to an example?

mshustov · 2024-11-02T10:30:59Z

docs/en/integrations/language-clients/java/client-v2.md

+|---------------------------------------|:-----------------------------------------------|:--------------------------------------------|
+| addEndpoint(String endpoint)          | - `enpoint` - URL formatted a server address.      | Adds a server endpoint to list of available servers. Currently only one endpoint is supported. |
+| addEndpoint(Protocol protocol, String host, int port, boolean secure) | - `protocol` - connection protocol `com.clickhouse.client.api.enums.Protocol#HTTP`.<br />- `host` - IP or hostname of a server.<br />- `secure` - if communication should use secure version of the protocol (HTTPs) | Adds a server endpoint to list of available servers. Currently only one endpoint is supported. |
+| setOption(String key, String value)   | - `key` - String key of an option.<br /> - `value` - String value of an option | Sets raw value of client options. Useful when reading configuration from properties files. It helps to avoid calling corresponding builder methods. | 


How about

key - String key of a client configuration option.

should add a link to the list of client configuration options?

Sounds good, but we do not have such list yet. Will work on it in 0.7.2 release.

Paultagoras · 2024-11-04T19:51:27Z

docs/en/integrations/language-clients/java/client-v2.md

+
+Authentication is configured per client at the initialization phase. There are three authentication methods supported: by password, by access token, by SSL Client Certificate. 
+
+Authentication by a password requires to `setUsername()` and `setPassword()`: 


"requires calls to" or "requires using"

Paultagoras · 2024-11-04T19:51:43Z

docs/en/integrations/language-clients/java/client-v2.md

+        .build();
+```
+
+Authentication by an access token requires to `setAccessToken()`:


Same idea here too

Paultagoras · 2024-11-04T19:51:51Z

docs/en/integrations/language-clients/java/client-v2.md

+        .build();
+```
+
+Authentication by a SSL Client Certificate require to `setUsername()`, enable SSL Authentication `useSSLAuthentication`, `setClientCertificate()` and `setClientKey`: 


Paultagoras · 2024-11-04T19:55:46Z

docs/en/integrations/language-clients/java/index.md

@@ -116,4 +116,7 @@ JDBC Drive inherits same features as underlying client implementation. Other JDB
 - All projects in this repo are tested with all [active LTS versions](https://github.com/ClickHouse/ClickHouse/pulls?q=is%3Aopen+is%3Apr+label%3Arelease) of ClickHouse.
 - [Support policy](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md#security-change-log-and-support)
 - We recommend to upgrade client continuously to not miss security fixes and new improvements
- If you have an issue with migration to v2 API - [create and issue](https://github.com/ClickHouse/clickhouse-java/issues/new?assignees=&labels=v2-feedback&projects=&template=v2-feedback.md&title=) and we will respond! 
+- If you have an issue with migration to v2 API - [create and issue](https://github.com/ClickHouse/clickhouse-java/issues/new?assignees=&labels=v2-feedback&projects=&template=v2-feedback.md&title=) and we will respond!


"create an issue"

Added client configuration docs and SSL authentication docs for Clien…

32d8ab9

…t V2

chernser mentioned this pull request Oct 16, 2024

[client-v2] SSL Authentication ClickHouse/clickhouse-java#1865

Merged

3 tasks

vercel bot deployed to Preview October 16, 2024 19:14 View deployment

chernser added 2 commits November 1, 2024 14:21

added new configuration parameters in client-v2

fb04d83

Merge branch 'main' into java_client_docs_update

29a7deb

chernser closed this Nov 1, 2024

chernser reopened this Nov 1, 2024

chernser marked this pull request as ready for review November 1, 2024 21:23

chernser requested a review from a team as a code owner November 1, 2024 21:23

chernser requested review from mzitnik and removed request for a team November 1, 2024 21:23

vercel bot deployed to Preview November 1, 2024 21:40 View deployment

mshustov reviewed Nov 2, 2024

View reviewed changes

mshustov approved these changes Nov 2, 2024

View reviewed changes

chernser mentioned this pull request Nov 4, 2024

[client-v2] Remove dependencies on old projects ClickHouse/clickhouse-java#1899

Open

chernser added 2 commits November 4, 2024 11:25

updated wording for some configuration methods

d9a1a95

Merge branch 'main' into java_client_docs_update

87d68f4

vercel bot deployed to Preview November 4, 2024 19:33 View deployment

updated wording for some configuration methods

a2d0fbc

vercel bot deployed to Preview November 4, 2024 19:40 View deployment

Paultagoras reviewed Nov 4, 2024

View reviewed changes

fixed a few comments

0839073

vercel bot deployed to Preview November 5, 2024 05:43 View deployment

chernser merged commit 9c1dcbf into main Nov 5, 2024
4 checks passed

chernser deleted the java_client_docs_update branch November 5, 2024 06:01

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs-java-client] Client V2 Configuration Docs #2707

[docs-java-client] Client V2 Configuration Docs #2707

chernser commented Oct 16, 2024

mshustov Nov 2, 2024

mshustov Nov 2, 2024

mshustov Nov 2, 2024

chernser Nov 4, 2024

Paultagoras Nov 4, 2024

Paultagoras Nov 4, 2024

Paultagoras Nov 4, 2024

Paultagoras Nov 4, 2024


		Authentication is configured per client at the initialization phase. There are three authentication methods supported: by password, by access token, by SSL Client Certificate.

		Authentication by a password requires to `setUsername()` and `setPassword()`:

[docs-java-client] Client V2 Configuration Docs #2707

[docs-java-client] Client V2 Configuration Docs #2707

Conversation

chernser commented Oct 16, 2024

Summary

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment