/*
 * 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 org.jdbi.v3.sqlobject.customizer;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.function.BiConsumer;

import org.jdbi.v3.core.statement.SqlStatement;
import org.jdbi.v3.sqlobject.customizer.internal.BindListFactory;

Binds each value in the annotated Iterable or array/varargs argument, and defines a named attribute as a comma-separated list of each bound parameter name. Common use cases: 
@SqlQuery("select * from things where id in (<ids>)")
List<Thing> getThings(@BindList int... ids)
@SqlQuery("insert into things (<columnNames>) values (<values>)")
void insertThings(@DefineList List<String> columnNames, @BindList List<Object> values)


Throws IllegalArgumentException if the argument is not an array or Iterable. How null and empty collections are handled can be configured with onEmpty:EmptyHandling - throws IllegalArgumentException by default.
/**
 * Binds each value in the annotated {@link Iterable} or array/varargs argument, and defines a named attribute as a
 * comma-separated list of each bound parameter name. Common use cases:
 * <pre>
 * &#64;SqlQuery("select * from things where id in (&lt;ids&gt;)")
 * List&lt;Thing&gt; getThings(@BindList int... ids)
 *
 * &#64;SqlQuery("insert into things (&lt;columnNames&gt;) values (&lt;values&gt;)")
 * void insertThings(@DefineList List&lt;String&gt; columnNames, @BindList List&lt;Object&gt; values)
 * </pre>
 * <p>
 * Throws IllegalArgumentException if the argument is not an array or Iterable. How null and empty collections are handled can be configured with onEmpty:EmptyHandling - throws IllegalArgumentException by default.
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER})
@SqlStatementCustomizingAnnotation(BindListFactory.class)
public @interface BindList {
    
The attribute name to define. If omitted, the name of the annotated parameter is used. It is an error to omit
the name when there is no parameter naming information in your class files.
Returns:
the attribute name./**
     * The attribute name to define. If omitted, the name of the annotated parameter is used. It is an error to omit
     * the name when there is no parameter naming information in your class files.
     *
     * @return the attribute name.
     */
    String value() default "";

    
Returns:
what to do when the argument is null or empty/**
     * @return what to do when the argument is null or empty
     */
    EmptyHandling onEmpty() default EmptyHandling.THROW;

    
describes what needs to be done if the passed argument is null or empty
/**
     * describes what needs to be done if the passed argument is null or empty
     */
    enum EmptyHandling {
        
Output "" (without quotes, i.e. nothing).
 select * from things where x in () /**
         * <p>Output "" (without quotes, i.e. nothing).</p>
         *
         * {@code select * from things where x in ()}
         */
        VOID((stmt, name) -> stmt.define(name, "")),
        
Output "null" (without quotes, as keyword), useful e.g. in postgresql where "in ()" is invalid syntax.
 select * from things where x in (null) 
Deprecated:
vaguely named in light of new additions, use NULL_STRING instead/**
         * <p>Output "null" (without quotes, as keyword), useful e.g. in postgresql where "in ()" is invalid syntax.</p>
         *
         * {@code select * from things where x in (null)}
         *
         * @deprecated vaguely named in light of new additions, use {@link EmptyHandling#NULL_STRING} instead
         */
        @Deprecated
        NULL((stmt, name) -> stmt.define(name, "null")),
        
Output "null" (without quotes, as keyword), useful e.g. in postgresql where "in ()" is invalid syntax.
 select * from things where x in (null) /**
         * <p>Output "null" (without quotes, as keyword), useful e.g. in postgresql where "in ()" is invalid syntax.</p>
         *
         * {@code select * from things where x in (null)}
         */
        NULL_STRING((stmt, name) -> stmt.define(name, "null")),
        
Define a null value, leaving the resulting query text up to the TemplateEngine to decide.
This value was specifically added to make conditionals work better with StringTemplate.
/**
         * <p>Define a {@code null} value, leaving the resulting query text up to the {@link org.jdbi.v3.core.statement.TemplateEngine} to decide.</p>
         *
         * This value was specifically added to <a href="https://github.com/jdbi/jdbi/issues/1377">make conditionals work better with <code>StringTemplate</code></a>.
         */
        NULL_VALUE((stmt, name) -> stmt.define(name, null)),
        
Throw IllegalArgumentException.
/**
         * Throw IllegalArgumentException.
         */
        THROW((stmt, name) -> {
            throw new IllegalArgumentException("argument is null or empty; this was explicitly forbidden on this instance of BindList");
        });

        private final BiConsumer<SqlStatement, String> rendering;

        EmptyHandling(BiConsumer<SqlStatement, String> rendering) {
            this.rendering = rendering;
        }

        public void define(SqlStatement stmt, String name) {
            rendering.accept(stmt, name);
        }
    }
}