Bug 1041547

Divya's feedback from BZ#1035940:

In the latest draft of Infinispan Query Guide [1] [2], we still use 2 DSLs. I think this is pretty confusing to the reader.

The name of the Guide is "Infinispan Query Guide" but we use 2 terms "Infinispan Query DSL" and "Hibernate Search DSL", with the "Infinispan Query DSL" unsupported (Tech Preview). The primary aim of this guide is to document the supported Embedded Querying feature.

Another confusing area:
In 1.1: We mention the 2 DSLs.
"In this document, the Hibernate Search Query DSL and the Infinispan Query DSL are discussed frequently. The two are separate DSLs which provide two different ways to create queries and should not be confused with each other."
However, in 1.2, we title as "1.2. Downloading Infinispan Query"
1.3.2 1.3.2. Apache Lucene and Infinispan Query

Afaik 1.2 and 1.3.2 are not related to the "Infinispan Query DSL", but the Lucene-based API (Hibernate Search).

I would hesitate to ack IQ guide in its current form. I would suggest following changes:
1) *Consistently* using the word "Lucene-based API" for Embedded Querying functionality, in chapters 1 to 5.
2) Use term "Query DSL" for Remote Querying only in Chapter 6.
3) We should probably consider renaming this guide to just "Querying Guide" 
4) re: Chapter 7, Where do we mention the JMX controls for Remote Querying (protostream) and Query statistics exposed in JON plugin ?

> Afaik 1.2 and 1.3.2 are not related to the "Infinispan Query DSL", but the 
> Lucene-based API (Hibernate Search).

1.2 - Downloading Infinispan Query 
 - I have suggesting renaming this topic "Installing Querying for Red Hat JBoss Data Grid". 
 - I have also replaced "Infinispan Query JAR files", with "the JAR files required to perform queries"

1.3.2 - Apache Lucene and Infinispan Query
 - for consistency with 1.3.1, I have renamed this topic Apache Lucene and the Query Module.
 - The last line has been changed from "Infinispan Query intercepts changes..." to "Hibernate Search intercepts changes..."


Chapter 6:

All references to Query DSL are now "Infinispan Query DSL".
6.4.2 is now "Enabling Infinispan Query DSL-based Queries"
6.4.3 is now "Running Infinispan Query DSL-based Queries"

There are a few obvious problems which should be fixed:

* 1.4.2. Batching

After changing Hibernate Search to Lucene-based API this topic does not make much sense. API (application programming interface) on its own
cannot work in transactional or batch mode. Only Hibernate Search engine does. Honestly, I don't see much value in the whole topic (1.4.2).

* 5.1.2. Building a Lucene Query

"The Lucene-based query DSL uses a fluent API." should be replaced with "The Lucene-based query API is fluent.
(to avoid using DSL)

* 6.3.2. Enabling Infinispan Query DSL-based Queries

The sentence starting with "All libraries required for Lucene-based Query API queries ..." should actually
use "Infinispan Query DSL" instead of "Lucene-based Query API"

Please make following revisions:

1) Section 1.1

Replace:
" Red Hat JBoss Data Grid's Infinispan Query is a combination of Hibernate Search's query capabilities and Infinispan. As a result, Infinispan Query and Hibernate Search share several concepts and APIs and the annotations used to map objects to indexes use the same package domain (org.hibernate.search).

The JBoss Data Grid querying API in Library mode leverages Apache Lucene and Hibernate Search. The Infinispan Query DSL discussed in later chapters, is available for both Library and Remote querying. Remote querying is a Technical Preview only in JBoss Data Grid 6.2, and is not currently supported. "

--> 
"The JBoss Data Grid Library-mode Querying API leverages Apache Lucene and Hibernate Search. This API is supported in JBoss Data Grid 6.2.

Remote Querying from a Hot Rod Java client, which is discussed in Chapter 6, is Technology Preview for JBoss Data Grid 6.2 and is not supported."


2) Section 1.3

Delete sentence:
"The Query Module uses the Infinispan Query internally and independent of the data source."

3) Section 1.5

Example 1.1
Please remove this content from this example, it is a bit confusing
"// create native Lucene query using the query DSL
// alternatively you can write the Lucene query using the Lucene query parser
// or the Lucene programmatic API. The Infinispan Query DSL is recommended"

Thanks again Divya for your feedback and Mandar for implementing it.

Unless there are further changes this bug will be set to ON QA once docs are brewed.

Adding NEEDINFO for Martin for QE ack of chapter 7 as per Divya's request in comment 18.

Chapter 7 is still incomplete. There's this BZ to track the effort: https://bugzilla.redhat.com/show_bug.cgi?id=1039044

The rest of the guide except chapter 7 looks fine.

Martin, can we move this bug to Verified?

Putting this bug on ON_QA.

The fix for this bug is now generally released and available here:

https://access.redhat.com/site/documentation/en-US/Red_Hat_JBoss_Data_Grid/6.2/index.html