[java][bidi] Allow passing subscription parameters for events

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

@@ -21,6 +21,7 @@
 
 import java.io.Closeable;
 import java.time.Duration;
+import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
@@ -116,6 +117,18 @@ public <X> String addListener(
     return subscriptionId;
   }
 
+  <X> String addListener(Event<X> event, Consumer<X> handler, SubscriptionScope scope) {
+    Require.nonNull("Event to listen for", event);
+    Require.nonNull("Handler to call", handler);
+    Require.nonNull("Subscription scope", scope);
+
+    Map<String, Object> params = new HashMap<>(scope.toMap());
+    params.put("events", List.of(event.getMethod()));
+    String subscriptionId = subscribe(params);
+    connection.addListener(subscriptionId, event, handler);
+    return subscriptionId;
+  }
+
   // The subscription id returned by the browser is the sole identifier we need to unsubscribe
   // later: it is unique regardless of whether the subscription was scoped to events, contexts, or
   // user contexts, so there is no need to separately track how a listener was subscribed.

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

@@ -45,6 +45,10 @@ <X> String subscribe(Event<X> event, Consumer<X> handler) {
     return bidi.addListener(event, handler);
   }
 
+  <X> String subscribe(Event<X> event, Consumer<X> handler, SubscriptionScope scope) {
+    return bidi.addListener(event, handler, scope);
+  }
+
   void unsubscribe(String subscriptionId) {
     bidi.removeListener(subscriptionId);
   }

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

@@ -49,6 +49,11 @@ protected final <X> String subscribe(Event<X> event, Consumer<X> handler) {
     return handle.subscribe(event, handler);
   }
 
+  protected final <X> String subscribe(
+      Event<X> event, Consumer<X> handler, SubscriptionScope scope) {
+    return handle.subscribe(event, handler, scope);
+  }
+
   protected final void unsubscribe(String subscriptionId) {
     handle.unsubscribe(subscriptionId);
   }

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

@@ -0,0 +1,74 @@
+// 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.bidi;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Set;
+import org.openqa.selenium.Beta;
+import org.openqa.selenium.internal.Require;
+
+/**
+ * Where a subscription applies: globally, or scoped to browsing contexts and/or user contexts. Part
+ * of the transport layer, not generated — the remote end decides which combinations are valid.
+ *
+ * <p>This class is intentionally limited to the scope of a subscription, not the full set of
+ * subscribe parameters.
+ *
+ * @see <a href="https://www.w3.org/TR/webdriver-bidi/#type-session-SubscriptionParameters">
+ *     session.SubscriptionParameters</a>
+ */
+@Beta
+public final class SubscriptionScope {
+
+  private Set<String> contexts = Set.of();
+  private Set<String> userContexts = Set.of();
+
+  /**
+   * Scopes the subscription to the given browsing contexts.
+   *
+   * @param contexts the browsing context ids to scope the subscription to
+   * @return this scope, for chaining
+   */
+  public SubscriptionScope contexts(Set<String> contexts) {
+    this.contexts = Set.copyOf(Require.nonNull("Browsing context ids", contexts));
+    return this;
+  }
+
+  /**
+   * Scopes the subscription to the given user contexts.
+   *
+   * @param userContexts the user context ids to scope the subscription to
+   * @return this scope, for chaining
+   */
+  public SubscriptionScope userContexts(Set<String> userContexts) {
+    this.userContexts = Set.copyOf(Require.nonNull("User context ids", userContexts));
+    return this;
+  }
+
+  Map<String, Object> toMap() {
+    Map<String, Object> params = new HashMap<>();
+    if (!contexts.isEmpty()) {
+      params.put("contexts", contexts);
+    }
+    if (!userContexts.isEmpty()) {
+      params.put("userContexts", userContexts);
+    }
+    return params;
+  }
+}