GH-2979 Allow query explanation via REST API

[odysa]

GitHub issue resolved: #

#2979

Briefly describe the changes proposed in this PR:

Add an additional parameter to the query endpoint. If parm explain is present, don't execute the query and return the query explaination instead.

Currently only supports Text and Json response format.

Requst to return Json

curl -G 'http://localhost:8080/rdf4j-server/repositories/testrepo' \
           --data-urlencode 'explain=Timed' \
           --data-urlencode 'query=SELECT * WHERE { ?s ?p ?o }' \
           -H 'Accept:application/json'

{
  "type" : "StatementPattern",
  "resultSizeEstimate" : 0.0,
  "resultSizeActual" : 0,
  "totalTimeActual" : 0.005417,
  "plans" : [ {
    "type" : "Var (name=s)"
  }, {
    "type" : "Var (name=p)"
  }, {
    "type" : "Var (name=o)"
  } ],
  "selfTimeActual" : 0.005417
}

Request to return plain text

curl -G 'http://localhost:8080/rdf4j-server/repositories/testrepo' \
           --data-urlencode 'explain=Timed' \
           --data-urlencode 'query=SELECT * WHERE { ?s ?p ?o }' \
           -H 'Accept: text/plain'

StatementPattern (resultSizeEstimate=0, resultSizeActual=0, totalTimeActual=0.004ms, selfTimeActual=0.004ms)
   s: Var (name=s)
   p: Var (name=p)
   o: Var (name=o)

---

PR Author Checklist (see the contributor guidelines for more details):

• my pull request is self-contained
• I've added tests for the changes I made
• I've applied code formatting (you can use mvn process-resources to format from the command line)
• I've squashed my commits where necessary
• every commit message starts with the issue number (GH-xxxx) followed by a meaningful description of the change

[hmottestad]

Does this in any way allow a remote repo (HTTPRepository) to use the existing query explanation method on a query object and retrieve the explanation from the remote server?

[odysa]

Does this in any way allow a remote repo (HTTPRepository) to use the existing query explanation method on a query object and retrieve the explanation from the remote server?

@hmottestad I think answer is yes. Add a method in RDF4JProtocolSession to send request to the remote server. Just like this.

rdf4j/core/http/client/src/main/java/org/eclipse/rdf4j/http/client/RDF4JProtocolSession.java

Lines 241 to 256 in b33d914

	public void getRepositoryList(TupleQueryResultHandler handler) throws IOException, TupleQueryResultHandlerException,
	RepositoryException, UnauthorizedException, QueryInterruptedException {
	checkServerURL();
	HttpGet method = applyAdditionalHeaders(new HttpGet(Protocol.getRepositoriesLocation(serverURL)));
	try {
	getTupleQueryResult(method, handler);
	} catch (MalformedQueryException e) {
	// This shouldn't happen as no queries are involved
	logger.warn("Server reported unexpected malfored query error", e);
	throw new RepositoryException(e.getMessage(), e);
	} finally {
	method.reset();
	}
	}

[hmottestad]

Serialisation would be the main issue then I guess.

Let me just have a little think to see if there could be any potential issues down the line.

[odysa]

@hmottestad Hey, let's only include the rest api in this PR. I will have some future work on HttpRepo and workbench to utilize this api.

[hmottestad]

Code looks good! Thanks!

The final thing I need to do is test this locally just to see how it looks.