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
public class SPARQLProtocolSession extends Object implements HttpClientDependent, AutoCloseable
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, seeBackgroundTupleResultandBackgroundGraphResult. 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 inRDF4JProtocolSession(which is used by HTTPRepository).- Author:
- Herko ter Horst, Arjohn Kampman, Andreas Schwarte, Jeen Broekstra
- See Also:
RDF4JProtocolSession, SPARQL 1.1 Protocol (W3C Recommendation)
-
-
Field Summary
Fields Modifier and Type Field Description static intDEFAULT_MAXIMUM_URL_LENGTHThe default value of the threshold for URL length, beyond which we use the POST method for SPARQL query requests.static intMAXIMUM_URL_LENGTHDeprecated.useDEFAULT_MAXIMUM_URL_LENGTHinstead.static StringMAXIMUM_URL_LENGTH_PARAMSystem property for configuration of URL length threshold:rdf4j.sparql.url.maxlength.protected static CharsetUTF8
-
Constructor Summary
Constructors Constructor Description SPARQLProtocolSession(org.apache.http.client.HttpClient client, ExecutorService executor)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description voidclose()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.Map<String,String>getAdditionalHttpHeaders()Get the additional HTTP headers which will be usedprotected TupleQueryResultgetBackgroundTupleQueryResult(org.apache.http.client.methods.HttpUriRequest method, WeakReference<?> callerRef)Parse the response in a background thread.protected booleangetBoolean(org.apache.http.client.methods.HttpUriRequest method)Parse the response in this thread using a suitableBooleanQueryResultParser.longgetConnectionTimeout()Gets the http connection read timeout in milliseconds.protected ErrorInfogetErrorInfo(org.apache.http.HttpResponse response)org.apache.http.client.HttpClientgetHttpClient()HttpClientthat has been assigned or has been used by this object.protected org.apache.http.protocol.HttpContextgetHttpContext()Get theHttpContextused for sending HTTP requests.ParserConfiggetParserConfig()BooleanQueryResultFormatgetPreferredBooleanQueryResultFormat()Gets the preferredBooleanQueryResultFormatfor encoding boolean query results.RDFFormatgetPreferredRDFFormat()Gets the preferredRDFFormatfor encoding RDF documents.TupleQueryResultFormatgetPreferredTupleQueryResultFormat()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)StringgetQueryURL()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)Parse the response in a background thread.protected 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)StringgetUpdateURL()ValueFactorygetValueFactory()booleanisPassThroughEnabled()Indicates 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)GraphQueryResultsendGraphQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, WeakReference<?> callerRef, Binding... bindings)voidsendGraphQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, RDFHandler handler, Binding... bindings)GraphQueryResultsendGraphQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, WeakReference<?> callerRef, Binding... bindings)voidsendGraphQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, RDFHandler handler, Binding... bindings)TupleQueryResultsendTupleQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, WeakReference<?> callerRef, Binding... bindings)voidsendTupleQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, TupleQueryResultHandler handler, Binding... bindings)TupleQueryResultsendTupleQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, WeakReference<?> callerRef, Binding... bindings)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.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.voidsetPreferredBooleanQueryResultFormat(BooleanQueryResultFormat format)Sets the preferred format for encoding boolean query results.voidsetPreferredRDFFormat(RDFFormat format)Sets the preferred format for encoding RDF documents.voidsetPreferredTupleQueryResultFormat(TupleQueryResultFormat format)Sets 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 Detail
-
UTF8
protected static final Charset UTF8
-
DEFAULT_MAXIMUM_URL_LENGTH
public static final int DEFAULT_MAXIMUM_URL_LENGTH
The 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:
- Constant Field Values
-
MAXIMUM_URL_LENGTH
@Deprecated public static final int MAXIMUM_URL_LENGTH
Deprecated.useDEFAULT_MAXIMUM_URL_LENGTHinstead.- See Also:
- Constant Field Values
-
MAXIMUM_URL_LENGTH_PARAM
public static final String 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:
- Constant Field Values
-
-
Constructor Detail
-
SPARQLProtocolSession
public SPARQLProtocolSession(org.apache.http.client.HttpClient client, ExecutorService executor)
-
-
Method Detail
-
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
public void setValueFactory(ValueFactory valueFactory)
-
getValueFactory
public ValueFactory getValueFactory()
-
setQueryURL
protected void setQueryURL(String queryURL)
-
setUpdateURL
protected void setUpdateURL(String updateURL)
-
setPreferredTupleQueryResultFormat
public void setPreferredTupleQueryResultFormat(TupleQueryResultFormat format)
Sets the preferred format for encoding tuple query results.- Parameters:
format- The preferredTupleQueryResultFormat, or null to indicate no specific format is preferred.
-
getPreferredTupleQueryResultFormat
public TupleQueryResultFormat 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
public void setPreferredRDFFormat(RDFFormat format)
Sets the preferred format for encoding RDF documents.- Parameters:
format- The preferredRDFFormat, or null to indicate no specific format is preferred.
-
getPreferredRDFFormat
public RDFFormat getPreferredRDFFormat()
- Returns:
- The preferred format, of null if no specific format is preferred.
-
setPreferredBooleanQueryResultFormat
public void setPreferredBooleanQueryResultFormat(BooleanQueryResultFormat format)
Sets the preferred format for encoding boolean query results.- Parameters:
format- The preferredBooleanQueryResultFormat, or null to indicate no specific format is preferred.
-
getPreferredBooleanQueryResultFormat
public BooleanQueryResultFormat 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
public void setUsernameAndPassword(String username, String password)
Set the username and password for authentication with the remote server.- Parameters:
username- the usernamepassword- the password
-
setUsernameAndPasswordForUrl
protected void setUsernameAndPasswordForUrl(String username, String password, String url)
-
getQueryURL
public String getQueryURL()
-
getUpdateURL
public String getUpdateURL()
-
close
public void close()
- Specified by:
closein interfaceAutoCloseable
-
sendTupleQuery
public TupleQueryResult sendTupleQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, WeakReference<?> callerRef, Binding... bindings) throws IOException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException
-
sendTupleQuery
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
-
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
public GraphQueryResult sendGraphQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, WeakReference<?> callerRef, Binding... bindings) throws IOException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException
-
sendGraphQuery
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
-
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
public Map<String,String> 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
public void setAdditionalHttpHeaders(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.- 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
protected boolean shouldUsePost(String fullQueryUrl)
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
protected List<org.apache.http.NameValuePair> getQueryMethodParameters(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings)
-
getUpdateMethodParameters
protected List<org.apache.http.NameValuePair> getUpdateMethodParameters(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings)
-
getUpdateMethodParameters
protected List<org.apache.http.NameValuePair> getUpdateMethodParameters(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings)
-
getBackgroundTupleQueryResult
protected TupleQueryResult getBackgroundTupleQueryResult(org.apache.http.client.methods.HttpUriRequest method, WeakReference<?> callerRef) throws RepositoryException, QueryInterruptedException, MalformedQueryException, IOException
Parse 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, QueryInterruptedExceptionParse the response in this thread using the providedTupleQueryResultHandler. All HTTP connections are closed and released in this method
-
getRDFBackground
protected GraphQueryResult getRDFBackground(org.apache.http.client.methods.HttpUriRequest method, boolean requireContext, WeakReference<?> callerRef) throws IOException, RDFHandlerException, RepositoryException, MalformedQueryException, UnauthorizedException, QueryInterruptedException
Parse 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, QueryInterruptedExceptionParse 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, RDF4JExceptionParse 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, RDF4JExceptionConvenience 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
protected String getResponseMIMEType(org.apache.http.HttpResponse method) throws IOException
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
protected ErrorInfo getErrorInfo(org.apache.http.HttpResponse response) throws RepositoryException
- Throws:
RepositoryException
-
setParserConfig
public void setParserConfig(ParserConfig parserConfig)
Sets the parser configuration used to process HTTP response data.- Parameters:
parserConfig- The parserConfig to set.
-
getParserConfig
public ParserConfig 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.
-
-