/*
 * 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.
 *
 * Other licenses:
 * -----------------------------------------------------------------------------
 * Commercial licenses for this work are available. These replace the above
 * ASL 2.0 and offer limited warranties, support, maintenance, and commercial
 * database integrations.
 *
 * For more information, please visit: http://www.jooq.org/licenses
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
package org.jooq;

import java.util.Collection;
import java.util.Map;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

A query storing objects to the database. This is either an insert or an
update query.

Instances of this type cannot be created directly, only of its subtypes.
Author:
Lukas Eder
Type parameters:
<R> – The record type of the table being modified/**
 * A query storing objects to the database. This is either an insert or an
 * update query.
 * <p>
 * Instances of this type cannot be created directly, only of its subtypes.
 *
 * @param <R> The record type of the table being modified
 * @author Lukas Eder
 */
public interface StoreQuery<R extends Record> extends RowCountQuery {

    
Add values to the store statement
Params:
record – The record holding values that are stored by the query/**
     * Add values to the store statement
     *
     * @param record The record holding values that are stored by the query
     */
    @Support
    void setRecord(R record);

    
Add a value to the store statement
Params:
field – The field
value – The value/**
     * Add a value to the store statement
     *
     * @param field The field
     * @param value The value
     */
    @Support
    <T> void addValue(Field<T> field, T value);

    
Add a value to the store statement
Params:
field – The field
value – The value. If value is null, this results in calling addValue(Field, Object) with null as a value./**
     * Add a value to the store statement
     *
     * @param field The field
     * @param value The value. If value is <code>null</code>, this results in
     *            calling {@link #addValue(Field, Object)} with null as a value.
     */
    @Support
    <T> void addValue(Field<T> field, Field<T> value);

    
Add multiple values to the store statement.
 Keys can either be of type String, Name, or Field. 

Values can either be of type <T> or
Field<T>. jOOQ will attempt to convert values to their
corresponding field's type.
/**
     * Add multiple values to the store statement.
     * <p>
     * Keys can either be of type {@link String}, {@link Name}, or
     * {@link Field}.
     * <p>
     * Values can either be of type <code>&lt;T&gt;</code> or
     * <code>Field&lt;T&gt;</code>. jOOQ will attempt to convert values to their
     * corresponding field's type.
     */
    @Support
    void addValues(Map<?, ?> map);

    
Configure the INSERT or UPDATE statement to return all fields in
R.
See Also:
getReturnedRecords()/**
     * Configure the <code>INSERT</code> or <code>UPDATE</code> statement to return all fields in
     * <code>R</code>.
     *
     * @see #getReturnedRecords()
     */
    @Support
    void setReturning();

    
Configure the INSERT or UPDATE statement to return the generated
identity value.
Params:
identity – The table's identity
See Also:
getReturnedRecords()/**
     * Configure the <code>INSERT</code> or <code>UPDATE</code> statement to return the generated
     * identity value.
     *
     * @param identity The table's identity
     * @see #getReturnedRecords()
     */
    @Support
    void setReturning(Identity<R, ?> identity);

    
Configure the INSERT or UPDATE statement to return a list of fields in
R.
Params:
fields – Fields to be returned
See Also:
getReturnedRecords()/**
     * Configure the <code>INSERT</code> or <code>UPDATE</code> statement to return a list of fields in
     * <code>R</code>.
     *
     * @param fields Fields to be returned
     * @see #getReturnedRecords()
     */
    @Support
    void setReturning(SelectFieldOrAsterisk... fields);

    
Configure the INSERT or UPDATE statement to return a list of fields in
R.
Params:
fields – Fields to be returned
See Also:
getReturnedRecords()/**
     * Configure the <code>INSERT</code> or <code>UPDATE</code> statement to return a list of fields in
     * <code>R</code>.
     *
     * @param fields Fields to be returned
     * @see #getReturnedRecords()
     */
    @Support
    void setReturning(Collection<? extends SelectFieldOrAsterisk> fields);

    
The record holding returned values as specified by any of the setReturning() methods. 

If the insert statement returns several records, this is the same as
calling getReturnedRecords().get(0)

This implemented differently for every dialect:

Firebird and Postgres have native support for
INSERT .. RETURNING and UPDATE .. RETURNING
clauses
HSQLDB, Oracle, and DB2 JDBC drivers allow for retrieving any table
column as "generated key" in one statement
Derby, H2, Ingres, MySQL, SQL Server only allow for retrieving
IDENTITY column values as "generated key". If other fields are requested,
a second statement is issued. Client code must assure transactional
integrity between the two statements.
Sybase and SQLite allow for retrieving IDENTITY values as
@@identity or last_inserted_rowid() values.
Those values are fetched in a separate SELECT statement. If
other fields are requested, a second statement is issued. Client code
must assure transactional integrity between the two statements.

See Also:
getReturnedRecords()
Returns:
The returned value as specified by any of the setReturning() methods. This may return null in case jOOQ could not retrieve any generated
        keys from the JDBC driver./**
     * The record holding returned values as specified by any of the
     * {@link #setReturning()} methods.
     * <p>
     * If the insert statement returns several records, this is the same as
     * calling <code>getReturnedRecords().get(0)</code>
     * <p>
     * This implemented differently for every dialect:
     * <ul>
     * <li>Firebird and Postgres have native support for
     * <code>INSERT .. RETURNING</code> and <code>UPDATE .. RETURNING</code>
     * clauses</li>
     * <li>HSQLDB, Oracle, and DB2 JDBC drivers allow for retrieving any table
     * column as "generated key" in one statement</li>
     * <li>Derby, H2, Ingres, MySQL, SQL Server only allow for retrieving
     * IDENTITY column values as "generated key". If other fields are requested,
     * a second statement is issued. Client code must assure transactional
     * integrity between the two statements.</li>
     * <li>Sybase and SQLite allow for retrieving IDENTITY values as
     * <code>@@identity</code> or <code>last_inserted_rowid()</code> values.
     * Those values are fetched in a separate <code>SELECT</code> statement. If
     * other fields are requested, a second statement is issued. Client code
     * must assure transactional integrity between the two statements.</li>
     * </ul>
     *
     * @return The returned value as specified by any of the
     *         {@link #setReturning()} methods. This may return
     *         <code>null</code> in case jOOQ could not retrieve any generated
     *         keys from the JDBC driver.
     * @see #getReturnedRecords()
     */
    @Nullable
    @Support
    R getReturnedRecord();

    
The records holding returned values as specified by any of the setReturning() methods. 

This implemented differently for every dialect:

Firebird and Postgres have native support for
INSERT .. RETURNING and UPDATE .. RETURNING
clauses
HSQLDB, Oracle, and DB2 JDBC drivers allow for retrieving any table
column as "generated key" in one statement
Derby, H2, Ingres, MySQL, SQL Server only allow for retrieving
IDENTITY column values as "generated key". If other fields are requested,
a second statement is issued. Client code must assure transactional
integrity between the two statements.
Sybase and SQLite allow for retrieving IDENTITY values as
@@identity or last_inserted_rowid() values.
Those values are fetched in a separate SELECT statement. If
other fields are requested, a second statement is issued. Client code
must assure transactional integrity between the two statements.


[#5070] Due to an early API design flaw, this method historically returns
the type R, not a more generic type Record.
This means that only actual columns in R can be returned. For a more generic set of column expressions, use getResult() instead. 
Returns:
The returned values as specified by any of the setReturning() methods. Note: 

        
Not all databases / JDBC drivers support returning several
        values on multi-row inserts!
        
This may return an empty Result in case jOOQ
        could not retrieve any generated keys from the JDBC driver.
        /**
     * The records holding returned values as specified by any of the
     * {@link #setReturning()} methods.
     * <p>
     * This implemented differently for every dialect:
     * <ul>
     * <li>Firebird and Postgres have native support for
     * <code>INSERT .. RETURNING</code> and <code>UPDATE .. RETURNING</code>
     * clauses</li>
     * <li>HSQLDB, Oracle, and DB2 JDBC drivers allow for retrieving any table
     * column as "generated key" in one statement</li>
     * <li>Derby, H2, Ingres, MySQL, SQL Server only allow for retrieving
     * IDENTITY column values as "generated key". If other fields are requested,
     * a second statement is issued. Client code must assure transactional
     * integrity between the two statements.</li>
     * <li>Sybase and SQLite allow for retrieving IDENTITY values as
     * <code>@@identity</code> or <code>last_inserted_rowid()</code> values.
     * Those values are fetched in a separate <code>SELECT</code> statement. If
     * other fields are requested, a second statement is issued. Client code
     * must assure transactional integrity between the two statements.</li>
     * </ul>
     * <p>
     * [#5070] Due to an early API design flaw, this method historically returns
     * the type <code>R</code>, not a more generic type <code>Record</code>.
     * This means that only actual columns in <code>R</code> can be returned.
     * For a more generic set of column expressions, use {@link #getResult()}
     * instead.
     *
     * @return The returned values as specified by any of the
     *         {@link #setReturning()} methods. Note:
     *         <ul>
     *         <li>Not all databases / JDBC drivers support returning several
     *         values on multi-row inserts!</li>
     *         <li>This may return an empty <code>Result</code> in case jOOQ
     *         could not retrieve any generated keys from the JDBC driver.</li>
     *         </ul>
     */
    @NotNull
    @Support
    Result<R> getReturnedRecords();

    
The records holding returned values as specified by any of the setReturning() methods. 

This implemented differently for every dialect:

Firebird and Postgres have native support for
INSERT .. RETURNING and UPDATE .. RETURNING
clauses
HSQLDB, Oracle, and DB2 JDBC drivers allow for retrieving any table
column as "generated key" in one statement
Derby, H2, Ingres, MySQL, SQL Server only allow for retrieving
IDENTITY column values as "generated key". If other fields are requested,
a second statement is issued. Client code must assure transactional
integrity between the two statements.
Sybase and SQLite allow for retrieving IDENTITY values as
@@identity or last_inserted_rowid() values.
Those values are fetched in a separate SELECT statement. If
other fields are requested, a second statement is issued. Client code
must assure transactional integrity between the two statements.

Returns:
The returned values as specified by any of the setReturning() methods. Note: 

        
Not all databases / JDBC drivers support returning several
        values on multi-row inserts!
This may return an empty
        Result in case jOOQ could not retrieve any generated
        keys from the JDBC driver.
        /**
     * The records holding returned values as specified by any of the
     * {@link #setReturning()} methods.
     * <p>
     * This implemented differently for every dialect:
     * <ul>
     * <li>Firebird and Postgres have native support for
     * <code>INSERT .. RETURNING</code> and <code>UPDATE .. RETURNING</code>
     * clauses</li>
     * <li>HSQLDB, Oracle, and DB2 JDBC drivers allow for retrieving any table
     * column as "generated key" in one statement</li>
     * <li>Derby, H2, Ingres, MySQL, SQL Server only allow for retrieving
     * IDENTITY column values as "generated key". If other fields are requested,
     * a second statement is issued. Client code must assure transactional
     * integrity between the two statements.</li>
     * <li>Sybase and SQLite allow for retrieving IDENTITY values as
     * <code>@@identity</code> or <code>last_inserted_rowid()</code> values.
     * Those values are fetched in a separate <code>SELECT</code> statement. If
     * other fields are requested, a second statement is issued. Client code
     * must assure transactional integrity between the two statements.</li>
     * </ul>
     *
     * @return The returned values as specified by any of the
     *         {@link #setReturning()} methods. Note:
     *         <ul>
     *         <li>Not all databases / JDBC drivers support returning several
     *         values on multi-row inserts!</li><li>This may return an empty
     *         <code>Result</code> in case jOOQ could not retrieve any generated
     *         keys from the JDBC driver.</li>
     *         </ul>
     */
    @NotNull
    @Support
    Result<?> getResult();

}