Explaining faceting and the non trivial way to read and select facets is not easy. We could simplify things by renaming a few APIs around canonical concepts:
Possible renames are:
FullTextQuery.enableFaceting -> FullTextQuery.enableFacetingRequest
FullTextQuery.disableFaceting -> FullTextQuery.disableFacetingRequest
FacetManager.getFacets() -> FacetManager.getFacetGroup()
FacetManager.getFacetGroup() -> FacetManager.getFacetSelection()
This is more an example to get us talk on the subject than a fully fledged proposal but since we do break things in 5, it's a good time to start it.
There remains an uneasy feeling connection between FacetingRequest and Facet group mainly due to the fact that their names uniquely identify them and that the names are shared between the two concepts. But one cannot merge FacetingRequest and Facet groups together I think.
Right, I'll need to think about it a bit more. I am planning to solve some of the open faceting issues next. I'll keep this issue in mind while working on these.
wondering why do you like the Request postfix. To me it evokes visions of slow remote requests: misleading.
I agree on the need to reorganize the API, but there are many things breaking in 5.0 already. Is the message to users that they basically will have to rewrite?
Just saying that while we can break backwards compatibility in 5.0 (as we need in many cases) there still is a fine balance to keep mind sanity during a migration. People would be really thankful if we could keep this kind of changes via a "traditional" @Deprecated path.
I have no idea why Request is associated to slow in you head but that's what the existing object is named
Most of what I recommend could be done with @Deprecated. The main issue is that getFacetGroup is returning FacetSelection today unfortunately Maybe with some clever naming we can avoid this breaking change.