PHOENIX-7879 Tests for EXPLAIN text and ExplainPlanAttributes serialization compatibility

phoenix-core-client/src/main/java/org/apache/phoenix/compile/ExplainPlanAttributes.java

@@ -17,6 +17,8 @@
  */
 package org.apache.phoenix.compile;
 
+import com.fasterxml.jackson.annotation.JsonPropertyOrder;
+import com.fasterxml.jackson.databind.annotation.JsonSerialize;
 import java.util.List;
 import java.util.Set;
 import org.apache.hadoop.hbase.HRegionLocation;
@@ -30,6 +32,15 @@
  * against. This also makes attribute retrieval easier as an API rather than retrieving list of
  * Strings containing entire plan.
  */
+@JsonPropertyOrder({ "abstractExplainPlan", "splitsChunk", "estimatedRows", "estimatedSizeInBytes",
+  "iteratorTypeAndScanSize", "samplingRate", "useRoundRobinIterator", "hexStringRVCOffset",
+  "consistency", "hint", "serverSortedBy", "explainScanType", "tableName", "keyRanges",
+  "scanTimeRangeMin", "scanTimeRangeMax", "serverWhereFilter", "serverDistinctFilter",
+  "serverOffset", "serverRowLimit", "serverArrayElementProjection", "serverAggregate",
+  "clientFilterBy", "clientAggregate", "clientSortedBy", "clientAfterAggregate",
+  "clientDistinctFilter", "clientOffset", "clientRowLimit", "clientSequenceCount",
+  "clientCursorName", "clientSortAlgo", "rhsJoinQueryExplainPlan", "serverMergeColumns",
+  "regionLocations", "numRegionLocationLookups" })
 public class ExplainPlanAttributes {
 
   private final String abstractExplainPlan;
@@ -299,10 +310,12 @@ public ExplainPlanAttributes getRhsJoinQueryExplainPlan() {
     return rhsJoinQueryExplainPlan;
   }
 
+  @JsonSerialize(using = ServerMergeColumnsSerializer.class)
   public Set<PColumn> getServerMergeColumns() {
     return serverMergeColumns;
   }
 
+  @JsonSerialize(using = RegionLocationsListSerializer.class)
   public List<HRegionLocation> getRegionLocations() {
     return regionLocations;
   }

phoenix-core-client/src/main/java/org/apache/phoenix/compile/RegionLocationsListSerializer.java

@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF 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.apache.phoenix.compile;
+
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.databind.SerializerProvider;
+import com.fasterxml.jackson.databind.ser.std.StdSerializer;
+import java.io.IOException;
+import java.util.List;
+import org.apache.hadoop.hbase.HRegionLocation;
+import org.apache.hadoop.hbase.ServerName;
+import org.apache.hadoop.hbase.client.RegionInfo;
+import org.apache.hadoop.hbase.util.Bytes;
+
+/**
+ * Jackson serializer for {@code List<HRegionLocation>} as it appears on
+ * {@link ExplainPlanAttributes#getRegionLocations()}. The HBase {@code HRegionLocation} bean is not
+ * cleanly serializable by Jackson's default introspection.
+ */
+public class RegionLocationsListSerializer extends StdSerializer<List<HRegionLocation>> {
+
+  private static final long serialVersionUID = 1L;
+
+  @SuppressWarnings("unchecked")
+  public RegionLocationsListSerializer() {
+    super((Class<List<HRegionLocation>>) (Class<?>) List.class);
+  }
+
+  @Override
+  public void serialize(List<HRegionLocation> value, JsonGenerator gen, SerializerProvider provider)
+    throws IOException {
+    gen.writeStartArray();
+    for (HRegionLocation loc : value) {
+      gen.writeStartObject();
+      RegionInfo region = loc == null ? null : loc.getRegion();
+      gen.writeStringField("startKey",
+        region == null ? null : Bytes.toStringBinary(region.getStartKey()));
+      gen.writeStringField("endKey",
+        region == null ? null : Bytes.toStringBinary(region.getEndKey()));
+      ServerName sn = loc == null ? null : loc.getServerName();
+      gen.writeStringField("server", sn == null ? null : sn.toString());
+      gen.writeEndObject();
+    }
+    gen.writeEndArray();
+  }
+}

phoenix-core-client/src/main/java/org/apache/phoenix/compile/ServerMergeColumnsSerializer.java

@@ -0,0 +1,63 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF 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.apache.phoenix.compile;
+
+import com.fasterxml.jackson.core.JsonGenerator;
+import com.fasterxml.jackson.databind.SerializerProvider;
+import com.fasterxml.jackson.databind.ser.std.StdSerializer;
+import java.io.IOException;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Set;
+import org.apache.phoenix.schema.PColumn;
+
+/**
+ * Jackson serializer for {@code Set<PColumn>} as it appears on
+ * {@link ExplainPlanAttributes#getServerMergeColumns()}. {@code PColumn} is an interface backed by
+ * implementations that are not Jackson-friendly.
+ */
+public class ServerMergeColumnsSerializer extends StdSerializer<Set<PColumn>> {
+
+  private static final long serialVersionUID = 1L;
+
+  @SuppressWarnings("unchecked")
+  public ServerMergeColumnsSerializer() {
+    super((Class<Set<PColumn>>) (Class<?>) Set.class);
+  }
+
+  @Override
+  public void serialize(Set<PColumn> value, JsonGenerator gen, SerializerProvider provider)
+    throws IOException {
+    List<String> names = new ArrayList<>(value.size());
+    for (PColumn column : value) {
+      names.add(column == null ? null : column.toString());
+    }
+    Collections.sort(names, (a, b) -> {
+      if (a == null && b == null) return 0;
+      if (a == null) return -1;
+      if (b == null) return 1;
+      return a.compareTo(b);
+    });
+    gen.writeStartArray();
+    for (String name : names) {
+      gen.writeString(name);
+    }
+    gen.writeEndArray();
+  }
+}

phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainChangeRule.java

@@ -0,0 +1,54 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF 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.apache.phoenix.query.explain;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import java.util.List;
+
+/**
+ * The {@link ExplainOracle} freezes today's EXPLAIN output as a set of golden fixtures. Future
+ * EXPLAIN-design PRs that intentionally change the output register an {@code ExplainChangeRule}
+ * that rewrites the (frozen) form into the new expected form, so every change to the grammar is
+ * explicit and reviewable.
+ */
+public interface ExplainChangeRule {
+
+  /**
+   * Transform the golden plan steps text for the named case. The default implementation returns
+   * {@code goldenText} unchanged.
+   * @param caseId     the corpus case identifier (e.g. {@code "pointLookup"})
+   * @param goldenText the line-oriented golden as currently expected (already transformed by any
+   *                   earlier rule in the chain)
+   * @return the next-expected golden text (may be a new list or the same instance)
+   */
+  default List<String> applyText(String caseId, List<String> goldenText) {
+    return goldenText;
+  }
+
+  /**
+   * Transform the golden JSON attributes tree for the named case. The default implementation
+   * returns {@code goldenJson} unchanged.
+   * @param caseId     the corpus case identifier
+   * @param goldenJson the JSON attributes tree as currently expected (already transformed by any
+   *                   earlier rule in the chain)
+   * @return the next-expected JSON tree (may be a mutated input or a new node)
+   */
+  default JsonNode applyJson(String caseId, JsonNode goldenJson) {
+    return goldenJson;
+  }
+}

phoenix-core/src/test/java/org/apache/phoenix/query/explain/ExplainJsonNormalizer.java

@@ -0,0 +1,71 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF 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.apache.phoenix.query.explain;
+
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.NullNode;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import java.util.regex.Pattern;
+
+/**
+ * Elides cluster- and connection-specific fields from the JSON view of
+ * {@code ExplainPlanAttributes} so the comparison is invariant under environment differences.
+ */
+public final class ExplainJsonNormalizer {
+
+  private static final Pattern WAY_COUNT = Pattern.compile("\\b\\d+-WAY\\b");
+
+  /**
+   * Recursively normalize the given attributes-shaped JSON node.
+   * @return the same node, for fluent chaining.
+   */
+  public JsonNode normalize(JsonNode node) {
+    if (node == null || node.isNull() || !node.isObject()) {
+      return node;
+    }
+    ObjectNode obj = (ObjectNode) node;
+
+    if (obj.has("regionLocations")) {
+      obj.set("regionLocations", NullNode.getInstance());
+    }
+    if (obj.has("numRegionLocationLookups")) {
+      obj.put("numRegionLocationLookups", 0);
+    }
+    if (obj.has("splitsChunk")) {
+      obj.set("splitsChunk", NullNode.getInstance());
+    }
+    if (obj.has("estimatedRows")) {
+      obj.set("estimatedRows", NullNode.getInstance());
+    }
+    if (obj.has("estimatedSizeInBytes")) {
+      obj.set("estimatedSizeInBytes", NullNode.getInstance());
+    }
+
+    JsonNode iter = obj.get("iteratorTypeAndScanSize");
+    if (iter != null && iter.isTextual()) {
+      obj.put("iteratorTypeAndScanSize", WAY_COUNT.matcher(iter.asText()).replaceAll("<N>-WAY"));
+    }
+
+    JsonNode rhs = obj.get("rhsJoinQueryExplainPlan");
+    if (rhs != null && rhs.isObject()) {
+      normalize(rhs);
+    }
+
+    return obj;
+  }
+}