8:45 a.m.
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.
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
* each Lucene index has a IndexManager
* the index manager gives access to directory and reader provider as well
as the backend to be used
* 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
What do you guys think about this view?
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?
--Hardy
9:13 a.m.
Hi Hardy,
commented inline:
On 11 October 2011 14:45, Hardy Ferentschik <hardy(a)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(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hibernate-dev
9:43 a.m.
Hi,
great, seems we are sharing the same view then.
I will go ahead change the Architecture and Configuration chapters
accordingly.
It won't be in the release tomorrow, but definitely for the Final.
> * 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."
ok. Are we consistent with this though? I am not sure we are, but I will
double
check. But basically that was just a typo.
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
Didn't we have the discussion once before? We do it this way, because its
what we do in Core? But I think even there we have some org.hibernate.xyz
and some hibernate.xyz
I have no strong opinion on transparently allowing the 'org' prefix.
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
No it is not and I am not so happy about the 'default' value either.
As you say, it gets too confusing. Question is what to about it?
Deprecating the default values? Or even removing them.
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
I know. I mentioned it to Emmanuel today. It would have been better to
address
this issue for the 4.0 release, but given the time constraints we skipped
it.
This means these changes need to be deferred until 4.1 where we then,
unfortunately,
also have to care about backward computability. Unfortunate, really.
Sounds all good. I'm not touching docs myself to avoid conflicts,
but
if you want to assign me some tasks in isolated chapters.
Changing anything outside chapter 2 and 3 is safe. I will focus on these
two
for now (and some minor typo fixes I have for the Getting Started section,
I'll
will create a separate pull request for them)
--Hardy
9:52 a.m.
On 11 October 2011 15:43, Hardy Ferentschik <hardy(a)hibernate.org> wrote:
Hi,
great, seems we are sharing the same view then.
I will go ahead change the Architecture and Configuration chapters
accordingly.
It won't be in the release tomorrow, but definitely for the Final.
>> * 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."
ok. Are we consistent with this though? I am not sure we are, but I will
double
check. But basically that was just a typo.
Yes we are consistent with this. In fact IndexManager implementations
only receive the properties from under these paths so anything
inconsistent wouldn't be able to work.
> 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
Didn't we have the discussion once before? We do it this way, because its
what we do in Core? But I think even there we have some org.hibernate.xyz
and some hibernate.xyz
I have no strong opinion on transparently allowing the 'org' prefix.
Ok, just wondering as this is definitely not the most urgent change;
I'll open an issue, seems a good starting point for a new contributor.
HSEARCH-942
> 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
No it is not and I am not so happy about the 'default' value either.
As you say, it gets too confusing. Question is what to about it?
Deprecating the default values? Or even removing them.
> 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
I know. I mentioned it to Emmanuel today. It would have been better to
address
this issue for the 4.0 release, but given the time constraints we skipped
it.
WDYM ? 4.0 was not released yet, if we see a change which should be
done, we should be able to make them now.
This means these changes need to be deferred until 4.1 where we
then,
unfortunately,
also have to care about backward computability. Unfortunate, really.
> Sounds all good. I'm not touching docs myself to avoid conflicts, but
> if you want to assign me some tasks in isolated chapters.
Changing anything outside chapter 2 and 3 is safe. I will focus on these
two
for now (and some minor typo fixes I have for the Getting Started section,
I'll
will create a separate pull request for them)
--Hardy
_______________________________________________
hibernate-dev mailing list
hibernate-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/hibernate-dev
9:59 a.m.
> Didn't we have the discussion once before? We do it this way,
because
> its
> what we do in Core? But I think even there we have some
> org.hibernate.xyz
> and some hibernate.xyz
>
> I have no strong opinion on transparently allowing the 'org' prefix.
Ok, just wondering as this is definitely not the most urgent change;
I'll open an issue, seems a good starting point for a new contributor.
HSEARCH-942
+1
> I know. I mentioned it to Emmanuel today. It would have been
better to
> address
> this issue for the 4.0 release, but given the time constraints we
> skipped
> it.
WDYM ? 4.0 was not released yet, if we see a change which should be
done, we should be able to make them now.
If we would have a concrete plan. Do you already have concrete ideas for a
change?
Even though I find the current state confusing as well, I am unsure about
a better solution.
--Hardy
10:21 a.m.
On 11 oct. 2011, at 16:52, Sanne Grinovero wrote:
>> 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
>
> I know. I mentioned it to Emmanuel today. It would have been better to
> address
> this issue for the 4.0 release, but given the time constraints we skipped
> it.
WDYM ? 4.0 was not released yet, if we see a change which should be
done, we should be able to make them now.
If you guys have a clear vision of what you want to change, we can do it in the next 24h.
10:20 a.m.
On 11 oct. 2011, at 16:43, Hardy Ferentschik wrote:
>
> 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
No it is not and I am not so happy about the 'default' value either.
As you say, it gets too confusing. Question is what to about it?
Deprecating the default values? Or even removing them.
The alternative is to force people to set the same settings over and over for every single
index.
<properties>
<property name="hibernate.search.Animal.indexBase"
value="/var/lucene/ndexes"/>
<property name="hibernate.search.Book.indexBase"
value="/var/lucene/ndexes"/>
<property name="hibernate.search.Plant.indexBase"
value="/var/lucene/ndexes"/>
<property name="hibernate.search.Car.indexBase"
value="/var/lucene/ndexes"/>
<property name="hibernate.search.Order.indexBase"
value="/var/lucene/ndexes"/>
<property name="hibernate.search.Address.indexBase"
value="/var/lucene/ndexes"/>
<property name="hibernate.search.Part.indexBase"
value="/var/lucene/ndexes"/>
<property name="hibernate.search.Producer.indexBase"
value="/var/lucene/ndexes"/>
<property name="hibernate.search.Kingdom.indexBase"
value="/var/lucene/ndexes"/>
<property name="hibernate.search.Country.indexBase"
value="/var/lucene/ndexes"/>
.... 300 times more
</properties>
10:13 a.m.
I generally agree with the direction described by Hardy.
Some comments inline
> * 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+.
We can call them Directory based IndexManagers which is the only family we have at the
moment. As Sanne pointed out, other families will come in 4.2 or above.
> * 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
I am against it. All the doc is consistent, I don't want two options to do one thing
if they are strictly equivalent.
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 ?
Can you be specific? default is a great way to apply the same behavior for all of your
indexes. Unless I've lost a train, using the same type of backend with the same
settings is likely to be the most probable choice for a lot of deployments.
10:39 a.m.
I am against it. All the doc is consistent, I don't want two options to do one thing
if they are strictly equivalent.
Sure, I'm not suggesting to support it: as I've written in the
description of HSEARCH-942 such a property should log a warning: we
could warn only, but we could also warn and still apply the property.
I'm happy to warn only if you prefer.
> 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 ?
Can you be specific? default is a great way to apply the same behavior for all of your
indexes. Unless I've lost a train, using the same type of backend with the same
settings is likely to be the most probable choice for a lot of deployments.
There are properties which are not related to a specific IndexManager:
_hibernate.search.lucene_version_
_hibernate.search.filter.cache_docidresults.size_
and some which are:
_hibernate.search.default.directory_provider_
_hibernate.search.default.indexwriter.merge_factor_
I definitely like the default mechanics, what I'm pointing out is that
it's not clear that "default" is referring to the "default
index",
which is an abstract contept to make it harder.
If this was a method to specify a default value for any property, I
would expect it to work too for
_hibernate.search.default.filter.cache_docidresults.size_
(which doesn't work as it's a different category).
11 a.m.
I see where you're coming from.
There are two options:
- don't care that much
- rename default to default_for_index or index_default (or some long and annoying name
like that) and deprecate default
Do you really think filter is in as much need as index for a default? Any other category
that would be in need for that?
On 11 oct. 2011, at 17:39, Sanne Grinovero wrote:
>
> I am against it. All the doc is consistent, I don't want two options to do one
thing if they are strictly equivalent.
Sure, I'm not suggesting to support it: as I've written in the
description of HSEARCH-942 such a property should log a warning: we
could warn only, but we could also warn and still apply the property.
I'm happy to warn only if you prefer.
>> 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 ?
>
> Can you be specific? default is a great way to apply the same behavior for all of
your indexes. Unless I've lost a train, using the same type of backend with the same
settings is likely to be the most probable choice for a lot of deployments.
There are properties which are not related to a specific IndexManager:
_hibernate.search.lucene_version_
_hibernate.search.filter.cache_docidresults.size_
and some which are:
_hibernate.search.default.directory_provider_
_hibernate.search.default.indexwriter.merge_factor_
I definitely like the default mechanics, what I'm pointing out is that
it's not clear that "default" is referring to the "default
index",
which is an abstract contept to make it harder.
If this was a method to specify a default value for any property, I
would expect it to work too for
_hibernate.search.default.filter.cache_docidresults.size_
(which doesn't work as it's a different category).
11:25 a.m.
On 11 October 2011 17:00, Emmanuel Bernard <emmanuel(a)hibernate.org> wrote:
I see where you're coming from.
There are two options:
- don't care that much
- rename default to default_for_index or index_default (or some long and annoying name
like that) and deprecate default
I'm tempted for option 1) "don't care that much" as I'm not having
better ideas. Just saying that we have this issue open and it would be
nice to solve it before the next CR.
Do you really think filter is in as much need as index for a default? Any other category
that would be in need for that?
Not at all, since they are global options they don't need any
default+override, people should write it down just once anyway. They
are just examples of different categories of properties.
I'm hoping that rewriting the docs and clarifying the inconsistency we
won't need to actually change anything: it doesn't look that bad now,
I was more concerned about these when we moved around all the code and
properties actually changed "position" in the "tree" of properties.
4825
days inactive
4825
days old
10 comments
3 participants
participants (3)
-
Emmanuel Bernard -
Hardy Ferentschik -
Sanne Grinovero