chore: make ScreencastFrame an interface in the playwright package

ScreencastFrame represents an event payload dispatched to the client,
so model it like WebSocketFrame: a top-level interface in the
com.microsoft.playwright package with accessor methods, and a hidden
*Impl class in the impl package.

Generator-side: when an Object inside a function arg carries a
langAlias, register it as a CustomInterface (rather than a CustomClass
of public fields) and write it to the playwright package directory.

This is a breaking change to the screencast API introduced in 1.59:
frame.data -> frame.data(), and the type now lives in
com.microsoft.playwright instead of com.microsoft.playwright.options.

Author: yury-s

…/playwright/options/ScreencastFrame.java …icrosoft/playwright/ScreencastFrame.javaplaywright/src/main/java/com/microsoft/playwright/options/ScreencastFrame.java renamed to playwright/src/main/java/com/microsoft/playwright/ScreencastFrame.java playwright/src/main/java/com/microsoft/playwright/options/ScreencastFrame.java renamed to playwright/src/main/java/com/microsoft/playwright/ScreencastFrame.java

@@ -14,25 +14,21 @@
  * limitations under the License.
  */
 
-package com.microsoft.playwright.options;
+package com.microsoft.playwright;
 
-public class ScreencastFrame {
+public interface ScreencastFrame {
   /**
    * JPEG-encoded frame data.
    */
-  public byte[] data;
+  byte[] data();
+
   /**
    * Width of the page viewport at the time the frame was captured.
    */
-  public int viewportWidth;
+  int viewportWidth();
+
   /**
    * Height of the page viewport at the time the frame was captured.
    */
-  public int viewportHeight;
-
-  public ScreencastFrame(byte[] data, int viewportWidth, int viewportHeight) {
-    this.data = data;
-    this.viewportWidth = viewportWidth;
-    this.viewportHeight = viewportHeight;
-  }
+  int viewportHeight();
 }

playwright/src/main/java/com/microsoft/playwright/impl/ScreencastFrameImpl.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) Microsoft Corporation.
+ *
+ * Licensed 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 com.microsoft.playwright.impl;
+
+import com.microsoft.playwright.ScreencastFrame;
+
+class ScreencastFrameImpl implements ScreencastFrame {
+  private final byte[] data;
+  private final int viewportWidth;
+  private final int viewportHeight;
+
+  ScreencastFrameImpl(byte[] data, int viewportWidth, int viewportHeight) {
+    this.data = data;
+    this.viewportWidth = viewportWidth;
+    this.viewportHeight = viewportHeight;
+  }
+
+  @Override
+  public byte[] data() {
+    return data;
+  }
+
+  @Override
+  public int viewportWidth() {
+    return viewportWidth;
+  }
+
+  @Override
+  public int viewportHeight() {
+    return viewportHeight;
+  }
+}

playwright/src/main/java/com/microsoft/playwright/impl/ScreencastImpl.java

@@ -19,7 +19,7 @@
 import com.google.gson.JsonObject;
 import com.microsoft.playwright.PlaywrightException;
 import com.microsoft.playwright.Screencast;
-import com.microsoft.playwright.options.ScreencastFrame;
+import com.microsoft.playwright.ScreencastFrame;
 
 import java.nio.file.Path;
 import java.util.function.Consumer;
@@ -46,7 +46,7 @@ void handleScreencastFrame(JsonObject params) {
     byte[] data = java.util.Base64.getDecoder().decode(dataBase64);
     int viewportWidth = params.get("viewportWidth").getAsInt();
     int viewportHeight = params.get("viewportHeight").getAsInt();
-    onFrame.accept(new ScreencastFrame(data, viewportWidth, viewportHeight));
+    onFrame.accept(new ScreencastFrameImpl(data, viewportWidth, viewportHeight));
   }
 
   @Override

playwright/src/test/java/com/microsoft/playwright/TestScreencast.java

@@ -16,7 +16,6 @@
 
 package com.microsoft.playwright;
 
-import com.microsoft.playwright.options.ScreencastFrame;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
 
@@ -113,9 +112,9 @@ void screencastStartShouldDeliverFramesViaOnFrame() throws Exception {
       assertFalse(frames.isEmpty(), "expected at least one frame");
       // JPEG-encoded frames start with FF D8.
       for (ScreencastFrame frame : frames) {
-        assertNotNull(frame.data);
-        assertEquals((byte) 0xFF, frame.data[0]);
-        assertEquals((byte) 0xD8, frame.data[1]);
+        assertNotNull(frame.data());
+        assertEquals((byte) 0xFF, frame.data()[0]);
+        assertEquals((byte) 0xD8, frame.data()[1]);
       }
     } finally {
       context.close();
@@ -135,8 +134,8 @@ void onFrameShouldReceiveViewportSize() {
       page.screencast().stop();
       assertFalse(frames.isEmpty(), "expected at least one frame");
       for (ScreencastFrame frame : frames) {
-        assertEquals(1000, frame.viewportWidth);
-        assertEquals(400, frame.viewportHeight);
+        assertEquals(1000, frame.viewportWidth());
+        assertEquals(400, frame.viewportHeight());
       }
     } finally {
       context.close();

tools/api-generator/src/main/java/com/microsoft/playwright/tools/ApiGenerator.java

@@ -328,8 +328,16 @@ private void createClassesAndEnums(JsonObject jsonObject) {
     }
     if ("function".equals(jsonObject.get("name").getAsString()) && jsonObject.has("args")) {
       for (JsonElement item : jsonObject.getAsJsonArray("args")) {
-        if (item.isJsonObject() && javaAlias(item.getAsJsonObject()) != null) {
-          createClassesAndEnums(item.getAsJsonObject());
+        if (!item.isJsonObject()) {
+          continue;
+        }
+        JsonObject argObject = item.getAsJsonObject();
+        if (!"Object".equals(argObject.get("name").getAsString())) {
+          continue;
+        }
+        String alias = javaAlias(argObject);
+        if (alias != null) {
+          typeScope().createTopLevelInterface(alias, this, argObject);
         }
       }
       return;
@@ -609,6 +617,14 @@ void createTopLevelClass(String name, Element parent, JsonObject jsonObject) {
     }
   }
 
+  void createTopLevelInterface(String name, Element parent, JsonObject jsonObject) {
+    Map<String, TypeDefinition> map = topLevelTypes();
+    TypeDefinition existing = map.putIfAbsent(name, new CustomInterface(parent, name, jsonObject));
+    if (existing != null && !(existing instanceof CustomInterface)) {
+      throw new RuntimeException("Two interfaces with same name have different values:\n" + jsonObject + "\n" + existing.jsonElement);
+    }
+  }
+
   void createNestedClass(String name, Element parent, JsonObject jsonObject) {
     for (CustomClass c : classes) {
       if (c.name.equals(name)) {
@@ -848,7 +864,7 @@ class Field extends Element {
   final String name;
   final TypeRef type;
 
-  Field(CustomClass parent, String name, JsonObject jsonElement) {
+  Field(TypeDefinition parent, String name, JsonObject jsonElement) {
     super(parent, jsonElement);
     this.name = name;
     this.type = new TypeRef(this, jsonElement.getAsJsonObject().get("type"));
@@ -1159,6 +1175,43 @@ private void writeConstructor(List<String> output, String bodyOffset) {
   }
 }
 
+class CustomInterface extends TypeDefinition {
+  final String name;
+  final List<Field> fields = new ArrayList<>();
+
+  CustomInterface(Element parent, String name, JsonObject jsonElement) {
+    super(parent, true, jsonElement);
+    this.name = name;
+    if (jsonElement.has("properties")) {
+      for (JsonElement item : jsonElement.getAsJsonArray("properties")) {
+        JsonObject propertyJson = item.getAsJsonObject();
+        fields.add(new Field(this, propertyJson.get("name").getAsString(), propertyJson));
+      }
+    }
+  }
+
+  @Override
+  String name() {
+    return name;
+  }
+
+  @Override
+  void writeTo(List<String> output, String offset) {
+    output.add(offset + "public interface " + name + " {");
+    String bodyOffset = offset + "  ";
+    boolean first = true;
+    for (Field f : fields) {
+      if (!first) {
+        output.add("");
+      }
+      first = false;
+      writeJavadoc(output, bodyOffset, f.comment());
+      output.add(bodyOffset + f.type.toJava() + " " + f.name + "();");
+    }
+    output.add(offset + "}");
+  }
+}
+
 class Enum extends TypeDefinition {
   final List<String> enumValues;
 
@@ -1207,18 +1260,25 @@ public class ApiGenerator {
     System.out.println("Writing assertion files to: " + dir.getCanonicalPath());
     generate(api, assertionsDir, "com.microsoft.playwright.assertions", isAssertion().and(isSoftAssertion().negate()), sharedTypes);
 
-    writeTopLevelTypes(sharedTypes, optionsDir, "com.microsoft.playwright");
+    writeTopLevelTypes(sharedTypes, dir, optionsDir, "com.microsoft.playwright");
   }
 
-  private void writeTopLevelTypes(Map<String, TypeDefinition> topLevelTypes, File optionsDir, String packageName) throws IOException {
+  private void writeTopLevelTypes(Map<String, TypeDefinition> topLevelTypes, File dir, File optionsDir, String packageName) throws IOException {
     for (TypeDefinition e : topLevelTypes.values()) {
       List<String> lines = new ArrayList<>();
       lines.add(Interface.header);
-      lines.add("package " + packageName + ".options;");
+      File targetDir;
+      if (e instanceof CustomInterface) {
+        lines.add("package " + packageName + ";");
+        targetDir = dir;
+      } else {
+        lines.add("package " + packageName + ".options;");
+        targetDir = optionsDir;
+      }
       lines.add("");
       e.writeTo(lines, "");
       String text = String.join("\n", lines);
-      try (FileWriter writer = new FileWriter(new File(optionsDir, e.name() + ".java"))) {
+      try (FileWriter writer = new FileWriter(new File(targetDir, e.name() + ".java"))) {
         writer.write(text);
       }
     }