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, SparqlSession

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, 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:

RDF4JProtocolSession, SPARQL 1.1 Protocol (W3C Recommendation)

Field Summary

Fields

Modifier and Type	Field and Description
static 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.
static int	MAXIMUM_URL_LENGTH Deprecated. use DEFAULT_MAXIMUM_URL_LENGTH instead.
static String	MAXIMUM_URL_LENGTH_PARAM System property for configuration of URL length threshold: rdf4j.sparql.url.maxlength.
protected static Charset	UTF8

Constructor Summary

Constructors

Constructor and Description
SPARQLProtocolSession(org.apache.http.client.HttpClient client, ExecutorService executor)

Method Summary

Modifier and Type	Method and Description
void	close()
protected org.apache.http.HttpResponse	execute(org.apache.http.client.methods.HttpUriRequest method)
protected void	executeNoContent(org.apache.http.client.methods.HttpUriRequest method)
protected org.apache.http.HttpResponse	executeOK(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 used
protected TupleQueryResult	getBackgroundTupleQueryResult(org.apache.http.client.methods.HttpUriRequest method) Parse the response in a background thread.
protected boolean	getBoolean(org.apache.http.client.methods.HttpUriRequest method) Parse the response in this thread using a suitable BooleanQueryResultParser.
long	getConnectionTimeout() Gets the http connection read timeout in milliseconds.
protected ErrorInfo	getErrorInfo(org.apache.http.HttpResponse response)
org.apache.http.client.HttpClient	getHttpClient() HttpClient that has been assigned or has been used by this object.
ParserConfig	getParserConfig()
BooleanQueryResultFormat	getPreferredBooleanQueryResultFormat() Gets the preferred BooleanQueryResultFormat for encoding boolean query results.
RDFFormat	getPreferredRDFFormat() Gets the preferred RDFFormat for encoding RDF documents.
TupleQueryResultFormat	getPreferredTupleQueryResultFormat() Gets the preferred TupleQueryResultFormat for encoding tuple query results.
protected org.apache.http.client.methods.HttpUriRequest	getQueryMethod(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)
String	getQueryURL()
protected void	getRDF(org.apache.http.client.methods.HttpUriRequest method, RDFHandler handler, boolean requireContext) Parse the response in this thread using the provided RDFHandler.
protected GraphQueryResult	getRDFBackground(org.apache.http.client.methods.HttpUriRequest method, boolean requireContext) Parse the response in a background thread.
protected String	getResponseMIMEType(org.apache.http.HttpResponse method) Gets the MIME type specified in the response headers of the supplied method, if any.
protected void	getTupleQueryResult(org.apache.http.client.methods.HttpUriRequest method, TupleQueryResultHandler handler) Parse the response in this thread using the provided TupleQueryResultHandler.
protected org.apache.http.client.methods.HttpUriRequest	getUpdateMethod(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings)
protected org.apache.http.client.methods.HttpUriRequest	getUpdateMethod(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)
protected List<org.apache.http.NameValuePair>	getUpdateMethodParameters(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings)
String	getUpdateURL()
ValueFactory	getValueFactory()
boolean	sendBooleanQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, Binding... bindings)
boolean	sendBooleanQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings)
GraphQueryResult	sendGraphQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, Binding... bindings)
void	sendGraphQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, RDFHandler handler, Binding... bindings)
GraphQueryResult	sendGraphQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings)
void	sendGraphQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, RDFHandler handler, Binding... bindings)
TupleQueryResult	sendTupleQuery(QueryLanguage ql, String query, Dataset dataset, boolean includeInferred, Binding... bindings)
TupleQueryResult	sendTupleQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings)
void	sendTupleQuery(QueryLanguage ql, String query, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, TupleQueryResultHandler handler, Binding... bindings)
void	sendUpdate(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, Binding... bindings)
void	sendUpdate(QueryLanguage ql, String update, String baseURI, Dataset dataset, boolean includeInferred, int maxQueryTime, Binding... bindings)
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.
void	setConnectionTimeout(long timeout) Sets the http connection read timeout.
void	setHttpClient(org.apache.http.client.HttpClient httpClient) Assign an HttpClient that this object should use.
void	setParserConfig(ParserConfig parserConfig) Sets the parser configuration used to process HTTP response data.
void	setPreferredBooleanQueryResultFormat(BooleanQueryResultFormat format) Sets the preferred format for encoding boolean query results.
void	setPreferredRDFFormat(RDFFormat format) Sets the preferred format for encoding RDF documents.
void	setPreferredTupleQueryResultFormat(TupleQueryResultFormat format) Sets the preferred format for encoding tuple query results.
protected void	setQueryURL(String queryURL)
protected void	setUpdateURL(String updateURL)
void	setUsernameAndPassword(String username, String password) Set the username and password for authentication with the remote server.
protected void	setUsernameAndPasswordForUrl(String username, String password, String url)
void	setValueFactory(ValueFactory valueFactory)
protected boolean	shouldUsePost(String fullQueryUrl) Return whether the provided query should use POST (otherwise use GET)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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. use DEFAULT_MAXIMUM_URL_LENGTH instead.

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: HttpClientDependent

HttpClient that 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 whether HttpClient was passed to or created by this object respectively.

Specified by:

getHttpClient in interface HttpClientDependent

Returns:

an HttpClient instance or null

setHttpClient

public void setHttpClient(org.apache.http.client.HttpClient httpClient)

Description copied from interface: HttpClientDependent

Assign an HttpClient that this object should use. The life cycle of the given HttpClient is 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:

setHttpClient in interface HttpClientDependent

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. The binary format is preferred by default.

Parameters:

format - The preferred TupleQueryResultFormat, or null to indicate no specific format is preferred.

getPreferredTupleQueryResultFormat

public TupleQueryResultFormat getPreferredTupleQueryResultFormat()

Gets the preferred TupleQueryResultFormat for encoding tuple query results.

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. The Turtle format is preferred by default.

Parameters:

format - The preferred RDFFormat, or null to indicate no specific format is preferred.

getPreferredRDFFormat

public RDFFormat getPreferredRDFFormat()

Gets the preferred RDFFormat for encoding RDF documents.

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. The binary format is preferred by default.

Parameters:

format - The preferred BooleanQueryResultFormat, or null to indicate no specific format is preferred.

getPreferredBooleanQueryResultFormat

public BooleanQueryResultFormat getPreferredBooleanQueryResultFormat()

Gets the preferred BooleanQueryResultFormat for encoding boolean query results.

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 username

password - 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:

close in interface AutoCloseable

sendTupleQuery

public TupleQueryResult sendTupleQuery(QueryLanguage ql,
                                       String query,
                                       Dataset dataset,
                                       boolean includeInferred,
                                       Binding... bindings)
                                throws IOException,
                                       RepositoryException,
                                       MalformedQueryException,
                                       UnauthorizedException,
                                       QueryInterruptedException

Throws:

IOException

RepositoryException

MalformedQueryException

UnauthorizedException

QueryInterruptedException

sendTupleQuery

public TupleQueryResult sendTupleQuery(QueryLanguage ql,
                                       String query,
                                       String baseURI,
                                       Dataset dataset,
                                       boolean includeInferred,
                                       int maxQueryTime,
                                       Binding... bindings)
                                throws IOException,
                                       RepositoryException,
                                       MalformedQueryException,
                                       UnauthorizedException,
                                       QueryInterruptedException

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

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

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

Throws:

IOException

RepositoryException

MalformedQueryException

UnauthorizedException

QueryInterruptedException

sendGraphQuery

public GraphQueryResult sendGraphQuery(QueryLanguage ql,
                                       String query,
                                       Dataset dataset,
                                       boolean includeInferred,
                                       Binding... bindings)
                                throws IOException,
                                       RepositoryException,
                                       MalformedQueryException,
                                       UnauthorizedException,
                                       QueryInterruptedException

Throws:

IOException

RepositoryException

MalformedQueryException

UnauthorizedException

QueryInterruptedException

sendGraphQuery

public GraphQueryResult sendGraphQuery(QueryLanguage ql,
                                       String query,
                                       String baseURI,
                                       Dataset dataset,
                                       boolean includeInferred,
                                       int maxQueryTime,
                                       Binding... bindings)
                                throws IOException,
                                       RepositoryException,
                                       MalformedQueryException,
                                       UnauthorizedException,
                                       QueryInterruptedException

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

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

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

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

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)
                                                  throws RepositoryException,
                                                         QueryInterruptedException,
                                                         MalformedQueryException,
                                                         IOException

Parse the response in a background thread. HTTP connections are dealt with in the BackgroundTupleResult or (in the error-case) in this method.

Throws:

RepositoryException

QueryInterruptedException

MalformedQueryException

IOException

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 provided TupleQueryResultHandler. All HTTP connections are closed and released in this method

Throws:

IOException

TupleQueryResultHandlerException

RepositoryException

MalformedQueryException

UnauthorizedException

QueryInterruptedException

getRDFBackground

protected GraphQueryResult getRDFBackground(org.apache.http.client.methods.HttpUriRequest method,
                                            boolean requireContext)
                                     throws IOException,
                                            RDFHandlerException,
                                            RepositoryException,
                                            MalformedQueryException,
                                            UnauthorizedException,
                                            QueryInterruptedException

Parse the response in a background thread. HTTP connections are dealt with in the BackgroundGraphResult or (in the error-case) in this method.

Throws:

IOException

RDFHandlerException

RepositoryException

MalformedQueryException

UnauthorizedException

QueryInterruptedException

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 provided RDFHandler. All HTTP connections are closed and released in this method

Throws:

IOException

RDFHandlerException

RepositoryException

MalformedQueryException

UnauthorizedException

QueryInterruptedException

getBoolean

protected boolean getBoolean(org.apache.http.client.methods.HttpUriRequest method)
                      throws IOException,
                             RDF4JException

Parse the response in this thread using a suitable BooleanQueryResultParser. All HTTP connections are closed and released in this method

Throws:

RDF4JException

IOException

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:

RDF4JException

IOException

executeNoContent

protected void executeNoContent(org.apache.http.client.methods.HttpUriRequest method)
                         throws IOException,
                                RDF4JException

Throws:

IOException

RDF4JException

execute

protected org.apache.http.HttpResponse execute(org.apache.http.client.methods.HttpUriRequest method)
                                        throws IOException,
                                               RDF4JException

Throws:

IOException

RDF4JException

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.