JdbcUpdate.java

/*
 * SPDX-FileCopyrightText: 2025 kaumei.io
 * SPDX-License-Identifier: Apache-2.0
 */
package io.kaumei.jdbc.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Defines the SQL for a JDBC update method.
 * <p>
 * It can also declare how generated values are returned.
 */
@Retention(RetentionPolicy.CLASS)
@Target(ElementType.METHOD)
public @interface JdbcUpdate {

    /**
     * SQL to execute.
     */
    String value();

    /**
     * How generated values are returned.
     */
    GeneratedValues returnGeneratedValues() default GeneratedValues.NONE;

    /**
     * Names generated columns to return through {@link java.sql.PreparedStatement#getGeneratedKeys()}.
     * <p>
     * This uses the JDBC {@code prepareStatement(sql, String[])} overload and is useful for
     * drivers, such as Oracle, that require requested generated-key columns to be named.
     * This attribute requires {@link #returnGeneratedValues()} to be {@link GeneratedValues#NONE}.
     */
    String[] returnGeneratedColumns() default {};

    enum GeneratedValues {

        /**
         * Do not return generated values.
         */
        NONE,

        /**
         * Use the configured default behaviour.
         */
        DEFAULT,

        /**
         * Return JDBC generated keys.
         */
        GENERATED_KEYS,

        /**
         * Return values from the SQL query result.
         */
        EXECUTE_QUERY
    }
}