Reorganise JCache info

[lauracowen]

https://openliberty.io/docs/latest/distributed-caching-jcache.html

This container topic is largely about configuration, which should instead be in the feature config reference topic: https://openliberty.io/docs/latest/reference/feature/sessionCache-1.0.html

It is not helpful for this to be the container topic. The Distributed caching topic should be the container topic: https://openliberty.io/docs/latest/distributed-session-caching.html It introduces the concept and gives context to anything else.

The topic about Infinispan starts with a generic shortdesc but it should mention Infinispan and why you might be using that as that's the point of the topic. Nothing in the whole intro section explains why you might choose Infinispan yet the topic assumes you're on OpenShift (which is not necessarily going to be the case). Is Infinispan the only option on OpenShift? Can it be used only on OpenShift? I'm not sure any of this context is given in the topic.

[dmuelle]

The reason these config examples aren't on a feature page is they arent specxiofic to a particular feature. The cache* elements in this topic are used by a handful of different liberty features, not just sessionCache. So far we document three use cases- session caching, authentication caching, and logged out cookie caching, the later two being documented in the Security section.

I believe the config in this topic is relevant to any of those use cases. But maybe the session caching stuff shouldn't sit beneath this topic since the other cache-related stuff is in security?

The infinispan topic does document a non-OpenShift use case breifly- Configuring Infinispan in embedded mode without OpenShift. But I agree it doesnt really help much to tell you why or when youd use OpenShift. I'll try to find the original issue for this one to see if we can provide more context, or whether this is still a popular usage pattern. The dev who worked on this feature is unfortunately no longer with IBM

[lauracowen]

Infinispan - ok

Caching - I'm not sure I follow, even looking at some of the topics I could find. Why can't the examples just go in the relevant feature config ref topics for whatever the use case is in the topic they're currently located in, even if there's some duplication between them?

The examples in the JCache config topic seem to be avoiding telling anyone which feature to use them under and are focused on the abstract config elements. Each of the use cases you mention above (session caching, authentication caching, logged-out cookie caching) must have some particular use of those config elements, even if they use the same config elements. So wouldn't each feature config ref topics provide specific framing of what the config examples do for their respective use case?

For example, the whole Configure a distributed logged-out cookie cache section should really be in the appSecurity feature as a section about configuring a distributed logged out cookie cache. Then the Tracked logged-out SSO cookies topic would talk about the fact that you can do this and then link to the feature config ref topic for the specific example of how to do it (can link directly to the section to make it clearer which example config is meant). Similarly, I guess, the Infinispan and Hazelcast example config.

And same for the JCache stuff but putting it in the sessionCache feature? Then in the JCache topic talk about caching and the types of caching available? Or, as they seem quite different use cases, probably as you currently have address each different type of caching separately and in there talk about how JCache can do that and point out to the config for that feature.

I'm not sure session caching is really security? Not in the way that SSO and authentication caching is anyway. I think it makes sense to keep them where they are. It's just that there's loads of config in so many of the main doc topics that I don't think should be there and should be in the feature config ref topics so that you can expect to find important examples there. Also, that JCache topic, which is largely reference info, doesn't really help you know where to put the config examples that are given, so it's not really guiding you in how to use the info anyway.

Does any of this make sense with what you know about the info in there? Or am I missing something still?

[dmuelle]

I think the jcahce config topic is showing you how to configure the API behavior, which you might do for various reasons. For each case- session caching, authentication, logged-out cookies, you need to configure the API at a high level in a similar way for basic set up, configuring alternate providers, or managing mulitple caches. That last one is good example- what if you have an app that needs to cache HTTP sessions, but also (unrelatedly) track logged out cookies? You'd configure the JCache stuff differently if you have multiple caches, but it's information you'd need for the perspective of each individual use case. So we point from both cases to general information about using JCache with Open LIberty. But maybe a better solution is to use include statements to reuse the same examples in different feature pages.

[lauracowen]

Yes, I like the idea of include statements to ensure maintenance doesn't get ridiculous.