[java] Add JSpecify annotations for By locators

Author: mk868

java/src/org/openqa/selenium/By.java

@@ -23,6 +23,8 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.regex.Pattern;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.internal.Require;
 
 /**
@@ -40,6 +42,7 @@
  * }
  * </code></pre>
  */
+@NullMarked
 public abstract class By {
   /**
    * @param id The value of the "id" attribute to search for.
@@ -158,7 +161,7 @@ protected JavascriptExecutor getJavascriptExecutor(SearchContext context) {
   }
 
   @Override
-  public boolean equals(Object o) {
+  public boolean equals(@Nullable Object o) {
     if (!(o instanceof By)) {
       return false;
     }
@@ -341,9 +344,9 @@ public interface Remotable {
 
     class Parameters {
       private final String using;
-      private final Object value;
+      private final @Nullable Object value;
 
-      public Parameters(String using, Object value) {
+      public Parameters(String using, @Nullable Object value) {
         this.using = Require.nonNull("Search mechanism", using);
         // There may be subclasses where the value is optional. Allow for this.
         this.value = value;
@@ -353,7 +356,7 @@ public String using() {
         return using;
       }
 
-      public Object value() {
+      public @Nullable Object value() {
         return value;
       }
 
@@ -363,7 +366,7 @@ public String toString() {
       }
 
       @Override
-      public boolean equals(Object o) {
+      public boolean equals(@Nullable Object o) {
         if (!(o instanceof Parameters)) {
           return false;
         }
@@ -376,8 +379,8 @@ public int hashCode() {
         return Objects.hash(using, value);
       }
 
-      private Map<String, Object> toJson() {
-        Map<String, Object> params = new HashMap<>();
+      private Map<String, @Nullable Object> toJson() {
+        Map<String, @Nullable Object> params = new HashMap<>();
         params.put("using", using);
         params.put("value", value);
         return Collections.unmodifiableMap(params);
@@ -409,7 +412,7 @@ public final Parameters getRemoteParameters() {
       return params;
     }
 
-    protected final Map<String, Object> toJson() {
+    protected final Map<String, @Nullable Object> toJson() {
       return getRemoteParameters().toJson();
     }
   }
@@ -440,7 +443,7 @@ public final Parameters getRemoteParameters() {
       return remoteParams;
     }
 
-    protected final Map<String, Object> toJson() {
+    protected final Map<String, @Nullable Object> toJson() {
       return fallback.toJson();
     }
 

java/src/org/openqa/selenium/support/ByIdOrName.java

@@ -20,11 +20,13 @@
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
+import org.jspecify.annotations.NullMarked;
 import org.openqa.selenium.By;
 import org.openqa.selenium.NoSuchElementException;
 import org.openqa.selenium.SearchContext;
 import org.openqa.selenium.WebElement;
 
+@NullMarked
 public class ByIdOrName extends By implements Serializable {
 
   private static final long serialVersionUID = 3986638402799576701L;

java/src/org/openqa/selenium/support/pagefactory/ByAll.java

@@ -20,6 +20,7 @@
 import java.io.Serializable;
 import java.util.ArrayList;
 import java.util.List;
+import org.jspecify.annotations.NullMarked;
 import org.openqa.selenium.By;
 import org.openqa.selenium.NoSuchElementException;
 import org.openqa.selenium.SearchContext;
@@ -36,6 +37,7 @@
  * will find all elements that match <var>by1</var> and then all elements that match <var>by2</var>.
  * This means that the list of elements returned may not be in document order.
  */
+@NullMarked
 public class ByAll extends By implements Serializable {
 
   private static final long serialVersionUID = 4573668832699497306L;

java/src/org/openqa/selenium/support/pagefactory/ByChained.java

@@ -22,6 +22,7 @@
 import java.util.List;
 import java.util.stream.Collectors;
 import java.util.stream.Stream;
+import org.jspecify.annotations.NullMarked;
 import org.openqa.selenium.By;
 import org.openqa.selenium.NoSuchElementException;
 import org.openqa.selenium.SearchContext;
@@ -38,6 +39,7 @@
  * will find all elements that match <var>by2</var> and appear under an element that matches
  * <var>by1</var>.
  */
+@NullMarked
 public class ByChained extends By implements Serializable {
 
   private static final long serialVersionUID = 1563769051170172451L;