GH-5723: maintain documentation for http client update

programming/setup.md

  Removed the outdated paragraph that instructed users to include the
jcl-over-slf4j bridge because "RDF4J internally uses the Apache Commons
HttpClient, which relies on JCL". Since AHC4 is gone, this requirement
no longer exists. The surrounding general advice about
  SLF4J bridges and the "single logger config" conclusion were
preserved.

programming/repository.md

  Replaced the brief "Configuring the HTTP session thread pool" section
with a fuller "Configuring the HTTP client" section covering:

  - HTTP client backends — Apache HC5 (default) vs JDK, and the
rdf4j.http.client.factory system property
  - Connection pooling, timeouts, and SSL — RDF4JHttpClientConfig
builder example, system properties table, and
HttpClientBuilders.getSslTrustAllConfig() for SSL trust-all
  - Thread pool — existing content preserved as a sub-section
  - Authentication — BasicAuthenticationHandler and
BearerTokenAuthenticationHandler examples

  The authentication section uses session.setAuthenticationHandler(...)

Author: aschwarte10

site/content/documentation/programming/repository.md

@@ -226,14 +226,59 @@ Repository repo = new SPARQLRepository(sparqlEndpoint);
 
 After you have done this, you can query the SPARQL endpoint just as you would any other type of Repository.
 
-#### Configuring the HTTP session thread pool
+#### Configuring the HTTP client
 
 Both the HTTPRepository and the SPARQLRepository use the SPARQL Protocol over
 HTTP under the hood (in the case of the HTTPRepository, it uses the extended
 RDF4J REST API). The HTTP client session is managed by the {{< javadoc
 "HttpClientSessionManager"
-"http/client/HttpClientSessionManager.html" >}}, which in turn depends
-on the Apache HttpClient.
+"http/client/HttpClientSessionManager.html" >}}.
+
+##### HTTP client backends
+
+RDF4J ships with two HTTP client backends:
+
+- **Apache HttpComponents 5** (`rdf4j-http-client-apache5`) — the preferred backend when multiple backends are available.
+- **JDK built-in HTTP client** (`rdf4j-http-client-jdk`) — a zero-dependency alternative using `java.net.http.HttpClient`.
+
+Both are included as runtime dependencies of `rdf4j-http-client`. Backend selection works as follows: if the system property `rdf4j.http.client.factory` is set, that backend is used; otherwise RDF4J prefers `apache5` when it is available, and if only one backend factory is present on the classpath, that backend becomes the default.
+
+##### Connection pooling, timeouts, and SSL
+
+HTTP client settings are configured via {{< javadoc "RDF4JHttpClientConfig" "http/client/spi/RDF4JHttpClientConfig.html" >}}, which is built using a fluent builder and passed to the repository:
+
+```java
+import org.eclipse.rdf4j.http.client.spi.RDF4JHttpClientConfig;
+import org.eclipse.rdf4j.http.client.spi.RDF4JHttpClients;
+
+RDF4JHttpClientConfig config = RDF4JHttpClientConfig.newBuilder()
+        .connectTimeoutMs(5_000)
+        .socketTimeoutMs(30_000)
+        .maxConnectionsPerRoute(10)
+        .maxConnectionsTotal(25)
+        .build();
+
+repo.setHttpClient(RDF4JHttpClients.newDefaultClient(config));
+```
+
+Connection pool size and timeouts can also be set globally via system properties on {{< javadoc "SharedHttpClientSessionManager" "http/client/SharedHttpClientSessionManager.html" >}}:
+
+| System property | Default | Description |
+|---|---|---|
+| `org.eclipse.rdf4j.client.http.maxConnPerRoute` | 25 | Max connections per host |
+| `org.eclipse.rdf4j.client.http.maxConnTotal` | 50 | Max total connections |
+| `org.eclipse.rdf4j.client.http.connectionTimeout` | 30 000 ms | TCP connection timeout |
+| `org.eclipse.rdf4j.client.http.connectionRequestTimeout` | — | Time to wait for a pooled connection |
+
+For SSL trust-all (e.g. self-signed certificates in test environments), use the {{< javadoc "HttpClientBuilders" "http/client/util/HttpClientBuilders.html" >}} utility. **Warning:** this disables SSL certificate validation and hostname verification, and must not be used in production.
+
+```java
+import org.eclipse.rdf4j.http.client.util.HttpClientBuilders;
+
+repo.setHttpClient(RDF4JHttpClients.newDefaultClient(HttpClientBuilders.getSslTrustAllConfig()));
+```
+
+##### Thread pool
 
 The session uses a caching thread pool executor to handle multithreaded
 access to a remote endpoint, defined by default to use a thread pool with a
@@ -243,6 +288,24 @@ To configure this to use a different core pool size, you can specify the
 `org.eclipse.rdf4j.client.executors.corePoolSize` system property with a
 different number.
 
+##### Authentication
+
+For HTTP-based repositories, basic authentication can be configured directly on the repository. If you need bearer-token authentication, configure a custom session manager that installs an {{< javadoc "AuthenticationHandler" "http/client/spi/AuthenticationHandler.html" >}} on each created {{< javadoc "SPARQLProtocolSession" "http/client/SPARQLProtocolSession.html" >}}:
+
+```java
+import org.eclipse.rdf4j.http.client.spi.BasicAuthenticationHandler;
+import org.eclipse.rdf4j.http.client.spi.BearerTokenAuthenticationHandler;
+
+// Basic authentication
+session.setAuthenticationHandler(new BasicAuthenticationHandler("user", "secret"));
+
+// Bearer token (static)
+session.setAuthenticationHandler(new BearerTokenAuthenticationHandler("my-token"));
+
+// Bearer token (dynamic, e.g. refreshing OAuth access token)
+session.setAuthenticationHandler(new BearerTokenAuthenticationHandler(tokenStore::currentToken));
+```
+
 ### The RepositoryManager and RepositoryProvider
 
 Using what we’ve seen in the previous section, we can create and use various different types of repositories. However, when developing an application in which you have to keep track of several repositories, sharing references to these repositories between different parts of your code can become complex. The {{< javadoc "RepositoryManager" "repository/manager/RepositoryManager.html" >}} and {{< javadoc "RepositoryProvider" "repository/manager/RepositoryProvider.html" >}} provide one central location where all information on the repositories in use (including id, type, directory for persistent data storage, etc.) is kept.

site/content/documentation/programming/setup.md

@@ -134,10 +134,6 @@ What you need to do is to decide which logging implementation you are going to u
 
 One thing to keep in mind when configuring logging is that SLF4J expects only a single logger implementation on the classpath. Thus, you should choose only a single logger. In addition, if parts of your code depend on projects that use other logging frameworks directly, you can include a Legacy Bridge which makes sure calls to the legacy logger get redirected to SLF4J (and from there on, to your logger of choice).
 
-In particular, when working with RDF4J’s HTTPRepository or SPARQLRepository libraries, you should include the `jcl-over-slf4j` legacy bridge. This is because RDF4J internally uses the Apache Commons HttpClient, which relies on JCL (Jakarta Commons Logging). You can do without this if your own app is a webapp, to be deployed in e.g. Tomcat, but otherwise, your application will probably show a lot of debug log messages on standard output, starting with something like:
-
-    DEBUG httpclient.wire.header
-
-When you set this up correctly, you can have a single logger configuration for your entire project, and you will be able to control both this kind of logging by third party libraries and by RDF4J itself using this single config.
+When you set this up correctly, you can have a single logger configuration for your entire project, and you will be able to control logging by third party libraries and by RDF4J itself using this single config.
 
 The RDF4J framework itself does not prescribe a particular logger implementation (after all, that’s the whole point of SLF4J, that you get to choose your preferred logger). However, several of the applications included in RDF4J (such as RDF4J Server, Workbench, and the command line console) do use a logger implementation. The server and console application both use logback, which is the successor to log4j and a native implementation of SLF4J. The Workbench uses `java.util.logging` instead.