From 9245a1a7dc5add29f2ee0d3ec2c548d1910d1cb0 Mon Sep 17 00:00:00 2001
From: Maciej Kucharczyk <maciej.kucharczyk@hotmail.com>
Date: Fri, 10 Jan 2025 22:40:13 +0100
Subject: [PATCH] [java] Nullness annotations for Cookie and Platform

---
 java/src/org/openqa/selenium/Cookie.java   | 65 +++++++++++++---------
 java/src/org/openqa/selenium/Platform.java | 65 +++++++++++-----------
 2 files changed, 73 insertions(+), 57 deletions(-)

diff --git a/java/src/org/openqa/selenium/Cookie.java b/java/src/org/openqa/selenium/Cookie.java
index 275e7a468cf2c..e5b98a0d6cd9f 100644
--- a/java/src/org/openqa/selenium/Cookie.java
+++ b/java/src/org/openqa/selenium/Cookie.java
@@ -24,18 +24,21 @@
 import java.util.Objects;
 import java.util.TimeZone;
 import java.util.TreeMap;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
+@NullMarked
 public class Cookie implements Serializable {
   private static final long serialVersionUID = 4115876353625612383L;
 
   private final String name;
   private final String value;
   private final String path;
-  private final String domain;
-  private final Date expiry;
+  private final @Nullable String domain;
+  private final @Nullable Date expiry;
   private final boolean isSecure;
   private final boolean isHttpOnly;
-  private final String sameSite;
+  private final @Nullable String sameSite;
 
   /**
    * Creates an insecure non-httpOnly cookie with no domain specified.
@@ -47,7 +50,7 @@ public class Cookie implements Serializable {
    * @param expiry The cookie's expiration date; may be null.
    * @see #Cookie(String, String, String, String, Date)
    */
-  public Cookie(String name, String value, String path, Date expiry) {
+  public Cookie(String name, String value, @Nullable String path, @Nullable Date expiry) {
     this(name, value, null, path, expiry);
   }
 
@@ -62,7 +65,12 @@ public Cookie(String name, String value, String path, Date expiry) {
    * @param expiry The cookie's expiration date; may be null.
    * @see #Cookie(String, String, String, String, Date, boolean)
    */
-  public Cookie(String name, String value, String domain, String path, Date expiry) {
+  public Cookie(
+      String name,
+      String value,
+      @Nullable String domain,
+      @Nullable String path,
+      @Nullable Date expiry) {
     this(name, value, domain, path, expiry, false);
   }
 
@@ -78,7 +86,12 @@ public Cookie(String name, String value, String domain, String path, Date expiry
    * @param isSecure Whether this cookie requires a secure connection.
    */
   public Cookie(
-      String name, String value, String domain, String path, Date expiry, boolean isSecure) {
+      String name,
+      String value,
+      @Nullable String domain,
+      @Nullable String path,
+      @Nullable Date expiry,
+      boolean isSecure) {
     this(name, value, domain, path, expiry, isSecure, false);
   }
 
@@ -97,9 +110,9 @@ public Cookie(
   public Cookie(
       String name,
       String value,
-      String domain,
-      String path,
-      Date expiry,
+      @Nullable String domain,
+      @Nullable String path,
+      @Nullable Date expiry,
       boolean isSecure,
       boolean isHttpOnly) {
     this(name, value, domain, path, expiry, isSecure, isHttpOnly, null);
@@ -121,12 +134,12 @@ public Cookie(
   public Cookie(
       String name,
       String value,
-      String domain,
-      String path,
-      Date expiry,
+      @Nullable String domain,
+      @Nullable String path,
+      @Nullable Date expiry,
       boolean isSecure,
       boolean isHttpOnly,
-      String sameSite) {
+      @Nullable String sameSite) {
     this.name = name;
     this.value = value;
     this.path = path == null || path.isEmpty() ? "/" : path;
@@ -174,7 +187,7 @@ public String getValue() {
     return value;
   }
 
-  public String getDomain() {
+  public @Nullable String getDomain() {
     return domain;
   }
 
@@ -190,15 +203,15 @@ public boolean isHttpOnly() {
     return isHttpOnly;
   }
 
-  public Date getExpiry() {
+  public @Nullable Date getExpiry() {
     return expiry == null ? null : new Date(expiry.getTime());
   }
 
-  public String getSameSite() {
+  public @Nullable String getSameSite() {
     return sameSite;
   }
 
-  private static String stripPort(String domain) {
+  private static @Nullable String stripPort(@Nullable String domain) {
     return (domain == null) ? null : domain.split(":")[0];
   }
 
@@ -270,7 +283,7 @@ public String toString() {
 
   /** Two cookies are equal if the name and value match */
   @Override
-  public boolean equals(Object o) {
+  public boolean equals(@Nullable Object o) {
     if (this == o) {
       return true;
     }
@@ -295,29 +308,29 @@ public static class Builder {
 
     private final String name;
     private final String value;
-    private String path;
-    private String domain;
-    private Date expiry;
+    private @Nullable String path;
+    private @Nullable String domain;
+    private @Nullable Date expiry;
     private boolean secure;
     private boolean httpOnly;
-    private String sameSite;
+    private @Nullable String sameSite;
 
     public Builder(String name, String value) {
       this.name = name;
       this.value = value;
     }
 
-    public Builder domain(String host) {
+    public Builder domain(@Nullable String host) {
       this.domain = stripPort(host);
       return this;
     }
 
-    public Builder path(String path) {
+    public Builder path(@Nullable String path) {
       this.path = path;
       return this;
     }
 
-    public Builder expiresOn(Date expiry) {
+    public Builder expiresOn(@Nullable Date expiry) {
       this.expiry = expiry == null ? null : new Date(expiry.getTime());
       return this;
     }
@@ -332,7 +345,7 @@ public Builder isHttpOnly(boolean httpOnly) {
       return this;
     }
 
-    public Builder sameSite(String sameSite) {
+    public Builder sameSite(@Nullable String sameSite) {
       this.sameSite = sameSite;
       return this;
     }
diff --git a/java/src/org/openqa/selenium/Platform.java b/java/src/org/openqa/selenium/Platform.java
index 98d859b642689..e4bc941cdfd4e 100644
--- a/java/src/org/openqa/selenium/Platform.java
+++ b/java/src/org/openqa/selenium/Platform.java
@@ -21,6 +21,8 @@
 import java.util.Locale;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Represents the known and supported Platforms that WebDriver runs on. This is pretty close to the
@@ -29,12 +31,13 @@
  */
 // Useful URLs:
 // http://hg.openjdk.java.net/jdk7/modules/jdk/file/a37326fa7f95/src/windows/native/java/lang/java_props_md.c
+@NullMarked
 public enum Platform {
 
   /** Never returned, but can be used to request a browser running on any version of Windows. */
   WINDOWS("windows") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return null;
     }
 
@@ -50,7 +53,7 @@ public String toString() {
    */
   XP("Windows Server 2003", "xp", "windows", "winnt", "windows_nt", "windows nt") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return WINDOWS;
     }
 
@@ -63,7 +66,7 @@ public String toString() {
   /** For versions of Windows that "feel like" Windows Vista. */
   VISTA("windows vista", "Windows Server 2008") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return WINDOWS;
     }
 
@@ -75,7 +78,7 @@ public String toString() {
 
   WIN7("windows 7", "win7") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return WINDOWS;
     }
 
@@ -88,7 +91,7 @@ public String toString() {
   /** For versions of Windows that "feel like" Windows 8. */
   WIN8("Windows Server 2012", "windows 8", "win8") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return WINDOWS;
     }
 
@@ -100,7 +103,7 @@ public String toString() {
 
   WIN8_1("windows 8.1", "win8.1") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return WINDOWS;
     }
 
@@ -112,7 +115,7 @@ public String toString() {
 
   WIN10("windows 10", "win10") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return WINDOWS;
     }
 
@@ -124,7 +127,7 @@ public String toString() {
 
   WIN11("windows 11", "win11") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return WINDOWS;
     }
 
@@ -136,7 +139,7 @@ public String toString() {
 
   MAC("mac", "darwin", "macOS", "mac os x", "os x") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return null;
     }
 
@@ -148,7 +151,7 @@ public String toString() {
 
   SNOW_LEOPARD("snow leopard", "os x 10.6", "macos 10.6") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -160,7 +163,7 @@ public String toString() {
 
   MOUNTAIN_LION("mountain lion", "os x 10.8", "macos 10.8") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -172,7 +175,7 @@ public String toString() {
 
   MAVERICKS("mavericks", "os x 10.9", "macos 10.9") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -184,7 +187,7 @@ public String toString() {
 
   YOSEMITE("yosemite", "os x 10.10", "macos 10.10") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -196,7 +199,7 @@ public String toString() {
 
   EL_CAPITAN("el capitan", "os x 10.11", "macos 10.11") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -208,7 +211,7 @@ public String toString() {
 
   SIERRA("sierra", "os x 10.12", "macos 10.12") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -220,7 +223,7 @@ public String toString() {
 
   HIGH_SIERRA("high sierra", "os x 10.13", "macos 10.13") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -232,7 +235,7 @@ public String toString() {
 
   MOJAVE("mojave", "os x 10.14", "macos 10.14") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -244,7 +247,7 @@ public String toString() {
 
   CATALINA("catalina", "os x 10.15", "macos 10.15") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -256,7 +259,7 @@ public String toString() {
 
   BIG_SUR("big sur", "os x 11.0", "macos 11.0") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -268,7 +271,7 @@ public String toString() {
 
   MONTEREY("monterey", "os x 12.0", "macos 12.0") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -280,7 +283,7 @@ public String toString() {
 
   VENTURA("ventura", "os x 13.0", "macos 13.0") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -292,7 +295,7 @@ public String toString() {
 
   SONOMA("sonoma", "os x 14.0", "macos 14.0") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -304,7 +307,7 @@ public String toString() {
 
   SEQUOIA("sequoia", "os x 15.0", "macos 15.0") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return MAC;
     }
 
@@ -317,14 +320,14 @@ public String toString() {
   /** Many platforms have UNIX traits, amongst them LINUX, Solaris and BSD. */
   UNIX("solaris", "bsd") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return null;
     }
   },
 
   LINUX("linux") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return UNIX;
     }
 
@@ -336,14 +339,14 @@ public String toString() {
 
   ANDROID("android", "dalvik") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return null;
     }
   },
 
   IOS("iOS") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return null;
     }
   },
@@ -351,7 +354,7 @@ public Platform family() {
   /** Never returned, but can be used to request a browser running on any operating system. */
   ANY("") {
     @Override
-    public Platform family() {
+    public @Nullable Platform family() {
       return ANY;
     }
 
@@ -366,7 +369,7 @@ public String toString() {
     }
   };
 
-  private static Platform current;
+  private static @Nullable Platform current;
   private final String[] partOfOsName;
   private int minorVersion = 0;
   private int majorVersion = 0;
@@ -493,7 +496,7 @@ public static Platform fromString(String name) {
    * @param matcher the newer match
    * @return true if newer match is better, false otherwise
    */
-  private static boolean isBetterMatch(String previous, String matcher) {
+  private static boolean isBetterMatch(@Nullable String previous, String matcher) {
     return previous == null || matcher.length() >= previous.length();
   }
 
@@ -528,7 +531,7 @@ public boolean is(Platform compareWith) {
    * @return the family platform for the current one, or {@code null} if this {@code Platform}
    *     represents a platform family (such as Windows, or MacOS)
    */
-  public abstract Platform family();
+  public abstract @Nullable Platform family();
 
   private boolean isCurrentPlatform(String osName, String matchAgainst) {
     return osName.contains(matchAgainst);