com.apple.foundationdb.record.query.plan.temp.matchers

Interface ExpressionMatcher<T extends Bindable>

Type Parameters:

T - the bindable type that this matcher binds to

All Known Implementing Classes:

ReferenceMatcher, TypeMatcher

@API(value=EXPERIMENTAL)
public interface ExpressionMatcher<T extends Bindable>

A ExpressionMatcher is an expression that can be matched against a PlannerExpression tree, while binding certain expressions/references in the tree to expression matcher objects. The bindings can be retrieved from the rule call once the binding is matched.

An ExpressionMatcher interacts with a PlannerExpression tree using its matchWith(PlannerExpression) and matchWith(ExpressionRef) methods. At a high level, the matchWith() methods are responsible for determining whether this matcher matches the root expression or reference passed to matchWith(). Although ExpressionMatchers are themselves hierarchical structures, an ExpressionMatcher must not try to match into the contents (in the case of matching a reference) or children (in the case of matching an expression) of the given root. Depending on the specific implementation of the root structure, matching against children/members can be quite complicated, so this behavior is implemented by the Bindable.bindTo(ExpressionMatcher) method instead. An ExpressionMatcher holds an ExpressionChildrenMatcher which describes how the children should be matched.

Extreme care should be taken when implementing ExpressionMatcher, since it can be very delicate. In particular, expression matchers may (or may not) be reused between successive rule calls and should be stateless. Additionally, implementors of ExpressionMatcher must use the (default) reference equals.

Method Summary

Modifier and Type	Method and Description
ExpressionChildrenMatcher	getChildrenMatcher() Return the child matchers of this matcher as a list.
Class<? extends PlannerExpression>	getRootClass() Get a class or interface extending PlannerExpression that is a super class of every planner expression that this matcher can match.
Stream<PlannerBindings>	matchWith(ExpressionRef<? extends PlannerExpression> ref) Attempt to match this matcher against the given expression reference.
Stream<PlannerBindings>	matchWith(PlannerExpression expression) Attempt to match this matcher against the given expression reference.

Method Detail

getRootClass

@Nonnull
Class<? extends PlannerExpression> getRootClass()

Get a class or interface extending PlannerExpression that is a super class of every planner expression that this matcher can match. Ideally, it should be the lowest such class but it may not be. A planner will generally use this method to quickly determine a set of rules that could match an expression, without considering each rule and trying to apply it. A good implementation of this method helps the planner match rules efficiently.

Returns:

a class object for a class that is a super class of every planner expression this matcher can match

getChildrenMatcher

@Nonnull
ExpressionChildrenMatcher getChildrenMatcher()

Return the child matchers of this matcher as a list.

Returns:

a list of the child matchers of this matcher

matchWith

@Nonnull
Stream<PlannerBindings> matchWith(@Nonnull
                                           ExpressionRef<? extends PlannerExpression> ref)

Attempt to match this matcher against the given expression reference. Note that implementations of matchWith() should only attempt to match the given root with this planner expression and should not call into the ExpressionChildrenMatcher returned by getChildrenMatcher() or attempt to access the members of the given reference.

Parameters:

ref - a reference to match with

Returns:

a stream of PlannerBindings containing the matched bindings, or an empty stream is no match was found

matchWith

@Nonnull
Stream<PlannerBindings> matchWith(@Nonnull
                                           PlannerExpression expression)

Attempt to match this matcher against the given expression reference. Note that implementations of matchWith() should only attempt to match the given root with this planner expression and should not call into the ExpressionChildrenMatcher returned by getChildrenMatcher() or attempt to access children of the given expression.

Parameters:

expression - a planner expression to match with

Returns:

a stream of PlannerBindings containing the matched bindings, or an empty stream is no match was found