Clarify UCN object refresh [v/5.5] (#1581)

github-actions[bot] · TomaszGaweda · web-flow · commit 2a6c3d0d3e52 · 2025-02-26T16:35:07.000Z
Backport of #1574 Classes' bytecode will be refreshed, but old instances will use old bytecode. Co-authored-by: Tomasz Gawęda <tomasz.gaweda@outlook.com>
diff --git a/docs/modules/clusters/pages/ucn-dynamic-client.adoc b/docs/modules/clusters/pages/ucn-dynamic-client.adoc
@@ -61,6 +61,8 @@ You must create a _Client.java_ file containing the required code and save it to
 
 NOTE: Ensure that you have configured your data structure (an `IMap` in this example) on the member side with the same {ucn} referenced in your client configuration.
 
+include::partial$ucn-obj-refresh-caution.adoc[]
+
 The file will be similar to the following:
 
 [source,java]
diff --git a/docs/modules/clusters/pages/ucn-dynamic-config.adoc b/docs/modules/clusters/pages/ucn-dynamic-config.adoc
@@ -9,6 +9,8 @@ For example, you can use the dynamic configuration API to add or replace a speci
 
 NOTE: Before you can use {ucn}, you must enable it as described in the xref:clusters:ucn-enable.adoc[] topic.
 
+include::partial$ucn-obj-refresh-caution.adoc[]
+
 You must create a _Client.java_ file containing the required code and save it to your class configuration folder. 
 The file will be similar to the following:
 [source,java]
diff --git a/docs/modules/clusters/partials/ucn-obj-refresh-caution.adoc b/docs/modules/clusters/partials/ucn-obj-refresh-caution.adoc
@@ -0,0 +1,3 @@
+CAUTION: {ucn} can replace resources dynamically, but this does not affect the lifecycle of existing instances using older class versions.
+This means that the creation of new objects will use new resources (latest bytecode), but existing objects won't be removed and recreated automatically. In this case, manual intervention is needed, such as destroying and recreating the relevant objects, or restarting Hazelcast members.
+This is particularly applicable to long-lived objects tied to the lifecycle of Hazelcast data structures, such as a `MapLoader`: deploying a new version won't replace an existing `MapLoader`, and to refresh such an object, a cluster restart is required.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+CAUTION: {ucn} can replace resources dynamically, but this does not affect the lifecycle of existing instances using older class versions.`
	`2`	`+This means that the creation of new objects will use new resources (latest bytecode), but existing objects won't be removed and recreated automatically. In this case, manual intervention is needed, such as destroying and recreating the relevant objects, or restarting Hazelcast members.`
	`3`	+This is particularly applicable to long-lived objects tied to the lifecycle of Hazelcast data structures, such as a `MapLoader`: deploying a new version won't replace an existing `MapLoader`, and to refresh such an object, a cluster restart is required.