This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/docs by this push:
new 4c43cb0ed2 docs: document JDK HttpClient as the built-in default
transport (TODO-41) and finish TODO-42 docs
4c43cb0ed2 is described below
commit 4c43cb0ed2932286223be656f615ed981ac34d95
Author: James Bognar <[email protected]>
AuthorDate: Tue May 19 10:26:07 2026 -0400
docs: document JDK HttpClient as the built-in default transport (TODO-41)
and finish TODO-42 docs
- 12.15.NextGenRestClient.md, 20.03.JuneauShadedRestClient.md: drop the
juneau-rest-client-java-httpclient row from the transport table and
rework the surrounding prose to call out the JDK HttpClient transport
as built into juneau-rest-client (the default) with the four sibling
transport modules as opt-in overrides via ServiceLoader.
- pages/release-notes/9.5.0.md: refresh the TODO-38 transport table to
delete the JDK row and add a new "JDK HttpClient is now the built-in
default transport (TODO-41)" section with usage examples.
- 09.01.JuneauRestCommonBasics.md: previously-unpushed TODO-42 rewrite
describing the juneau-rest-common / juneau-rest-common-classic split.
- 23.01.V9.5-migration-guide.md: previously-unpushed TODO-42 migration
rows for the rest-common split and the EntityTag/EntityTags moves.
No migration-guide row was added for TODO-41 —
juneau-rest-client-java-httpclient
was never released, so no downstream consumer can have referenced it.
---
pages/release-notes/9.5.0.md | 57 ++++++++++++++++++++++++--
pages/topics/09.01.JuneauRestCommonBasics.md | 61 +++++++++++++++++++++-------
pages/topics/12.15.NextGenRestClient.md | 16 ++++----
pages/topics/20.03.JuneauShadedRestClient.md | 4 +-
pages/topics/23.01.V9.5-migration-guide.md | 31 ++++++++++++++
5 files changed, 143 insertions(+), 26 deletions(-)
diff --git a/pages/release-notes/9.5.0.md b/pages/release-notes/9.5.0.md
index 03ecc69d96..928482f2fb 100644
--- a/pages/release-notes/9.5.0.md
+++ b/pages/release-notes/9.5.0.md
@@ -2117,17 +2117,18 @@ The legacy Apache HttpClient 4.5–based client moved to
`org.apache.juneau.rest
#### Transport Implementations
-Each transport is an independent module pulling in only its native client. The
`HttpTransportProvider` `ServiceLoader` entries let
`RestClient.create().build()` auto-discover the highest-priority transport on
the classpath.
+The JDK `HttpClient`–based `JavaHttpTransport` ships built into the canonical
`juneau-rest-client` artifact and is the default — `RestClient.create()` works
out of the box on Java 11+ with zero third-party dependencies (see TODO-41
below).
+
+To swap in a different native HTTP client, add one of the optional transport
modules. Each registers a higher-priority `HttpTransportProvider` via
`ServiceLoader`, so `RestClient.create().build()` automatically picks it up.
| Module | Artifact ID | Native client |
|---|---|---|
| Apache HttpClient 4.5 | `juneau-rest-client-apache-httpclient-45` |
`org.apache.httpcomponents:httpclient:4.5.x` |
| Apache HttpClient 5 | `juneau-rest-client-apache-httpclient-50` |
`org.apache.httpcomponents.client5:httpclient5` |
-| JDK `HttpClient` | `juneau-rest-client-java-httpclient` |
`java.net.http.HttpClient` (Java 11+) — zero third-party deps |
| OkHttp | `juneau-rest-client-okhttp` | `com.squareup.okhttp3:okhttp` |
| Eclipse Jetty client | `juneau-rest-client-jetty` |
`org.eclipse.jetty:jetty-client` |
-Each transport module ships `*Transport`, `*TransportBuilder` (with native
client–specific configuration accessible via cast), and `*TransportProvider`.
Common transport-builder configuration (`connectTimeout`, `readTimeout`,
`sslContext`, `hostnameVerifier`, `proxy`, `maxConnections`,
`maxConnectionsPerRoute`, `followRedirects`, …) lives on `HttpTransportBuilder`
so most callers don't need to cast.
+Each optional transport module ships `*Transport`, `*TransportBuilder` (with
native client–specific configuration accessible via cast), and
`*TransportProvider`. Common transport-builder configuration (`connectTimeout`,
`readTimeout`, `sslContext`, `hostnameVerifier`, `proxy`, `maxConnections`,
`maxConnectionsPerRoute`, `followRedirects`, …) lives on `HttpTransportBuilder`
so most callers don't need to cast.
#### `juneau-rest-mock` — `org.apache.juneau.rest.mock`
@@ -2149,6 +2150,23 @@ The pre-existing Apache HttpClient 4.5–based REST client
moved into a new sibl
Both modules can be on the classpath simultaneously — they share
`juneau-rest-common` but expose disjoint packages. The aggregator artifacts
(`juneau-shaded-rest-client`, `juneau-shaded-all`, `juneau-microservice`,
`juneau-rest-mock`, `juneau-distrib`) pull in both flavors so existing
assemblies see no behavioral change.
+### `juneau-rest-common` split into `juneau-rest-common` +
`juneau-rest-common-classic` (TODO-42)
+
+Mirroring the `juneau-rest-client` split above, the `juneau-rest-common`
module is now split into a pure transport-neutral module and a new sibling that
owns every Apache HttpClient 4.5–compatible facade.
+
+| Artifact | Contents | Apache HttpClient 4.5 dependency? |
+|---|---|---|
+| `juneau-rest-common` | Transport-neutral types under
`org.apache.juneau.http.*` (annotations, lazy header beans, remote-proxy meta,
parts, entities, `HttpHeaders` factory), plus
`org.apache.juneau.http.remote.*`. | **No.** Zero `org.apache.httpcomponents:*`
on the classpath. |
+| `juneau-rest-common-classic` (new) | Every type formerly at
`org.apache.juneau.http.classic.*` — Apache HttpClient 4.5–style headers,
parts, entities, resources, responses, the classic `HeaderList`, and the
classic `Remote*Meta` proxy bridges. **FQCNs unchanged** — only the Maven
coordinate moved. | **Yes.** Depends on `org.apache.juneau:juneau-rest-common`
and `org.apache.httpcomponents:httpcore:4.4.16`. |
+
+**Why:** `juneau-rest-common` was the last `juneau-rest-*` module forcing
`org.apache.httpcomponents:httpcore` onto every downstream consumer
(transports, microservices, examples, mock). Splitting it lets the canonical NG
stack ship genuinely transport-neutral.
+
+**Backward compatibility:**
+- Fully qualified class names are unchanged —
`org.apache.juneau.http.classic.header.EntityTag` is still
`org.apache.juneau.http.classic.header.EntityTag`. Source-compatible.
+- Code that already depended on `juneau-rest-common` and used a `classic.*`
type now needs an additional `<dependency>` on `juneau-rest-common-classic`.
The aggregator artifacts (`juneau-rest-server`, `juneau-rest-client-classic`,
`juneau-rest-mock`, `juneau-microservice`, `juneau-rest-server-springboot`,
`juneau-shaded-rest-server`, `juneau-shaded-rest-client`, `juneau-shaded-all`,
`juneau-distrib`) already pull both modules in transitively, so most callers
see no Maven change.
+- `EntityTag` / `EntityTags` value types (no HC 4.5 dependency, despite the
historical package) moved out of `classic.header` to
`org.apache.juneau.http.header.EntityTag` / `EntityTags`. **This is a
source-incompatible change** for any caller that imported them explicitly — see
the v9.5 migration guide.
+- `@Remote(headerList = ...)` annotation method changed from `Class<? extends
HeaderList>` to `Class<?>`. Existing user annotations like `@Remote(headerList
= MyHeaderList.class)` continue to work; the classic `RemoteMeta` performs an
`instanceof HeaderList` check at runtime before invoking. The default sentinel
changed from `HeaderList.Void.class` to `java.lang.Void.class`.
+
#### Usage Examples
```java
@@ -2199,6 +2217,39 @@ The classic `RestClient` / `juneau-rest-common` APIs
remain fully supported. Mig
The classic stack is **not** deprecated in 9.5; the canonical stack will
graduate to stable in a future release, at which point the classic stack may be
deprecated and eventually removed.
+### JDK `HttpClient` is now the built-in default transport (TODO-41)
+
+The JDK `java.net.http.HttpClient`–based transport (`JavaHttpTransport`) is
now part of the `juneau-rest-client` artifact itself. The previously separate
`juneau-rest-client-java-httpclient` module — which had no third-party
dependencies and was never released — has been folded in and removed.
+
+**What this means for callers:**
+
+- `RestClient.create()` works out of the box on Java 11+ with **zero**
third-party dependencies. No transport module is required for a baseline HTTP
client.
+- The four remaining sibling transport modules
(`juneau-rest-client-apache-httpclient-45`, `-apache-httpclient-50`, `-okhttp`,
`-jetty`) continue to register higher-priority providers via `ServiceLoader`
and automatically take over discovery when added to the classpath.
+- Explicit `RestClient.builder().transport(...)` always wins over
auto-discovery.
+- `RestClient.discoverTransport()` now falls back to
`JavaHttpTransport.create()` when `ServiceLoader` returns no providers (a
defensive measure for heavily-shaded uber-jars that strip `META-INF/services`
files).
+
+**Package promotion:**
+
+`JavaHttpTransport`, `JavaHttpTransportBuilder`, and
`JavaHttpTransportProvider` were promoted from
`org.apache.juneau.rest.client.javahttpclient.*` to the canonical
`org.apache.juneau.rest.client.*` package root. No previously released version
exposed the `javahttpclient` package, so this is an internal restructuring of
unreleased beta code — no migration steps required.
+
+```java
+// Zero-config: uses the built-in JavaHttpTransport
+try (var req = RestClient.create().get("https://api.example.com/users";)) {
+ var users = req.run().as(User[].class);
+}
+
+// Explicit tuning of the JDK client
+var transport = JavaHttpTransport.builder()
+ .httpClient(java.net.http.HttpClient.newBuilder()
+ .connectTimeout(Duration.ofSeconds(5))
+ .build())
+ .build();
+RestClient client = RestClient.builder().transport(transport).build();
+
+// Or swap to a different transport entirely just by adding its module
+// (no code change needed — ServiceLoader picks up the higher-priority
provider)
+```
+
### juneau-bean-mcp (new module)
A new bean module, `juneau-bean-mcp`, models the [Model Context
Protocol](https://modelcontextprotocol.io/) wire format as Juneau `@Bean`
POJOs. The beans round-trip cleanly through any Juneau serializer/parser (JSON,
JSON5, MessagePack, CBOR, YAML, etc.) and were the foundation for
`juneau-rest-server-mcp`.
diff --git a/pages/topics/09.01.JuneauRestCommonBasics.md
b/pages/topics/09.01.JuneauRestCommonBasics.md
index 273caf05b7..0acb93a1cd 100644
--- a/pages/topics/09.01.JuneauRestCommonBasics.md
+++ b/pages/topics/09.01.JuneauRestCommonBasics.md
@@ -3,8 +3,17 @@ title: "juneau-rest-common Basics"
slug: JuneauRestCommonBasics
---
+`juneau-rest-common` ships as two sibling Maven artifacts:
+
+| Artifact | Contents | Apache HttpClient 4.5 dependency? |
+|---|---|---|
+| `juneau-rest-common` | Transport-neutral types under
`org.apache.juneau.http.*` and `org.apache.juneau.http.remote.*` — annotations,
lazy header beans, remote-proxy meta, transport-neutral parts. Used by every
`juneau-rest-*` module. | **No.** Zero `org.apache.httpcomponents:*` on the
classpath. |
+| `juneau-rest-common-classic` | Apache HttpClient 4.5–compatible facades
under `org.apache.juneau.http.classic.*` — `BasicHeader`,
`BasicMediaTypeHeader`, `BasicHttpEntity`, `BasicHttpResponse`,
response/exception classes, `HeaderList`, etc. (~170 types). | **Yes.** Depends
on `juneau-rest-common` and `org.apache.httpcomponents:httpcore:4.4.16`. |
+
#### Maven Dependency
+For NG (transport-neutral) consumers — the canonical path:
+
```xml
<dependency>
<groupId>org.apache.juneau</groupId>
@@ -13,37 +22,61 @@ slug: JuneauRestCommonBasics
</dependency>
```
+For code that uses any `org.apache.juneau.http.classic.*` facade (e.g.
`BasicHeader`, `BasicHttpResponse`, `HeaderList`), add **both** artifacts:
+
+```xml
+<dependency>
+ <groupId>org.apache.juneau</groupId>
+ <artifactId>juneau-rest-common</artifactId>
+ <version>${juneau.version}</version>
+</dependency>
+<dependency>
+ <groupId>org.apache.juneau</groupId>
+ <artifactId>juneau-rest-common-classic</artifactId>
+ <version>${juneau.version}</version>
+</dependency>
+```
+
+The aggregator artifacts (`juneau-rest-server`, `juneau-rest-client-classic`,
`juneau-rest-mock`, `juneau-microservice`, `juneau-rest-server-springboot`,
`juneau-shaded-rest-server`, `juneau-shaded-rest-client`, `juneau-shaded-all`,
`juneau-distrib`) already pull both modules in transitively, so most callers
don't need to declare them directly.
+
#### Java Library
```text
juneau-rest-common-0.0.0.jar
+juneau-rest-common-classic-0.0.0.jar
```
#### OSGi Module
```text
org.apache.juneau.rest.common_0.0.0.jar
+org.apache.juneau.rest.common.classic_0.0.0.jar
```
#### Contents/Features
-The <a href="/site/apidocs/org/apache/juneau/http/package-summary.html"
target="_blank">org.apache.juneau.http</a> package contains a slew of useful
extensions to the Apache
-HttpComponents libraries and define APIs used extensively in the REST server
and client APIs.
+The transport-neutral packages in `juneau-rest-common`:
<tree>
-<node-0>HTTP Packages</node-0>
-<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/package-summary.html"
target="_blank">org.apache.juneau.http</a></java-package> - Utility classes
used for HTTP parts/headers/entities.</node-1>
+<node-0>Transport-neutral HTTP packages (no Apache HttpClient 4.5
dependency)</node-0>
+<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/package-summary.html"
target="_blank">org.apache.juneau.http</a></java-package> - Static
`HttpHeaders` factory facade and shared utilities.</node-1>
<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/annotation/package-summary.html"
target="_blank">org.apache.juneau.http.annotation</a></java-package> -
Swagger-based annotations used on both server-side APIs and client-side proxy
interfaces.</node-1>
-<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/entity/package-summary.html"
target="_blank">org.apache.juneau.http.entity</a></java-package> - HTTP entity
classes.</node-1>
-<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/header/package-summary.html"
target="_blank">org.apache.juneau.http.header</a></java-package> - HTTP header
classes.</node-1>
+<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/header/package-summary.html"
target="_blank">org.apache.juneau.http.header</a></java-package> -
Lazy-resolved HTTP header beans (no Apache `Header` interface dependency) and
the `EntityTag` / `EntityTags` value types.</node-1>
<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/part/package-summary.html"
target="_blank">org.apache.juneau.http.part</a></java-package> - HTTP
query/form-data/path classes.</node-1>
-<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/remote/package-summary.html"
target="_blank">org.apache.juneau.http.remote</a></java-package> - Remote proxy
interface API</node-1>
-<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/resource/package-summary.html"
target="_blank">org.apache.juneau.http.resource</a></java-package> - HTTP
resource classes.</node-1>
-<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/response/package-summary.html"
target="_blank">org.apache.juneau.http.response</a></java-package> - HTTP
response classes.</node-1>
+<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/remote/package-summary.html"
target="_blank">org.apache.juneau.http.remote</a></java-package> - `@Remote` /
`@RemoteOp` / `@RemoteGet` / etc. proxy-interface annotations.</node-1>
+</tree>
+
+The Apache HttpClient 4.5–compatible facades in `juneau-rest-common-classic`:
+
+<tree>
+<node-0>Apache HttpClient 4.5–compatible facades</node-0>
+<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/classic/package-summary.html"
target="_blank">org.apache.juneau.http.classic</a></java-package> - Classic
`HttpHeaders`, `HttpEntities`, `HttpResponses`, `HttpParts` facades.</node-1>
+<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/classic/entity/package-summary.html"
target="_blank">org.apache.juneau.http.classic.entity</a></java-package> - HTTP
entity classes built on `org.apache.http.HttpEntity`.</node-1>
+<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/classic/header/package-summary.html"
target="_blank">org.apache.juneau.http.classic.header</a></java-package> - HTTP
header classes built on `org.apache.http.Header`, plus `HeaderList`.</node-1>
+<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/classic/part/package-summary.html"
target="_blank">org.apache.juneau.http.classic.part</a></java-package> - HTTP
part classes built on `org.apache.http.NameValuePair`.</node-1>
+<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/classic/remote/package-summary.html"
target="_blank">org.apache.juneau.http.classic.remote</a></java-package> -
Classic RRPC interface meta types used by the classic REST client.</node-1>
+<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/classic/resource/package-summary.html"
target="_blank">org.apache.juneau.http.classic.resource</a></java-package> -
HTTP resource classes (entity + headers bundle).</node-1>
+<node-1><java-package><a
href="/site/apidocs/org/apache/juneau/http/classic/response/package-summary.html"
target="_blank">org.apache.juneau.http.classic.response</a></java-package> -
HTTP response / exception classes built on
`org.apache.http.HttpResponse`.</node-1>
</tree>
-These APIs extend from the Apache HttpComponents libraries and can be used
with libraries based on it such as Apache
-HttpClient.
-The REST Client API described later is built on top of Apache HttpClient and
many of the classes defined in this package
-make up integral components of that API.
-Likewise, the APIs defined here are also used in the REST Server APIs also
described later.
+These classic APIs extend the Apache HttpComponents 4.5 libraries and are
consumed by `juneau-rest-server`, `juneau-rest-client-classic`, and
`juneau-rest-mock` (classic flavor). The canonical NG REST client built on top
of `juneau-rest-common` is fully decoupled from Apache HttpClient.
diff --git a/pages/topics/12.15.NextGenRestClient.md
b/pages/topics/12.15.NextGenRestClient.md
index c6d3a814ac..18cdf7c869 100644
--- a/pages/topics/12.15.NextGenRestClient.md
+++ b/pages/topics/12.15.NextGenRestClient.md
@@ -45,19 +45,22 @@ The next-generation stack:
## Transport Modules
-Each transport is a separate Maven module pulling in only its native HTTP
client.
-The `HttpTransportProvider` `ServiceLoader` SPI auto-discovers the
highest-priority transport
-on the classpath at `build()` time when no explicit transport is passed.
+The JDK `HttpClient`–based `JavaHttpTransport` is built into the canonical
`juneau-rest-client`
+artifact and is the default — it requires no third-party dependencies on Java
11+.
+
+To swap to a different native HTTP client, add one of the optional transport
modules below. Each
+ships only its own native client and registers a higher-priority
`HttpTransportProvider` via
+`ServiceLoader`, which automatically takes over discovery. An explicit
+`RestClient.builder().transport(...)` call always wins.
| Module | Artifact ID | Native client |
|---|---|---|
| Apache HttpClient 4.5 | `juneau-rest-client-apache-httpclient-45` |
`org.apache.httpcomponents:httpclient:4.5.x` |
| Apache HttpClient 5 | `juneau-rest-client-apache-httpclient-50` |
`org.apache.httpcomponents.client5:httpclient5` |
-| JDK `HttpClient` | `juneau-rest-client-java-httpclient` |
`java.net.http.HttpClient` (Java 11+) — zero third-party deps |
| OkHttp | `juneau-rest-client-okhttp` | `com.squareup.okhttp3:okhttp` |
| Eclipse Jetty client | `juneau-rest-client-jetty` |
`org.eclipse.jetty:jetty-client` |
-Each module ships three classes:
+Each optional module ships three classes:
- `*Transport` — the `HttpTransport` implementation.
- `*TransportBuilder` — extends `HttpTransportBuilder` with
native-client–specific options
@@ -177,10 +180,9 @@ Logging is framework-agnostic via
`java.lang.System.Logger`:
```java
RestClient client = RestClient.create()
- .transportBuilder(JavaHttpTransport.create())
.marshaller(Json5.DEFAULT)
.logger(BasicRestLogger.of(System.getLogger("myapp.http")))
- .build();
+ .build(); // uses the built-in JavaHttpTransport by default
// Per-request verbose logging
try (var req = client.get("/users/123").debug()) {
diff --git a/pages/topics/20.03.JuneauShadedRestClient.md
b/pages/topics/20.03.JuneauShadedRestClient.md
index 32e1593f8e..976e94305e 100644
--- a/pages/topics/20.03.JuneauShadedRestClient.md
+++ b/pages/topics/20.03.JuneauShadedRestClient.md
@@ -70,10 +70,10 @@ java_binary(
`juneau-shaded-rest-client` requires:
### Required
-- **Apache HttpClient 4.5.x** - bundled via `juneau-rest-client-classic` for
the legacy client. The canonical `juneau-rest-client` artifact itself has **no
Apache HttpClient dependency** — it composes any `HttpTransport` implementation
you put on the classpath (HC 4.5, HC 5, JDK `HttpClient`, OkHttp, Jetty client,
or a custom transport).
+- **Apache HttpClient 4.5.x** - bundled via `juneau-rest-client-classic` for
the legacy client. The canonical `juneau-rest-client` artifact itself has **no
Apache HttpClient dependency** — it ships with a built-in `JavaHttpTransport`
backed by the JDK's `java.net.http.HttpClient` and works out of the box on Java
11+.
### Optional
-- **Apache HttpClient 5.x** / **`java.net.http.HttpClient`** / **OkHttp** /
**Jetty client** - pick one of the `juneau-rest-client-apache-httpclient-50` /
`juneau-rest-client-java-httpclient` / `juneau-rest-client-okhttp` /
`juneau-rest-client-jetty` transport modules to drive the canonical
`RestClient` over a non-HC-4.5 transport.
+- **Apache HttpClient 4.5.x** / **Apache HttpClient 5.x** / **OkHttp** /
**Jetty client** - to swap the default JDK-`HttpClient`-based transport for a
different native HTTP client, pull in one of the
`juneau-rest-client-apache-httpclient-45` /
`juneau-rest-client-apache-httpclient-50` / `juneau-rest-client-okhttp` /
`juneau-rest-client-jetty` transport modules. Each registers a higher-priority
`HttpTransportProvider` via `ServiceLoader` and is picked up automatically.
- **Jakarta XML Bind API 3.0+** - For XML serialization
- **Apache Jena** - For RDF support
diff --git a/pages/topics/23.01.V9.5-migration-guide.md
b/pages/topics/23.01.V9.5-migration-guide.md
index 003f51ff4b..a38f51cda4 100644
--- a/pages/topics/23.01.V9.5-migration-guide.md
+++ b/pages/topics/23.01.V9.5-migration-guide.md
@@ -339,5 +339,36 @@ The package promotion changes the canonical imports for
every `juneau-rest-commo
The new canonical `org.apache.juneau.http.*` (and sub-packages `entity` /
`header` / `part` / `response`) host the JDK-native NG types. The
`org.apache.juneau.http.remote.*` annotation package (`@Remote`, `@RemoteGet`,
etc.) **did not move**.
+## `juneau-rest-common` Module Split (TODO-42)
+
+Continues the work started in TODO-38: `juneau-rest-common` is now split into
a pure, transport-neutral module and a new sibling that owns every Apache
HttpClient 4.5–style facade. After the split, `juneau-rest-common` no longer
drags `org.apache.httpcomponents:httpcore` onto every downstream consumer.
+
+### Maven module changes
+
+| Old (single artifact) | New (two artifacts) | Notes |
+|-----|-----|-------|
+| `<artifactId>juneau-rest-common</artifactId>` *(carries `httpcore`
transitively)* | `<artifactId>juneau-rest-common</artifactId>`
*(transport-neutral, **no** `httpcore`)* **and/or**
`<artifactId>juneau-rest-common-classic</artifactId>` *(new, depends on
`httpcore`)* | Code using only `org.apache.juneau.http.*` /
`org.apache.juneau.http.header.*` / `org.apache.juneau.http.remote.*` /
`org.apache.juneau.http.part.*` / `org.apache.juneau.http.entity.*` /
`org.apache.juneau.http.response.* [...]
+
+### Class moves (source-incompatible)
+
+`EntityTag` and `EntityTags` are pure value types with no `org.apache.http.*`
dependency despite their historical package. They moved out of
`org.apache.juneau.http.classic.header` so the transport-neutral header beans
that already stored them (`HttpEntityTagHeader`, `HttpEntityTagsHeader`,
`IfMatch`, `IfNoneMatch`, `IfRange`, `ETag`, top-level `HttpHeaders`) can stay
free of the classic dependency.
+
+| Old | New | Notes |
+|-----|-----|-------|
+| `import org.apache.juneau.http.classic.header.EntityTag;` | `import
org.apache.juneau.http.header.EntityTag;` | Update the import. FQCN is the only
thing that changed; constructor / `of(...)` / accessors are unchanged. |
+| `import org.apache.juneau.http.classic.header.EntityTags;` | `import
org.apache.juneau.http.header.EntityTags;` | Update the import. FQCN is the
only thing that changed. |
+
+Every other `org.apache.juneau.http.classic.*` type stayed in place — only the
**Maven coordinate** that publishes them moved. `import
org.apache.juneau.http.classic.header.HeaderList;` still resolves; you just
need `juneau-rest-common-classic` on the classpath rather than
`juneau-rest-common`.
+
+### `@Remote` annotation change
+
+`@Remote` is transport-neutral (both the NG and classic clients consume it).
To keep `@Remote` out of the classic Maven coordinate, the `headerList()`
method's return type was widened from `Class<? extends HeaderList>` to
`Class<?>`, and the default sentinel changed from `HeaderList.Void.class` to
`java.lang.Void.class`.
+
+| Old | New | Notes |
+|-----|-----|-------|
+| `@Remote(headerList = MyHeaderList.class)` *(where `MyHeaderList extends
org.apache.juneau.http.classic.header.HeaderList`)* | `@Remote(headerList =
MyHeaderList.class)` *(unchanged)* | Source-compatible — user annotations
continue to work. The classic `RemoteMeta` now performs an `instanceof
HeaderList` check at runtime before invoking the constructor, so
non-`HeaderList` values are silently ignored rather than causing a
`ClassCastException`. |
+| `Class<? extends HeaderList> hl =
Remote.class.getMethod("headerList").getReturnType().asSubclass(HeaderList.class);`
| `Class<?> hl = remoteAnnotation.headerList();` followed by an explicit
`isAssignableFrom` check before use. | Reflective callers must cast/check
explicitly. |
+| `Remote.headerList()` default was `HeaderList.Void.class`. | Default is
`java.lang.Void.class`. | The framework's `isVoid` check still recognizes the
default and skips header-list resolution. |
+
<!-- Additional rows will be populated as 9.5 breaking changes land. See
todo/TODO-17 for the
ongoing 9.5.0 audit. -->
