org.apache.kafka.streams.query.QueryResult 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 org.apache.kafka.streams.query;

import org.apache.kafka.streams.processor.StateStore;
import org.apache.kafka.streams.query.internals.FailedQueryResult;
import org.apache.kafka.streams.query.internals.SucceededQueryResult;

import java.util.List;

/**
 * Container for a single partition's result when executing a {@link StateQueryRequest}.
 *
 * @param  The result type of the query.
 */
public interface QueryResult {
    /**
     * Static factory method to create a result object for a successful query. Used by StateStores
     * to respond to a {@link StateStore#query(Query, PositionBound, QueryConfig)}.
     */
    static  QueryResult forResult(final R result) {
        return new SucceededQueryResult<>(result);
    }

    /**
     * Static factory method to create a result object for a failed query. Used by StateStores to
     * respond to a {@link StateStore#query(Query, PositionBound, QueryConfig)}.
     */
    static  QueryResult forFailure(
        final FailureReason failureReason,
        final String failureMessage) {

        return new FailedQueryResult<>(failureReason, failureMessage);
    }

    /**
     * Static factory method to create a failed query result object to indicate that the store does
     * not know how to handle the query.
     * 
     * Used by StateStores to respond to a {@link StateStore#query(Query, PositionBound, QueryConfig)}.
     */
    static  QueryResult forUnknownQueryType(
        final Query query,
        final StateStore store) {

        return forFailure(
            FailureReason.UNKNOWN_QUERY_TYPE,
            "This store (" + store.getClass() + ") doesn't know how to execute "
                + "the given query (" + query + ")." +
                " Contact the store maintainer if you need support for a new query type.");
    }

    /**
     * Static factory method to create a failed query result object to indicate that the store has
     * not yet caught up to the requested position bound.
     * 

     * Used by StateStores to respond to a {@link StateStore#query(Query, PositionBound, QueryConfig)}.
     */
    static  QueryResult notUpToBound(
        final Position currentPosition,
        final PositionBound positionBound,
        final Integer partition) {

        if (partition == null) {
            return new FailedQueryResult<>(
                FailureReason.NOT_UP_TO_BOUND,
                "The store is not initialized yet, so it is not yet up to the bound "
                    + positionBound
            );
        } else {
            return new FailedQueryResult<>(
                FailureReason.NOT_UP_TO_BOUND,
                "For store partition " + partition + ", the current position "
                    + currentPosition + " is not yet up to the bound "
                    + positionBound
            );
        }
    }

    /**
     * Used by stores to add detailed execution information (if requested) during query execution.
     */
    void addExecutionInfo(final String message);

    /**
     * Used by stores to report what exact position in the store's history it was at when it
     * executed the query.
     */
    void setPosition(final Position position);

    /**
     * True iff the query was successfully executed. The response is available in {@link
     * #getResult()}.
     */
    boolean isSuccess();


    /**
     * True iff the query execution failed. More information about the failure is available in
     * {@link #getFailureReason()} and {@link #getFailureMessage()}.
     */
    boolean isFailure();

    /**
     * If detailed execution information was requested in {@link StateQueryRequest#enableExecutionInfo()},
     * this method returned the execution details for this partition's result.
     */
    List getExecutionInfo();

    /**
     * This state partition's exact position in its history when this query was executed. Can be
     * used in conjunction with subsequent queries via {@link StateQueryRequest#withPositionBound(PositionBound)}.
     * 
     * Note: stores are encouraged, but not required to set this property.
     */
    Position getPosition();

    /**
     * If this partition failed to execute the query, returns the reason.
     *
     * @throws IllegalArgumentException if this is not a failed result.
     */
    FailureReason getFailureReason();

    /**
     * If this partition failed to execute the query, returns the failure message.
     *
     * @throws IllegalArgumentException if this is not a failed result.
     */
    String getFailureMessage();

    /**
     * Returns the result of executing the query on one partition. The result type is determined by
     * the query. Note: queries may choose to return {@code null} for a successful query, so {@link
     * #isSuccess()} and {@link #isFailure()} must be used to determine whether the query
     * was successful of failed on this partition.
     *
     * @throws IllegalArgumentException if this is not a successful query.
     */
    R getResult();
}