refactor: Migrate from JSR 305 to JSpecify (#2281)

valfirst · web-flow · commit 9a59abddfc67 · 2025-03-28T08:20:50.000+03:00
diff --git a/build.gradle b/build.gradle
@@ -67,7 +67,7 @@ dependencies {
     }
     implementation 'com.google.code.gson:gson:2.12.1'
     implementation "org.slf4j:slf4j-api:${slf4jVersion}"
-    implementation 'com.google.code.findbugs:jsr305:3.0.2'
+    implementation 'org.jspecify:jspecify:1.0.0'
 }
 
 dependencyCheck {
diff --git a/src/main/java/io/appium/java_client/AppiumClientConfig.java b/src/main/java/io/appium/java_client/AppiumClientConfig.java
@@ -18,12 +18,12 @@
 
 import io.appium.java_client.internal.filters.AppiumIdempotencyFilter;
 import io.appium.java_client.internal.filters.AppiumUserAgentFilter;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.Credentials;
 import org.openqa.selenium.internal.Require;
 import org.openqa.selenium.remote.http.ClientConfig;
 import org.openqa.selenium.remote.http.Filter;
 
-import javax.annotation.Nullable;
 import javax.net.ssl.SSLContext;
 import java.net.Proxy;
 import java.net.URI;
diff --git a/src/main/java/io/appium/java_client/AppiumDriver.java b/src/main/java/io/appium/java_client/AppiumDriver.java
@@ -25,6 +25,7 @@
 import io.appium.java_client.service.local.AppiumDriverLocalService;
 import io.appium.java_client.service.local.AppiumServiceBuilder;
 import lombok.Getter;
+import org.jspecify.annotations.NonNull;
 import org.openqa.selenium.Capabilities;
 import org.openqa.selenium.ImmutableCapabilities;
 import org.openqa.selenium.OutputType;
@@ -47,7 +48,6 @@
 import org.openqa.selenium.remote.http.HttpClient;
 import org.openqa.selenium.remote.http.HttpMethod;
 
-import javax.annotation.Nonnull;
 import java.net.URI;
 import java.net.URISyntaxException;
 import java.net.URL;
@@ -275,7 +275,7 @@ public Optional<BiDi> maybeGetBiDi() {
     }
 
     @Override
-    @Nonnull
+    @NonNull
     public BiDi getBiDi() {
         var webSocketUrl = ((BaseOptions<?>) this.capabilities).getWebSocketUrl().orElseThrow(
                 () -> {
diff --git a/src/main/java/io/appium/java_client/CommandExecutionHelper.java b/src/main/java/io/appium/java_client/CommandExecutionHelper.java
@@ -16,9 +16,9 @@
 
 package io.appium.java_client;
 
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.remote.Response;
 
-import javax.annotation.Nullable;
 import java.util.Collections;
 import java.util.Map;
 
diff --git a/src/main/java/io/appium/java_client/ComparesImages.java b/src/main/java/io/appium/java_client/ComparesImages.java
@@ -23,8 +23,8 @@
 import io.appium.java_client.imagecomparison.OccurrenceMatchingResult;
 import io.appium.java_client.imagecomparison.SimilarityMatchingOptions;
 import io.appium.java_client.imagecomparison.SimilarityMatchingResult;
+import org.jspecify.annotations.Nullable;
 
-import javax.annotation.Nullable;
 import java.io.File;
 import java.io.IOException;
 import java.nio.file.Files;
diff --git a/src/main/java/io/appium/java_client/ExecuteCDPCommand.java b/src/main/java/io/appium/java_client/ExecuteCDPCommand.java
@@ -16,9 +16,9 @@
 
 package io.appium.java_client;
 
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.remote.Response;
 
-import javax.annotation.Nullable;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
diff --git a/src/main/java/io/appium/java_client/ExecutesDriverScript.java b/src/main/java/io/appium/java_client/ExecutesDriverScript.java
@@ -18,9 +18,9 @@
 
 import io.appium.java_client.driverscripts.ScriptOptions;
 import io.appium.java_client.driverscripts.ScriptValue;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.remote.Response;
 
-import javax.annotation.Nullable;
 import java.util.HashMap;
 import java.util.Map;
 
diff --git a/src/main/java/io/appium/java_client/InteractsWithApps.java b/src/main/java/io/appium/java_client/InteractsWithApps.java
@@ -22,10 +22,10 @@
 import io.appium.java_client.appmanagement.BaseOptions;
 import io.appium.java_client.appmanagement.BaseRemoveApplicationOptions;
 import io.appium.java_client.appmanagement.BaseTerminateApplicationOptions;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.InvalidArgumentException;
 import org.openqa.selenium.UnsupportedCommandException;
 
-import javax.annotation.Nullable;
 import java.time.Duration;
 import java.util.HashMap;
 import java.util.Map;
diff --git a/src/main/java/io/appium/java_client/Location.java b/src/main/java/io/appium/java_client/Location.java
@@ -19,8 +19,7 @@
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.ToString;
-
-import javax.annotation.Nullable;
+import org.jspecify.annotations.Nullable;
 
 /**
  * Represents the physical location.
diff --git a/src/main/java/io/appium/java_client/MobileCommand.java b/src/main/java/io/appium/java_client/MobileCommand.java
@@ -21,10 +21,10 @@
 import io.appium.java_client.imagecomparison.ComparisonMode;
 import io.appium.java_client.screenrecording.BaseStartScreenRecordingOptions;
 import io.appium.java_client.screenrecording.BaseStopScreenRecordingOptions;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.remote.CommandInfo;
 import org.openqa.selenium.remote.http.HttpMethod;
 
-import javax.annotation.Nullable;
 import java.nio.charset.StandardCharsets;
 import java.time.Duration;
 import java.util.Collections;
diff --git a/src/main/java/io/appium/java_client/android/StartsActivity.java b/src/main/java/io/appium/java_client/android/StartsActivity.java
@@ -19,10 +19,9 @@
 import io.appium.java_client.CanRememberExtensionPresence;
 import io.appium.java_client.CommandExecutionHelper;
 import io.appium.java_client.ExecutesMethod;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.UnsupportedCommandException;
 
-import javax.annotation.Nullable;
-
 import java.util.Map;
 
 import static io.appium.java_client.MobileCommand.CURRENT_ACTIVITY;
diff --git a/src/main/java/io/appium/java_client/internal/CapabilityHelpers.java b/src/main/java/io/appium/java_client/internal/CapabilityHelpers.java
@@ -16,9 +16,9 @@
 
 package io.appium.java_client.internal;
 
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.Capabilities;
 
-import javax.annotation.Nullable;
 import java.net.MalformedURLException;
 import java.net.URL;
 import java.time.Duration;
diff --git a/src/main/java/io/appium/java_client/internal/filters/AppiumUserAgentFilter.java b/src/main/java/io/appium/java_client/internal/filters/AppiumUserAgentFilter.java
@@ -17,14 +17,13 @@
 package io.appium.java_client.internal.filters;
 
 import io.appium.java_client.internal.Config;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.remote.http.AddSeleniumUserAgent;
 import org.openqa.selenium.remote.http.Filter;
 import org.openqa.selenium.remote.http.HttpHandler;
 import org.openqa.selenium.remote.http.HttpHeader;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
-
 /**
  * Manage Appium Client configurations.
  */
@@ -41,7 +40,7 @@ public class AppiumUserAgentFilter implements Filter {
      */
     public static final String USER_AGENT = buildUserAgentHeaderValue(AddSeleniumUserAgent.USER_AGENT);
 
-    private static String buildUserAgentHeaderValue(@Nonnull String previousUA) {
+    private static String buildUserAgentHeaderValue(@NonNull String previousUA) {
         return String.format("%s%s (%s)",
                 USER_AGENT_PREFIX, Config.main().getValue(VERSION_KEY, String.class), previousUA);
     }
diff --git a/src/main/java/io/appium/java_client/pagefactory/AppiumElementLocatorFactory.java b/src/main/java/io/appium/java_client/pagefactory/AppiumElementLocatorFactory.java
@@ -19,9 +19,9 @@
 import io.appium.java_client.pagefactory.bys.builder.AppiumByBuilder;
 import io.appium.java_client.pagefactory.locator.CacheableElementLocatorFactory;
 import io.appium.java_client.pagefactory.locator.CacheableLocator;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.SearchContext;
 
-import javax.annotation.Nullable;
 import java.lang.ref.WeakReference;
 import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Field;
diff --git a/src/main/java/io/appium/java_client/pagefactory/AppiumFieldDecorator.java b/src/main/java/io/appium/java_client/pagefactory/AppiumFieldDecorator.java
@@ -19,6 +19,8 @@
 import io.appium.java_client.internal.CapabilityHelpers;
 import io.appium.java_client.pagefactory.bys.ContentType;
 import io.appium.java_client.pagefactory.locator.CacheableLocator;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.HasCapabilities;
 import org.openqa.selenium.SearchContext;
 import org.openqa.selenium.WebDriver;
@@ -30,8 +32,6 @@
 import org.openqa.selenium.support.pagefactory.ElementLocatorFactory;
 import org.openqa.selenium.support.pagefactory.FieldDecorator;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
 import java.lang.ref.WeakReference;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Field;
@@ -123,7 +123,7 @@ contextReference, duration, new WidgetByBuilder(platform, automation)
         );
     }
 
-    @Nonnull
+    @NonNull
     private static WeakReference<WebDriver> requireWebDriverReference(SearchContext searchContext) {
         var wd = unpackObjectFromSearchContext(
                 checkNotNull(searchContext, "The provided search context cannot be null"),
diff --git a/src/main/java/io/appium/java_client/pagefactory/WidgetInterceptor.java b/src/main/java/io/appium/java_client/pagefactory/WidgetInterceptor.java
@@ -19,11 +19,11 @@
 import io.appium.java_client.pagefactory.bys.ContentType;
 import io.appium.java_client.pagefactory.interceptors.InterceptorOfASingleElement;
 import io.appium.java_client.pagefactory.locator.CacheableLocator;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.WebDriver;
 import org.openqa.selenium.WebElement;
 import org.openqa.selenium.support.PageFactory;
 
-import javax.annotation.Nullable;
 import java.lang.ref.WeakReference;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Method;
@@ -48,11 +48,9 @@ public class WidgetInterceptor extends InterceptorOfASingleElement {
      * Proxy interceptor class for widgets.
      */
     public WidgetInterceptor(
-            @Nullable
-            CacheableLocator locator,
+            @Nullable CacheableLocator locator,
             WeakReference<WebDriver> driverReference,
-            @Nullable
-            WeakReference<WebElement> cachedElementReference,
+            @Nullable WeakReference<WebElement> cachedElementReference,
             Map<ContentType, Constructor<? extends Widget>> instantiationMap,
             Duration duration
     ) {
diff --git a/src/main/java/io/appium/java_client/pagefactory/WidgetListInterceptor.java b/src/main/java/io/appium/java_client/pagefactory/WidgetListInterceptor.java
@@ -19,10 +19,10 @@
 import io.appium.java_client.pagefactory.bys.ContentType;
 import io.appium.java_client.pagefactory.interceptors.InterceptorOfAListOfElements;
 import io.appium.java_client.pagefactory.locator.CacheableLocator;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.WebDriver;
 import org.openqa.selenium.WebElement;
 
-import javax.annotation.Nullable;
 import java.lang.ref.WeakReference;
 import java.lang.reflect.Constructor;
 import java.lang.reflect.Method;
@@ -50,8 +50,7 @@ public class WidgetListInterceptor extends InterceptorOfAListOfElements {
      * Proxy interceptor class for lists of widgets.
      */
     public WidgetListInterceptor(
-            @Nullable
-            CacheableLocator locator,
+            @Nullable CacheableLocator locator,
             WeakReference<WebDriver> driver,
             Map<ContentType, Constructor<? extends Widget>> instantiationMap,
             Class<? extends Widget> declaredType,
diff --git a/src/main/java/io/appium/java_client/pagefactory/bys/ContentMappedBy.java b/src/main/java/io/appium/java_client/pagefactory/bys/ContentMappedBy.java
@@ -17,11 +17,11 @@
 package io.appium.java_client.pagefactory.bys;
 
 import lombok.EqualsAndHashCode;
+import org.jspecify.annotations.NonNull;
 import org.openqa.selenium.By;
 import org.openqa.selenium.SearchContext;
 import org.openqa.selenium.WebElement;
 
-import javax.annotation.Nonnull;
 import java.util.List;
 import java.util.Map;
 
@@ -43,7 +43,7 @@ public ContentMappedBy(Map<ContentType, By> map) {
      * @param type required content type {@link ContentType}
      * @return self-reference.
      */
-    public By useContent(@Nonnull ContentType type) {
+    public By useContent(@NonNull ContentType type) {
         requireNonNull(type);
         currentContent = type;
         return this;
diff --git a/src/main/java/io/appium/java_client/pagefactory/bys/builder/AppiumByBuilder.java b/src/main/java/io/appium/java_client/pagefactory/bys/builder/AppiumByBuilder.java
@@ -16,11 +16,11 @@
 
 package io.appium.java_client.pagefactory.bys.builder;
 
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.By;
 import org.openqa.selenium.support.pagefactory.AbstractAnnotations;
 import org.openqa.selenium.support.pagefactory.ByAll;
 
-import javax.annotation.Nullable;
 import java.lang.annotation.Annotation;
 import java.lang.reflect.AnnotatedElement;
 import java.lang.reflect.Constructor;
diff --git a/src/main/java/io/appium/java_client/pagefactory/interceptors/InterceptorOfAListOfElements.java b/src/main/java/io/appium/java_client/pagefactory/interceptors/InterceptorOfAListOfElements.java
@@ -17,10 +17,10 @@
 package io.appium.java_client.pagefactory.interceptors;
 
 import io.appium.java_client.proxy.MethodCallListener;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.WebElement;
 import org.openqa.selenium.support.pagefactory.ElementLocator;
 
-import javax.annotation.Nullable;
 import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.List;
diff --git a/src/main/java/io/appium/java_client/pagefactory/interceptors/InterceptorOfASingleElement.java b/src/main/java/io/appium/java_client/pagefactory/interceptors/InterceptorOfASingleElement.java
@@ -17,13 +17,13 @@
 package io.appium.java_client.pagefactory.interceptors;
 
 import io.appium.java_client.proxy.MethodCallListener;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.WebDriver;
 import org.openqa.selenium.WebElement;
 import org.openqa.selenium.WrapsDriver;
 import org.openqa.selenium.remote.RemoteWebElement;
 import org.openqa.selenium.support.pagefactory.ElementLocator;
 
-import javax.annotation.Nullable;
 import java.lang.ref.WeakReference;
 import java.lang.reflect.Method;
 import java.util.Objects;
@@ -34,8 +34,7 @@ public abstract class InterceptorOfASingleElement implements MethodCallListener
     private final WeakReference<WebDriver> driverReference;
 
     public InterceptorOfASingleElement(
-            @Nullable
-            ElementLocator locator,
+            @Nullable ElementLocator locator,
             WeakReference<WebDriver> driverReference
     ) {
         this.locator = locator;
diff --git a/src/main/java/io/appium/java_client/pagefactory/utils/WebDriverUnpackUtility.java b/src/main/java/io/appium/java_client/pagefactory/utils/WebDriverUnpackUtility.java
@@ -18,14 +18,13 @@
 
 import io.appium.java_client.HasBrowserCheck;
 import io.appium.java_client.pagefactory.bys.ContentType;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.ContextAware;
 import org.openqa.selenium.SearchContext;
 import org.openqa.selenium.WebDriver;
 import org.openqa.selenium.WrapsDriver;
 import org.openqa.selenium.WrapsElement;
 
-import javax.annotation.Nullable;
-
 import java.util.Optional;
 
 import static io.appium.java_client.HasBrowserCheck.NATIVE_CONTEXT;
diff --git a/src/main/java/io/appium/java_client/proxy/Helpers.java b/src/main/java/io/appium/java_client/proxy/Helpers.java
@@ -26,8 +26,8 @@
 import net.bytebuddy.implementation.MethodDelegation;
 import net.bytebuddy.matcher.ElementMatcher;
 import net.bytebuddy.matcher.ElementMatchers;
+import org.jspecify.annotations.Nullable;
 
-import javax.annotation.Nullable;
 import java.lang.reflect.Method;
 import java.util.Collection;
 import java.util.Collections;
diff --git a/src/main/java/io/appium/java_client/remote/AppiumCommandExecutor.java b/src/main/java/io/appium/java_client/remote/AppiumCommandExecutor.java
@@ -20,6 +20,8 @@
 import io.appium.java_client.AppiumClientConfig;
 import io.appium.java_client.internal.ReflectionHelpers;
 import lombok.Getter;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.Nullable;
 import org.openqa.selenium.SessionNotCreatedException;
 import org.openqa.selenium.WebDriverException;
 import org.openqa.selenium.remote.Command;
@@ -34,12 +36,11 @@
 import org.openqa.selenium.remote.ResponseCodec;
 import org.openqa.selenium.remote.codec.w3c.W3CHttpCommandCodec;
 import org.openqa.selenium.remote.http.HttpClient;
+import org.openqa.selenium.remote.http.HttpClient.Factory;
 import org.openqa.selenium.remote.http.HttpRequest;
 import org.openqa.selenium.remote.http.HttpResponse;
 import org.openqa.selenium.remote.service.DriverService;
 
-import javax.annotation.Nonnull;
-import javax.annotation.Nullable;
 import java.io.IOException;
 import java.net.ConnectException;
 import java.net.MalformedURLException;
@@ -69,10 +70,10 @@ public class AppiumCommandExecutor extends HttpCommandExecutor {
      * @param appiumClientConfig take a look at {@link AppiumClientConfig}
      */
     public AppiumCommandExecutor(
-            @Nonnull Map<String, CommandInfo> additionalCommands,
+            @NonNull Map<String, CommandInfo> additionalCommands,
             @Nullable DriverService service,
-            @Nullable HttpClient.Factory httpClientFactory,
-            @Nonnull AppiumClientConfig appiumClientConfig) {
+            @Nullable Factory httpClientFactory,
+            @NonNull AppiumClientConfig appiumClientConfig) {
         super(additionalCommands,
                 appiumClientConfig,
                 ofNullable(httpClientFactory).orElseGet(AppiumCommandExecutor::getDefaultClientFactory)
diff --git a/src/main/java/io/appium/java_client/remote/DirectConnect.java b/src/main/java/io/appium/java_client/remote/DirectConnect.java
diff --git a/src/main/java/io/appium/java_client/remote/SupportsContextSwitching.java b/src/main/java/io/appium/java_client/remote/SupportsContextSwitching.java
diff --git a/src/main/java/io/appium/java_client/remote/options/BaseOptions.java b/src/main/java/io/appium/java_client/remote/options/BaseOptions.java
diff --git a/src/main/java/io/appium/java_client/service/local/AppiumDriverLocalService.java b/src/main/java/io/appium/java_client/service/local/AppiumDriverLocalService.java
diff --git a/src/main/java/io/appium/java_client/service/local/AppiumServiceBuilder.java b/src/main/java/io/appium/java_client/service/local/AppiumServiceBuilder.java
diff --git a/src/main/java/io/appium/java_client/ws/StringWebSocketClient.java b/src/main/java/io/appium/java_client/ws/StringWebSocketClient.java
diff --git a/src/test/java/io/appium/java_client/TestUtils.java b/src/test/java/io/appium/java_client/TestUtils.java

Original file line number	Diff line number	Diff line change
`@@ -67,7 +67,7 @@ dependencies {`
`67`	`67`	`}`
`68`	`68`	`implementation 'com.google.code.gson:gson:2.12.1'`
`69`	`69`	`implementation "org.slf4j:slf4j-api:${slf4jVersion}"`
`70`		`- implementation 'com.google.code.findbugs:jsr305:3.0.2'`
	`70`	`+ implementation 'org.jspecify:jspecify:1.0.0'`
`71`	`71`	`}`
`72`	`72`
`73`	`73`	`dependencyCheck {`