[java] JSpecify annotations for `org.openqa.selenium.net` by mk868 · Pull Request #16463 · SeleniumHQ/selenium

mk868 · 2025-10-18T10:46:45Z

User description

🔗 Related Issues

Related #14291

💥 What does this PR do?

JSpecify annotations added to the:

org.openqa.selenium.net.LinuxEphemeralPortRangeDetector
org.openqa.selenium.net.NetworkUtils
org.openqa.selenium.net.PortProber
org.openqa.selenium.net.UrlChecker
org.openqa.selenium.net.Urls

🔧 Implementation Notes

💡 Additional Considerations

🔄 Types of changes

New feature (non-breaking change which adds functionality and tests!)

PR Type

Enhancement

Description

Add JSpecify @NullMarked annotations to five net package classes
Mark nullable fields and return types with @nullable annotation
Add null-safety checks using Require.nonNull() for guaranteed non-null returns
Improve type safety and null-handling in NetworkUtils class

Diagram Walkthrough

flowchart LR
  A["Five net package classes"] -->|Add @NullMarked| B["Class-level null contracts"]
  A -->|Mark nullable fields| C["@Nullable annotations"]
  A -->|Add null checks| D["Require.nonNull() calls"]
  B --> E["Improved type safety"]
  C --> E
  D --> E

File Walkthrough

Relevant files

Enhancement

LinuxEphemeralPortRangeDetector.java `Add JSpecify @NullMarked annotation` java/src/org/openqa/selenium/net/LinuxEphemeralPortRangeDetector.java Add @NullMarked class-level annotation Import org.jspecify.annotations.NullMarked	+2/-0
NetworkUtils.java `Add comprehensive null-safety annotations and checks` java/src/org/openqa/selenium/net/NetworkUtils.java Add @NullMarked class-level annotation and @nullable imports Mark four fields as @nullable (cachedIp4NonLoopbackAddressOfThisMachine, cachedIp4NonLoopbackAddressHostName, hostname, address) Add Require.nonNull() checks in getHostname() and getHostAddress() methods Mark three method return types as @nullable (getNonLoopbackAddressOfThisMachine, obtainLoopbackIp4Address, getIpOfLoopBackIp4) Add null-safety check for loopback InetAddress in obtainLoopbackIp4Address() Mark getLoopBackAndIp4Only() return type as @nullable	+18/-11
PortProber.java `Add JSpecify @NullMarked annotation` java/src/org/openqa/selenium/net/PortProber.java Add @NullMarked class-level annotation Import org.jspecify.annotations.NullMarked	+2/-0
UrlChecker.java `Add JSpecify @NullMarked annotation` java/src/org/openqa/selenium/net/UrlChecker.java Add @NullMarked class-level annotation Import org.jspecify.annotations.NullMarked	+2/-0
Urls.java `Add JSpecify @NullMarked annotation` java/src/org/openqa/selenium/net/Urls.java Add @NullMarked class-level annotation Import org.jspecify.annotations.NullMarked	+2/-0

qodo-code-review · 2025-10-18T10:47:24Z

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance

⚪

Nullability contract change

Description: The new nullable return in obtainLoopbackIp4Address() may return null where callers
previously expected a non-null String, potentially causing NPEs or logic errors in
unadjusted call sites outside this PR.
NetworkUtils.java [120-131]

Referred Code

public @Nullable String obtainLoopbackIp4Address() {
  final NetworkInterface networkInterface = getLoopBackAndIp4Only();
  if (networkInterface != null) {
    InetAddress loopback = networkInterface.getIp4LoopbackOnly();
    if (loopback != null) {
      return loopback.getHostName();
    }
  }

  final String ipOfIp4LoopBack = getIpOfLoopBackIp4();
  if (ipOfIp4LoopBack != null) {
    return ipOfIp4LoopBack;

Unexpected runtime throw

Description: getHostname() and getHostAddress() now throw at runtime via Require.nonNull if
hostname/address remain null, which could be triggered by edge network states and may
introduce unexpected exceptions.
NetworkUtils.java [60-70]

Referred Code

public String getHostname() {
  determineHostnameAndAddress();

  return Require.nonNull("Hostname", hostname);
}

public String getHostAddress() {
  determineHostnameAndAddress();

  return Require.nonNull("Address", address);
}

Ticket Compliance

🟡

🎫 #14291

🟢	Add JSpecify nullness annotations (@NullMarked, @nullable) across Selenium Java code to explicitly document null contracts for parameters and return values.
	Ensure IDEs and static analyzers can infer nullability to help prevent NullPointerExceptions.
	Apply annotations starting with relevant interfaces/classes, e.g., network-related utilities, without breaking existing behavior.
	Where nullable values are possible, add appropriate null-safety handling to avoid NPEs.
⚪	Verify project-wide consistency of nullness contracts beyond the five modified classes to meet broader ticket intent across the codebase.
	Confirm build integration includes jspecify dependency and that IDE/static analyzer tooling picks up annotations in CI.
	Validate no behavioral regressions at runtime in environments with diverse network configurations.

Codebase Duplication Compliance

⚪

Codebase context is not defined

Follow the guide to enable codebase context checks.

Custom Compliance

⚪

No custom compliance provided

Follow the guide to enable custom compliance check.

Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

qodo-code-review · 2025-10-18T10:48:44Z

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Re-evaluate the nullability contract change The PR introduces a breaking change by making `getHostname()` and `getHostAddress()` throw exceptions instead of returning null. It is suggested to instead annotate the methods' return types with `@Nullable` to align with their "best-effort" nature and avoid breaking the public API. Examples: java/src/org/openqa/selenium/net/NetworkUtils.java [60-70] public String getHostname() { determineHostnameAndAddress(); return Require.nonNull("Hostname", hostname); } public String getHostAddress() { determineHostnameAndAddress(); return Require.nonNull("Address", address); ... (clipped 1 lines) Solution Walkthrough: Before: // in NetworkUtils.java @NullMarked public class NetworkUtils { private volatile @Nullable String hostname; private volatile @Nullable String address; public String getHostname() { determineHostnameAndAddress(); return Require.nonNull("Hostname", hostname); // Throws if hostname is null } public String getHostAddress() { determineHostnameAndAddress(); return Require.nonNull("Address", address); // Throws if address is null } } After: // in NetworkUtils.java @NullMarked public class NetworkUtils { private volatile @Nullable String hostname; private volatile @Nullable String address; public @Nullable String getHostname() { determineHostnameAndAddress(); return hostname; // Can return null } public @Nullable String getHostAddress() { determineHostnameAndAddress(); return address; // Can return null } } Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a breaking change in the public API contract of `getHostname()` and `getHostAddress()`, proposing a more appropriate, non-breaking solution that aligns with the PR's goal of improving null-safety via annotations.	High
Possible issue	Prevent potential NullPointerException on address Add a null check for `ip4NonLoopbackAddressOfThisMachine` before calling `getHostAddress()` to prevent a potential `NullPointerException`. java/src/org/openqa/selenium/net/NetworkUtils.java [88-96] public @Nullable String getNonLoopbackAddressOfThisMachine() { InetAddress ip4NonLoopbackAddressOfThisMachine = getIp4NonLoopbackAddressOfThisMachine(); if (!Objects.equals( cachedIp4NonLoopbackAddressOfThisMachine, ip4NonLoopbackAddressOfThisMachine)) { cachedIp4NonLoopbackAddressOfThisMachine = ip4NonLoopbackAddressOfThisMachine; - cachedIp4NonLoopbackAddressHostName = ip4NonLoopbackAddressOfThisMachine.getHostAddress(); + cachedIp4NonLoopbackAddressHostName = + ip4NonLoopbackAddressOfThisMachine == null + ? null + : ip4NonLoopbackAddressOfThisMachine.getHostAddress(); } return cachedIp4NonLoopbackAddressHostName; } Apply / Chat Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a potential `NullPointerException` that could occur if `getIp4NonLoopbackAddressOfThisMachine()` returns `null`, which is a valid scenario. The proposed fix prevents this critical runtime error.	High
Update

diemol · 2025-10-21T10:58:56Z

I will merge this as the failures are unrelated.

selenium-ci added the C-java Java Bindings label Oct 18, 2025

qodo-code-review bot added the Review effort 2/5 label Oct 18, 2025

mk868 force-pushed the jspecify-net branch 2 times, most recently from d1db2b9 to da5d929 Compare October 18, 2025 12:41

[java] JSpecify annotations for org.openqa.selenium.net

7cbd0a7

mk868 force-pushed the jspecify-net branch from da5d929 to 7cbd0a7 Compare October 19, 2025 17:16

diemol added 2 commits October 20, 2025 13:01

Merge branch 'trunk' into jspecify-net

de736eb

Merge branch 'trunk' into jspecify-net

4631dd7

diemol merged commit c88ea44 into SeleniumHQ:trunk Oct 21, 2025
35 of 38 checks passed

mk868 deleted the jspecify-net branch October 21, 2025 11:25

dependabot bot mentioned this pull request Dec 22, 2025

chore(deps): nuget update: Bump Selenium.WebDriver from 4.34.0 to 4.39.0 BySuspect/AutoPixAiCreditClaimer#40

Closed

dependabot bot mentioned this pull request Jan 5, 2026

Bump Selenium.WebDriver from 4.36.0 to 4.39.0 Dor-bl/dotnet-client#173

Closed

dependabot bot mentioned this pull request Feb 11, 2026

chore: Bump Selenium.WebDriver from 4.36.0 to 4.40.0 appium/dotnet-client#1008

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

[java] JSpecify annotations for `org.openqa.selenium.net`#16463

[java] JSpecify annotations for `org.openqa.selenium.net`#16463
diemol merged 3 commits intoSeleniumHQ:trunkfrom
mk868:jspecify-net

mk868 commented Oct 18, 2025 •

edited by qodo-code-review bot

Loading

Uh oh!

qodo-code-review bot commented Oct 18, 2025 •

edited

Loading

Uh oh!

qodo-code-review bot commented Oct 18, 2025 •

edited

Loading

Examples:

Solution Walkthrough:

Before:

After:

Uh oh!

diemol commented Oct 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

mk868 commented Oct 18, 2025 • edited by qodo-code-review bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

User description

🔗 Related Issues

💥 What does this PR do?

🔧 Implementation Notes

💡 Additional Considerations

🔄 Types of changes

PR Type

Description

Diagram Walkthrough

File Walkthrough

Uh oh!

qodo-code-review bot commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Compliance Guide 🔍

Uh oh!

qodo-code-review bot commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Code Suggestions ✨

Examples:

Solution Walkthrough:

Before:

After:

Uh oh!

diemol commented Oct 21, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mk868 commented Oct 18, 2025 •

edited by qodo-code-review bot

Loading

qodo-code-review bot commented Oct 18, 2025 •

edited

Loading

qodo-code-review bot commented Oct 18, 2025 •

edited

Loading