Document breaking changes and address user's feedback (#2106)

Co-authored-by: Rob Swain <rob.swain@hazelcast.com>

Author: TomaszGaweda

docs/modules/spring/pages/hazelcast-spring-session.adoc

@@ -51,13 +51,13 @@ dependencies {
 
 TIP: Hazelcast Spring Session uses the same major version number as Spring Boot it was created for. For Spring Boot 4.x, the compatible Hazelcast Spring Session will be always 4.x.
 
-=== Migrate from Spring Session Hazelcast 3.x
+== Migrate from Spring Session Hazelcast 3.x
 
 From version 4.0, the Hazelcast integration with Spring Session is owned by the Hazelcast team.
 
 To migrate your application from using Spring Session Hazelcast 3.x to the new Hazelcast Spring Session 4.x:
 
-. Change the GroupId to `com.hazelcast` and artifactId to `hazelcast-spring-session`.
+. Change the GroupId to `com.hazelcast.spring` and artifactId to `hazelcast-spring-session`.
 . Update your code and change the packages. All Hazelcast-specific classes were moved from `org.springframework.session.hazelcast` to `com.hazelcast.spring.session`.
 . Remove this configuration for `PrincipalNameExtractor`:
 +
@@ -74,17 +74,33 @@ config.getMapConfig(SESSIONS_MAP_NAME)
 [source,java]
 ----
 SerializerConfig serializerConfig = new SerializerConfig();
-    serializerConfig.setImplementation(new HazelcastSessionSerializer()).setTypeClass(MapSession.class);
-    config.getSerializationConfig().addSerializerConfig(serializerConfig);
+serializerConfig.setImplementation(new HazelcastSessionSerializer()).setTypeClass(MapSession.class);
+config.getSerializationConfig().addSerializerConfig(serializerConfig);
 ----
 With a call:
 +
 [source,java]
 ----
 config = HazelcastSessionConfiguration.applySerializationConfig(config);
 ----
-. Index configuration for `PRINCIPAL_ATTRIBUTE_NAME` **if** no other IMap customization is wanted.
-
++
+Note that this call should be made before instance creation (before the call to `Hazelcast.newHazelcastInstance`).
+. Remove index configuration for `PRINCIPAL_ATTRIBUTE_NAME` **if** no other IMap customization is wanted; it will be configured automatically. If you want to further customize the session IMap, you can either:
+- create `MapConfig` manually and then create an index of type `HASH` on the `principalName` attribute.
+- create a bean of type `SessionMapCustomizer` to apply your customizations on predefined `MapConfig`.
+
+=== List of breaking changes
+
+Spring Session 4.0.0 is a major release. It contains the following breaking changes:
+
+- Group ID and artifact ID are changed to `com.hazelcast.spring` / `hazelcast-spring-session`.
+- The main package name is changed from `org.springframework.session.hazelcast` to `com.hazelcast.spring.session`.
+- Serialization is reworked. It no longer uses an optional `HazelcastSessionSerializer`, but relies on Compact Serialization with two new serializers: `com.hazelcast.spring.session.AttributeValueCompactSerializer` and `com.hazelcast.spring.session.HazelcastSessionCompactSerializer`. Additionally, a `SessionUpdateEntryProcessor` serializer will be configured automatically on server nodes if a JAR is deployed on server nodes.
+- The binary representation of the data is changed. Instead of using Spring's `MapSession`, it uses `com.hazelcast.spring.session.BackingMapSession` with attributes stored as `com.hazelcast.spring.session.AttributeValue`. This change enables true client-server deployments without the need for any custom code deployment on server nodes for classes used as session attributes.
+- Method `void setDefaultMaxInactiveInterval(Integer defaultMaxInactiveInterval)` in `HazelcastIndexedSessionRepository` is removed. Use an alternative with `Duration` as a parameter.
+- Most of the setter methods in `HazelcastIndexedSessionRepository` now return `HazelcastIndexedSessionRepository` (`this`) for fluent API.
+- The default logging framework is changed to SLF4J; the default annotations library is now JSpecify.
+- Spring Session now fully supports Java Modules.
 
 == Supported topologies
 

docs/modules/spring/pages/spring-session-3.5.2.zip

@@ -101,11 +101,12 @@ This section describes how to work with the Hazelcast Spring Security sample app
 
 === Running the sample application
 
-You can run the sample by obtaining the link:https://docs.hazelcast.com/hazelcast/latest/spring/spring-session-3.5.2.zip[source code] and invoking the following command:
+You can run the sample by obtaining the link:https://github.com/hazelcast/hazelcast-code-samples/tree/master/spring/spring-session-servlet[source code] and invoking the following command:
 
 [source,shell]
 ----
-$ ./gradlew :spring-session-sample-javaconfig-hazelcast:tomcatRun
+$ cd spring/spring-session-servlet
+$ mvn jetty:run
 ----
 
 NOTE: By default, Hazelcast runs in embedded mode with your application.