Hi Hardy, commented inline: On 11 October 2011 14:45, Hardy Ferentschik <ha...@hibernate.org> wrote: > hi, > > as you know I am reviewing the Search documentation and I keep banging my > head against chapter > 2 (Architecture) and 3 (Configuration). > This two chapters are most affected by the Search 4 changes and I think we > need to rethink how > we want to describe the system to our users. The current documentation is > a bit of a patch work > were we basically just added things introducing quite a bit of confusion. > > For example we in the Architecture we start talking about things like > backend and reader strategy > even before mentioning the IndexManager. > > Here is how I think we could arrange the content (correct me from wrong). > The basic idea is that > the IndexManager moves into focus.
+1 > I think this is also already implied by the following: > > "The default IndexManager implementation is named transactional. This is > the one mostly referred to in this documentation, > unless stated otherwise, and is highly configurable as you can select > different implementations for the reader strategy, > back ends and Directory Providers" > > For me the architecture is not as follows: > > * each entity can be indexed into one (ore more) Lucene index but also multiple entities in the same index is an option. > * each Lucene index has a IndexManager yes, and a unique name to identify it. > * the index manager gives access to directory and reader provider as well > as the backend to be used This is a tricky point. Generally this is correct, especially for the default IndexManager, but alternative implementations don't have to use a backend, or at least not one as defined by BackendQueueProcessor: we don't expose this interface so if someone wants to implement an IndexManager using a different approach, they can. And we will be providing some in 4.1+. > * when using properties of the form org.hibernate.search.<index-name>.xyz > you are effectively configuring the > IndexManager for the specified index +1 > * properties of the form org.hibernate.search.xyz are default values which > apply for any index manager if > not overridden explicitly warning it's actually "hibernate.search.default." a- no "org." in the front b- it must end with ".default" to be picked up by other IndexManagers on a) : shall we relax this and allow "org." prefix too? This bytes myself periodically on b) : I really think this ".default" business got out of hand; it made sense in initial days as there wasn't much to configure, but nowaday? Is it still self-speaking that "default" relates to the IndexManager / indexes ? We have an issue open around reviewing configuration properties, this thought was one of the reason to open it: HSEARCH-859 - Review names and composition of configuration properties So let's point out more property names which could be improved if you hit one. > What do you guys think about this view? Yes I think this clarifies a lot. Keep in mind that index names might have a dot in it, and we allow inheritance from the parent named (for example for sharding) and inheritance from the default index settings. > In the configuration chapter I also would like to apply some other > changes. For example, moving "Sharing indexes" into > advanced features. We even mention in the docs that we don't recommend it, > still it appears so early. Besides of that > I would like to rearrange a little the different back-end configurations. > > Thoughts? Sounds all good. I'm not touching docs myself to avoid conflicts, but if you want to assign me some tasks in isolated chapters. Sanne > > --Hardy > _______________________________________________ > hibernate-dev mailing list > hibernate-dev@lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev > _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
