From d9b083eee0cb206880a7f43b9b1935b037c9ac0e Mon Sep 17 00:00:00 2001 From: Maciej Kucharczyk Date: Sat, 10 Aug 2024 13:32:22 +0200 Subject: [PATCH] [java] Add JSpecify annotations for WebDriver, TakesScreenshot, JavascriptExecutor, OutputType interfaces --- java/src/org/openqa/selenium/JavascriptExecutor.java | 9 ++++++--- java/src/org/openqa/selenium/OutputType.java | 2 ++ java/src/org/openqa/selenium/TakesScreenshot.java | 3 +++ java/src/org/openqa/selenium/WebDriver.java | 11 +++++++---- 4 files changed, 18 insertions(+), 7 deletions(-) diff --git a/java/src/org/openqa/selenium/JavascriptExecutor.java b/java/src/org/openqa/selenium/JavascriptExecutor.java index ab660e5e25c35..a744eb8d8df91 100644 --- a/java/src/org/openqa/selenium/JavascriptExecutor.java +++ b/java/src/org/openqa/selenium/JavascriptExecutor.java @@ -20,6 +20,8 @@ import java.util.Collections; import java.util.Set; import java.util.stream.Collectors; +import org.jspecify.annotations.NullMarked; +import org.jspecify.annotations.Nullable; import org.openqa.selenium.internal.Require; /** @@ -30,6 +32,7 @@ * request or when trying to access another frame. Most times when troubleshooting failure it's best * to view the browser's console after executing the WebDriver request. */ +@NullMarked public interface JavascriptExecutor { /** * Executes JavaScript in the context of the currently selected frame or window. The script @@ -63,7 +66,7 @@ public interface JavascriptExecutor { * @param args The arguments to the script. May be empty * @return One of Boolean, Long, Double, String, List, Map or WebElement. Or null. */ - Object executeScript(String script, Object... args); + @Nullable Object executeScript(String script, @Nullable Object... args); /** * Execute an asynchronous piece of JavaScript in the context of the currently selected frame or @@ -139,7 +142,7 @@ public interface JavascriptExecutor { * @return One of Boolean, Long, String, List, Map, WebElement, or null. * @see WebDriver.Timeouts#scriptTimeout(java.time.Duration) */ - Object executeAsyncScript(String script, Object... args); + @Nullable Object executeAsyncScript(String script, @Nullable Object... args); /** * Commonly used scripts may be "pinned" to the WebDriver session, allowing them to be called @@ -186,7 +189,7 @@ default Set getPinnedScripts() { * * @see #executeScript(String, Object...) */ - default Object executeScript(ScriptKey key, Object... args) { + default @Nullable Object executeScript(ScriptKey key, @Nullable Object... args) { Require.stateCondition( key instanceof UnpinnedScriptKey, "Script key should have been generated by this driver"); diff --git a/java/src/org/openqa/selenium/OutputType.java b/java/src/org/openqa/selenium/OutputType.java index 1d0e013e41266..78c38614d9ce3 100644 --- a/java/src/org/openqa/selenium/OutputType.java +++ b/java/src/org/openqa/selenium/OutputType.java @@ -22,6 +22,7 @@ import java.nio.file.Files; import java.nio.file.Path; import java.util.Base64; +import org.jspecify.annotations.NullMarked; /** * Defines the output type for a screenshot. @@ -29,6 +30,7 @@ * @see TakesScreenshot * @param Type for the screenshot output. */ +@NullMarked public interface OutputType { /** Obtain the screenshot as base64 data. */ OutputType BASE64 = diff --git a/java/src/org/openqa/selenium/TakesScreenshot.java b/java/src/org/openqa/selenium/TakesScreenshot.java index 99a1173434a94..d37f2b0530491 100644 --- a/java/src/org/openqa/selenium/TakesScreenshot.java +++ b/java/src/org/openqa/selenium/TakesScreenshot.java @@ -16,6 +16,8 @@ // under the License. package org.openqa.selenium; +import org.jspecify.annotations.NullMarked; + /** * Indicates a driver or an HTML element that can capture a screenshot and store it in different * ways. @@ -29,6 +31,7 @@ * * @see OutputType */ +@NullMarked public interface TakesScreenshot { /** * Capture the screenshot and store it in the specified location. diff --git a/java/src/org/openqa/selenium/WebDriver.java b/java/src/org/openqa/selenium/WebDriver.java index 843d4fc4247bf..a77c1dc3d8b4d 100644 --- a/java/src/org/openqa/selenium/WebDriver.java +++ b/java/src/org/openqa/selenium/WebDriver.java @@ -22,6 +22,8 @@ import java.util.List; import java.util.Set; import java.util.concurrent.TimeUnit; +import org.jspecify.annotations.NullMarked; +import org.jspecify.annotations.Nullable; import org.openqa.selenium.logging.LoggingPreferences; import org.openqa.selenium.logging.Logs; @@ -46,6 +48,7 @@ *

Most implementations of this interface follow W3C * WebDriver specification */ +@NullMarked public interface WebDriver extends SearchContext { // Navigation @@ -74,7 +77,7 @@ public interface WebDriver extends SearchContext { * * @return The URL of the page currently loaded in the browser */ - String getCurrentUrl(); + @Nullable String getCurrentUrl(); // General properties @@ -87,7 +90,7 @@ public interface WebDriver extends SearchContext { * @return The title of the current page, with leading and trailing whitespace stripped, or null * if one is not already set */ - String getTitle(); + @Nullable String getTitle(); /** * Find all elements within the current page using the given mechanism. This method is affected by @@ -142,7 +145,7 @@ public interface WebDriver extends SearchContext { * * @return The source of the current page */ - String getPageSource(); + @Nullable String getPageSource(); /** * Close the current window, quitting the browser if it's the last window currently open. @@ -261,7 +264,7 @@ interface Options { * @param name the name of the cookie * @return the cookie, or null if no cookie with the given name is present */ - Cookie getCookieNamed(String name); + @Nullable Cookie getCookieNamed(String name); /** * @return the interface for managing driver timeouts.