Refactor DocumentSource to enforce parameter count for polygon coordinates; update documentation for clarity on expected format and return values.

Author: wangchangjian1130

sdk/contentunderstanding/azure-ai-contentunderstanding/customization/src/main/java/ContentUnderstandingCustomizations.java

@@ -1489,18 +1489,18 @@ private void addSourcesMethod(LibraryCustomization customization, Logger logger)
         + "import java.util.List;\n"
         + "import java.util.Objects;\n\n"
         + "/**\n"
-        + " * Represents a parsed document grounding source in the format {@code D(page,x1,y1,...,xN,yN)} or {@code D(page)}.\n"
+        + " * Represents a parsed document grounding source in the format {@code D(page,x1,y1,x2,y2,x3,y3,x4,y4)}.\n"
         + " *\n"
-        + " * <p>The page number is 1-based. The polygon defines a region with three or more points\n"
-        + " * in the document's coordinate space. When only a page number is provided (no coordinates),\n"
-        + " * {@link #getPolygon()} and {@link #getBoundingBox()} return {@code null}.</p>\n"
+        + " * <p>The page number is 1-based. The polygon is a quadrilateral defined by four points\n"
+        + " * with coordinates in the document's coordinate space.</p>\n"
         + " *\n"
         + " * @see ContentSource\n"
         + " */\n"
         + "@Immutable\n"
         + "public final class DocumentSource extends ContentSource {\n"
         + "    private static final ClientLogger LOGGER = new ClientLogger(DocumentSource.class);\n"
-        + "    private static final String PREFIX = \"D(\";\n\n"
+        + "    private static final String PREFIX = \"D(\";\n"
+        + "    private static final int EXPECTED_PARAM_COUNT = 9;\n\n"
         + "    private final int pageNumber;\n"
         + "    private final List<PointF> polygon;\n"
         + "    private final RectangleF boundingBox;\n\n"
@@ -1512,6 +1512,11 @@ private void addSourcesMethod(LibraryCustomization customization, Logger logger)
         + "        }\n"
         + "        String inner = source.substring(PREFIX.length(), source.length() - 1);\n"
         + "        String[] parts = inner.split(\",\");\n"
+        + "        if (parts.length != EXPECTED_PARAM_COUNT) {\n"
+        + "            throw LOGGER.logExceptionAsError(\n"
+        + "                new IllegalArgumentException(\"Document source expected \" + EXPECTED_PARAM_COUNT\n"
+        + "                    + \" parameters (page + 8 coordinates), got \" + parts.length + \": '\" + source + \"'.\"));\n"
+        + "        }\n"
         + "        try {\n"
         + "            this.pageNumber = Integer.parseInt(parts[0].trim());\n"
         + "        } catch (NumberFormatException e) {\n"
@@ -1522,23 +1527,10 @@ private void addSourcesMethod(LibraryCustomization customization, Logger logger)
         + "            throw LOGGER.logExceptionAsError(\n"
         + "                new IllegalArgumentException(\"Page number must be >= 1, got \" + this.pageNumber + \".\"));\n"
         + "        }\n"
-        + "        if (parts.length == 1) {\n"
-        + "            // Page-only: D(page)\n"
-        + "            this.polygon = null;\n"
-        + "            this.boundingBox = null;\n"
-        + "            return;\n"
-        + "        }\n"
-        + "        int coordCount = parts.length - 1;\n"
-        + "        if (coordCount < 6 || coordCount % 2 != 0) {\n"
-        + "            throw LOGGER.logExceptionAsError(\n"
-        + "                new IllegalArgumentException(\"Document source expected page-only (1 param) or page + at least 3 coordinate pairs (7+ params), got \"\n"
-        + "                    + parts.length + \": '\" + source + \"'.\"));\n"
-        + "        }\n"
-        + "        int pointCount = coordCount / 2;\n"
-        + "        List<PointF> points = new ArrayList<>(pointCount);\n"
+        + "        List<PointF> points = new ArrayList<>(4);\n"
         + "        float minX = Float.MAX_VALUE, minY = Float.MAX_VALUE;\n"
         + "        float maxX = -Float.MAX_VALUE, maxY = -Float.MAX_VALUE;\n"
-        + "        for (int i = 0; i < pointCount; i++) {\n"
+        + "        for (int i = 0; i < 4; i++) {\n"
         + "            int xIndex = 1 + (i * 2);\n"
         + "            int yIndex = 2 + (i * 2);\n"
         + "            float x, y;\n"
@@ -1572,27 +1564,26 @@ private void addSourcesMethod(LibraryCustomization customization, Logger logger)
         + "        return pageNumber;\n"
         + "    }\n\n"
         + "    /**\n"
-        + "     * Gets the polygon coordinates defining the region, or {@code null} when only a page number is available.\n"
+        + "     * Gets the polygon coordinates as four points defining a quadrilateral region.\n"
         + "     *\n"
-        + "     * @return An unmodifiable list of {@link PointF} values, or {@code null} for page-only sources.\n"
+        + "     * @return An unmodifiable list of four {@link PointF} values.\n"
         + "     */\n"
         + "    public List<PointF> getPolygon() {\n"
         + "        return polygon;\n"
         + "    }\n\n"
         + "    /**\n"
-        + "     * Gets the axis-aligned bounding rectangle computed from the polygon coordinates,\n"
-        + "     * or {@code null} when only a page number is available.\n"
+        + "     * Gets the axis-aligned bounding rectangle computed from the polygon coordinates.\n"
         + "     * Useful for drawing highlight rectangles over extracted fields.\n"
         + "     *\n"
-        + "     * @return The bounding box, or {@code null} for page-only sources.\n"
+        + "     * @return The bounding box.\n"
         + "     */\n"
         + "    public RectangleF getBoundingBox() {\n"
         + "        return boundingBox;\n"
         + "    }\n\n"
         + "    /**\n"
         + "     * Parses a single document source segment.\n"
         + "     *\n"
-        + "     * @param source The source string in the format {@code D(page)} or {@code D(page,x1,y1,...,xN,yN)}.\n"
+        + "     * @param source The source string in the format {@code D(page,x1,y1,...,x4,y4)}.\n"
         + "     * @return A new {@link DocumentSource}.\n"
         + "     * @throws NullPointerException if {@code source} is null.\n"
         + "     * @throws IllegalArgumentException if the source string is not in the expected format.\n"