Clean up RelNode.explain, to make it easier to extend. A RelNode derived class can now call super.explainTerms, so only needs to describe the attributes it adds over its base class.

Author: julianhyde

src/main/java/net/hydromatic/optiq/rules/java/JavaRules.java

@@ -550,9 +550,8 @@ public PhysType getPhysType() {
             return physType;
         }
 
-        public void explain(RelOptPlanWriter pw)
-        {
-            program.explainCalc(this, pw);
+        public RelOptPlanWriter explainTerms(RelOptPlanWriter pw) {
+            return program.explainCalc(super.explainTerms(pw));
         }
 
         public double getRows() {

src/main/java/org/eigenbase/oj/rel/IterCalcRel.java

@@ -105,9 +105,8 @@ public IterCalcRel(
     // TODO jvs 10-May-2004: need a computeSelfCost which takes condition into
     // account; maybe inherit from CalcRelBase?
 
-    public void explain(RelOptPlanWriter pw)
-    {
-        program.explainCalc(this, pw);
+    public RelOptPlanWriter explainTerms(RelOptPlanWriter pw) {
+        return program.explainCalc(super.explainTerms(pw));
     }
 
     protected String computeDigest()

src/main/java/org/eigenbase/rel/AbstractRelNode.java

@@ -299,9 +299,20 @@ public RelOptCost computeSelfCost(RelOptPlanner planner)
             0);
     }
 
-    public void explain(RelOptPlanWriter pw)
-    {
-        pw.explain(this, Util.emptyStringArray, Util.emptyObjectArray);
+    public final void explain(RelOptPlanWriter pw) {
+        explainTerms(pw).done(this);
+    }
+
+    /** Describes the inputs and attributes of this relational expression.
+     * Each node should call {@code super.explainTerms}, then call the
+     * {@link RelOptPlanWriter#input(String, RelNode)}
+     * and {@link RelOptPlanWriter#item(String, Object)} methods for each input
+     * and attribute.
+     *
+     * @param pw Plan writer
+     */
+    public RelOptPlanWriter explainTerms(RelOptPlanWriter pw) {
+        return pw;
     }
 
     public RelNode onRegister(RelOptPlanner planner)
@@ -380,8 +391,6 @@ public RelOptTable getTable()
 
     /**
      * Computes the digest. Does not modify this object.
-     *
-     * @post return != null
      */
     protected String computeDigest()
     {
@@ -391,54 +400,28 @@ protected String computeDigest()
                 new PrintWriter(sw),
                 SqlExplainLevel.DIGEST_ATTRIBUTES)
             {
-                public void explain(
-                    RelNode rel,
-                    String [] terms,
-                    Object [] values)
+                protected void explain_(
+                    RelNode rel, List<Pair<String, Object>> values)
                 {
-                    List<RelNode> inputs = rel.getInputs();
-                    RexNode [] childExps = rel.getChildExps();
-                    assert terms.length
-                        == (inputs.size() + childExps.length + values.length)
-                        : "terms.length="
-                        + terms.length
-                        + " inputs.length=" + inputs.size()
-                        + " childExps.length=" + childExps.length
-                        + " values.length=" + values.length;
-                    write(getRelTypeName());
-
-                    for (int i = 0; i < traitSet.size(); i++) {
-                        write(".");
-                        write(traitSet.getTrait(i).toString());
+                    pw.write(getRelTypeName());
+
+                    for (RelTrait trait : traitSet) {
+                        pw.write(".");
+                        pw.write(trait.toString());
                     }
 
-                    write("(");
+                    pw.write("(");
                     int j = 0;
-                    for (int i = 0; i < inputs.size(); i++) {
-                        if (j > 0) {
-                            write(",");
-                        }
-                        write(terms[j++] + "=" + inputs.get(i).getDigest());
-                    }
-                    for (int i = 0; i < childExps.length; i++) {
-                        if (j > 0) {
-                            write(",");
-                        }
-                        RexNode childExp = childExps[i];
-                        write(terms[j++] + "=" + childExp.toString());
-                    }
-                    for (int i = 0; i < values.length; i++) {
-                        Object value = values[i];
-                        if (j > 0) {
-                            write(",");
+                    for (Pair<String, Object> value : values) {
+                        if (j++ > 0) {
+                            pw.write(",");
                         }
-                        write(terms[j++] + "=" + value);
+                        pw.write(value.left + "=" + value.right);
                     }
-                    write(")");
+                    pw.write(")");
                 }
             };
         explain(pw);
-        pw.flush();
         return sw.toString();
     }
 }

src/main/java/org/eigenbase/rel/AggregateRelBase.java

@@ -27,6 +27,8 @@
 import org.eigenbase.sql.validate.*;
 import org.eigenbase.util.*;
 
+import net.hydromatic.linq4j.Ord;
+
 
 /**
  * <code>AggregateRelBase</code> is an abstract base class for implementations
@@ -120,39 +122,19 @@ public BitSet getGroupSet()
         return groupSet;
     }
 
-    public void explain(RelOptPlanWriter pw)
-    {
-        List<String> names = new ArrayList<String>();
-        List<Object> values = new ArrayList<Object>();
-        populateExplainAttributes(names, values);
-        pw.explain(this, names, values);
-    }
-
-    /**
-     * Populates attributes for EXPLAIN.
-     *
-     * @param names Names of attributes
-     * @param values Values of attributes
-     */
-    protected void populateExplainAttributes(
-        List<String> names,
-        List<Object> values)
-    {
-        names.add("child");
-        names.add("group");
-        values.add(groupSet);
-        int i = -1;
-        for (AggregateCall aggCall : aggCalls) {
-            ++i;
+    public RelOptPlanWriter explainTerms(RelOptPlanWriter pw) {
+        super.explainTerms(pw)
+            .item("group", groupSet);
+        for (Ord<AggregateCall> ord : Ord.zip(aggCalls)) {
             final String name;
-            if (aggCall.getName() != null) {
-                name = aggCall.getName();
+            if (ord.e.getName() != null) {
+                name = ord.e.getName();
             } else {
-                name = "agg#" + i;
+                name = "agg#" + ord.i;
             }
-            names.add(name);
-            values.add(aggCall);
+            pw.item(name, ord.e);
         }
+        return pw;
     }
 
     // implement RelNode

src/main/java/org/eigenbase/rel/CalcRelBase.java

@@ -129,9 +129,8 @@ public RelOptCost computeSelfCost(RelOptPlanner planner)
         return RexNode.EMPTY_ARRAY;
     }
 
-    public void explain(RelOptPlanWriter pw)
-    {
-        program.explainCalc(this, pw);
+    public RelOptPlanWriter explainTerms(RelOptPlanWriter pw) {
+        return program.explainCalc(super.explainTerms(pw));
     }
 }
 

src/main/java/org/eigenbase/rel/CorrelatorRel.java

@@ -120,17 +120,9 @@ public CorrelatorRel copy(
             joinType);
     }
 
-    public void explain(RelOptPlanWriter pw)
-    {
-        pw.explain(
-            this,
-            new String[] {
-                "left", "right", "condition", "joinType", "correlations"
-            },
-            new Object[] {
-                joinType.name().toLowerCase(),
-                correlations
-            });
+    public RelOptPlanWriter explainTerms(RelOptPlanWriter pw) {
+        return super.explainTerms(pw)
+            .item("correlations", correlations);
     }
 
     /**

src/main/java/org/eigenbase/rel/EmptyRel.java

@@ -93,19 +93,15 @@ public double getRows()
     }
 
     // implement RelNode
-    public void explain(RelOptPlanWriter pw)
-    {
-        if (pw.getDetailLevel() == SqlExplainLevel.DIGEST_ATTRIBUTES) {
+    public RelOptPlanWriter explainTerms(RelOptPlanWriter pw) {
+        return super.explainTerms(pw)
             // For rel digest, include the row type to discriminate
             // this from other empties with different row types.
-            pw.explain(
-                this,
-                new String[] { "type", },
-                new Object[] { rowType });
-        } else {
             // For normal EXPLAIN PLAN, omit the type.
-            super.explain(pw);
-        }
+            .itemIf(
+                "type",
+                rowType,
+                pw.getDetailLevel() == SqlExplainLevel.DIGEST_ATTRIBUTES);
     }
 }
 

src/main/java/org/eigenbase/rel/FilterRelBase.java

@@ -107,11 +107,9 @@ public static double estimateFilteredRows(RelNode child, RexNode condition)
             * RelMetadataQuery.getSelectivity(child, condition);
     }
 
-    public void explain(RelOptPlanWriter pw)
-    {
-        pw.explain(
-            this,
-            new String[] { "child", "condition" });
+    public RelOptPlanWriter explainTerms(RelOptPlanWriter pw) {
+        return super.explainTerms(pw)
+            .item("condition", condition);
     }
 }
 

src/main/java/org/eigenbase/rel/JoinRel.java

@@ -146,22 +146,16 @@ public JoinRel copy(
             systemFieldList);
     }
 
-    public void explain(RelOptPlanWriter pw)
+    public RelOptPlanWriter explainTerms(RelOptPlanWriter pw)
     {
         // NOTE jvs 14-Mar-2006: Do it this way so that semijoin state
         // don't clutter things up in optimizers that don't use semijoins
         if (!semiJoinDone) {
-            super.explain(pw);
-            return;
+            return super.explainTerms(pw);
         }
-        pw.explain(
-            this,
-            new String[] {
-                "left", "right", "condition", "joinType", "semiJoinDone"
-            },
-            new Object[] {
-                joinType.name().toLowerCase(), semiJoinDone
-            });
+        return super.explainTerms(pw)
+            .item("joinType", joinType.name().toLowerCase())
+            .item("semiJoinDone", semiJoinDone);
     }
 
     /**

src/main/java/org/eigenbase/rel/JoinRelBase.java

@@ -201,18 +201,16 @@ public void childrenAccept(RelVisitor visitor)
         visitor.visit(right, 1, this);
     }
 
-    public void explain(RelOptPlanWriter pw)
-    {
-        final List<String> nameList =
-            new ArrayList<String>(Arrays.asList("left", "right", "condition"));
-        final List<Object> valueList = new ArrayList<Object>();
-        nameList.add("joinType");
-        valueList.add(joinType.name().toLowerCase());
-        if (!getSystemFieldList().isEmpty()) {
-            nameList.add("systemFields");
-            valueList.add(getSystemFieldList());
-        }
-        pw.explain(this, nameList, valueList);
+    public RelOptPlanWriter explainTerms(RelOptPlanWriter pw) {
+        return super.explainTerms(pw)
+            .input("left", left)
+            .input("right", right)
+            .item("condition", condition)
+            .item("joinType", joinType.name().toLowerCase())
+            .itemIf(
+                "systemFields",
+                getSystemFieldList(),
+                !getSystemFieldList().isEmpty());
     }
 
     public void registerStoppedVariable(String name)