Class SPARQLProtocolSession
java.lang.Object
org.eclipse.rdf4j.http.client.SPARQLProtocolSession
- All Implemented Interfaces:
AutoCloseable, HttpClientDependent
- Direct Known Subclasses:
RDF4JProtocolSession
The SPARQLProtocolSession provides low level HTTP methods for communication with SPARQL endpoints. All methods are
compliant to the SPARQL 1.1 Protocol W3C Recommendation.
For both Tuple and Graph queries there is a variant which parses the result in the background, see
BackgroundTupleResult and BackgroundGraphResult. For boolean queries the result is parsed in the
current thread. All methods in this class guarantee that HTTP connections are closed properly and returned to the
connection pool. The methods in this class are not guaranteed to be thread-safe.
Functionality specific to the RDF4J HTTP protocol can be found in RDF4JProtocolSession (which is used by
HTTPRepository).- Author:
- Herko ter Horst, Arjohn Kampman, Andreas Schwarte, Jeen Broekstra
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intThe default value of the threshold for URL length, beyond which we use the POST method for SPARQL query requests.static final intDeprecated.static final StringSystem property for configuration of URL length threshold:rdf4j.sparql.url.maxlength.protected static final Charset -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionvoidclose()protected HttpResponseexecute(HttpRequest request) Executes the given HTTP request and returns the response on success (2xx or 404).protected voidexecuteNoContent(HttpRequest method) protected HttpResponseexecuteOK(HttpRequest method) Convenience method to deal with HTTP level errors of tuple, graph and boolean queries in the same way.Get the additional HTTP headers which will be usedReturns the currentAuthenticationHandler, ornullif none has been set.protected TupleQueryResultgetBackgroundTupleQueryResult(HttpRequest method, WeakReference<?> callerRef) Deprecated.WeakReferenceinvalid input: '<'?protected booleangetBoolean(HttpRequest method) Parse the response in this thread using a suitableBooleanQueryResultParser.protected ErrorInfogetErrorInfo(HttpResponse response) final RDF4JHttpClientRDF4JHttpClientthat has been assigned or has been used by this object.Gets the preferredBooleanQueryResultFormatfor encoding boolean query results.Gets the preferredRDFFormatfor encoding RDF documents.Gets the preferredTupleQueryResultFormatfor encoding tuple query results.protected HttpRequestgetQueryMethod(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) protected List<NameValuePair> getQueryMethodParameters(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) protected voidgetRDF(HttpRequest method, RDFHandler handler, boolean requireContext) Parse the response in this thread using the providedRDFHandler.protected GraphQueryResultgetRDFBackground(HttpRequest method, boolean requireContext, WeakReference<?> callerRef) Deprecated.WeakReferenceinvalid input: '<'?protected StringgetResponseMIMEType(HttpResponse response) Gets the MIME type specified in the response headers of the supplied method, if any.protected voidgetTupleQueryResult(HttpRequest method, TupleQueryResultHandler handler) Parse the response in this thread using the providedTupleQueryResultHandler.protected HttpRequestgetUpdateMethod(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) protected HttpRequestgetUpdateMethod(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings) protected List<NameValuePair> getUpdateMethodParameters(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) protected List<NameValuePair> getUpdateMethodParameters(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings) booleanIndicates if direct pass-through of the endpoint result to the suppliedSinkis enabled.booleansendBooleanQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) booleansendBooleanQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, Binding... bindings) sendGraphQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, WeakReference<?> callerRef, Binding... bindings) Deprecated.WeakReferenceinvalid input: '<'?voidsendGraphQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, RDFHandler handler, Binding... bindings) sendGraphQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, WeakReference<?> callerRef, Binding... bindings) Deprecated.WeakReferenceinvalid input: '<'?voidsendGraphQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, RDFHandler handler, Binding... bindings) sendTupleQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, WeakReference<?> callerRef, Binding... bindings) Deprecated.WeakReferenceinvalid input: '<'?voidsendTupleQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, TupleQueryResultHandler handler, Binding... bindings) sendTupleQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, WeakReference<?> callerRef, Binding... bindings) Deprecated.WeakReferenceinvalid input: '<'?voidsendUpdate(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) voidsendUpdate(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings) voidsetAdditionalHttpHeaders(Map<String, String> additionalHttpHeaders) Set additional HTTP headers to be included in every request to the server, which may be required for certain unusual server configurations.voidSets anAuthenticationHandlerthat will be applied to every outgoing request.voidsetHttpClient(RDF4JHttpClient httpClient) Assign anRDF4JHttpClientthat this object should use.voidsetParserConfig(ParserConfig parserConfig) Sets the parser configuration used to process HTTP response data.voidsetPassThroughEnabled(boolean passThroughEnabled) Configure direct pass-through of the endpoint result to the suppliedSink.voidSets the preferred format for encoding boolean query results.voidsetPreferredRDFFormat(RDFFormat format) Sets the preferred format for encoding RDF documents.voidSets the preferred format for encoding tuple query results.protected voidsetQueryURL(String queryURL) protected voidsetUpdateURL(String updateURL) voidsetUsernameAndPassword(String username, String password) Set the username and password for authentication with the remote server.protected voidsetUsernameAndPasswordForUrl(String username, String password, String url) voidsetValueFactory(ValueFactory valueFactory) protected booleanshouldUsePost(String fullQueryUrl) Return whether the provided query should use POST (otherwise use GET)
-
Field Details
-
UTF8
-
DEFAULT_MAXIMUM_URL_LENGTH
public static final int DEFAULT_MAXIMUM_URL_LENGTHThe default value of the threshold for URL length, beyond which we use the POST method for SPARQL query requests. The default is based on the lowest common denominator for various web servers.- See Also:
-
MAXIMUM_URL_LENGTH
Deprecated.useDEFAULT_MAXIMUM_URL_LENGTHinstead.- See Also:
-
MAXIMUM_URL_LENGTH_PARAM
System property for configuration of URL length threshold:rdf4j.sparql.url.maxlength. A threshold of 0 (or a negative value) means that the POST method is used for every SPARQL query request.- See Also:
-
-
Constructor Details
-
SPARQLProtocolSession
-
-
Method Details
-
getHttpClient
Description copied from interface:HttpClientDependentRDF4JHttpClientthat has been assigned or has been used by this object. The life cycle might not be or might be tied to this object, depending on whetherRDF4JHttpClientwas passed to or created by this object respectively.- Specified by:
getHttpClientin interfaceHttpClientDependent- Returns:
- an
RDF4JHttpClientinstance or null
-
setHttpClient
Description copied from interface:HttpClientDependentAssign anRDF4JHttpClientthat this object should use. The life cycle of the givenRDF4JHttpClientis independent of this object. Closing or shutting down this object does not have any impact on the given client. Callers must ensure that the given client is properly closed elsewhere.- Specified by:
setHttpClientin interfaceHttpClientDependent- Parameters:
httpClient-
-
setValueFactory
-
getValueFactory
-
setQueryURL
-
setUpdateURL
-
setPreferredTupleQueryResultFormat
Sets the preferred format for encoding tuple query results.- Parameters:
format- The preferredTupleQueryResultFormat, or null to indicate no specific format is preferred.
-
getPreferredTupleQueryResultFormat
Gets the preferredTupleQueryResultFormatfor encoding tuple query results. TheSPARQL/XMLformat is preferred by default.- Returns:
- The preferred format, of null if no specific format is preferred.
-
setPreferredRDFFormat
-
getPreferredRDFFormat
-
setPreferredBooleanQueryResultFormat
Sets the preferred format for encoding boolean query results.- Parameters:
format- The preferredBooleanQueryResultFormat, or null to indicate no specific format is preferred.
-
getPreferredBooleanQueryResultFormat
Gets the preferredBooleanQueryResultFormatfor encoding boolean query results. Thebinaryformat is preferred by default.- Returns:
- The preferred format, of null if no specific format is preferred.
-
setUsernameAndPassword
-
setUsernameAndPasswordForUrl
-
setAuthenticationHandler
Sets anAuthenticationHandlerthat will be applied to every outgoing request. The handler may modify the request, for example by adding anAuthorizationheader.- Parameters:
handler- the authentication handler to use, ornullto remove authentication
-
getAuthenticationHandler
Returns the currentAuthenticationHandler, ornullif none has been set.- Returns:
- the authentication handler, or
null
-
getQueryURL
-
getUpdateURL
-
close
public void close()- Specified by:
closein interfaceAutoCloseable
-
sendTupleQuery
@Deprecated(since="4.1.2") public TupleQueryResult sendTupleQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, WeakReference<?> callerRef, Binding... bindings) throws IOException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException Deprecated.WeakReferenceinvalid input: '<'?> callerRef argument will be removed -
sendTupleQuery
@Deprecated(since="4.1.2") public TupleQueryResult sendTupleQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, WeakReference<?> callerRef, Binding... bindings) throws IOException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException Deprecated.WeakReferenceinvalid input: '<'?> callerRef argument will be removed -
sendTupleQuery
public void sendTupleQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, TupleQueryResultHandler handler, Binding... bindings) throws IOException, TupleQueryResultHandlerException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException -
sendUpdate
public void sendUpdate(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings) throws IOException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException -
sendUpdate
public void sendUpdate(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) throws IOException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException -
sendGraphQuery
@Deprecated(since="4.1.2") public GraphQueryResult sendGraphQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, WeakReference<?> callerRef, Binding... bindings) throws IOException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException Deprecated.WeakReferenceinvalid input: '<'?> callerRef argument will be removed -
sendGraphQuery
@Deprecated(since="4.1.2") public GraphQueryResult sendGraphQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, WeakReference<?> callerRef, Binding... bindings) throws IOException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException Deprecated.WeakReferenceinvalid input: '<'?> callerRef argument will be removed -
sendGraphQuery
public void sendGraphQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, RDFHandler handler, Binding... bindings) throws IOException, RDFHandlerException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException -
sendGraphQuery
public void sendGraphQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, RDFHandler handler, Binding... bindings) throws IOException, RDFHandlerException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException -
sendBooleanQuery
public boolean sendBooleanQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, Binding... bindings) throws IOException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException -
sendBooleanQuery
public boolean sendBooleanQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) throws IOException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException -
getAdditionalHttpHeaders
-
setAdditionalHttpHeaders
Set additional HTTP headers to be included in every request to the server, which may be required for certain unusual server configurations.- Parameters:
additionalHttpHeaders- a map containing pairs of header names and values. May be null
-
getQueryMethod
protected HttpRequest getQueryMethod(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) -
shouldUsePost
Return whether the provided query should use POST (otherwise use GET)- Parameters:
fullQueryUrl- the complete URL, including hostname and all HTTP query parameters
-
getUpdateMethod
protected HttpRequest getUpdateMethod(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings) -
getUpdateMethod
protected HttpRequest getUpdateMethod(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) -
getQueryMethodParameters
protected List<NameValuePair> getQueryMethodParameters(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) -
getUpdateMethodParameters
protected List<NameValuePair> getUpdateMethodParameters(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings) -
getUpdateMethodParameters
protected List<NameValuePair> getUpdateMethodParameters(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) -
getBackgroundTupleQueryResult
@Deprecated(since="4.1.2") protected TupleQueryResult getBackgroundTupleQueryResult(HttpRequest method, WeakReference<?> callerRef) throws RepositoryException, QueryInterruptedException, MalformedQueryException, IOException Deprecated.WeakReferenceinvalid input: '<'?> callerRef argument will be removedParse the response in a background thread. HTTP connections are dealt with in theBackgroundTupleResultor (in the error-case) in this method. -
getTupleQueryResult
protected void getTupleQueryResult(HttpRequest method, TupleQueryResultHandler handler) throws IOException, TupleQueryResultHandlerException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException Parse the response in this thread using the providedTupleQueryResultHandler. All HTTP connections are closed and released in this method -
getRDFBackground
@Deprecated(since="4.1.2") protected GraphQueryResult getRDFBackground(HttpRequest method, boolean requireContext, WeakReference<?> callerRef) throws IOException, RDFHandlerException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException Deprecated.WeakReferenceinvalid input: '<'?> callerRef argument will be removedParse the response in a background thread. HTTP connections are dealt with in theBackgroundGraphResultor (in the error-case) in this method. -
getRDF
protected void getRDF(HttpRequest method, RDFHandler handler, boolean requireContext) throws IOException, RDFHandlerException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException Parse the response in this thread using the providedRDFHandler. All HTTP connections are closed and released in this method -
getBoolean
Parse the response in this thread using a suitableBooleanQueryResultParser. All HTTP connections are closed and released in this method- Throws:
RDF4JExceptionIOException
-
executeOK
Convenience method to deal with HTTP level errors of tuple, graph and boolean queries in the same way. This method aborts the HTTP connection.- Parameters:
method-- Throws:
RDF4JExceptionIOException
-
executeNoContent
- Throws:
IOExceptionRDF4JException
-
execute
Executes the given HTTP request and returns the response on success (2xx or 404).The caller is responsible for closing the returned
HttpResponse. On error (non-2xx other than 404) the response is consumed and closed internally and an appropriate exception is thrown.- Parameters:
request- the request to execute- Returns:
- the response; the caller must close it after use
- Throws:
IOException- if a network or I/O error occursRDF4JException- if the server reports a protocol-level error
-
getResponseMIMEType
Gets the MIME type specified in the response headers of the supplied method, if any. For example, if the response headers contain Content-Type: application/xml;charset=UTF-8, this method will return application/xml as the MIME type.- Parameters:
response- The response to get the MIME type from.- Returns:
- The response MIME type, or null if not available.
- Throws:
IOException
-
getErrorInfo
- Throws:
RepositoryException
-
setParserConfig
Sets the parser configuration used to process HTTP response data.- Parameters:
parserConfig- The parserConfig to set.
-
getParserConfig
- Returns:
- Returns the parser configuration used to process HTTP response data.
-
isPassThroughEnabled
public boolean isPassThroughEnabled()Indicates if direct pass-through of the endpoint result to the suppliedSinkis enabled.- Returns:
- the passThroughEnabled setting.
-
setPassThroughEnabled
public void setPassThroughEnabled(boolean passThroughEnabled) Configure direct pass-through of the endpoint result to the suppliedSink.If not explicitly configured, the setting defaults to
true.- Parameters:
passThroughEnabled- the passThroughEnabled to set.
-
DEFAULT_MAXIMUM_URL_LENGTHinstead.