io.helidon.dbclient.DbStatement Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of helidon-dbclient Show documentation
Helidon Database Client API
There is a newer version: 4.1.4
/*
 * Copyright (c) 2019, 2020 Oracle and/or its affiliates.
 *
 * 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 io.helidon.dbclient;

import java.util.Arrays;
import java.util.List;
import java.util.Map;

/**
 * Database statement that can process parameters.
 * Method {@link #execute()} processes the statement and returns appropriate response.
 * 
 * All methods are non-blocking. The {@link #execute()} method returns either a {@link java.util.concurrent.CompletionStage}
 * or another object that provides similar API for eventual processing of the response.
 * 

 * Once parameters are set using one of the {@code params} methods, all other methods throw an
 * {@link IllegalStateException}.
 * 

 * Once a parameter is added using {@link #addParam(Object)} or {@link #addParam(String, Object)}, all other
 * {@code params} methods throw an {@link IllegalStateException}.
 * 
 * Once {@link #execute()} is called, all methods would throw an {@link IllegalStateException}.
 *
 * @param  Type of the result of this statement (e.g. a {@link java.util.concurrent.CompletionStage})
 * @param  Type of the descendant of this class
 */
public interface DbStatement, R> {
    /**
     * Configure parameters from a {@link java.util.List} by order.
     * The statement must use indexed parameters and configure them by order in the provided array.
     *
     * @param parameters ordered parameters to set on this statement, never null
     * @return updated db statement
     */
    D params(List parameters);

    /**
     * Configure parameters from an array by order.
     * The statement must use indexed parameters and configure them by order in the provided array.
     *
     * @param parameters ordered parameters to set on this statement
     * @return updated db statement
     */
    default D params(Object... parameters) {
        return params(Arrays.asList(parameters));
    }

    /**
     * Configure named parameters.
     * The statement must use named parameters and configure them from the provided map.
     *
     * @param parameters named parameters to set on this statement
     * @return updated db statement
     */
    D params(Map parameters);

    /**
     * Configure parameters using {@link Object} instance with registered mapper.
     * The statement must use named parameters and configure them from the map provided by mapper.
     *
     * @param parameters {@link Object} instance containing parameters
     * @return updated db statement
     */
    D namedParam(Object parameters);

    /**
     * Configure parameters using {@link Object} instance with registered mapper.
     * The statement must use indexed parameters and configure them by order in the array provided by mapper.
     *
     * @param parameters {@link Object} instance containing parameters
     * @return updated db statement
     */
    D indexedParam(Object parameters);

    /**
     * Add next parameter to the list of ordered parameters (e.g. the ones that use {@code ?} in SQL).
     *
     * @param parameter next parameter to set on this statement
     * @return updated db statement
     */
    D addParam(Object parameter);

    /**
     * Add next parameter to the map of named parameters (e.g. the ones that use {@code :name} in Helidon
     * JDBC SQL integration).
     *
     * @param name      name of parameter
     * @param parameter value of parameter
     * @return updated db statement
     */
    D addParam(String name, Object parameter);

    /**
     * Execute this statement using the parameters configured with {@code params} and {@code addParams} methods.
     *
     * @return The result of this statement, never blocking.
     */
    R execute();
}