Package org.eclipse.rdf4j.http.client
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
ConstructorsConstructorDescriptionSPARQLProtocolSession(org.apache.http.client.HttpClient client, ExecutorService executor) -
Method Summary
Modifier and TypeMethodDescriptionvoidclose()protected org.apache.http.HttpResponseexecute(org.apache.http.client.methods.HttpUriRequest method) protected voidexecuteNoContent(org.apache.http.client.methods.HttpUriRequest method) protected org.apache.http.HttpResponseexecuteOK(org.apache.http.client.methods.HttpUriRequest 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 usedprotected TupleQueryResultgetBackgroundTupleQueryResult(org.apache.http.client.methods.HttpUriRequest method, WeakReference<?> callerRef) Deprecated.WeakReference<?> callerRef argument will be removedprotected booleangetBoolean(org.apache.http.client.methods.HttpUriRequest method) Parse the response in this thread using a suitableBooleanQueryResultParser.longGets the http connection read timeout in milliseconds.protected ErrorInfogetErrorInfo(org.apache.http.HttpResponse response) final org.apache.http.client.HttpClientHttpClientthat has been assigned or has been used by this object.protected org.apache.http.protocol.HttpContextGet theHttpContextused for sending HTTP requests.Gets the preferredBooleanQueryResultFormatfor encoding boolean query results.Gets the preferredRDFFormatfor encoding RDF documents.Gets the preferredTupleQueryResultFormatfor encoding tuple query results.protected org.apache.http.client.methods.HttpUriRequestgetQueryMethod(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) protected List<org.apache.http.NameValuePair>getQueryMethodParameters(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) protected voidgetRDF(org.apache.http.client.methods.HttpUriRequest method, RDFHandler handler, boolean requireContext) Parse the response in this thread using the providedRDFHandler.protected GraphQueryResultgetRDFBackground(org.apache.http.client.methods.HttpUriRequest method, boolean requireContext, WeakReference<?> callerRef) Deprecated.WeakReference<?> callerRef argument will be removedprotected StringgetResponseMIMEType(org.apache.http.HttpResponse method) Gets the MIME type specified in the response headers of the supplied method, if any.protected voidgetTupleQueryResult(org.apache.http.client.methods.HttpUriRequest method, TupleQueryResultHandler handler) Parse the response in this thread using the providedTupleQueryResultHandler.protected org.apache.http.client.methods.HttpUriRequestgetUpdateMethod(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) protected org.apache.http.client.methods.HttpUriRequestgetUpdateMethod(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings) protected List<org.apache.http.NameValuePair>getUpdateMethodParameters(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) protected List<org.apache.http.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.WeakReference<?> callerRef argument will be removedvoidsendGraphQuery(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.WeakReference<?> callerRef argument will be removedvoidsendGraphQuery(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.WeakReference<?> callerRef argument will be removedvoidsendTupleQuery(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.WeakReference<?> callerRef argument will be removedvoidsendUpdate(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.voidsetConnectionTimeout(long timeout) Sets the http connection read timeout.voidsetHttpClient(org.apache.http.client.HttpClient httpClient) Assign anHttpClientthat 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
public final org.apache.http.client.HttpClient getHttpClient()Description copied from interface:HttpClientDependentHttpClientthat 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 whetherHttpClientwas passed to or created by this object respectively.- Specified by:
getHttpClientin interfaceHttpClientDependent- Returns:
- an
HttpClientinstance or null
-
setHttpClient
public void setHttpClient(org.apache.http.client.HttpClient httpClient) Description copied from interface:HttpClientDependentAssign anHttpClientthat this object should use. The life cycle of the givenHttpClientis 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
-
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
Sets the preferred format for encoding RDF documents.- Parameters:
format- The preferredRDFFormat, or null to indicate no specific format is preferred.
-
getPreferredRDFFormat
- Returns:
- The preferred format, of null if no specific format is preferred.
-
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
Set the username and password for authentication with the remote server.- Parameters:
username- the usernamepassword- the password
-
setUsernameAndPasswordForUrl
-
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.WeakReference<?> 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.WeakReference<?> 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.WeakReference<?> 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.WeakReference<?> 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
Get the additional HTTP headers which will be used- Returns:
- a read-only view of the additional HTTP headers which will be included in every request to the server.
-
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 org.apache.http.client.methods.HttpUriRequest 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 org.apache.http.client.methods.HttpUriRequest getUpdateMethod(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings) -
getUpdateMethod
protected org.apache.http.client.methods.HttpUriRequest getUpdateMethod(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings) -
getQueryMethodParameters
-
getUpdateMethodParameters
-
getUpdateMethodParameters
-
getBackgroundTupleQueryResult
@Deprecated(since="4.1.2") protected TupleQueryResult getBackgroundTupleQueryResult(org.apache.http.client.methods.HttpUriRequest method, WeakReference<?> callerRef) throws RepositoryException, QueryInterruptedException, MalformedQueryException, IOException Deprecated.WeakReference<?> 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(org.apache.http.client.methods.HttpUriRequest 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(org.apache.http.client.methods.HttpUriRequest method, boolean requireContext, WeakReference<?> callerRef) throws IOException, RDFHandlerException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException Deprecated.WeakReference<?> 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(org.apache.http.client.methods.HttpUriRequest 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
protected boolean getBoolean(org.apache.http.client.methods.HttpUriRequest method) throws IOException, RDF4JException Parse the response in this thread using a suitableBooleanQueryResultParser. All HTTP connections are closed and released in this method- Throws:
RDF4JExceptionIOException
-
executeOK
protected org.apache.http.HttpResponse executeOK(org.apache.http.client.methods.HttpUriRequest method) throws IOException, RDF4JException 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
protected void executeNoContent(org.apache.http.client.methods.HttpUriRequest method) throws IOException, RDF4JException - Throws:
IOExceptionRDF4JException
-
execute
protected org.apache.http.HttpResponse execute(org.apache.http.client.methods.HttpUriRequest method) throws IOException, RDF4JException - Throws:
IOExceptionRDF4JException
-
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:
method- The method to get the reponse 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.
-
getConnectionTimeout
public long getConnectionTimeout()Gets the http connection read timeout in milliseconds. -
setConnectionTimeout
public void setConnectionTimeout(long timeout) Sets the http connection read timeout.- Parameters:
timeout- timeout in milliseconds. Zero sets to infinity.
-
getHttpContext
protected org.apache.http.protocol.HttpContext getHttpContext()Get theHttpContextused for sending HTTP requests.- Returns:
- the
HttpContextinstance used for all protocol session requests.
-
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.