Bug 821401 - Bugs in Hibernate Search Guide
Bugs in Hibernate Search Guide
Status: CLOSED CURRENTRELEASE
Product: JBoss Enterprise WFK Platform 2
Classification: JBoss
Component: HibernateSearch (Show other bugs)
2.0.0.GA
Unspecified Unspecified
medium Severity medium
: GA
: 2.1.0
Assigned To: Isaac Rooskov
Marek Schmidt
:
: 815471 (view as bug list)
Depends On: 815471
Blocks:
  Show dependency treegraph
 
Reported: 2012-05-14 07:25 EDT by Sanne Grinovero
Modified: 2015-08-06 01:54 EDT (History)
3 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2012-11-30 10:33:50 EST
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Sanne Grinovero 2012-05-14 07:25:33 EDT
# Chapter 3.4.2. JGroups Master/Slave back end
 - chapter should be removed

# Chapter 3.3.1. Infinispan Directory configuration
 - chapter should be removed

# on the Highlighted questions:
 - 1.2.1. Using a Maven Archetype / Will there be a product archetype?
   Question for Strong Liu - I think we could remove the archetype?
 - 1.2. Using Maven / Is this stuff about the artifact identifier still current for product version?
  *NO* and they are wrong. 
  -- All version for Hibernate search should match the build of the product, so each instance of _<version>4.1.0.Final</version>_ should be _<version>4.1.1.Final-redhat-1</version>_, or updated to newer for newer builds of the product. Ideally if the documentation build was coupled to the project build, this would happen automatically at any new build.
  -- Dependency for _Infinispan integration_ should be removed from Example 1.2
 - 1.1. System Requirements / Is this relevant with the product version?
  -- No, it would be best to remove the sentence "Hibernate Search 3.x was compatible with Java version 5."

# Legal notice:
 - Copyright year should likely be 2012
 - Why do we mention the _Linux®_ or _XFS®_ trademarks (which are totally not relevant nor mentioned) but not _Apache Lucene_ or _Hibernate_ which are also trademarks and very relevant for this documentation?

# 1.7. What's next
 - Remove pointers to “Infinispan Directory configuration”

# 3.6.1. Control segment size
 - The note is related to Infinispan only -> should be removed.

# "Please check the Lucene documentation or the excellent Lucene In Action from Otis Gospodnetic and Erik Hatcher. "
 - This is referring to _Lucene in Action_ first edition, should suggest second edition. (sorry our fault, I just notice it); suggestion: "Lucene in Action (Second Edition) by Michael McCandless, Erik Hatcher, and Otis Gospodnetić", or just refer to the last chapter "Further reading" were we already link to it.

# 4.3.2. Named analyzers
 - In the note, example dependency: make sure as well the version is fixed (as noted before)

# 5.1.3.4. Fetching strategy
 - First note: "will _return_ a SearchException" should be "will _throw_ a SearchException"
Comment 1 Sanne Grinovero 2012-05-14 07:31:24 EDT
Also to remove sentence: "To use hibernate-search-infinispan, adding the JBoss Maven repository is mandatory, because it contains the needed Infinispan dependencies which are currently not mirrored by central. "

In this section we are explaining the user how to setup Maven, and configuring the JBoss.org repositories: this should be replaced with instructions about the repositories were users can get the product artifacts.
Comment 2 Strong Liu 2012-05-17 00:01:26 EDT
yes, there is no product archetype
Comment 3 Rebecca Newton 2012-05-17 00:05:15 EDT
Taking this bug, it's all mine, mwuhaha!
Comment 4 Rebecca Newton 2012-05-30 23:14:33 EDT
Hey guys, thanks for this info. I've included most of it, here are my responses in order:

3.4.2. Done.
3.3.1. Done.
1.2.1. Done.
1.2. Done.
Versions: Should be correct throughout.
Infinispan - I've taken out the references detailed in the bug, but should I just remove all mentions of Infinispan I see? There are a few spare floating around.
1.1 Done.

Legal Notice
Linux, XFS, etc, are included by default by the doc creation tool, and we have no legal obligation to include the Apache Lucene trademark. I can include the Hibernate one if required, though.

1.7 Done.

3.3.1 Done

Legal:
Copyright year: Done.
Lucene documentation: We can't refer people to other books in Enterprise so this is removed.

4.3.2. Done
5.1.3.4. Done.

hibernate-search-infinispan: Done. 

You can see it all here, on stage: http://documentation-stage.bne.redhat.com/docs/en-US/JBoss_Web_Framework_Kit/2/html-single/Hibernate_Search/index.html
Comment 5 Sanne Grinovero 2012-05-31 05:07:00 EDT
> Infinispan - I've taken out the references detailed in the bug, but should I just remove all mentions of Infinispan I see? There are a few spare floating around.

Yes please remove them all.

> Legal Notice

I obviously have no authority on it: just my worthless impression. I just pointed out it's weird, I understand that might be a "default" as they are related to most Red Hat products, but they have nothing to do with Hibernate Search, and particularly those trademarks are never mentioned in the documentation.

thanks!
Comment 6 Sanne Grinovero 2012-05-31 05:13:22 EDT
To be more accurate on Infinispan removal:

# mention in Table 3.1 -> Remove entire last row of table (the one on Infinispan)

# warning in 5.1.3.6 -> That needs to stay!

# 9.6 sentence "One example is the ability the share an Infinispan cache instance between several directory providers running in different JVMs to store the various indexes using the same underlying infrastructure; this provides real-time replication of indexes across nodes."

 -> Remove

# End of chapter 3.7, sentence "The Infinispan Directory uses a custom implementation; it's still possible to override it but make sure you understand how that will work, especially with clustered indexes. "

 -> Remove

# 9.6.1.2. Provided services
here we make an example pointing to how a community project makes use of the service being described. I think it would be useful to keep, not sure if we can refer to our other community projects. In case you can remove the example.
Comment 7 Rebecca Newton 2012-05-31 23:43:34 EDT
Hey Sanne,

Legal Notice: I don't think it really does any harm to leave the trademarks in, even if they're not related to H'Search itself, especially since I'm not sure what would be involved in removing it. I'll have a think on it.

I've taken out all the detailed Infinispan references but for 9.6.1.2 I can leave it in if you think it's useful and maybe put a note saying Infinispan is not supported? Something like:

Infinispan Unsupported
Infinispan is unsupported with the JBWFK 2 release. This section is included for reference only.

What do you think? The changes should be live on stage by the time you read this :)
Comment 8 Sanne Grinovero 2012-06-01 06:29:14 EDT
# Legal : I have no strong feeling about it; just pointed it out, as I think brevity is a nice to have and that's totally unrelated with the subject, but trust it to you.

# 9.6.1.2.

saying that Infinispan is not supported is misleading; we supported it in other ways, varying across products and platforms, in some cases using different brand name (JBoss Data Grid). The bits we removed so far are related to a specific use of it which is not supported.

proposal: remove the whole sentence "For example, Infinispan which uses Hibernate Search as its internal search engine can pass the CacheContainer to Hibernate Search."

as I just checked the code, and it's a rather confusing example. Things changed since that was written.

# 9.6. Using external services

This sentence should definitely be removed, as it mentiones exactly the "ability" which we removed:

"One example is the ability the share an Infinispan cache instance between several directory providers running in different JVMs to store the various indexes using the same underlying infrastructure; this provides real-time replication of indexes across nodes."

(besides it contains an error too).
Comment 9 Rebecca Newton 2012-06-14 01:01:45 EDT
9.6.1.2 -- In this case, should I just remove the section entirely? I can add it back in after release if we can find a way to explain it better. Wdyt?

9.6. Done.
Comment 10 Sanne Grinovero 2012-06-14 06:00:09 EDT
9.6.1.2 : Yes we could remove the section, we don't expect end users to need this feature in 99% of cases. But it might be worth mentioning the feature at least; removing the sentence I mentioned previously would fix the ambiguity.

+1 to remove if we can add it back soon if you think that's a good short term plan, especially if you don't think the section is clear enough without that sentence. (But I think removing just the sentence would be fine too)

thanks!
Comment 11 Rebecca Newton 2012-06-14 21:57:37 EDT
I removed the sentence. I'll revisit it after GA if it needs it. It should be up on stage by the time you read this. Thanks for your help, Sanne.
Comment 12 Marek Schmidt 2012-06-20 11:02:13 EDT
1.1. System Requirements

"These instructions have been tested against Hibernate 4.1. You will need hibernate-core-4.1.0.Final.jar and its transitive dependencies (either from the distribution bundle or the maven repository). "

* technically it's 4.1.3 AFAIK, but that is irrelevant, the docs should just say that the user needs the Hibernate core version as distributed in the EAP6 distribution or the EAP6 Maven Repository.
* The "distribution bundle" links to some community distribution, which is wrong. It should probably just say one should use the files from the EAP6 distribution or the EAP6 Maven Repository.

1.2. Using Maven

It would be really helpful if the the information about which BOM can the user use to define the proper version of hibernate-search and which hibernate-search groupIds/artifactIds should be used for hibernate-search in a maven project:

e.g. You may use the following configuration in your Maven project to add the correct hibernate-search dependency:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.jboss.bom</groupId>
            <artifactId>jboss-javaee-6.0-with-hibernate</artifactId>
            <version>1.0.0.M12-redhat-1</version>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.hibernate</groupId>
        <artifactId>hibernate-search</artifactId>
    </dependency>
</dependencies>
Comment 13 Marek Schmidt 2012-06-20 11:25:01 EDT
1.3. Configuration

"analyze=analyze.YES" should be "analyze=Analyze.YES"  (2x)
Comment 14 Marek Schmidt 2012-06-20 11:27:26 EDT
3.2.1. directory-based

Link to "Worker configuration" is broken, there is no element with id "configuration-worker" in the html_single HTML file.
Comment 15 Marek Schmidt 2012-06-20 11:52:51 EDT
3.4. Worker configuration

Table 3.4. Backend configuration

contains 

"jgroupsMaster or jgroupsSlave: Backend using JGroups as communication layer." 

this should be removed, as AFAIK we don't support the jgroups backend.
Comment 16 Rebecca Newton 2012-06-21 00:41:08 EDT
Hey guys, thanks for the feedback. This information has come a bit too close to GA to make it into this release, so I'll have to work on this after GA and do an async update.
Comment 17 Marek Schmidt 2012-06-22 04:15:02 EDT
Hi Bec, Thanks! Post-GA is fine, these are not critical issues.

I have a few more:

4.1.1.2. @Field

* name, store are bold, while index, analyze, norms, termVector are not. Those should probably be made bold too (at the beginning of the itemized paragraphs)

* "Index.NO can be useful for cases where a property does is not required to be searchable, but should be available for projection."

    "does is" (English syntax error?)


4.3.2. Named analyzers

*    "Prior to Search version 3.3.0.Beta2 it was required to add the Solr dependency org.apache.solr:solr-core when you wanted to use the analyzer definition framework..." references to previous community versions should probably be removed.

*    The hibernate-search-analyzers version should be updated to the product version:

    <dependency>
       <groupId>org.hibernate</groupId>
       <artifactId>hibernate-search-analyzers</artifactId>
       <version>4.1.1.Final-redhat-1</version>
    <dependency>

4.4.1. Built-in bridges

*    "Using a Range query is debatable and has drawbacks, an alternative approach is to use a Filter query which will filter the result query to the appropriate range. Hibernate Search will support a padding mechanism",

     It is not clear to me what the "Hibernate Search will support a padding mechanism" means. Shouldn't it say to use a custom StringBridge, as described in 4.4.2.1. StringBridge ?

Chapter 5. Querying

*    Two of the examples in the chapter introduction text are not formatted nicely:

   "Example 5.2. Creating a Lucene query via the QueryParser"

    and the one untitled just above Example 5.2


5.2.4. Understanding results

* "The second approach let's you project the Explanation object using the FullTextQuery.EXPLANATION constant."

    "let's" should be "lets" ?

* "Don't do it if you don't need the object"
    missing "." at the end of the sentence.

9.2. Using an IndexReader

* "(described inSection 2.3, “Reader strategy”)"
        No space between "in" and the link

* "Never call indexReader.close(), but always call readerProvider.closeReader(reader), preferably in a finally block."

      Inconsistent with the example as it doesn't use any "readerProvider", but the "indexReaderAccessor.close(reader)". OTOH it also mentions ReaderProviders, but those have "closeIndexReader", not "closeReader" method, so I am sure it is wrong, but I don't know what should be there instead.
Comment 18 Marek Schmidt 2012-06-22 07:30:21 EDT
Missed on from my list:

5.3.1. Using filters in a sharded environment

* typo in the example "FFullTextFilter" should be "FullTextFilter"
Comment 19 Karel Piwko 2012-06-22 08:51:46 EDT
*** Bug 815471 has been marked as a duplicate of this bug. ***
Comment 20 Marek Schmidt 2012-06-22 08:59:19 EDT
4.1.1.3. @NumericField

"Lucene marks the numeric field API still as experimental and warns for incompatible changes in coming releases. Using Hibernate Search will hopefully shield you from any underlying API changes, but that is not guaranteed."

should be removed, as it is not experimental anymore in Lucene 3.5.
Comment 21 Isaac Rooskov 2012-09-13 21:12:37 EDT
This has been corrected for WFK 2.1
Comment 26 Karel Piwko 2012-11-30 10:33:50 EST
Distributed as a part of WFK 2.1.0.GA release.

Note You need to log in before you can comment on or make changes to this bug.