[java] JSpecify annotations for By locators (#14372)

[java] Add JSpecify annotations for By locators

Co-authored-by: Diego Molina <[email protected]>
Co-authored-by: Viet Nguyen Duc <[email protected]>

Author: 3 people

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;
     }
@@ -342,9 +345,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;
@@ -354,7 +357,7 @@ public String using() {
         return using;
       }
 
-      public Object value() {
+      public @Nullable Object value() {
         return value;
       }
 
@@ -364,7 +367,7 @@ public String toString() {
       }
 
       @Override
-      public boolean equals(Object o) {
+      public boolean equals(@Nullable Object o) {
         if (!(o instanceof Parameters)) {
           return false;
         }
@@ -377,8 +380,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);
@@ -410,7 +413,7 @@ public final Parameters getRemoteParameters() {
       return params;
     }
 
-    protected final Map<String, Object> toJson() {
+    protected final Map<String, @Nullable Object> toJson() {
       return getRemoteParameters().toJson();
     }
   }
@@ -441,7 +444,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/BUILD.bazel

@@ -1,4 +1,4 @@
-load("//java:defs.bzl", "java_export", "java_library")
+load("//java:defs.bzl", "artifact", "java_export", "java_library")
 load("//java:version.bzl", "SE_VERSION")
 
 java_export(
@@ -57,5 +57,6 @@ java_library(
     deps = [
         "//java/src/org/openqa/selenium:core",
         "//java/src/org/openqa/selenium/support/ui:components",
+        artifact("org.jspecify:jspecify"),
     ],
 )

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;