[hibernate-dev] [hsearch] documentation
sanne at hibernate.org
Tue Oct 11 10:13:07 EDT 2011
On 11 October 2011 14:45, Hardy Ferentschik <hardy at hibernate.org> wrote:
> 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.
> 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
> * 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
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
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.
Sounds all good. I'm not touching docs myself to avoid conflicts, but
if you want to assign me some tasks in isolated chapters.
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
More information about the hibernate-dev