Scaffolding for implementing the W3C Actions APIs.

Try and do this with minimal impact on the existing
classes, other than adding the implementation. This
allows us to make the switch to the new API lighter
and easier to rollback without losing everything if
we discover we've Made A Terrible Mistake somewhere
in our implementation.

java/client/src/org/openqa/selenium/BUCK

@@ -78,6 +78,7 @@ genrule(name = 'manifest',
 java_library(name = 'beta',
   srcs = [ 'Beta.java' ],
   visibility = [
+    '//java/client/src/org/openqa/selenium/interactions:interactions',
     '//java/client/src/org/openqa/selenium/logging:api',
     '//java/client/src/org/openqa/selenium/logging:logging',
     '//java/client/src/org/openqa/selenium/os:os',
@@ -119,6 +120,7 @@ java_library(name = 'exceptions',
   ],
   visibility = [
     '//java/client/src/org/openqa/selenium/interactions:exceptions',
+    '//java/client/src/org/openqa/selenium/interactions:interactions',
     '//java/client/src/org/openqa/selenium/io:io',
     '//java/client/src/org/openqa/selenium/net:net',
     '//java/client/src/org/openqa/selenium/os:os',

java/client/src/org/openqa/selenium/interactions/BUCK

@@ -1,13 +1,18 @@
 java_library(name = 'interactions',
   srcs = [
     'Actions.java',
+    'KeyInput.java',
+    'IsInteraction.java',
+    'PointerInput.java',
   ] + glob(['*Action.java', 'internal/*Action.java', 'touch/*.java'], excludes = ['Action.java']),
   exported_deps = [
     ':core',
     ':exceptions',
     '//java/client/src/org/openqa/selenium:core',
   ],
   deps = [
+    '//java/client/src/org/openqa/selenium:beta',
+    '//java/client/src/org/openqa/selenium:exceptions',
     '//third_party/java/guava:guava',
   ],
   visibility = [
@@ -18,10 +23,17 @@ java_library(name = 'interactions',
 java_library(name = 'core',
   srcs = [
     'Action.java',
+    'Encodable.java',
     'HasInputDevices.java',
     'HasTouchScreen.java',
+    'InputSource.java',
+    'Interaction.java',
+    'Interactive.java',
     'Keyboard.java',
     'Mouse.java',
+    'Pause.java',
+    'Sequence.java',
+    'SourceType.java',
     'TouchScreen.java',
     'internal/Coordinates.java',
   ],

java/client/src/org/openqa/selenium/interactions/Encodable.java

@@ -0,0 +1,29 @@
+// 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.interactions;
+
+import java.util.Map;
+
+/**
+ * This interface allows a custom {@link Interaction} to be JSON encoded for the W3C wire format. It
+ * should not normally be exposed or used by user-facing APIs. Instead, these should traffic in the
+ * {@link Interaction} interface.
+ */
+public interface Encodable {
+  Map<String, Object> encode();
+}

java/client/src/org/openqa/selenium/interactions/InputSource.java

@@ -0,0 +1,26 @@
+// 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.interactions;
+
+/**
+ * Models an <a href="https://www.w3.org/TR/webdriver/#dfn-input-source">input source</a> as defined
+ * and used by the W3C WebDriver spec.
+ */
+public interface InputSource {
+  SourceType getInputType();
+}

java/client/src/org/openqa/selenium/interactions/Interaction.java

@@ -0,0 +1,43 @@
+// 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.interactions;
+
+/**
+ * Used as the basis of {@link Sequence}s for the W3C WebDriver spec
+ * <a href="https://www.w3.org/TR/webdriver/#actions">Action commands</a>.
+ */
+public abstract class Interaction {
+
+  private final InputSource source;
+
+  protected Interaction(InputSource source) {
+    // Avoiding a guava dependency.
+    if (source == null) {
+      throw new NullPointerException("Input source must not be null");
+    }
+    this.source = source;
+  }
+
+  protected boolean isValidFor(SourceType sourceType) {
+    return source.getInputType() == sourceType;
+  }
+
+  public InputSource getSource() {
+    return source;
+  }
+}

java/client/src/org/openqa/selenium/interactions/Interactive.java

@@ -0,0 +1,29 @@
+// 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.interactions;
+
+import java.util.Collection;
+
+/**
+ * Indicates that a class can be used with the W3C WebDriver
+ * <a href="https://www.w3.org/TR/webdriver/#actions">Actions commands</a>.
+ */
+public interface Interactive {
+  void perform(Collection<Sequence> actions);
+  void resetInputState();
+}

java/client/src/org/openqa/selenium/interactions/IsInteraction.java

@@ -0,0 +1,30 @@
+// 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.interactions;
+
+import org.openqa.selenium.Beta;
+
+import java.util.List;
+
+/**
+ * Interface to help us transition code to The New World
+ */
+@Beta
+public interface IsInteraction {
+  List<Interaction> asInteractions(PointerInput mouse, KeyInput keyboard);
+}

java/client/src/org/openqa/selenium/interactions/KeyInput.java

@@ -0,0 +1,81 @@
+// 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.interactions;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * Models a <a href="https://www.w3.org/TR/webdriver/#dfn-key-input-source">key input source</a>.
+ */
+public class KeyInput implements InputSource, Encodable {
+
+  private final String name;
+
+  public KeyInput(Optional<String> name) {
+    this.name = name.orElse(UUID.randomUUID().toString());
+  }
+
+  @Override
+  public SourceType getInputType() {
+    return SourceType.KEY;
+  }
+
+  public Interaction createKeyDown(int codePoint) {
+    return new TypingInteraction(this, "keyDown", codePoint);
+  }
+
+  public Interaction createKeyUp(int codePoint) {
+    return new TypingInteraction(this, "keyUp", codePoint);
+  }
+
+  @Override
+  public Map<String, Object> encode() {
+    Map<String, Object> toReturn = new HashMap<>();
+
+    toReturn.put("type", "key");
+    toReturn.put("id", name);
+
+    return toReturn;
+  }
+
+  private static class TypingInteraction extends Interaction implements Encodable {
+
+    private final String type;
+    private final String value;
+
+    TypingInteraction(InputSource source, String type, int codePoint) {
+      super(source);
+
+      this.type = type;
+      this.value = new StringBuilder().appendCodePoint(codePoint).toString();
+    }
+
+    @Override
+    public Map<String, Object> encode() {
+      HashMap<String, Object> toReturn = new HashMap<>();
+
+      toReturn.put("type", type);
+      toReturn.put("value", value);
+
+      return toReturn;
+    }
+  }
+}

java/client/src/org/openqa/selenium/interactions/Pause.java

@@ -0,0 +1,59 @@
+// 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.interactions;
+
+import java.time.Duration;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Indicates that a given {@link InputSource} should pause for a given duration.
+ */
+public class Pause extends Interaction implements Encodable {
+
+  private final Duration duration;
+
+  /**
+   * @param duration If 0, this means "wait until all other actions in the tick have been
+   *   evaluated". Must be greater than 0.
+   */
+  // TODO(simons): Reduce visibility?
+  public Pause(InputSource device, Duration duration) {
+    super(device);
+
+    if (duration.isNegative()) {
+      throw new IllegalStateException("Duration must be set to 0 or more: " + duration);
+    }
+    this.duration = duration;
+  }
+
+  @Override
+  protected boolean isValidFor(SourceType sourceType) {
+    return true;
+  }
+
+  @Override
+  public Map<String, Object> encode() {
+    Map<String, Object> toReturn = new HashMap<>();
+
+    toReturn.put("type", "pause");
+    toReturn.put("duration", duration.toMillis());
+
+    return toReturn;
+  }
+}