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

[Hardy Ferentschik]

On 19 Jan 2013, at 18:17, Sanne Grinovero <sanne at hibernate.org> wrote:

> 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).

A move to asciidoc might be beneficial, but not a requirement.

>> 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.

Well, for starters we could change the description in the infinispan module pom which says “Hibernate Search Infinispan Backend”.
In the current light I would even suggest to rename the module directory to infinispan-dp or infinispan-directory-provider. Much more 
telling than infinispan.

>> 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.

It is not necessarily a matter of getting rid of things, but how you present them. This might also require some coding to offer,
for example, an index manger implementation for all our standard setups. However, in the end there should be a cohesive way
of doing things as long as you stick to the provided setups. The concept of a DirectoryProvider can then become a advanced 
topic. We could for example have a section (topical guide ;-)) how to bake your own IndexManager. 

> 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.

IMO there is no way to know to determine how users use it. That depends on which version they started using Search
and which documentation/examples they have seen. The more interesting question is, how we think it should be configured. 

On a related note, we have been discussing abandoning the properties approach and moving to a more structured configuration
approach (xml, yaml, …). In this case I see a configuration being ways more index manager centric as well. Users would either just name a 
default configuration or they configure their own index manager. 

I don’t think we will be able to transition to this type of configuration for the initial Search 5 version, but in the light of these plans it might
make sense to weed out some of the configuration options which we kept for backwards compatibility.

> 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.

+1

> 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.

I think a lot can be moved into a advanced user chapter

—Hardy