Module org.apache.jena.arq

Package org.apache.jena.http

Class HttpLib

java.lang.Object

org.apache.jena.http.HttpLib

public class HttpLib
extends Object

Operations related to SPARQL HTTP requests - Query, Update and Graph Store protocols. This class is not considered "API".

Field Summary

Fields

Modifier and Type	Field	Description
static String	BEARER
static String	BEARER_PREFIX
static String	FusekiRequestIdHeader

Method Summary

Modifier and Type	Method	Description
static HttpRequest.Builder	acceptHeader(HttpRequest.Builder builder, String acceptHeader)	Set the "Accept" header if value is not null.
static String	basicAuth(String username, String password)	Calculate basic auth header value.
static String	bearerAuthHeader(String tokenBase64)	Calculate bearer auth header value.
static String	bearerAuthTokenFromHeader(String authHeaderString)	Extract the token, without decoding, The token supplied is expected to already be in base 64.
static HttpRequest.Builder	contentTypeHeader(HttpRequest.Builder builder, String contentType)	Set the "Content-Type" header if value is not null.
static <X> List<X>	copyArray(List<X> array)
static HttpRequest.Builder	createBuilder(HttpRequest request)	Create a HttpRequest.Builder from an HttpRequest.
static <X> X	dft(X value, X dftValue)
static String	endpoint(String uriStr)	Return a string (assumed to be an absolute URI) without query string or fragment.
static URI	endpointURI(URI uri)	URI, without query string and fragment.
static HttpResponse<InputStream>	execute(HttpClient httpClient, HttpRequest httpRequest)	Execute a request, return a HttpResponse<InputStream> which can be passed to handleResponseInputStream(HttpResponse) which will convert non-2xx status code to HttpExceptions.
static CompletableFuture<HttpResponse<InputStream>>	executeAsync(HttpClient httpClient, HttpRequest httpRequest)	Execute a request, return a HttpResponse<X> which can be passed to handleHttpStatusCode(HttpResponse) which will convert non-2xx status code to HttpExceptions.
static <T> HttpResponse<T>	executeJDK(HttpClient httpClient, HttpRequest httpRequest, HttpResponse.BodyHandler<T> bodyHandler)	Execute request and return a response without authentication challenge handling.
static CompletableFuture<HttpResponse<InputStream>>	executeJDKAsync(HttpClient httpClient, HttpRequest httpRequest)	Execute request and return a HttpResponse<InputStream> response.
static <T> CompletableFuture<HttpResponse<T>>	executeJDKAsync(HttpClient httpClient, HttpRequest httpRequest, HttpResponse.BodyHandler<T> bodyHandler)
static void	finishInputStream(InputStream input)	Read to end of InputStream.
static void	finishResponse(HttpResponse<InputStream> response)	Finish with HttpResponse<InputStream>.
static InputStream	getInputStream(HttpResponse<InputStream> httpResponse)	Get the InputStream from an HttpResponse, handling possible compression settings.
static void	handleHttpStatusCode(HttpResponse<InputStream> response)	Deal with status code and any error message sent as a body in the response.
static InputStream	handleResponseInputStream(HttpResponse<InputStream> httpResponse)	Handle the HTTP response (see handleHttpStatusCode(HttpResponse)) and return the InputStream if a 200.
static void	handleResponseNoBody(HttpResponse<InputStream> response)	Handle the HTTP response and consume the body if a 200.
static String	handleResponseRtnString(HttpResponse<InputStream> response)	Handle the HTTP response and read the body to produce a string if a 200.
static String	handleResponseRtnString(HttpResponse<InputStream> response, Consumer<InputStream> callback)	Handle the HTTP response and read the body to produce a string if a 200.
static TypedInputStream	handleResponseTypedInputStream(HttpResponse<InputStream> httpResponse)	Handle the HTTP response (see handleHttpStatusCode(HttpResponse)) and return the TypedInputStream that includes the Content-Type if a 200.
static void	httpPushData(HttpClient httpClient, Push style, String url, Consumer<HttpRequest.Builder> modifier, HttpRequest.BodyPublisher body)	Push data.
static HttpResponse<InputStream>	httpPushWithResponse(HttpClient httpClient, Push style, String url, Consumer<HttpRequest.Builder> modifier, HttpRequest.BodyPublisher body)
static boolean	isEndpoint(URI uri)	Test whether a URI is a service endpoint.
static boolean	isFuseki(String datasetURL)	Test whether a URL identifies a Fuseki server.
static void	modifyByService(String serviceURI, Context context, Params params, Map<String,String> httpHeaders)	Allow setting additional/optional HTTP headers and query parameters on a per remote service (including for SERVICE) basis.
static HttpRequest	newGetRequest(String url, Consumer<HttpRequest.Builder> modifier)	Return a HttpRequest
static HttpResponse.BodyHandler<Void>	noBody()
static HttpRequest.Builder	requestBuilder(String url, Map<String,String> httpHeaders, long readTimeout, TimeUnit readTimeoutUnit)
static HttpRequest.Builder	requestBuilderFor(String serviceEndpoint)
static String	requestTargetServer(URI uri)	The "request target" for digest auth.
static String	requestURL(String url, String queryString)	Query string is assumed to already be encoded.
static String	responseHeader(HttpResponse<?> response, String headerName)	Return the first header of the given name, or null if none
static Consumer<HttpRequest.Builder>	setHeaders(Map<String,String> headers)	Return a modifier that will set headers using the values in the map.
static HttpRequest.BodyPublisher	stringBody(String str)
static URI	toRequestURI(String uriStr)	String to URI.
static String	urlEncodeQueryString(String str)	Encode a string suitable for use in an URL query string

Methods inherited from class java.lang.Object

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

Field Details

BEARER

public static String BEARER

BEARER_PREFIX

public static String BEARER_PREFIX

FusekiRequestIdHeader

public static String FusekiRequestIdHeader

Method Details

noBody

public static HttpResponse.BodyHandler<Void> noBody()

stringBody

public static HttpRequest.BodyPublisher stringBody(String str)

basicAuth

public static String basicAuth(String username,
 String password)

Calculate basic auth header value. Use with header "Authorization" (constant HttpNames.hAuthorization). Best used over https.

bearerAuthHeader

public static String bearerAuthHeader(String tokenBase64)

Calculate bearer auth header value. The token supplied is expected to already be in base 64. Use with header "Authorization" (constant HttpNames.hAuthorization).

bearerAuthTokenFromHeader

public static String bearerAuthTokenFromHeader(String authHeaderString)

Extract the token, without decoding, The token supplied is expected to already be in base 64. Use with header "Authorization" (constant HttpNames.hAuthorization).

getInputStream

public static InputStream getInputStream(HttpResponse<InputStream> httpResponse)

Get the InputStream from an HttpResponse, handling possible compression settings. The application must consume or close the InputStream (see finishInputStream(InputStream)). Closing the InputStream may close the HTTP connection. Assumes the status code has been handled e.g. handleHttpStatusCode(java.net.http.HttpResponse<java.io.InputStream>) has been called.

handleHttpStatusCode

public static void handleHttpStatusCode(HttpResponse<InputStream> response)

Deal with status code and any error message sent as a body in the response.

It is this handling 4xx/5xx error messages in the body that forces the use of InputStream, not generic T. We don't know until we see the status code how we are going to process the response body.

Exits normally without processing the body if the response is 200.

Throws HttpException for 3xx (redirection should have happened by now), 4xx and 5xx, having consumed the body input stream.

handleResponseInputStream

public static InputStream handleResponseInputStream(HttpResponse<InputStream> httpResponse)

Handle the HTTP response (see handleHttpStatusCode(HttpResponse)) and return the InputStream if a 200.

Parameters:

httpResponse -

Returns:

InputStream

handleResponseTypedInputStream

public static TypedInputStream handleResponseTypedInputStream(HttpResponse<InputStream> httpResponse)

Handle the HTTP response (see handleHttpStatusCode(HttpResponse)) and return the TypedInputStream that includes the Content-Type if a 200.

Parameters:

httpResponse -

Returns:

TypedInputStream

handleResponseNoBody

public static void handleResponseNoBody(HttpResponse<InputStream> response)

Handle the HTTP response and consume the body if a 200. Otherwise, throw an HttpException.

Parameters:

response -

handleResponseRtnString

public static String handleResponseRtnString(HttpResponse<InputStream> response)

Handle the HTTP response and read the body to produce a string if a 200. Otherwise, throw an HttpException.

Parameters:

response -

Returns:

String

handleResponseRtnString

public static String handleResponseRtnString(HttpResponse<InputStream> response,
 Consumer<InputStream> callback)

Handle the HTTP response and read the body to produce a string if a 200. Otherwise, throw an HttpException.

Parameters:

response -

callback - A callback that receives the opened input stream.

Returns:

String

finishResponse

public static void finishResponse(HttpResponse<InputStream> response)

Finish with HttpResponse<InputStream>. This read and drops any remaining bytes in the response body. close may close the underlying HTTP connection. See HttpResponse.BodySubscribers.ofInputStream().

finishInputStream

public static void finishInputStream(InputStream input)

Read to end of InputStream. close may close the underlying HTTP connection. See HttpResponse.BodySubscribers.ofInputStream().

toRequestURI

public static URI toRequestURI(String uriStr)

String to URI. Throws HttpException on bad syntax or if the URI isn't absolute.

isEndpoint

public static boolean isEndpoint(URI uri)

Test whether a URI is a service endpoint. It must be absolute, with host and path, and without query string or fragment.

endpoint

public static String endpoint(String uriStr)

Return a string (assumed to be an absolute URI) without query string or fragment.

endpointURI

public static URI endpointURI(URI uri)

URI, without query string and fragment.

requestTargetServer

public static String requestTargetServer(URI uri)

The "request target" for digest auth. The server-side name of a resource - no authority (the host part).

RFC 7616 (digest auth), section 3.4 The Effective Request URI (Section 5.5 of RFC7230).

For SPARQL, the target is the service, not a resource named by the uri+query string.

This makes query-by-GET and query-by-POST work the same way.

newGetRequest

public static HttpRequest newGetRequest(String url,
 Consumer<HttpRequest.Builder> modifier)

Return a HttpRequest

dft

public static <X> X dft(X value,
 X dftValue)

copyArray

public static <X> List<X> copyArray(List<X> array)

urlEncodeQueryString

public static String urlEncodeQueryString(String str)

Encode a string suitable for use in an URL query string

requestURL

public static String requestURL(String url,
 String queryString)

Query string is assumed to already be encoded.

requestBuilderFor

public static HttpRequest.Builder requestBuilderFor(String serviceEndpoint)

requestBuilder

public static HttpRequest.Builder requestBuilder(String url,
 Map<String,String> httpHeaders,
 long readTimeout,
 TimeUnit readTimeoutUnit)

createBuilder

public static HttpRequest.Builder createBuilder(HttpRequest request)

Create a HttpRequest.Builder from an HttpRequest.

acceptHeader

public static HttpRequest.Builder acceptHeader(HttpRequest.Builder builder,
 String acceptHeader)

Set the "Accept" header if value is not null. Returns the builder.

contentTypeHeader

public static HttpRequest.Builder contentTypeHeader(HttpRequest.Builder builder,
 String contentType)

Set the "Content-Type" header if value is not null. Returns the builder.

execute

public static HttpResponse<InputStream> execute(HttpClient httpClient,
 HttpRequest httpRequest)

Execute a request, return a HttpResponse<InputStream> which can be passed to handleResponseInputStream(HttpResponse) which will convert non-2xx status code to HttpExceptions.

This function applies the HTTP authentication challenge support and will repeat the request if necessary with added authentication.

See AuthEnv for authentication registration.
See executeJDK(java.net.http.HttpClient, java.net.http.HttpRequest, java.net.http.HttpResponse.BodyHandler<T>) to execute exactly once without challenge response handling.

Parameters:

httpClient -

httpRequest -

Returns:

HttpResponse

See Also:

• AuthEnv for authentic registration
• executeJDK to execute exacly once.

executeAsync

public static CompletableFuture<HttpResponse<InputStream>> executeAsync(HttpClient httpClient,
 HttpRequest httpRequest)

Execute a request, return a HttpResponse<X> which can be passed to handleHttpStatusCode(HttpResponse) which will convert non-2xx status code to HttpExceptions.

This function applies the HTTP authentication challenge support and will repeat the request if necessary with added authentication.

See AuthEnv for authentication registration.
See executeJDK(java.net.http.HttpClient, java.net.http.HttpRequest, java.net.http.HttpResponse.BodyHandler<T>) to execute exactly once without challenge response handling.

Parameters:

httpClient -

httpRequest -

Returns:

HttpResponse

See Also:

• AuthEnv for authentic registration
• executeJDK to execute exacly once.

executeJDK

public static <T> HttpResponse<T> executeJDK(HttpClient httpClient,
 HttpRequest httpRequest,
 HttpResponse.BodyHandler<T> bodyHandler)

Execute request and return a response without authentication challenge handling. Status codes have not been handled. This is a call to HttpClient.send converting exceptions to HttpException. request and responses are logged as "debug" to logger org.apache.jena.http.HTTP.

Parameters:

httpClient -

httpRequest -

bodyHandler -

Returns:

HttpResponse

executeJDKAsync

public static CompletableFuture<HttpResponse<InputStream>> executeJDKAsync(HttpClient httpClient,
 HttpRequest httpRequest)

Execute request and return a HttpResponse<InputStream> response. Status codes have not been handled. The response can be passed to handleResponseInputStream(HttpResponse) which will convert non-2xx status code to HttpExceptions.

Parameters:

httpClient -

httpRequest -

Returns:

HttpResponse

executeJDKAsync

public static <T>
CompletableFuture<HttpResponse<T>> executeJDKAsync(HttpClient httpClient,
 HttpRequest httpRequest,
 HttpResponse.BodyHandler<T> bodyHandler)

httpPushData

public static void httpPushData(HttpClient httpClient,
 Push style,
 String url,
 Consumer<HttpRequest.Builder> modifier,
 HttpRequest.BodyPublisher body)

Push data. POST, PUT, PATCH request with no response body data.

httpPushWithResponse

public static HttpResponse<InputStream> httpPushWithResponse(HttpClient httpClient,
 Push style,
 String url,
 Consumer<HttpRequest.Builder> modifier,
 HttpRequest.BodyPublisher body)

modifyByService

public static void modifyByService(String serviceURI,
 Context context,
 Params params,
 Map<String,String> httpHeaders)

Allow setting additional/optional HTTP headers and query parameters on a per remote service (including for SERVICE) basis.

• ARQ.httpRequestModifer - the specific modifier
• ARQ.httpRegistryRequestModifer - the registry, keyed by service URL.

setHeaders

public static Consumer<HttpRequest.Builder> setHeaders(Map<String,String> headers)

Return a modifier that will set headers using the values in the map. An argument of "null" means "no action".

responseHeader

public static String responseHeader(HttpResponse<?> response,
 String headerName)

Return the first header of the given name, or null if none

isFuseki

public static boolean isFuseki(String datasetURL)

Test whether a URL identifies a Fuseki server. This operation can not guarantee to detect a Fuseki server - for example, it may be behind a reverse proxy that masks the signature.