introduction of conditional planner rules

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/query/plan/RecordQueryPlannerConfiguration.java

@@ -24,6 +24,7 @@
 import com.apple.foundationdb.record.IndexFetchMethod;
 import com.apple.foundationdb.record.RecordPlannerConfigurationProto;
 import com.apple.foundationdb.record.query.RecordQuery;
+import com.apple.foundationdb.record.query.plan.cascades.AbstractCascadesRule;
 import com.apple.foundationdb.record.query.plan.cascades.CascadesRule;
 import com.apple.foundationdb.record.query.plan.cascades.PlannerRule;
 import com.apple.foundationdb.record.query.plan.cascades.PlanningRuleSet;
@@ -622,9 +623,9 @@ public Builder setAllowNonIndexSort(final boolean allowNonIndexSort) {
          */
         @CanIgnoreReturnValue
         @Nonnull
-        public Builder setDisabledTransformationRules(@Nonnull final Set<Class<? extends CascadesRule<?>>> disabledTransformationRules) {
+        public Builder setDisabledTransformationRules(@Nonnull final Set<Class<? extends AbstractCascadesRule<?>>> disabledTransformationRules) {
             protoBuilder.clearDisabledTransformationRules();
-            for (Class<? extends CascadesRule<?>> rule : disabledTransformationRules) {
+            for (Class<? extends AbstractCascadesRule<?>> rule : disabledTransformationRules) {
                 protoBuilder.addDisabledTransformationRules(rule.getSimpleName());
             }
             return this;
@@ -664,7 +665,7 @@ public Builder setDisabledTransformationRuleNames(@Nonnull final Set<String> dis
         @Nonnull
         public Builder disableRewritingRules() {
             for (CascadesRule<?> rule : RewritingRuleSet.OPTIONAL_RULES) {
-                disableTransformationRule((Class<? extends CascadesRule<?>>) rule.getClass());
+                disableTransformationRule((Class<? extends AbstractCascadesRule<?>>) rule.getClass());
             }
             return this;
         }
@@ -676,7 +677,7 @@ public Builder disableRewritingRules() {
          */
         @CanIgnoreReturnValue
         @Nonnull
-        public Builder disableTransformationRule(@Nonnull Class<? extends CascadesRule<?>> ruleClass) {
+        public Builder disableTransformationRule(@Nonnull Class<? extends AbstractCascadesRule<?>> ruleClass) {
             protoBuilder.addDisabledTransformationRules(ruleClass.getSimpleName());
             return this;
         }

fdb-record-layer-core/src/main/java/com/apple/foundationdb/record/query/plan/cascades/AbstractCascadesRule.java

@@ -0,0 +1,106 @@
+/*
+ * AbstractCascadesRule.java
+ *
+ * This source file is part of the FoundationDB open source project
+ *
+ * Copyright 2015-2018 Apple Inc. and the FoundationDB project authors
+ *
+ * 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.apple.foundationdb.record.query.plan.cascades;
+
+import com.apple.foundationdb.annotation.API;
+import com.apple.foundationdb.record.query.plan.cascades.expressions.RelationalExpression;
+import com.apple.foundationdb.record.query.plan.cascades.matching.structure.BindingMatcher;
+import com.google.common.collect.ImmutableSet;
+
+import javax.annotation.Nonnull;
+import java.util.Collection;
+import java.util.Optional;
+import java.util.Set;
+
+/**
+ * Classes that inherit from <code>AbstractCascadesRule</code> form the base of the Cascades planning system. During the planning
+ * process, rules are matched to a current {@link RelationalExpression} and then provide zero or more logically equivalent
+ * expressions.
+ * <br>
+ * The rule matching occurs in two stages: first, the planner examines the {@link #matcher} of the rule,
+ * which is a {@link BindingMatcher} expression that expresses the operators that the rule applies to and the hierarchical
+ * structure that they take on in the expression tree. If the rule matches the binding, its {@link #onMatch(PlannerRuleCall)}
+ * method is called, with a parameter that provides the planner's {@link PlanContext} and access to the map of bindings,
+ * among other things. This method can inspect the operators bound during the structural matching and implement other
+ * logic.
+ * <br>
+ * The <code>onMatch()</code> method returns logically equivalent expressions to the planner by calling the
+ * yield methods on its rule call, with a new {@link RelationalExpression}s. These methods can be called more than once,
+ * or zero times if no alternative expressions are found.
+ * <br>
+ * A rule should not attempt to modify any of the bound objects that the rule call provides. Nearly all such objects are
+ * immutable, and the mutable ones are hidden behind interfaces that do not expose mutation methods. In particular,
+ * a rule should never cast an {@link Reference} in an attempt to access it.
+ * <br>
+ * A <code>AbstractCascadesRule</code> should not store state between successive calls to {@link #onMatch(PlannerRuleCall)},
+ * since it may be reused an arbitrary number of times and may be reinstantiated at any time. To simplify cleanup,
+ * any state that needs to be shared within a rule call should be encapsulated in a helper object (such as a static
+ * inner class) or documented carefully.
+ * @param <T> a parent planner expression type of all possible root planner expressions that this rule could match
+ * @see com.apple.foundationdb.record.query.plan.cascades
+ * @see PlannerRuleCall
+ */
+@API(API.Status.EXPERIMENTAL)
+public abstract class AbstractCascadesRule<T> implements CascadesRule<T> {
+    @Nonnull
+    private final BindingMatcher<T> matcher;
+
+    @Nonnull
+    private final Set<PlannerConstraint<?>> requirementDependencies;
+
+    public AbstractCascadesRule(@Nonnull BindingMatcher<T> matcher) {
+        this.matcher = matcher;
+        this.requirementDependencies = ImmutableSet.of();
+    }
+
+    public AbstractCascadesRule(@Nonnull BindingMatcher<T> matcher, Collection<PlannerConstraint<?>> requirementDependencies) {
+        this.matcher = matcher;
+        this.requirementDependencies = ImmutableSet.copyOf(requirementDependencies);
+    }
+
+    /**
+     * Returns the class of the operator at the root of the binding expression, if this rule uses a non-trivial binding.
+     * Used primarily for indexing rules for more efficient rule search.
+     * @return the class of the root of this rule's binding, or <code>Optional.empty()</code> if the rule matches anything
+     * @see PlanningRuleSet
+     */
+    @Nonnull
+    @Override
+    public Optional<Class<?>> getRootOperator() {
+        return Optional.of(matcher.getRootClass());
+    }
+
+    @Nonnull
+    public Set<PlannerConstraint<?>> getConstraintDependencies() {
+        return requirementDependencies;
+    }
+
+    @Nonnull
+    @Override
+    public BindingMatcher<T> getMatcher() {
+        return matcher;
+    }
+
+    @Override
+    public String toString() {
+        return getClass().getSimpleName();
+    }
+}