com.hazelcast.org.apache.calcite.rel.hint.HintStrategy Maven / Gradle / Ivy

/*
 * 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 com.hazelcast.org.apache.calcite.rel.hint;

import com.hazelcast.org.apache.calcite.plan.RelOptRule;
import com.hazelcast.org.apache.calcite.rel.convert.ConverterRule;

import com.hazelcast.com.google.common.collect.ImmutableSet;

import java.util.Objects;
import javax.annotation.Nullable;

/**
 * Represents a hint strategy entry of {@link HintStrategyTable}.
 *
 * A {@code HintStrategy} includes:
 *
 * 

 *   {@link HintPredicate}: tests whether a hint should apply to
 *   a relational expression;
 *   {@link HintOptionChecker}: validates the hint options;
 *   {@code excludedRules}: rules to exclude when a relational expression
 *   is going to apply a planner rule;
 *   {@code converterRules}: fallback rules to apply when there are
 *   no proper implementations after excluding the {@code excludedRules}.
 * 
 *
 * The {@link HintPredicate} is required, all the other items are optional.
 *
 * 
A {@link HintStrategy} is immutable.
 */
public class HintStrategy {
  //~ Instance fields --------------------------------------------------------

  public final HintPredicate predicate;
  public final HintOptionChecker hintOptionChecker;
  public final ImmutableSet excludedRules;
  public final ImmutableSet converterRules;

  //~ Constructors -----------------------------------------------------------

  private HintStrategy(
      HintPredicate predicate,
      HintOptionChecker hintOptionChecker,
      ImmutableSet excludedRules,
      ImmutableSet converterRules) {
    this.predicate = predicate;
    this.hintOptionChecker = hintOptionChecker;
    this.excludedRules = excludedRules;
    this.converterRules = converterRules;
  }

  /**
   * Returns a {@link HintStrategy} builder with given hint predicate.
   *
   * @param hintPredicate hint predicate
   * @return {@link Builder} instance
   */
  public static Builder builder(HintPredicate hintPredicate) {
    return new Builder(hintPredicate);
  }

  //~ Inner Class ------------------------------------------------------------

  /** Builder for {@link HintStrategy}. */
  public static class Builder {
    private final HintPredicate predicate;
    @Nullable
    private HintOptionChecker optionChecker;
    private ImmutableSet excludedRules;
    private ImmutableSet converterRules;

    private Builder(HintPredicate predicate) {
      this.predicate = Objects.requireNonNull(predicate);
      this.excludedRules = ImmutableSet.of();
      this.converterRules = ImmutableSet.of();
    }

    /** Registers a hint option checker to validate the hint options. */
    public Builder optionChecker(HintOptionChecker optionChecker) {
      this.optionChecker = Objects.requireNonNull(optionChecker);
      return this;
    }

    /**
     * Registers an array of rules to exclude during the
     * {@link com.hazelcast.org.apache.calcite.plan.RelOptPlanner} planning.
     *
     * 
The desired converter rules work together with the excluded rules.
     * We have no validation here but they expect to have the same
     * function(semantic equivalent).
     *
     * 
A rule fire cancels if:
     *
     * 

     *   The registered {@link #excludedRules} contains the rule
     *   And the desired converter rules conversion is not possible
     *   for the rule matched root node
     * 
     *
     * @param rules excluded rules
     */
    public Builder excludedRules(RelOptRule... rules) {
      this.excludedRules = ImmutableSet.copyOf(rules);
      return this;
    }

    /**
     * Registers an array of desired converter rules during the
     * {@link com.hazelcast.org.apache.calcite.plan.RelOptPlanner} planning.
     *
     * The desired converter rules work together with the excluded rules.
     * We have no validation here but they expect to have the same
     * function(semantic equivalent).
     *
     * 
A rule fire cancels if:
     *
     * 

     *   The registered {@link #excludedRules} contains the rule
     *   And the desired converter rules conversion is not possible
     *   for the rule matched root node
     * 
     *
     * If no converter rules are specified, we assume the conversion is possible.
     *
     * @param rules desired converter rules
     */
    public Builder converterRules(ConverterRule... rules) {
      this.converterRules = ImmutableSet.copyOf(rules);
      return this;
    }

    public HintStrategy build() {
      return new HintStrategy(predicate, optionChecker, excludedRules, converterRules);
    }
  }
}