HSEARCH-3761 Return the result of explanations as a JsonObject in the Elasticsearch backend

Author: yrodiere

backend/elasticsearch/src/main/java/org/hibernate/search/backend/elasticsearch/search/query/ElasticsearchSearchQuery.java

@@ -8,6 +8,8 @@
 
 import org.hibernate.search.engine.search.query.ExtendedSearchQuery;
 
+import com.google.gson.JsonObject;
+
 public interface ElasticsearchSearchQuery<H>
 		extends ExtendedSearchQuery<H, ElasticsearchSearchResult<H>>, ElasticsearchSearchFetchable<H> {
 
@@ -17,11 +19,11 @@ public interface ElasticsearchSearchQuery<H>
 	 * This is a shorthand for {@link #explain(String, String)} when the query only targets one index.
 	 *
 	 * @param id The id of the document to test.
-	 * @return A string representing a JSON object describing the score computation for the hit.
+	 * @return A {@link JsonObject} describing the score computation for the hit.
 	 * @throws org.hibernate.search.util.common.SearchException If the query targets multiple indexes,
 	 * or if the explain request fails.
 	 */
-	String explain(String id);
+	JsonObject explain(String id);
 
 	/**
 	 * Explain score computation of this query for the document with the given id in the given index.
@@ -30,10 +32,10 @@ public interface ElasticsearchSearchQuery<H>
 	 *
 	 * @param indexName The name of the index containing the document to test.
 	 * @param id The id of the document to test.
-	 * @return A string representing a JSON object describing the score computation for the hit.
+	 * @return A {@link JsonObject} describing the score computation for the hit.
 	 * @throws org.hibernate.search.util.common.SearchException If the given index name does not refer to an index targeted by this query,
 	 * or if the explain request fails.
 	 */
-	String explain(String indexName, String id);
+	JsonObject explain(String indexName, String id);
 
 }

backend/elasticsearch/src/main/java/org/hibernate/search/backend/elasticsearch/search/query/impl/ElasticsearchSearchQueryImpl.java

@@ -125,7 +125,7 @@ public long fetchTotalHitCount() {
 	}
 
 	@Override
-	public String explain(String id) {
+	public JsonObject explain(String id) {
 		Contracts.assertNotNull( id, "id" );
 
 		Set<URLEncodedString> targetedIndexNames = searchContext.getIndexNames();
@@ -137,7 +137,7 @@ public String explain(String id) {
 	}
 
 	@Override
-	public String explain(String indexName, String id) {
+	public JsonObject explain(String indexName, String id) {
 		Contracts.assertNotNull( indexName, "indexName" );
 		Contracts.assertNotNull( id, "id" );
 
@@ -170,7 +170,7 @@ private Integer defaultedLimit(Integer limit, Integer offset) {
 		}
 	}
 
-	private String doExplain(URLEncodedString encodedIndexName, String id) {
+	private JsonObject doExplain(URLEncodedString encodedIndexName, String id) {
 		URLEncodedString elasticsearchId = URLEncodedString.fromString(
 				searchContext.toElasticsearchId( sessionContext.getTenantIdentifier(), id )
 		);
@@ -180,6 +180,6 @@ private String doExplain(URLEncodedString encodedIndexName, String id) {
 				.build();
 
 		ExplainResult explainResult = Futures.unwrappedExceptionJoin( queryOrchestrator.submit( work ) );
-		return searchContext.getUserFacingGson().toJson( explainResult.getJsonObject() );
+		return explainResult.getJsonObject();
 	}
 }

documentation/src/test/java/org/hibernate/search/documentation/search/query/QueryDslIT.java

@@ -44,6 +44,7 @@
 import org.junit.runner.RunWith;
 import org.junit.runners.Parameterized;
 
+import com.google.gson.JsonObject;
 import org.apache.lucene.search.Explanation;
 
 @RunWith(Parameterized.class)
@@ -296,14 +297,14 @@ public void explain_elasticsearch() {
 							.matching( "robot" ) )
 					.toQuery(); // <2>
 
-			String explanation1 = query.explain( "1" ); // <3>
-			String explanation2 = query.explain( "Book", "1" ); // <4>
+			JsonObject explanation1 = query.explain( "1" ); // <3>
+			JsonObject explanation2 = query.explain( "Book", "1" ); // <4>
 
 			ElasticsearchSearchQuery<Book> elasticsearchQuery = query.extension( ElasticsearchExtension.get() ); // <5>
 			// end::explain-elasticsearch[]
 
-			assertThat( explanation1 ).contains( "title" );
-			assertThat( explanation2 ).contains( "title" );
+			assertThat( explanation1 ).asString().contains( "title" );
+			assertThat( explanation2 ).asString().contains( "title" );
 			assertThat( elasticsearchQuery ).isNotNull();
 		} );
 	}

integrationtest/backend/elasticsearch/src/test/java/org/hibernate/search/integrationtest/backend/elasticsearch/ElasticsearchExtensionIT.java

@@ -202,11 +202,13 @@ public void query_explain_singleIndex() {
 
 		// Matching document
 		Assertions.assertThat( query.explain( FIRST_ID ) )
+				.asString()
 				.contains( "\"description\":" )
 				.contains( "\"details\":" );
 
 		// Non-matching document
 		Assertions.assertThat( query.explain( FIFTH_ID ) )
+				.asString()
 				.contains( "\"description\":" )
 				.contains( "\"details\":" );
 	}
@@ -246,11 +248,13 @@ public void query_explain_multipleIndexes() {
 
 		// Matching document
 		Assertions.assertThat( query.explain( INDEX_NAME, FIRST_ID ) )
+				.asString()
 				.contains( "\"description\":" )
 				.contains( "\"details\":" );
 
 		// Non-matching document
 		Assertions.assertThat( query.explain( INDEX_NAME, FIFTH_ID ) )
+				.asString()
 				.contains( "\"description\":" )
 				.contains( "\"details\":" );
 	}