com.apple.foundationdb.record.EvaluationContext Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of fdb-record-layer-core Show documentation
A record-oriented layer built for FoundationDB (proto2).
There is a newer version: 2.8.110.0
Show newest version
/*
 * EvaluationContext.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;

import com.apple.foundationdb.annotation.API;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;

/**
 * A context for query evaluation.
 * 
 * The primary state of an evaluation context is a set of parameter {@link Bindings}.
 * 
 * @see com.apple.foundationdb.record.query.expressions.QueryComponent#eval
 * @see com.apple.foundationdb.record.query.plan.plans.RecordQueryPlan#execute
 */
@API(API.Status.MAINTAINED)
public class EvaluationContext {
    @Nonnull
    private final Bindings bindings;

    public static final EvaluationContext EMPTY = new EvaluationContext(Bindings.EMPTY_BINDINGS);

    /**
     * Get an empty evaluation context.
     * @return an evaluation context with no bindings
     */
    @SuppressWarnings("squid:S1845") // The field and the function mean the same thing.
    public static EvaluationContext empty() {
        return EMPTY;
    }

    private EvaluationContext(@Nonnull Bindings bindings) {
        this.bindings = bindings;
    }

    /**
     * Create a new {@link EvaluationContext} around a given set of {@link Bindings}
     * from parameter names to values.
     * @param bindings a mapping from parameter name to values
     * @return a new evaluation context with the bindings
     */
    @Nonnull
    public static EvaluationContext forBindings(@Nonnull Bindings bindings) {
        return new EvaluationContext(bindings);
    }

    /**
     * Create a new EvaluationContext with a single binding.
     *
     * @param bindingName the binding name to add
     * @param value the value to bind the name to
     * @return a new EvaluationContext with the new binding
     */
    @Nonnull
    public static EvaluationContext forBinding(@Nonnull String bindingName, @Nullable Object value) {
        return new EvaluationContext(Bindings.newBuilder().set(bindingName, value).build());
    }

    /**
     * Retrieve the mapping from parameter names to values associated with
     * this context.
     *
     * @return a mapping from parameter names to to values
     */
    @Nonnull
    public Bindings getBindings() {
        return bindings;
    }

    /**
     * Get the value bound to a single parameter.
     *
     * @param name the name of the parameter to retrieve the binding of
     * @return the value bound to the given parameter
     * @see Bindings#get(String)
     */
    @Nullable
    public Object getBinding(@Nonnull String name) {
        return bindings.get(name);
    }

    /**
     * Construct a builder from this context. This allows the user to create
     * a new EvaluationContext that has all of the same data
     * as the current context except for a few modifications expressed as
     * mutations made to the builder.
     *
     * @return a builder for this class based on this instance
     */
    @Nonnull
    public EvaluationContextBuilder childBuilder() {
        return new EvaluationContextBuilder(this);
    }

    /**
     * Construct a new builder from this context.
     *
     * @return a builder for this class based on this instance
     */
    @Nonnull
    public static EvaluationContextBuilder newBuilder() {
        return new EvaluationContextBuilder();
    }

    /**
     * Create a new EvaluationContext with an additional binding.
     * The returned context will have all of the same state as the current
     * context included all bindings except that it will bind an additional
     * parameter to an additional value.
     *
     * @param bindingName the binding name to add
     * @param value the value to bind the name to
     * @return a new EvaluationContext with the new binding
     */
    @Nonnull
    public EvaluationContext withBinding(@Nonnull String bindingName, @Nullable Object value) {
        return childBuilder().setBinding(bindingName, value).build();
    }

}