HSEARCH-2441 Clarify that the JSON provided to ElasticsearchHSQueryIm…

…pl is the Search API payload

... and not simply the query part.

elasticsearch/src/main/java/org/hibernate/search/elasticsearch/ElasticsearchQueries.java

@@ -28,19 +28,21 @@ private ElasticsearchQueries() {
 	}
 
 	/**
-	 * Creates an Elasticsearch query from the given JSON query representation. See the <a
-	 * href="https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html">official
-	 * documentation</a> for the complete query syntax.
+	 * Creates an Elasticsearch query from the given JSON payload for the Elasticsearch Search API.
+	 * <p>
+	 * See the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html">
+	 * official documentation</a> for the complete payload syntax.
 	 */
-	public static QueryDescriptor fromJson(String jsonQuery) {
-		return new ElasticsearchJsonQueryDescriptor( PARSER.parse( jsonQuery ).getAsJsonObject() );
+	public static QueryDescriptor fromJson(String payload) {
+		return new ElasticsearchJsonQueryDescriptor( PARSER.parse( payload ).getAsJsonObject() );
 	}
 
 	/**
 	 * Creates an Elasticsearch query from the given Query String Query, as e.g. to be used with the "q" parameter in
-	 * the Elasticsearch API. See the <a
-	 * href="https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html">official
-	 * documentation</a> for a description of the query syntax.
+	 * the Elasticsearch Search API.
+	 * <p>
+	 * See the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-query-string-query.html">
+	 * official documentation</a> for the query syntax.
 	 */
 	public static QueryDescriptor fromQueryString(String queryStringQuery) {
 		// Payload looks like so:

elasticsearch/src/main/java/org/hibernate/search/elasticsearch/impl/ElasticsearchHSQueryImpl.java

@@ -125,7 +125,15 @@ public class ElasticsearchHSQueryImpl extends AbstractHSQuery {
 			)
 	);
 
-	private final JsonObject jsonQuery;
+	/**
+	 * The constructor-provided payload for the Search API, holding
+	 * the search query in particular.
+	 * <p>
+	 * This raw payload will serve as a basis for the actual payload to be sent toElasticsearch,
+	 * which will also contain automatically generated data related in particular to sorts
+	 * and projections.
+	 */
+	private final JsonObject rawSearchPayload;
 
 	private Integer resultSize;
 	private IndexSearcher searcher;
@@ -135,9 +143,9 @@ public class ElasticsearchHSQueryImpl extends AbstractHSQuery {
 
 	private transient FacetManagerImpl facetManager;
 
-	public ElasticsearchHSQueryImpl(JsonObject jsonQuery, ExtendedSearchIntegrator extendedIntegrator) {
+	public ElasticsearchHSQueryImpl(JsonObject rawSearchPayload, ExtendedSearchIntegrator extendedIntegrator) {
 		super( extendedIntegrator );
-		this.jsonQuery = jsonQuery;
+		this.rawSearchPayload = rawSearchPayload;
 	}
 
 	@Override
@@ -160,7 +168,7 @@ public Query getLuceneQuery() {
 
 	@Override
 	public String getQueryString() {
-		return jsonQuery.toString();
+		return rawSearchPayload.toString();
 	}
 
 	@Override
@@ -253,7 +261,7 @@ protected void clearCachedResults() {
 	@Override
 	protected TimeoutManagerImpl buildTimeoutManager() {
 		return new TimeoutManagerImpl(
-				jsonQuery,
+				rawSearchPayload,
 				timeoutExceptionFactory,
 				this.extendedIntegrator.getTimingSource()
 		);
@@ -317,7 +325,7 @@ private IndexSearcher() {
 					if ( !( indexManager instanceof ElasticsearchIndexManager ) ) {
 						throw LOG.cannotRunEsQueryTargetingEntityIndexedWithNonEsIndexManager(
 							queriedEntityType,
-							jsonQuery.toString()
+							rawSearchPayload.toString()
 						);
 					}
 
@@ -329,7 +337,7 @@ private IndexSearcher() {
 			}
 
 			// Query filters; always a type filter, possibly a tenant id filter;
-			JsonObject filteredQuery = getFilteredQuery( jsonQuery.get( "query" ), typeFilters );
+			JsonObject filteredQuery = getFilteredQuery( rawSearchPayload.get( "query" ), typeFilters );
 
 			JsonBuilder.Object payloadBuilder = JsonBuilder.object();
 			payloadBuilder.add( "query", filteredQuery );

elasticsearch/src/main/java/org/hibernate/search/elasticsearch/impl/ElasticsearchJsonQueryDescriptor.java

@@ -20,19 +20,23 @@
  */
 public class ElasticsearchJsonQueryDescriptor implements QueryDescriptor {
 
-	private final JsonObject jsonQuery;
+	/**
+	 * The raw payload for the Search API, which will serve as a base
+	 * to build the actual payload.
+	 */
+	private final JsonObject rawSearchPayload;
 
-	public ElasticsearchJsonQueryDescriptor(JsonObject jsonQuery) {
-		this.jsonQuery = jsonQuery;
+	public ElasticsearchJsonQueryDescriptor(JsonObject rawSearchPayload) {
+		this.rawSearchPayload = rawSearchPayload;
 	}
 
 	@Override
 	public HSQuery createHSQuery(SearchIntegrator searchIntegrator) {
-		return new ElasticsearchHSQueryImpl( jsonQuery, searchIntegrator.unwrap( ExtendedSearchIntegrator.class ) );
+		return new ElasticsearchHSQueryImpl( rawSearchPayload, searchIntegrator.unwrap( ExtendedSearchIntegrator.class ) );
 	}
 
 	@Override
 	public String toString() {
-		return jsonQuery.toString();
+		return rawSearchPayload.toString();
 	}
 }