JCache session persistence

[lauracowen]

Based on:
https://openliberty.io/blog/2018/03/22/distributed-in-memory-session-caching.html

[aguibert]

review comments for @ManasiGandhi

• "Sessions" is sort of an ambiguous term. Lets change the first sentence from "Caching sessions in your applications" to "Caching HTTP sessions in your applications"
• when referring to the feature, should we be saying "the sessionCache-1.0 feature" instead of "the sessionCache feature"?
• Instead of saying "Also, a relational database might not be always available." lets phrase it as "Also, a relational database might not be part of your application architecture.".
• when we first mention JCache, we can link to this page if users want to read more about JCache: https://hazelcast.com/glossary/jcache-java-cache/
• Wording change "since Liberty handles the session caching in its HttpSession implementation" --> "since Liberty handles the session caching in the web container layer"
• Wording change "If your application is already using HttpSession caching" --> "If your application is already using HttpSessions, it"
• I suggest removing this sentence, because Hazelcast is valid for development or production env "For development purposes, you can use the Hazelcast open source implementation or any other implementation that complies with the JCache specification."
• Several of the code blocks have a stray ---- in them, which I think is an asciidoc marker that is supposed to mark the start/end of a code block
• The annotation @WebServlet("/ExampleServlet") has extra indentation in front of it
• In the "Joining multiple servers together" section, this block of text is already used earlier in the article. I suggest just removing it:

You can store sessions locally on a server, on a relational database, or in-memory of your application. However a cached session on the server can be lost if the application instance fails. Also, a relational database might not be always available.

The sessionCache feature in Open Liberty provides distributed in-memory HttpSession caching. The sessionCache feature builds on top of an existing technology called JCache (JSR 107) that offers a standardized distributed in-memory caching API. Though the feature builds on top of JCache, no direct usage of JCache API is necessary in your application, since Liberty handles the session caching in its HttpSession implementation. If your application is already using HttpSession caching, it can benefit from the sessionCache feature without making any code changes.

Will post second half of comments later. I noticed several sections in the page were duplicated, so I've asked Manasi to fix it and then get back to me when the duplication issues are fixed.

[ManasiGandhi]

@aguibert I worked on the updates. Here is the link https://draft-openlibertyio.mybluemix.net/docs/20.0.0.12/distributed-session-caching.html. Let me know if the changes look good.

[aguibert]

@ManasiGandhi thanks, changes look good now

[lauracowen]

Thanks. Comments below:

• Intro

  • Nice intro in general.
  • Is the JSR number really necessary? The page linked to that gives an intro to JCache already mentions that it's a JSR standard.
  • Can we give a quick definition of what is meant by "distributed caching" as opposed to non-distributed caching? A distinction is made later in the topic but it's not really clear why/when you'd use distributed caching.
  • Can we have the diagram from the blog post too? (with a succinct explanation of what it shows, plus an explanation of why you'd have two Liberty servers)
  • What are the benefits of using the sessionCache feature if you've already used HttpSessions - surely the easiest option would be to just stick with that and not start adding additional features into your config? Why would you bother? The "If your application is already using HttpSesssion..." sentence should probably be the start of a new paragraph that goes on to say why you should bother.

• All code snippets in this topic:

  • All the Java code examples are incorrectly marked up as XML so the syntax highlighting is incorrect.
  • All the examples are quite wide (esp the Java ones; XML ones maybe ok) and wrap oddly if the browser window isn't wide enough. Can you ask Andy to suggest where the longest lines should be broken and indented neatly?
  • Don't include the <server> and </server> root tags in server.xml config examples. It's unnecessary.

• "Configuring session caching" section

  • Don't include basic configuration in the topic. Instead, tell them to enable the sessionCache feature (point them to thesessionCache feature doc topic) and then to point them to the config in the sessionCache feature doc topic. This is simple enough that the user can cope with finding the config in the other topic.
  • This section's server.xml example is even more minimal than the one labelled "Minimum configuration..." in the sessionCache feature doc topic. Can you insert this simpler example into the Examples section of sessionCache feature doc topic under the heading of "Minimum configuration..." and then label the slightly less simple config that's already in the feature doc as as "Providing additional Hazelcast configuration" instead. So you end up with two examples in the feature doc topic.

• "Session caching" section

  • In fact, make the instruction about enabling the feature and doing the basic config from the "Configuring..." section, into the first part of this section (we don't need the separate "Configuring" section).
  • "If your application caches data" - should this be something more like "If your application already uses HttpSessionCaching to cache data" or at least say "already" - otherwise it's not obvious why you'd consider including the sessionCache feature (so who cares that no code changes are needed?).

• At the end of this section, give some hint that you need to then join at least two servers together to benefit from using the sessionCaching feature. Without that, it looks like the sections are optional alternatives when really we want the reader to move from one section to the next.

• "Joining multiple servers" section

  • The two Java examples need to each be preceded by a sentence saying what they are; eg "The following example shows the application running on Server A:". It's correct to remove the code comments from the code example but the information in those comments needs to be carried over from the blog post too.
  • I don't really see how an explanation of how you can configure Hazelcast follows on from the sentence "Each JCache implementation configures the cluster instances independently.". Should "For Hazelcast..." be the start of a new paragraph? Or even a new section about configuring a Hazelcast implementation?
  • "For Hazelcast, a simple configuration file might look like the following example, though you don’t need to specify any Hazelcast configuration file if you are happy with the default Hazelcast configuration:" - flip this round so that the simplest, most straightforward approach is mentioned first: "For Hazelcast, you don’t need to specify any additional Hazelcast configuration if you are happy with the default Hazelcast configuration. You can optionally create a Hazelcast configuration file, as shown in the following example, and add a reference to the Hazelcast configuration file in your server.xml:" and make "add a reference to the Hazelcast configuration file" a link to the exact section in the sessionCache feature doc topic that shows the config to do that.
  • Then remove the last example (which is a duplicate of what's in the feature doc topic).
  • Above or below the hazelcast.xml example, there needs to be an explanation of what the config does (which is described in the code comment in the blog post).

• Does there need to be some mention (maybe in the intro?) of what other caching implementations could be used instead of Hazelcast? Either a list of the open source options (with links to their project sites) or at least a statement saying that other implementations can be used? Or do we only want to mention Hazelcast because that's what we've tested with - the blog post implies others can be used.

• BTW, when we've published this doc topic, we will redirect the blog post to the doc topic.

[ManasiGandhi]

I worked on Laura's review for this issue. Waiting for the changes to show after the builds are resolved.

[ManasiGandhi]

@rw2513 Can you peer review this topic https://draft-openlibertyio.mybluemix.net/docs/21.0.0.2/distributed-session-caching.html

[Rwalls1]

Content review

Intro

-I think you still need to address Laura’s comment regarding further explanation for using the sessionCache feature when HTTPSessions is already in use. I agree that clarifying why would someone would use the sessionCache feature in this scenario would be helpful.
-Laura also mentions adding the diagram from the blog. I agree that the diagram would be helpful, particularly to highlight how the sessionCache feature works after it’s enabled in the application. While you provide different examples of how to configure the feature later in the topic, I think it would it be valuable to illustrate how the feature actually by including and explaining the diagram from the blog. I think you should speak with Andy McCright about who could help to explain the diagram if there isn’t enough info in the blog and also how to get a copy of the diagram.

Configure session caching

• Make sure to review Laura’s feedback as she indicated that this section should be removed and its info should be rewritten and moved to the “Session caching in your application” section
• For the sentence "The sessionCache feature does not include a JCache implementation, so you need to pick one and reference it as a library in your server.xml file.”, I think you should also describe how the library is referenced in the example to provide additional context to users.
• Also, based on Laura’s feedback, I think she wanted this example included in the sessionCache feature doc topic so make sure to review her most recent feedback again.

Session caching in your application

• You should review Laura’s feedback for this section as well as there seems to be some feedback that wasn’t addressed

Joining multiple servers

• Review Laura’s feedback for this section as I don’t see the changes

[ManasiGandhi]

@Rwalls1 I worked on your review. Here is the link to the draft https://draft-openlibertyio.mybluemix.net/docs/21.0.0.4/distributed-session-caching.html

• I think you still need to address Laura’s comment regarding further explanation for using the sessionCache feature when HTTPSessions is already in use. I agree that clarifying why would someone would use the sessionCache feature in this scenario would be helpful.
• Laura also mentions adding the diagram from the blog. I agree that the diagram would be helpful, particularly to highlight how the sessionCache feature works after it’s enabled in the application. While you provide different examples of how to configure the feature later in the topic, I think it would it be valuable to illustrate how the feature actually by including and explaining the diagram from the blog. I think you should speak with Andy McCright about who could help to explain the diagram if there isn’t enough info in the blog and also how to get a copy of the diagram.
• Make sure to review Laura’s feedback as she indicated that this section should be removed and its info should be rewritten and moved to the “Session caching in your application” section.
• For the sentence "The sessionCache feature does not include a JCache implementation, so you need to pick one and reference it as a library in your server.xml file.”, I think you should also describe how the library is referenced in the example to provide additional context to users.
• Also, based on Laura’s feedback, I think she wanted this example included in the sessionCache feature doc topic so make sure to review her most recent feedback again.
• You should review Laura’s feedback for this section as well as there seems to be some feedback that wasn’t addressed.
• Review Laura’s feedback for this section as I don’t see the changes.

[Rwalls1]

Content review

@ManasiGandhi Thanks, I think you addressed all of Laura's feedback, I just have a few more comments:

Global

I think you should refer to the sessionCache feature as the JCache Session Persistence feature, as that is the actual name of the feature, and also to maintain consistency across topics.

Intro

• Typo: Change "with the distributed in-memory HttpSession caching” to “with distributed in-memory HttpSession caching”
• I think you should add a bit more explanation after the sentence, " With distributed caching, the server or database doesn’t need to store a cached session, as compared to non-distributed caching, which needs dedicated resources." I think maybe in a separate paragraph or additional sentence, you should explain why this is important or what benefits does distributed caching provide, such as improved performance and availability. This is mentioned in the short description, but I think expanding on the detail here would help to provide more context. This isn’t mentioned anywhere else in the topic so I think this approach would also add more value.
• I think the sentence, “The sessionCache feature in Open Liberty provides distributed in-memory HttpSession caching.” is too similar to the second sentence of your short description that also starts with, “The sessionCache feature”, and doesn’t add much value. I think the approach should be to expand on what’s mentioned in short description. So I think you could reword the start of this paragraph to say something like, “To provide distributed in-memory HttpSession caching, the JCache Session Persistence feature builds on an existing technology that is called JCache, which offers a standardized distributed in-memory caching API.
• To address a typo and avoid the use of “on top”, change “Though, the feature builds on top of JCache, no direct usage of JCache API” to “Though the feature builds on JCache, no direct usage of the JCache API”

Session caching in your application

I think the sentence, “The following example shows what the HTTP session caching might look like.” needs more context. It is not clear where the configuration in the example is happening. I think you should identify where this HTTP session caching is configured. Also, it is not clear what purpose the dbThing object that is referenced servers within the context of the example. Without further detail, the included example doesn’t add much value. I think you should either add that detail here or also add the example to the JCache Session Persistence feature page with more detail and link to it from this section.

Joining multiple servers together

• I think you should additional detail to the sentence, "The sessionCache feature is only useful when it is connected to at least one other server.” to give more context about what a “cluster” is, since it is referenced later in the section. So, I think you should change the sentence to something like, "The sessionCache feature is only useful when it is connected to at least one other server, which forms a cluster”.
• You should provide a link to the Hazelcast platform page on first reference to provide the necessary context.
• After, "those sessions are persisted” I think it would be helpful to add a phrase or sentence that briefly explains what persisted means. I know that it is a common term but since this is a conceptual topic I think including a bit more detail would add more value
• To be more concise, change “starts up” to “starts”
• Typo: Change, "Besides the open source Hazelcast implementations that you can also use other implementations” to "Besides the open source Hazelcast implementations, you can also use other implementations”
• When you mention Infinispan, I think it would be good to add a link to the new “Configuring Infinispan as a JCache provider” that is still being developed.
• Typo: Change “Open Liberty server” to "Open Liberty servers”. Also, I think you should add a colon instead of a period after the sentence that starts with this phrase to introduce the list that follows.
• I think the list that references the “Client-Server model” and “Peer-to-Peer” model should be unordered as there isn’t a defined order that applies to either. Also, see Description lists for a possible formatting method.
• I think you should change "The following code shows a simple example of how two Liberty servers might share information” to something like “The following example shows how two Open Liberty servers might share information” to be more concise by removing extra words.
• The config examples included in this section need more context. After the examples, I think you should include some details about how the servers share information by maybe explaining which aspects of the configurations enable that interaction.
• Typo: Change ‘myCluster’ to myCluster

[ManasiGandhi]

@Rwalls1 Thanks for your review. I worked on your comments. Here's a link to the updated draft https://draft-openlibertyio.mybluemix.net/docs/21.0.0.5/distributed-session-caching.html

Content review

@ManasiGandhi Thanks, I think you addressed all of Laura's feedback, I just have a few more comments:

Global

• I think you should refer to the sessionCache feature as the JCache Session Persistence feature, as that is the actual name of the feature, and also to maintain consistency across topics.

Intro

• Typo: Change "with the distributed in-memory HttpSession caching” to “with distributed in-memory HttpSession caching”

• I think you should add a bit more explanation after the sentence, " With distributed caching, the server or database doesn’t need to store a cached session, as compared to non-distributed caching, which needs dedicated resources." I think maybe in a separate paragraph or additional sentence, you should explain why this is important or what benefits does distributed caching provide, such as improved performance and availability. This is mentioned in the short description, but I think expanding on the detail here would help to provide more context. This isn’t mentioned anywhere else in the topic so I think this approach would also add more value.

• I think the sentence, “The sessionCache feature in Open Liberty provides distributed in-memory HttpSession caching.” is too similar to the second sentence of your short description that also starts with, “The sessionCache feature”, and doesn’t add much value. I think the approach should be to expand on what’s mentioned in short description. So I think you could reword the start of this paragraph to say something like, “To provide distributed in-memory HttpSession caching, the JCache Session Persistence feature builds on an existing technology that is called JCache, which offers a standardized distributed in-memory caching API.

• To address a typo and avoid the use of “on top”, change “Though, the feature builds on top of JCache, no direct usage of JCache API” to “Though the feature builds on JCache, no direct usage of the JCache API”- "on top" is not used here with reference to location on the webpage, so not an accessibility issue. Leaving as is.

Session caching in your application

• I think the sentence, “The following example shows what the HTTP session caching might look like.” needs more context. It is not clear where the configuration in the example is happening. I think you should identify where this HTTP session caching is configured. Also, it is not clear what purpose the dbThing object that is referenced servers within the context of the example. Without further detail, the included example doesn’t add much value. I think you should either add that detail here or also add the example to the JCache Session Persistence feature page with more detail and link to it from this section.

Joining multiple servers together

• I think you should additional detail to the sentence, "The sessionCache feature is only useful when it is connected to at least one other server.” to give more context about what a “cluster” is, since it is referenced later in the section. So, I think you should change the sentence to something like, "The sessionCache feature is only useful when it is connected to at least one other server, which forms a cluster”.

• You should provide a link to the Hazelcast platform page on first reference to provide the necessary context.

• After, "those sessions are persisted” I think it would be helpful to add a phrase or sentence that briefly explains what persisted means. I know that it is a common term but since this is a conceptual topic I think including a bit more detail would add more value. The relevant info is included in the second paragraph based on the info provided in the guide.

• To be more concise, change “starts up” to “starts”

• Typo: Change, "Besides the open source Hazelcast implementations that you can also use other implementations” to "Besides the open source Hazelcast implementations, you can also use other implementations”

• When you mention Infinispan, I think it would be good to add a link to the new “Configuring Infinispan as a JCache provider” that is still being developed.

• Typo: Change “Open Liberty server” to "Open Liberty servers”. Also, I think you should add a colon instead of a period after the sentence that starts with this phrase to introduce the list that follows.

• I think the list that references the “Client-Server model” and “Peer-to-Peer” model should be unordered as there isn’t a defined order that applies to either. Also, see Description lists for a possible formatting method.

• I think you should change "The following code shows a simple example of how two Liberty servers might share information” to something like “The following example shows how two Open Liberty servers might share information” to be more concise by removing extra words.

• The config examples included in this section need more context. After the examples, I think you should include some details about how the servers share information by maybe explaining which aspects of the configurations enable that interaction. I think the detailed explanations can be provided in the feature topic.

• Typo: Change ‘myCluster’ to myCluster

[Rwalls1]

@ManasiGandhi Thanks, I just have a few more comments:

Intro

While the use of the phrase of "on top" is not an accessibility issue in relation to referencing a location on the page , I still think the phrase doesn't add value without additional context and could potentially be confusing. The word "top" is also flagged by Acrolinx. I think to be more concise and avoid the use of an unnecessary extra word, I think should change each instance of, "on top" to "on".

Session caching in your application

I think the example provided in this section still needs a more detailed description to help understand how the configuration shows "how two Open Liberty servers might share information". Which elements in the configuration enable this information sharing? I think you should either provide more details in this section or include this example on the JCache Session Persistence feature page and include more details there.

Joining multiple servers together

• Typo: Change " it has access to sessions created by other servers." to "it has access to sessions that are created by other servers."
• I think you should change "Open Liberty servers can behave in two different ways in a cluster." to "Open Liberty servers in a cluster can behave in the following ways:" to more clearly introduce the two methods and avoid the use of the unnecessary word "different".
• I think you should change, "The following code shows a simple example of how two Liberty servers might share information"
  to something like "The following example shows how two Liberty servers might share information" to be more concise and avoid unnecessary words such as "simple".
• Typo: Change "Http" to "HTTP".
• I still think the config examples included in this section need more context. Without additional details, it is unclear how information is shared between the two servers. I think you should add more detail after the examples or provide a link to the feature page that provides more information. If you leave as is, I think the section might cause confusion.

[ManasiGandhi]

@Rwalls1 Thanks for reviewing. I worked on your suggestions. Here's a link to the draft https://docs-draft-openlibertyio.mybluemix.net/docs/21.0.0.5/distributed-session-caching.html

Intro

While the use of the phrase of "on top" is not an accessibility issue in relation to referencing a location on the page , I still think the phrase doesn't add value without additional context and could potentially be confusing. The word "top" is also flagged by Acrolinx. I think to be more concise and avoid the use of an unnecessary extra word, I think should change each instance of, "on top" to "on".

Session caching in your application

• I think the example provided in this section still needs a more detailed description to help understand how the configuration shows "how two Open Liberty servers might share information". Which elements in the configuration enable this information sharing? I think you should either provide more details in this section or include this example on the JCache Session Persistence feature page and include more details there.I added a link to the configuration from the JCache config example per suggestion from Allan Zhang.

Joining multiple servers together

• Typo: Change " it has access to sessions created by other servers." to "it has access to sessions that are created by other servers."
• I think you should change "Open Liberty servers can behave in two different ways in a cluster." to "Open Liberty servers in a cluster can behave in the following ways:" to more clearly introduce the two methods and avoid the use of the unnecessary word "different".
• I think you should change, "The following code shows a simple example of how two Liberty servers might share information"
  to something like "The following example shows how two Liberty servers might share information" to be more concise and avoid unnecessary words such as "simple".
• Typo: Change "Http" to "HTTP".
• I still think the config examples included in this section need more context. Without additional details, it is unclear how information is shared between the two servers. I think you should add more detail after the examples or provide a link to the feature page that provides more information. If you leave as is, I think the section might cause confusion. I've added link for reference to the Hazelcast configuration file

[dmuelle]

Peer review

Topic looks good- I have a few suggestions for clarity and to restore some details that were lost from the original blog post.

Intro

• Caching HTTP sessions in your applications helps to improve performance and availability for the users.
  I'd revise this to make reference to "high availability", which is a good SEO term for this topic. ANdy also mentioned shopping carts in his intro, which is a good concrete example to orient the reader. Maybe something like:
  Caching HTTP sessions in your applications helps provide high availability for users and enables functions such as shopping cart retrieval in e-commerce applications.

• You can store sessions--->You can store HTTP sessions (throughout the doc need to refer consistently to HTTP sessions, where appropriate)>

• With distributed caching, the server or database doesn’t need to store a cached session, as compared to non-distributed caching, which needs dedicated resources, thus providing failover and improved performance.
  This seems a little vague and convoluted. Maybe:
  With distributed caching, you don't need a single dedicated server or database to store a cached HTTP session. HTTP session cache data is distributed across multiple servers that act as a cluster.

• Though the feature builds on JCache, no direct usage of JCache API is necessary in your application, because Open Liberty handles the session caching in the web container layer.
  --->
  Though the feature builds on JCache, your application doesn't need to use the JCache API. Open Liberty handles the session caching in the web container layer. For more information about how Open Liberty handles HTTP session data, see the HttpSession interface.

Session caching in your application.

• no code changes are needed to include the JCache Session Persistence feature. Since you do need to edit your server code, this is a little misleading. Also should be in active voice. Maybe:
  If your application already caches HTTP session data, you don't need to make any code changes in the application to use the the JCache Session Persistence feature. Instead, configure the JCache Session Persistence feature in your server.xml file and reference the library that contains your chosen JCache implementation. To benefit from the JCache Session Persistence feature, you must join at least two servers together.

• recommend moving the diagram and its description into this section, along with the statement about the different Jcache providers. Move the introduction sentence before the diagram. Something like:
  The following diagram shows two Open Liberty servers that share a persisted session cache by using a JCache implementation:

• So when a new server starts in a cloud environment, it has access to sessions that are created by other servers.
  I don't think this is quite accurate, because the servers would have to be joined, not just in the same environment. Maybe:
  When a new server joins the cluster, it has access to HTTP session data that is created by other servers in the same cluster. Similarly, if a server in the cluster fails, its HTTP session data is preserved by other servers in the cluster.

Joining multiple servers together

---> Join multiple servers together (since this is not a task topic, avoid gerunds in the heading).

• The following code shows how two Open Liberty servers might share information that is cached in an HTTP session. The first example shows the application running on Server A and the second example shows the application running on Server B:

This description needs more detail. The examples show two applications, service A and service B, that are both running on different Open Liberty servers that are part of the same cluster. In the example, service A sets the value for the foo attribute to equal bar. Service B can then retrieve that value for the foo attribute from the distributed cache that is shared by all servers in the cluster.

• Each JCache implementation configures the cluster instances independently.
  I think this is based on this sentence in the blog post:
  Each JCache implementation has its own way of configuring cluster instances.
  But it's not saying the same thing. The sentence should communicate the fact that the JCache configuration is different for different implementations, and that the examples in this topic use hazelcast as the implementation. Maybe:
  Each JCache implementation configures the cluster instances differently. See the documentation for your chosen implementation.
• For Hazelcast, a simple configuration file might look like the following example. However, you don’t need to specify a Hazelcast configuration file if the default Hazelcast configuration works for you. You can optionally create a Hazelcast configuration file, as shown in the following example, and add a reference to the Hazelcast configuration file in your server.xml file:

This doesnt really tell the user why or when they would create their own config file. Maybe:

You don’t need to specify a Hazelcast configuration file if the default Hazelcast configuration works for you. However, you can create configuration file similar to the following example and add a reference to it from your server.xml file to customize how Hazelcast defines the cluster:

[example]

In this example, specifying the myCluster group name causes the Hazelcast instance to connect only with other instances that are also named myCluster.

[ManasiGandhi]

@dmuelle I worked on your review. Here's the link to the updated doc https://draft-openlibertyio.mybluemix.net/docs/21.0.0.6/distributed-session-caching.html

Peer review

Topic looks good- I have a few suggestions for clarity and to restore some details that were lost from the original blog post.

Intro

• Caching HTTP sessions in your applications helps to improve performance and availability for the users._

I'd revise this to make reference to "high availability", which is a good SEO term for this topic. ANdy also mentioned shopping carts in his intro, which is a good concrete example to orient the reader. Maybe something like:
Caching HTTP sessions in your applications helps provide high availability for users and enables functions such as shopping cart retrieval in e-commerce applications.

• You can store sessions--->You can store HTTP sessions (throughout the doc need to refer consistently to HTTP sessions, where appropriate)>

• With distributed caching, the server or database doesn’t need to store a cached session, as compared to non-distributed caching, which needs dedicated resources, thus providing failover and improved performance._

This seems a little vague and convoluted. Maybe:
With distributed caching, you don't need a single dedicated server or database to store a cached HTTP session. HTTP session cache data is distributed across multiple servers that act as a cluster.

• Though the feature builds on JCache, no direct usage of JCache API is necessary in your application, because Open Liberty handles the session caching in the web container layer._

--->
Though the feature builds on JCache, your application doesn't need to use the JCache API. Open Liberty handles the session caching in the web container layer. For more information about how Open Liberty handles HTTP session data, see the HttpSession interface.

Session caching in your application.

• no code changes are needed to include the JCache Session Persistence feature._ Since you do need to edit your server code, this is a little misleading. Also should be in active voice. Maybe:

If your application already caches HTTP session data, you don't need to make any code changes in the application to use the the JCache Session Persistence feature. Instead, configure the JCache Session Persistence feature in your server.xml file and reference the library that contains your chosen JCache implementation. To benefit from the JCache Session Persistence feature, you must join at least two servers together.

• recommend moving the diagram and its description into this section, along with the statement about the different Jcache providers. Move the introduction sentence before the diagram. Something like:

The following diagram shows two Open Liberty servers that share a persisted session cache by using a JCache implementation:

• So when a new server starts in a cloud environment, it has access to sessions that are created by other servers._

I don't think this is quite accurate, because the servers would have to be joined, not just in the same environment. Maybe:
When a new server joins the cluster, it has access to HTTP session data that is created by other servers in the same cluster. Similarly, if a server in the cluster fails, its HTTP session data is preserved by other servers in the cluster.

• ## Joining multiple servers together

---> Join multiple servers together (since this is not a task topic, avoid gerunds in the heading).

• The following code shows how two Open Liberty servers might share information that is cached in an HTTP session. The first example shows the application running on Server A and the second example shows the application running on Server B:_

This description needs more detail. The examples show two applications, service A and service B, that are both running on different Open Liberty servers that are part of the same cluster. In the example, service A sets the value for the foo attribute to equal bar. Service B can then retrieve that value for the foo attribute from the distributed cache that is shared by all servers in the cluster.

• Each JCache implementation configures the cluster instances independently._

I think this is based on this sentence in the blog post:
Each JCache implementation has its own way of configuring cluster instances.
But it's not saying the same thing. The sentence should communicate the fact that the JCache configuration is different for different implementations, and that the examples in this topic use hazelcast as the implementation. Maybe:
Each JCache implementation configures the cluster instances differently. See the documentation for your chosen implementation.

• For Hazelcast, a simple configuration file might look like the following example. However, you don’t need to specify a Hazelcast configuration file if the default Hazelcast configuration works for you. You can optionally create a Hazelcast configuration file, as shown in the following example, and add a reference to the Hazelcast configuration file in your server.xml file:_

This doesnt really tell the user why or when they would create their own config file. Maybe:

You don’t need to specify a Hazelcast configuration file if the default Hazelcast configuration works for you. However, you can create configuration file similar to the following example and add a reference to it from your server.xml file to customize how Hazelcast defines the cluster:

[example]

In this example, specifying the myCluster group name causes the Hazelcast instance to connect only with other instances that are also named myCluster.

[dmuelle]

Topic looks good! I just have a couple more suggestions to provide clarity and continuity throughout the topic:

• Link The JCache Session Persistence to the feature page on 1st mention (in 3rd paragraph)
• link this phrase to the JCache feature examples: "configure the JCache Session Persistence feature in your server.xml file". Don't monospace server.xml in the linked text though.

Joining multiple servers together

I think this section needs another sentence or two to explain why or when you would chose client vs p2p. Look at the infinspan topic, last paragraph if the intro. It discusses the differences btwn the two models for infinispan. But I think something more general would fit here, after you introduce the two models, like
Which model is best for you depends on the needs of your application, the resources that are available, and the specifications of your chosen Cache implementation.

• The examples show two applications-->The following examples show two applications,
• See the documentation for your chosen implementation.--->For more information, see the documentation for your chosen implementation.

I think the last part should be it's own section: "Customize your JCache implementation"
The section should be more general and use hazlecast as an example. like:
Most JCache implementations provide sensible default settings. However, if you need to customize your implementation, you can specify a JCache configuration file and reference it from your server.xml file (link to the example on the Jcache feature page). The following example Hazlecast configuration file customizes how Hazelcast defines the cluster:
[exaMPLE]

I also recommend adding a See also section that links to Richard's Infinispan topic

[ManasiGandhi]

@dmuelle I made the updates per your suggestions. Here's the link to the draft https://draft-openlibertyio.mybluemix.net/docs/21.0.0.6/distributed-session-caching.html

• Link The JCache Session Persistence to the feature page on 1st mention (in 3rd paragraph)

• link this phrase to the JCache feature examples: "configure the JCache Session Persistence feature in your server.xml file". Don't monospace server.xml in the linked text though.

Joining multiple servers together

• I think this section needs another sentence or two to explain why or when you would chose client vs p2p. Look at the infinspan topic, last paragraph if the intro. It discusses the differences btwn the two models for infinispan. But I think something more general would fit here, after you introduce the two models, like

• Which model is best for you depends on the needs of your application, the resources that are available, and the specifications of your chosen Cache implementation._

• The examples show two applications-->The following examples show two applications,

• See the documentation for your chosen implementation.--->For more information, see the documentation for your chosen implementation.

• I think the last part should be it's own section: "Customize your JCache implementation"

• The section should be more general and use hazlecast as an example. like:

Most JCache implementations provide sensible default settings. However, if you need to customize your implementation, you can specify a JCache configuration file and reference it from your server.xml file (link to the example on the Jcache feature page). The following example Hazlecast configuration file customizes how Hazelcast defines the cluster:
[exaMPLE]

• I also recommend adding a See also section that links to Richard's Infinispan topic

[dmuelle]

added peer review label. I also restored technical reviewed label. Andy had added the label previously and I removed it when we revised the doc. However, the technical details did not change in the revision so I added it back.

[ManasiGandhi]

https://docs-draft-openlibertyio.mybluemix.net/docs/21.0.0.6/distributed-session-caching.html

[dmuelle]

updated url: https://openliberty.io/docs/latest/distributed-session-caching.html

This topic will be revised or possibly removed as part of #5910