[hibernate-dev] [Search] Search 5 and architecture review

[Sanne Grinovero]

On 19 December 2013 15:19, Hardy Ferentschik <hardy at hibernate.org> wrote:
> Hi,
>
> IMO we should rethink how we describe the architecture of Search and especially its extension points.
> I think for Search 5 we will need to review/rewrite the documentation (maybe as part of moving to asciidoc) and clear out some
> of the ambiguities we have in the used terminology.

+1 !
My hope would be that we'd first move to asciidoc, so to minimize the
effort of the reorganization (more on this below).

>
> For example, ‘backend’. Technically it is the implementation of BackendQueueProcessor, but I think we sometimes used the
> term in the wrong context as well, for example when we talk about the "Infinispan backend” which is really a DirectoryProvider.

We can certainly clarify, and I did talked frequently about an
"Infinispan backend" as I'm working on such a thing.
The difference is quite clear in my mind so I don't think I would have
messed up the terminology but ok I guess not all my emails are well
crafted.

> Speaking of the latter, my understanding is that we wanted to move away from DirectoryProvider (at least from a configuration/
> documentation point of view) and consistently refer to IndexManager.

+0,8 :-)
I agree we should be moving in that direction, but we can't get
completely rid of the concepts.

We probably should review how the user actually configures these
things; we introduced the IndexManager notion during 4.0, but for
backwards compatibility we kept explicit options around
DirectoryProvider and Backends, and these are accepted if no IM is
configured.
Still even back then the intention was to develop a collection of
IndexManager(s) to phase away the need to explain what should be just
an implementation detail. However these "implementation details" are
important to understand for proper tuning and to be able to make a
sound choice of deployment architecture, so I don't think we'll be
able to get rid of them - especially in the architecture chapter.

We also need to make sure people on our team understand these terms,
as these are our means for talking to each other, but I hope that goes
without saying as it's not the first time or the last that we'll see
people using names of interfaces in technical discussions.

> These are just two examples of various major and minor inconsistencies in how we describe Search. I think we really should
> spend some time and work out the terminology we want to use and weed out the documentation. Maybe this is something
> everyone can just keep in mind for a while to think about.
>
> Should we create an issue for this where we can collect ideas on what needs to be changed?

Creating two issues as a starter:
 - https://hibernate.atlassian.net/browse/HSEARCH-1471 Migrate
documentation to asciidoc
 - https://hibernate.atlassian.net/browse/HSEARCH-1472 Broaden
collection of built in IndexManager implementations to simplify choice
of sensible configurations

Needless to say HSEARCH-1472 implies a significant documentation work,
we can see after these are done if you want to add more?

On asciidoc: I'd be tempted to say we should do it first to lower the
cost of any further patches, but I'm not too happy in considering it a
blocker for 5.0 .. thoughts?

Cheers,
Sanne


>
> —Hardy
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev