Skip to content

Commit 6feeaa2

Browse files
aschwarte10aschwarte10
committed
GH-5723: upgrade notes for HTTP client facade
1 parent dd4b2bb commit 6feeaa2

1 file changed

Lines changed: 142 additions & 0 deletions

File tree

‎site/content/release-notes/6.0.0-M1.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: "6.0.0 Milestone 1"
3+
toc: true
4+
---
5+
RDF4J 6.0.0-M1 is the first Milestone build of the upcoming 6.0.0 release of RDF4J.
6+
7+
RDF4J 6.0.0 is a major release of the RDF4J framework.
8+
9+
Some of the highlights covered in this first milestone:
10+
11+
- Upgrade to Java 25 as the minimally-required version of Java
12+
- Introduction of a pluggable HTTP client SPI with Apache HttpComponents 5 and JDK built-in backends
13+
- Migration from Apache HttpComponents 4 to the new HTTP client facade
14+
15+
This milestone build is not yet feature-complete, but we are putting it out to receive early feedback on all the improvements we have put in.
16+
17+
- [issues fixed in 6.0.0 Milestone 1](https://github.com/eclipse-rdf4j/rdf4j/issues?q=is%3Aissue+label%3AM1+is%3Aclosed+milestone%3A6.0.0)
18+
- [issues planned for 6.0.0](https://github.com/eclipse-rdf4j/rdf4j/milestone/TODO)
19+
20+
# Upgrade notes
21+
22+
RDF4J 6.0.0 contains several [backward incompatible changes](https://github.com/eclipse-rdf4j/rdf4j/issues?q=is%3Aclosed+is%3Aissue+label%3A%22%E2%9B%94+Not+backwards+compatible%22+milestone%3A6.0.0).
23+
24+
## HTTP client migration (Apache HttpComponents 4 removed)
25+
26+
RDF4J previously used Apache HttpComponents 4 (AHC4) as its sole HTTP client, with AHC4 types directly exposed in the public API. In 6.0.0, this dependency has been replaced by a new HTTP-client-agnostic facade. Apache HC4 is no longer on the classpath for the general use of RDF4J.
27+
28+
### User-facing changes
29+
30+
**No dependency changes required for most users.** The `rdf4j-http-client` artifact continues to bundle both built-in backend implementations as runtime dependencies, so upgrading the RDF4J version is sufficient for standard use cases.
31+
32+
Two HTTP client backends are now available:
33+
34+
- **Apache HttpComponents 5** (`rdf4j-http-client-apache5`) — the default backend when on the classpath.
35+
- **JDK built-in HTTP client** (`rdf4j-http-client-jdk`) — a zero-dependency alternative using `java.net.http.HttpClient` (JDK 11+).
36+
37+
To select a specific backend, set the system property `rdf4j.http.client.factory` to either `apache5` or `jdk`:
38+
39+
```
40+
-Drdf4j.http.client.factory=jdk
41+
```
42+
43+
If you previously configured connection pooling or timeouts via system properties on `SharedHttpClientSessionManager`, those properties are still supported:
44+
45+
- `org.eclipse.rdf4j.client.http.maxConnPerRoute` (default: 25)
46+
- `org.eclipse.rdf4j.client.http.maxConnTotal` (default: 50)
47+
- `org.eclipse.rdf4j.client.http.connectionTimeout` (default: 30 000 ms)
48+
- `org.eclipse.rdf4j.client.http.connectionRequestTimeout`
49+
50+
If you need a minimal-footprint deployment without Apache HC5, exclude `rdf4j-http-client-apache5` and ensure `rdf4j-http-client-jdk` is on the classpath.
51+
52+
### Developer-facing changes
53+
54+
#### Removed public API: Apache HC4 types
55+
56+
The following methods previously exposed `org.apache.http.client.HttpClient` (AHC4) in the public API and have been replaced ([GH-5723](https://github.com/eclipse-rdf4j/rdf4j/issues/5723)):
57+
58+
| Old method | Replacement |
59+
|---|---|
60+
| `HttpClientDependent#getHttpClient()` returns `org.apache.http.client.HttpClient` | Returns `org.eclipse.rdf4j.http.client.spi.RDF4JHttpClient` |
61+
| `HttpClientDependent#setHttpClient(HttpClient)` | Accepts `org.eclipse.rdf4j.http.client.spi.RDF4JHttpClient` |
62+
| `HttpClientSessionManager#getHttpClient()` returns `org.apache.http.client.HttpClient` | Returns `org.eclipse.rdf4j.http.client.spi.RDF4JHttpClient` |
63+
64+
If your code calls `setHttpClient()` with a custom Apache HC4 client, you must migrate to the new API (see below).
65+
66+
#### New HTTP client SPI (`rdf4j-http-client-api`)
67+
68+
A new module, `rdf4j-http-client-api`, defines the HTTP client facade with no third-party HTTP dependencies. The key types are:
69+
70+
- `RDF4JHttpClientFactory` — SPI interface discovered via `java.util.ServiceLoader`. Implement this to plug in a custom HTTP backend.
71+
- `RDF4JHttpClient` — the HTTP client interface used internally by `SPARQLProtocolSession` and `RDF4JProtocolSession`.
72+
- `RDF4JHttpClientConfig` — immutable configuration object (timeouts, connection pooling, SSL, default headers), constructed via a builder.
73+
- `RDF4JHttpClients` — utility class for obtaining the default factory or creating clients.
74+
75+
#### Configuring the HTTP client programmatically
76+
77+
Use `RDF4JHttpClientConfig` and `RDF4JHttpClients` to create a configured client and pass it to a repository or session:
78+
79+
```java
80+
RDF4JHttpClientConfig config = RDF4JHttpClientConfig.newBuilder()
81+
.connectTimeoutMs(5_000)
82+
.socketTimeoutMs(30_000)
83+
.maxConnectionsPerRoute(10)
84+
.build();
85+
86+
RDF4JHttpClient client = RDF4JHttpClients.newDefaultClient(config);
87+
88+
HTTPRepository repo = new HTTPRepository("http://localhost:8080/rdf4j-server/repositories/myrepo");
89+
repo.setHttpClient(client);
90+
```
91+
92+
#### SSL configuration
93+
94+
The previous `HttpClientBuilders.getSSLTrustAllHttpClientBuilder()` helper (which returned an AHC4 builder) has been replaced by `HttpClientBuilders.getSslTrustAllConfig()`, which returns an `RDF4JHttpClientConfig`:
95+
96+
```java
97+
// Old (AHC4, removed):
98+
// HttpClient client = HttpClientBuilders.getSSLTrustAllHttpClientBuilder().build();
99+
100+
// New:
101+
RDF4JHttpClientConfig config = HttpClientBuilders.getSslTrustAllConfig();
102+
RDF4JHttpClient client = RDF4JHttpClients.newDefaultClient(config);
103+
repo.setHttpClient(client);
104+
```
105+
106+
#### Authentication
107+
108+
Authentication is now handled via the `AuthenticationHandler` SPI rather than Apache HC4 credential stores. Two built-in implementations are provided:
109+
110+
- `BasicAuthenticationHandler` — adds an `Authorization: Basic <base64>` header to every request.
111+
- `BearerTokenAuthenticationHandler` — adds an `Authorization: Bearer <token>` header, with optional support for a dynamic token producer to handle short-lived tokens (e.g. OAuth).
112+
113+
```java
114+
// Basic auth
115+
session.setAuthenticationHandler(new BasicAuthenticationHandler("user", "secret"));
116+
117+
// Bearer token (static)
118+
session.setAuthenticationHandler(new BearerTokenAuthenticationHandler("my-token"));
119+
120+
// Bearer token (dynamic, e.g. refreshing OAuth token)
121+
session.setAuthenticationHandler(new BearerTokenAuthenticationHandler(tokenStore::currentToken));
122+
```
123+
124+
#### Custom HTTP client backend
125+
126+
To provide a fully custom HTTP backend, implement `RDF4JHttpClientFactory` and register it as a `java.util.ServiceLoader` service in `META-INF/services/org.eclipse.rdf4j.http.client.spi.RDF4JHttpClientFactory`.
127+
128+
To extend the Apache HC5 backend with additional configuration (e.g. custom interceptors or connection managers), subclass `ApacheHC5RDF4JHttpClientFactory` and override `buildHttpClient(HttpClientBuilder, RDF4JHttpClientConfig)`:
129+
130+
```java
131+
public class MyFactory extends ApacheHC5RDF4JHttpClientFactory {
132+
@Override
133+
protected CloseableHttpClient buildHttpClient(HttpClientBuilder builder, RDF4JHttpClientConfig config) {
134+
builder.addRequestInterceptorFirst(myInterceptor);
135+
return super.buildHttpClient(builder, config);
136+
}
137+
}
138+
```
139+
140+
## Acknowledgements
141+
142+
This milestone was made possible by contributions from ...

0 commit comments

Comments
 (0)