HSEARCH-1296


https://hibernate.atlassian.net/browse/HSEARCH-1296
https://hibernate.atlassian.net/browse/HSEARCH-1304
https://hibernate.atlassian.net/browse/HSEARCH-1305

Documentation to be added very soon, but since the code is complex it would be nice if someone could start having a look:  I'm not going to change the code anymore (unless to address review).