make augmentation of HasBiDi/HasDevTools lazy-loaded (#16338)

* make augmentation of HasBiDi/HasDevTools lazy-loaded

Otherwise, command `new Augmenter().augment(remoteWebDriver)` fails immediately (even if I don't want to use CDP or BiDi).

* Augmenter should only augment (create instance of interfaces).
* Augmenter should not perform any other actions (establish CDP connection, establish BiDi connection etc.)

* avoid establishing CDP connection in `maybeGet*()` method

1. method `getBiDi`/`getDevTools` should establish a connection, BUT
1. method `maybeGet*()` returns connection only if the connection is already established, but should NOT establish a new connection.

It's because method `maybeGet*()` is used from `WebDriver.close()` and `WebDriver.quite()`. At this moment, we don't want a new connection, we only want to close the existing connection.

* extract reusable code to Lazy.java

Now we have a convenient factory method `lazy` for declaring lazy-initialized values like BiDi or DevTools.

This simplifies BiDiProvider and DevToolsProvider code.

* add log informing user that CDP/BiDi connection is not established immediately anymore

* reformat the code

---------

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

Author: asolntsev

java/src/org/openqa/selenium/bidi/BUILD.bazel

@@ -14,6 +14,7 @@ java_library(
         ":bidi",
         "//java:auto-service",
         "//java/src/org/openqa/selenium:core",
+        "//java/src/org/openqa/selenium/concurrent",
         "//java/src/org/openqa/selenium/remote:api",
         "//java/src/org/openqa/selenium/remote/http",
     ],

java/src/org/openqa/selenium/bidi/BiDiProvider.java

@@ -17,12 +17,17 @@
 
 package org.openqa.selenium.bidi;
 
+import static java.util.logging.Level.INFO;
+import static org.openqa.selenium.concurrent.Lazy.lazy;
+
 import com.google.auto.service.AutoService;
 import java.net.URI;
 import java.net.URISyntaxException;
 import java.util.Optional;
 import java.util.function.Predicate;
+import java.util.logging.Logger;
 import org.openqa.selenium.Capabilities;
+import org.openqa.selenium.concurrent.Lazy;
 import org.openqa.selenium.remote.AugmenterProvider;
 import org.openqa.selenium.remote.ExecuteMethod;
 import org.openqa.selenium.remote.http.ClientConfig;
@@ -31,6 +36,7 @@
 @SuppressWarnings({"rawtypes", "RedundantSuppression"})
 @AutoService(AugmenterProvider.class)
 public class BiDiProvider implements AugmenterProvider<HasBiDi> {
+  private static final Logger LOG = Logger.getLogger(BiDiProvider.class.getName());
 
   @Override
   public Predicate<Capabilities> isApplicable() {
@@ -44,15 +50,35 @@ public Class<HasBiDi> getDescribedInterface() {
 
   @Override
   public HasBiDi getImplementation(Capabilities caps, ExecuteMethod executeMethod) {
+    final Lazy<BiDi> biDi = lazy(() -> establishBiDiConnection(caps));
+
+    LOG.log(
+        INFO,
+        "WebDriver augmented with BiDi interface; connection will not be verified until first"
+            + " use.");
+
+    return new HasBiDi() {
+      @Override
+      public Optional<BiDi> maybeGetBiDi() {
+        return biDi.getIfInitialized();
+      }
+
+      @Override
+      public BiDi getBiDi() {
+        return biDi.get();
+      }
+    };
+  }
 
+  private BiDi establishBiDiConnection(Capabilities caps) {
     URI wsUri = getBiDiUrl(caps).orElseThrow(() -> new BiDiException("BiDi not supported"));
 
     HttpClient.Factory clientFactory = HttpClient.Factory.createDefault();
     ClientConfig wsConfig = ClientConfig.defaultConfig().baseUri(wsUri);
     HttpClient wsClient = clientFactory.createClient(wsConfig);
     Connection connection = new Connection(wsClient, wsUri.toString());
 
-    return () -> Optional.of(new BiDi(connection));
+    return new BiDi(connection);
   }
 
   private Optional<URI> getBiDiUrl(Capabilities caps) {

java/src/org/openqa/selenium/concurrent/BUILD.bazel

@@ -4,11 +4,15 @@ java_library(
     name = "concurrent",
     srcs = glob(["*.java"]),
     visibility = [
+        "//java/src/org/openqa/selenium/bidi:__subpackages__",
+        "//java/src/org/openqa/selenium/devtools:__subpackages__",
         "//java/src/org/openqa/selenium/events:__subpackages__",
         "//java/src/org/openqa/selenium/grid:__subpackages__",
         "//java/src/org/openqa/selenium/remote:__subpackages__",
+        "//java/test/org/openqa/selenium/concurrent:__subpackages__",
     ],
     deps = [
         "//java/src/org/openqa/selenium:core",
+        "@maven//:org_jspecify_jspecify",
     ],
 )

java/src/org/openqa/selenium/concurrent/Lazy.java

@@ -0,0 +1,53 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.openqa.selenium.concurrent;
+
+import static java.util.Objects.requireNonNull;
+
+import java.util.Optional;
+import java.util.function.Supplier;
+import org.jspecify.annotations.Nullable;
+
+public class Lazy<T> {
+
+  @Nullable private volatile T value;
+  private final Supplier<T> supplier;
+
+  private Lazy(Supplier<T> supplier) {
+    this.supplier = supplier;
+  }
+
+  public Optional<T> getIfInitialized() {
+    return Optional.ofNullable(value);
+  }
+
+  public T get() {
+    if (value == null) {
+      synchronized (this) {
+        if (value == null) {
+          value = supplier.get();
+        }
+      }
+    }
+    return requireNonNull(value);
+  }
+
+  public static <T> Lazy<T> lazy(Supplier<T> supplier) {
+    return new Lazy<>(supplier);
+  }
+}

java/src/org/openqa/selenium/concurrent/package-info.java

@@ -0,0 +1,21 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+@NullMarked
+package org.openqa.selenium.concurrent;
+
+import org.jspecify.annotations.NullMarked;

java/src/org/openqa/selenium/devtools/BUILD.bazel

@@ -46,6 +46,7 @@ java_library(
         ":devtools",
         "//java:auto-service",
         "//java/src/org/openqa/selenium:core",
+        "//java/src/org/openqa/selenium/concurrent",
         "//java/src/org/openqa/selenium/remote:api",
     ],
 )

java/src/org/openqa/selenium/devtools/DevToolsProvider.java

@@ -17,18 +17,24 @@
 
 package org.openqa.selenium.devtools;
 
+import static java.util.logging.Level.INFO;
+import static org.openqa.selenium.concurrent.Lazy.lazy;
+
 import com.google.auto.service.AutoService;
 import java.net.URI;
 import java.util.Optional;
 import java.util.function.Predicate;
+import java.util.logging.Logger;
 import org.openqa.selenium.Capabilities;
+import org.openqa.selenium.concurrent.Lazy;
 import org.openqa.selenium.devtools.noop.NoOpCdpInfo;
 import org.openqa.selenium.remote.AugmenterProvider;
 import org.openqa.selenium.remote.ExecuteMethod;
 
 @SuppressWarnings({"rawtypes", "RedundantSuppression"})
 @AutoService(AugmenterProvider.class)
 public class DevToolsProvider implements AugmenterProvider<HasDevTools> {
+  private static final Logger LOG = Logger.getLogger(DevToolsProvider.class.getName());
 
   @Override
   public Predicate<Capabilities> isApplicable() {
@@ -42,14 +48,34 @@ public Class<HasDevTools> getDescribedInterface() {
 
   @Override
   public HasDevTools getImplementation(Capabilities caps, ExecuteMethod executeMethod) {
+    final Lazy<DevTools> devTools = lazy(() -> establishDevToolsConnection(caps));
+
+    LOG.log(
+        INFO,
+        "WebDriver augmented with DevTools interface; connection will not be verified until first"
+            + " use.");
+
+    return new HasDevTools() {
+      @Override
+      public Optional<DevTools> maybeGetDevTools() {
+        return devTools.getIfInitialized();
+      }
+
+      @Override
+      public DevTools getDevTools() {
+        return devTools.get();
+      }
+    };
+  }
+
+  private DevTools establishDevToolsConnection(Capabilities caps) {
     Object cdpVersion = caps.getCapability("se:cdpVersion");
     String version = cdpVersion instanceof String ? (String) cdpVersion : caps.getBrowserVersion();
 
     CdpInfo info = new CdpVersionFinder().match(version).orElseGet(NoOpCdpInfo::new);
-    Optional<DevTools> devTools =
-        SeleniumCdpConnection.create(caps).map(conn -> new DevTools(info::getDomains, conn));
-
-    return () -> devTools;
+    return SeleniumCdpConnection.create(caps)
+        .map(conn -> new DevTools(info::getDomains, conn))
+        .orElseThrow(() -> new DevToolsException("Unable to create DevTools connection"));
   }
 
   private String getCdpUrl(Capabilities caps) {

java/test/org/openqa/selenium/concurrent/BUILD.bazel

@@ -0,0 +1,14 @@
+load("@rules_jvm_external//:defs.bzl", "artifact")
+load("//java:defs.bzl", "JUNIT5_DEPS", "java_test_suite")
+
+java_test_suite(
+    name = "SmallTests",
+    size = "small",
+    srcs = glob(["*Test.java"]),
+    deps = [
+        "//java/src/org/openqa/selenium/concurrent",
+        "//java/test/org/openqa/selenium/testing:annotations",
+        artifact("org.junit.jupiter:junit-jupiter-api"),
+        artifact("org.assertj:assertj-core"),
+    ] + JUNIT5_DEPS,
+)

java/test/org/openqa/selenium/concurrent/LazyTest.java

@@ -0,0 +1,66 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+package org.openqa.selenium.concurrent;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.util.concurrent.atomic.AtomicInteger;
+import org.junit.jupiter.api.Tag;
+import org.junit.jupiter.api.Test;
+
+@Tag("UnitTests")
+public class LazyTest {
+  private final AtomicInteger counter = new AtomicInteger(0);
+
+  @Test
+  void trivialCase() {
+    Lazy expression = Lazy.lazy(() -> "constant");
+    assertThat(expression.get()).isEqualTo("constant");
+    assertThat(expression.getIfInitialized()).contains("constant");
+  }
+
+  @Test
+  void getIfInitialized_returnsNothing_ifNotInitializedYet() {
+    Lazy expression = Lazy.lazy(() -> "value#" + counter.incrementAndGet());
+    assertThat(expression.getIfInitialized()).isEmpty();
+  }
+
+  @Test
+  void lazyEvaluatedExpression() {
+    Lazy expression = Lazy.lazy(() -> "value#" + counter.incrementAndGet());
+    assertThat(expression.get()).isEqualTo("value#1");
+    assertThat(expression.get()).isEqualTo("value#1");
+    assertThat(expression.getIfInitialized()).contains("value#1");
+    assertThat(expression.getIfInitialized()).contains("value#1");
+  }
+
+  @Test
+  void differentLazyInstances_produce_differentValues() {
+    Lazy expression1 = Lazy.lazy(() -> "one#" + counter.incrementAndGet());
+    Lazy expression2 = Lazy.lazy(() -> "two#" + counter.incrementAndGet());
+    assertThat(expression1.get()).isEqualTo("one#1");
+    assertThat(expression1.getIfInitialized()).contains("one#1");
+    assertThat(expression2.getIfInitialized()).isEmpty();
+
+    assertThat(expression2.get()).isEqualTo("two#2");
+    assertThat(expression2.getIfInitialized()).contains("two#2");
+
+    assertThat(expression1.get()).isEqualTo("one#1");
+    assertThat(expression2.get()).isEqualTo("two#2");
+  }
+}