Java Thin Client documentation page for 5.5.0 added #1240

sergey-serdyukov · 2024-08-02T14:30:46Z

Based on https://github.com/hazelcast/hz-docs/blob/main/docs/modules/clients/pages/java.adoc

netlify · 2024-08-02T14:31:03Z

✅ Deploy Preview for hardcore-allen-f5257d ready!

Name	Link
🔨 Latest commit	`58740ba`
🔍 Latest deploy log	https://app.netlify.com/sites/hardcore-allen-f5257d/deploys/66e7e050422d0d0008076f5d
😎 Deploy Preview	https://deploy-preview-1240--hardcore-allen-f5257d.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

docs/modules/clients/pages/java-thin-client.adoc

srknzl · 2024-08-22T14:25:19Z

Why is the preview not working? Can we restart it?

ollyhowell · 2024-08-23T09:00:40Z

Why is the preview not working? Can we restart it?

Try https://deploy-preview-1240--hardcore-allen-f5257d.netlify.app/hazelcast/5.5/clients/java-thin-client

There's a current known issue that the preview is generated but it doesn't link correctly. I think I know where the cause is but we have a bundle of build errors and warnings right now that need a proper audit and tidy up - it's planned but that's the workaround right now.

docs/modules/clients/pages/java-thin-client.adoc

srknzl

I can say that your new file is based on https://github.com/hazelcast/hz-docs/blob/main/docs/modules/clients/pages/java.adoc but there're a lot of changed words etc. Do you take master branch as reference ? If you copy any text from somewhere, can you add it to the description including the branch/version of it so that we will save time reviewing the PR. ty

In general, can you describe how you write the document? I'll not focus on grammar stuff much (doc team does that) but I need to know what's new that you've written and what's already copied from our documentation

I can already see that you deleted the non-applicable sections for thin-client from the original version

srknzl · 2024-08-23T13:20:39Z

docs/modules/clients/pages/java-thin-client.adoc

+NOTE: If you have a Hazelcast {enterprise-product-name} license, you do not need to set the license key in your clients to use the xref:getting-started:editions.adoc#features-in-hazelcast-enterprise[{enterprise-product-name} features]. It is sufficient to set the license on the member side, and include the `hazelcast-enterprise-java-client-{full-version}.jar` dependency in your classpath.
+
+If using Maven, add the `hazelcast` dependency
+to your `pom.xml`, or to the `hazelcast-enterprise` dependency if you want the client to use {enterprise-product-name} features, and you have the Hazelcast {enterprise-product-name} license),


Suggested change

to your `pom.xml`, or to the `hazelcast-enterprise` dependency if you want the client to use {enterprise-product-name} features, and you have the Hazelcast {enterprise-product-name} license),

to your `pom.xml`, or the `hazelcast-enterprise` dependency if you want the client to use {enterprise-product-name} features, and you have the Hazelcast {enterprise-product-name} license),

Indded we initially started from java.adoc and removed all the sections irrelevant to the thin client (and also changed the structure of the document). Since then both sides has been changed. In the java.adoc it was both functional changes (e.g. Cluster Routing Modes) and stylistic (words, punctuation etc). On the thin client side we've implemented a lot of stuff missing in the very first version and so in the java-thin-client.adoc we added back respective sections. But we haven't compared the two documents side-by-side and transfer all the stylistic changes. We suggest that we don't do it right now and release the 5.5b with what we currently have. After the release we will either establish some process of continuously merging the changes from java.adoc (and maintaining two nearly identical versions of the doc) or do something more clever -- we can discuss it then. What do you think?

ok, sounds good. lets create a jira for this

srknzl · 2024-08-23T13:29:01Z

docs/modules/clients/pages/java-thin-client.adoc

+If you use a <<client-network,discovery mechanism>> to find the initial member for the connection instead of an address list,
+you can use the same property to configure whether the initial member connection uses the private or public address.
+
+For an example of this scenario, refer to
+link:https://docs.hazelcast.com/tutorials/hazelcast-platform-operator-expose-externally[Connect to Hazelcast from Outside Kubernetes, window=_blank] in the Operator documentation.


you can use the same property to

these two paragprahs are about a property that enables configuring client to use public or private ip to connect to members.

the property is not mentioned before these paragraphs, so which property? These paragraphs should be removed or the property should be mentioned before them.

Section "Handling Client Connection Failure" updated from java.adoc

Thin Client does not support routing modes as I know, it's better to modify the copied text, or revert the change and add the public ip property(this is preferred, or remove 2 paragraphs

Does thin client not support routing modes?

docs/modules/clients/pages/java-thin-client.adoc

srknzl · 2024-08-24T10:38:37Z

docs/modules/clients/pages/java-thin-client.adoc

+<<setting-connection-timeout, Setting Connection Timeout section>>.
+
+[[blue-green-deployment-and-disaster-recovery]]
+== Blue-Green Deployment


Why is "Ordering of Clusters When Clients Try to Connect" section missing from thin client? See https://github.com/hazelcast/hz-docs/blob/main/docs/modules/clients/pages/java.adoc

Should this section be added back in then?

Yes, I don't see the reason of excluding this section. The feature might be missing in the thin client (in this case it's fine to exclude) or it can be forgotten (or the source page was old compared to main branch)

Alexey will look at this section soon

Added the section (allow some time to address other changes and commit the changes)

srknzl · 2024-08-24T10:42:59Z

I finished my review by comparing the new doc to https://github.com/hazelcast/hz-docs/blob/main/docs/modules/clients/pages/java.adoc (with the version in the same branch (PR branch))

srknzl · 2024-09-03T09:25:49Z

docs/modules/clients/pages/java-thin-client.adoc

+If using the `MULTI_MEMBER` cluster routing mode, and the cluster has multiple partition groups defined 
+and the client connection to a partition group fails, connectivity is maintained by failing over to an alternative partition group.
+If the connection is lost, which occurs only if all members of the partition group become unavailable, there is no attempt to retry the connection before failing over to another partition group.
+For further information on client cluster routing modes, see <<client-cluster-routing-modes,Client Cluster Routing Modes>>.


Does the thin client support cluster routing modes? like MULTI_MEMBER etc?

It does but in the newest version. In the verion 5.5 (the one which this doc relates to) it didn't. I have reverted the change and removed the mention of that property. Hope this is OK for now since once this is merged we will submit another PR for the newest version -- in which mentioning MULTI_MEMBER and other cluster routing modes will be valid

This reverts commit 03b6304.

…on Failure section

srknzl · 2024-09-11T09:47:32Z

There're broken links it seems. https://github.com/hazelcast/hz-docs/actions/runs/10681051704/job/29603869724?pr=1240

srknzl · 2024-09-11T11:18:08Z

docs/modules/clients/pages/java-thin-client.adoc

@@ -0,0 +1,1118 @@
+= {java-standard-client-name}


It's a "standalone" client, not standard

I've created new variables and I'm using these, will highlight when new PR is up

ihsandemir · 2024-09-11T10:23:38Z

docs/modules/clients/pages/java-thin-client.adoc

@@ -0,0 +1,1118 @@
+= {java-standard-client-name}


please remove thin from file names as well.

Also done in my branch

ihsandemir · 2024-09-11T10:27:16Z

docs/modules/clients/pages/java-thin-client.adoc

@@ -0,0 +1,1118 @@
+= {java-standard-client-name}
+:url-cloud-signup: https://cloud.hazelcast.com/sign-up


missing

:page-api-reference: https://docs.hazelcast.org/docs/{page-latest-supported-java-client}/javadoc

but this should change to this new client javadoc.

Dependent on API discussions but I have two variables in my branch so we can track compatibility and API links separately if needed.

docs/modules/clients/pages/java-thin-client.adoc

ihsandemir · 2024-09-11T15:04:45Z

docs/modules/clients/pages/java-thin-client.adoc

+to your `pom.xml`, or to the `hazelcast-enterprise` dependency if you want the client to use {enterprise-product-name} features, and you have the Hazelcast {enterprise-product-name} license,
+which might have been done when starting using Hazelcast.
+
+The `pom.xml` file is updated as follows:


This is for os artifact, can you also add the EE jar maven usage example. It can be in tabs.

Done in my local branch

ihsandemir · 2024-09-11T15:06:55Z

docs/modules/clients/pages/java-thin-client.adoc

+    <version>{full-version}</version>
+</dependency>
+----
+The {java-standard-client-name} is mostly compatible with the Embed client. However, one notable difference is that methods which threw `UnsupportedOperationException` in the Embed client are not present at all in the {java-standard-client-name}. For example, the following methods from `ClientMapProxy`:


Why is this different? Is there a decision log for this? We want 1:1 same with platform client including the exceptions we throw.

As currently implemented: it is because the embed client shares some common code with the members and it stubs some methods via throwing exceptions in cases when the user decides to call impropriate method on the client side.
In the Standard/Thin client the "member" code was eliminated.

Let's discuss this item with the developers outside the PR's conversation.

ihsandemir · 2024-09-11T15:08:13Z

docs/modules/clients/pages/java-thin-client.adoc

+NOTE: Currently, using both the {java-standard-client-name} and the Member code (including the Embed client) on the same JVM is not supported.
+It will be supported in the future versions.
+
+


missing this from java.adoc:

You can find Hazelcast Java client's code samples https://github.com/hazelcast/hazelcast-code-samples/tree/master/clients[here^].

Can you please take a diff and update you PR?

I think this was taken out deliberately but this is superseded by latest discussions and plans.

ihsandemir · 2024-09-11T15:09:27Z

docs/modules/clients/pages/java-thin-client.adoc

+
+The client API is your gateway to access your Hazelcast cluster, including distributed objects and data pipelines (jobs).
+
+First, you must configure your client. Currently, the {java-standard-client-name} supports only programmatic configuration, as follows:


The java.adoc refers to a section, can you update this?

# Conflicts: # docs/modules/clients/pages/java-thin-client.adoc

Co-authored-by: ihsan demir <[email protected]>

oliverhowell · 2024-09-16T08:29:45Z

See #1289 for fresh PR with latest changes

oliverhowell · 2024-09-16T16:14:53Z

docs/modules/clients/pages/java-thin-client.adoc

+```java
+Properties properties = new Properties();
+properties.setProperty("protocol", "TLSv1.2");
+properties.setProperty("trustCertCollectionFile", "/path/server.crt");
+
+SSLConfig sslConfig = new SSLConfig().setEnabled(true)
+                                     .setProperties(properties);
+sslConfig.setFactoryClassName(BasicSSLContextFactory.class.getName())
+         .setFactoryImplementation(new BasicSSLContextFactory());
+ClientConfig clientConfig = new ClientConfig();
+clientConfig.getNetworkConfig().setSSLConfig(sslConfig);
+```
+Please note that the paths in the properties here are *absolute paths* to the resources in classpath.
+
+To enable mutual authentication on the client, add to the properties:
+```java
+properties.setProperty("keyFile", "/path/client.pem");
+properties.setProperty("keyCertChainFile", "/path/client.crt");
+```
+To use the OpenSSL engine instead of the Basic SSL context,
+replace the SSL context factory class name and implementation as follows:
+```java
+sslConfig.setFactoryClassName(OpenSSLEngineFactory.class.getName())
+        .setFactoryImplementation(new OpenSSLEngineFactory());
+```


Is this code sample from the original Cloud section (now removed)?

oliverhowell · 2024-09-30T10:54:36Z

Closing this PR as we have the replacement PR linked above...

Java Thin Client documentation page for 5.5.0 added

89294bc

sergey-serdyukov requested a review from oliverhowell as a code owner August 2, 2024 14:30

sergey-serdyukov added 2 commits August 19, 2024 13:00

Replace the TJC client name with a variable (v5.5.0)

064a88c

Migrating from Embed client guide (v5.5.0)

c5b4df3

oliverhowell reviewed Aug 21, 2024

View reviewed changes

docs/modules/clients/pages/java-thin-client.adoc Outdated Show resolved Hide resolved

oliverhowell reviewed Aug 21, 2024

View reviewed changes

docs/modules/clients/pages/java-thin-client.adoc Outdated Show resolved Hide resolved

oliverhowell reviewed Aug 21, 2024

View reviewed changes

docs/modules/clients/pages/java-thin-client.adoc Outdated Show resolved Hide resolved

oliverhowell self-requested a review August 22, 2024 09:17

jerrinot reviewed Aug 23, 2024

View reviewed changes

docs/modules/clients/pages/java-thin-client.adoc Outdated Show resolved Hide resolved

srknzl reviewed Aug 24, 2024

View reviewed changes

docs/modules/clients/pages/java-thin-client.adoc Outdated Show resolved Hide resolved

srknzl reviewed Aug 24, 2024

View reviewed changes

sergey-serdyukov and others added 5 commits September 2, 2024 14:39

Standard client name var moved to antora.yml, other minor fixes

f2b1c03

Resolve conflict

6062433

Resolve conflict

f7e687e

section added Ordering of Clusters When Clients Try to Connect

151a9fd

section updated Handling Client Connection Failure

03b6304

srknzl reviewed Sep 3, 2024

View reviewed changes

alexey-agapov-hazelcast added 2 commits September 3, 2024 12:16

Revert "section updated Handling Client Connection Failure"

f40be4e

This reverts commit 03b6304.

Removed mentioning of discovery mechanism in Handling Client Connecti…

2a2ce0d

…on Failure section

srknzl approved these changes Sep 3, 2024

View reviewed changes

srknzl reviewed Sep 11, 2024

View reviewed changes

ihsandemir requested changes Sep 11, 2024

View reviewed changes

alexey-agapov-hazelcast added 2 commits September 12, 2024 13:43

Merge branch 'v/5.5-b-plus' into v/5.5

3fc1de3

# Conflicts: # docs/modules/clients/pages/java-thin-client.adoc

Renamed the {client-name} variable post-merge

72886eb

alexey-agapov-hazelcast and others added 4 commits September 12, 2024 13:52

Update docs/modules/clients/pages/java-thin-client.adoc

0e89bf4

Co-authored-by: ihsan demir <[email protected]>

Update docs/modules/clients/pages/java-thin-client.adoc

ef9e49f

Co-authored-by: ihsan demir <[email protected]>

Update docs/modules/clients/pages/java-thin-client.adoc

2046cfa

Co-authored-by: ihsan demir <[email protected]>

Configuring near cache section added

58740ba

oliverhowell mentioned this pull request Sep 16, 2024

Java clients v2 #1289

Merged

oliverhowell reviewed Sep 16, 2024

View reviewed changes

oliverhowell closed this Sep 30, 2024

	to your `pom.xml`, or to the `hazelcast-enterprise` dependency if you want the client to use {enterprise-product-name} features, and you have the Hazelcast {enterprise-product-name} license),
	to your `pom.xml`, or the `hazelcast-enterprise` dependency if you want the client to use {enterprise-product-name} features, and you have the Hazelcast {enterprise-product-name} license),

		@@ -0,0 +1,1118 @@
		= {java-standard-client-name}
		:url-cloud-signup: https://cloud.hazelcast.com/sign-up

		NOTE: Currently, using both the {java-standard-client-name} and the Member code (including the Embed client) on the same JVM is not supported.
		It will be supported in the future versions.


		The client API is your gateway to access your Hazelcast cluster, including distributed objects and data pipelines (jobs).

		First, you must configure your client. Currently, the {java-standard-client-name} supports only programmatic configuration, as follows:

Java Thin Client documentation page for 5.5.0 added #1240

Java Thin Client documentation page for 5.5.0 added #1240

Conversation

sergey-serdyukov commented Aug 2, 2024 • edited by srknzl Loading

netlify bot commented Aug 2, 2024 • edited Loading

✅ Deploy Preview for hardcore-allen-f5257d ready!

srknzl commented Aug 22, 2024

ollyhowell commented Aug 23, 2024

srknzl left a comment • edited Loading

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

srknzl Sep 3, 2024 • edited Loading

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

srknzl Sep 2, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

srknzl commented Aug 24, 2024 • edited Loading

Choose a reason for hiding this comment

alexey-agapov-hazelcast Sep 3, 2024 • edited Loading

Choose a reason for hiding this comment

srknzl commented Sep 11, 2024 • edited Loading

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

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

oliverhowell commented Sep 16, 2024

Choose a reason for hiding this comment

oliverhowell commented Sep 30, 2024

sergey-serdyukov commented Aug 2, 2024 •

edited by srknzl

Loading

netlify bot commented Aug 2, 2024 •

edited

Loading

srknzl left a comment •

edited

Loading

srknzl Sep 3, 2024 •

edited

Loading

srknzl Sep 2, 2024 •

edited

Loading

srknzl commented Aug 24, 2024 •

edited

Loading

alexey-agapov-hazelcast Sep 3, 2024 •

edited

Loading

srknzl commented Sep 11, 2024 •

edited

Loading