[java] deprecate the 'native' methods inside the HttpClient interface

[joerg1985]

🔗 Related Issues

#16781

🔧 Implementation Notes

This PR will also advise the agents to take care this will not happen again.
Though this is really basic java knowledge the agent should bring out of the box.

💡 Additional Considerations

🔄 Types of changes

• Cleanup (formatting, renaming)

[qodo-code-review]

Review Summary by Qodo

Deprecate native methods in HttpClient interface and add guidelines

✨ Enhancement 📝 Documentation

Walkthroughs

Description

• Deprecate native HTTP methods in HttpClient interface
• Add public accessor method to JdkHttpClient for underlying HttpClient
• Document interface design conventions in AGENTS.md
• Guide developers to use JdkHttpClient#client() instead of native methods

File Changes

1. java/src/org/openqa/selenium/remote/http/HttpClient.java ✨ Enhancement +6/-4

Deprecate native HTTP methods with replacement guidance

• Added @Deprecated(forRemoval = true) annotation to sendAsyncNative() method
• Added @Deprecated(forRemoval = true) annotation to sendNative() method
• Updated JavaDoc to reference JdkHttpClient#httpClient() as replacement
• Improved documentation formatting for deprecated methods

java/src/org/openqa/selenium/remote/http/HttpClient.java

---

2. java/src/org/openqa/selenium/remote/http/jdk/JdkHttpClient.java ✨ Enhancement +5/-0

Add public accessor for underlying HttpClient instance

• Added public client() accessor method to expose underlying HttpClient
• Method provides access to native java.net.http.HttpClient instance
• Includes JavaDoc explaining the method's purpose

java/src/org/openqa/selenium/remote/http/jdk/JdkHttpClient.java

---

3. java/AGENTS.md 📝 Documentation +3/-0

Document interface design conventions for developers

• Added new "Interfaces" section under Code conventions
• Documented requirement for default implementations in interface methods
• Added guideline against exposing native implementation classes in interfaces

java/AGENTS.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (2)   📘 Rule violations (1)   📎 Requirement gaps (0)   🎨 UX Issues (0)

🐞\ ☼ Reliability (1) ⚙ Maintainability (1)

📘\ ⚙ Maintainability (1)

1. Broken @deprecated reference 📘 ⚙

Description

The new @deprecated Javadoc for sendAsyncNative/sendNative points to
JdkHttpClient#httpClient(), but JdkHttpClient exposes client() instead, so the deprecation
message does not provide a valid migration path. This violates the requirement that deprecations
include a clear alternative.

Code

java/src/org/openqa/selenium/remote/http/HttpClient.java[R42-56]

  /**
-   * Sends an HTTP request using java.net.http.HttpClient and allows specifying the BodyHandler.
-   *
+   * @deprecated use JdkHttpClient#httpClient() instead Sends an HTTP request using
+   *     java.net.http.HttpClient and allows specifying the BodyHandler.
   * @param <T> the response body type
   * @param request the HTTP request to send
   * @param handler the BodyHandler that determines how to handle the response body
   * @return a CompletableFuture containing the HTTP response
   */
+  @Deprecated(forRemoval = true)
  <T> CompletableFuture<java.net.http.HttpResponse<T>> sendAsyncNative(
      java.net.http.HttpRequest request, java.net.http.HttpResponse.BodyHandler<T> handler);

  /**
-   * Sends an HTTP request using java.net.http.HttpClient and allows specifying the BodyHandler.
-   *
+   * @deprecated use JdkHttpClient#httpClient() instead Sends an HTTP request using
+   *     java.net.http.HttpClient and allows specifying the BodyHandler.

Evidence

PR Compliance ID 5 requires deprecations to include an alternative in the deprecation message. The
deprecation Javadoc references a non-existent alternative (JdkHttpClient#httpClient()), while the
implementation provides client(), making the message incorrect and non-actionable.

AGENTS.md
java/src/org/openqa/selenium/remote/http/HttpClient.java[42-56]
java/src/org/openqa/selenium/remote/http/jdk/JdkHttpClient.java[161-164]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`HttpClient#sendAsyncNative` and `HttpClient#sendNative` were deprecated with a Javadoc alternative pointing to `JdkHttpClient#httpClient()`, but `JdkHttpClient` does not define `httpClient()` (it defines `client()`). This makes the deprecation guidance incorrect.

## Issue Context
Compliance requires that deprecation messages include a valid alternative so users can migrate before removal.

## Fix Focus Areas
- java/src/org/openqa/selenium/remote/http/HttpClient.java[42-56]
- java/src/org/openqa/selenium/remote/http/jdk/JdkHttpClient.java[161-164]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. client() returns null 🐞 ☼

Description

JdkHttpClient#client() returns the internal java.net.http.HttpClient field directly, but close()
sets that field to null, so client() can return null at runtime. This exposes callers to a
NullPointerException when they try to use the returned HttpClient after the Selenium client is
closed.

Code

java/src/org/openqa/selenium/remote/http/jdk/JdkHttpClient.java[R161-164]

+  /** Will expose the underlying native HttpClient used. */
+  public java.net.http.HttpClient client() {
+    return client;
+  }

Evidence

The new accessor returns client as-is, and the existing close() implementation nulls out
this.client, so the accessor’s return value is not stable across the object lifecycle.

java/src/org/openqa/selenium/remote/http/jdk/JdkHttpClient.java[161-165]
java/src/org/openqa/selenium/remote/http/jdk/JdkHttpClient.java[583-610]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`JdkHttpClient#client()` can return `null` after `close()` because `close()` assigns `this.client = null`. This makes it easy for callers to hit a `NullPointerException` when using the returned JDK client.

### Issue Context
`client()` is a new public method intended to expose the underlying JDK client; it should have a clear/robust contract around closed state.

### Fix Focus Areas
- java/src/org/openqa/selenium/remote/http/jdk/JdkHttpClient.java[161-165]
- java/src/org/openqa/selenium/remote/http/jdk/JdkHttpClient.java[583-610]

### Implementation notes
- Prefer throwing an `IllegalStateException` (or similar) when `this.client` is `null` in `client()`.
- Alternatively, keep `client` non-null and rely on the underlying client/executor shutdown semantics, but then ensure resources are still released correctly.
- Update the Javadoc to specify behavior after `close()` (e.g., “throws if closed”).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Interface rule unclear 🐞 ⚙

Description

AGENTS.md states “Interfaces must not expose the native classes of their implementations” without
scoping it to new APIs or acknowledging transitional deprecated APIs. HttpClient still contains
deprecated methods exposing java.net.http types, so the guideline can be read as contradicting the
current codebase during the deprecation window.

Code

java/AGENTS.md[R15-17]

+### Interfaces
+- New methods added to existing interfaces must provide a default implementation, if possible.
+- Interfaces must not expose the native classes of their implementations.

Evidence

The new convention is absolute as written, while HttpClient still publicly exposes native
java.net.http types (even though those methods are now deprecated).

java/AGENTS.md[14-18]
java/src/org/openqa/selenium/remote/http/HttpClient.java[31-67]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
AGENTS.md introduces an absolute rule about interface-native type exposure, but the codebase currently contains deprecated legacy interface methods that still expose native types. The guideline should clarify scope to avoid ambiguity for contributors.

### Issue Context
The PR is explicitly deprecating legacy native-method exposure on `HttpClient`, so a short clarification would align the guidance with the transition plan.

### Fix Focus Areas
- java/AGENTS.md[14-18]

### Implementation notes
- Reword the bullet to scope it to *new* interface methods (e.g., “New interface methods must not…”), or add a short note that legacy APIs may remain temporarily while deprecated-for-removal.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

ⓘ The new review experience is currently in Beta. Learn more