/*
 * 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.stream.Stream;

import org.jooq.impl.DSL;

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

A row value expression.

Row value expressions are mainly useful for use in predicates, when comparing
several values in one go, which can be more elegant than expanding the row
value expression predicate in other equivalent syntaxes. This is especially
true for non-equality predicates. For instance, the following two predicates
are equivalent in SQL:

(A, B) > (X, Y)
(A > X) OR (A = X AND B > Y)


Example:

// Assuming import static org.jooq.impl.DSL.*;
using(configuration)
   .select()
   .from(CUSTOMER)
   .where(row(CUSTOMER.FIRST_NAME, CUSTOMER.LAST_NAME).in(
       select(ACTOR.FIRST_NAME, ACTOR.LAST_NAME).from(ACTOR)
   ))
   .fetch();


Note: Not all databases support row value expressions, but many row value
expression operations can be emulated on all databases. See relevant row
value expression method Javadocs for details.
 Instances can be created using DSL.row(Object...) and overloads. 
Author:
Lukas Eder/**
 * A row value expression.
 * <p>
 * Row value expressions are mainly useful for use in predicates, when comparing
 * several values in one go, which can be more elegant than expanding the row
 * value expression predicate in other equivalent syntaxes. This is especially
 * true for non-equality predicates. For instance, the following two predicates
 * are equivalent in SQL:
 * <p>
 * <code><pre>
 * (A, B) &gt; (X, Y)
 * (A &gt; X) OR (A = X AND B &gt; Y)
 * </pre></code>
 * <p>
 * <strong>Example:</strong>
 * <p>
 * <code><pre>
 * // Assuming import static org.jooq.impl.DSL.*;
 *
 * using(configuration)
 *    .select()
 *    .from(CUSTOMER)
 *    .where(row(CUSTOMER.FIRST_NAME, CUSTOMER.LAST_NAME).in(
 *        select(ACTOR.FIRST_NAME, ACTOR.LAST_NAME).from(ACTOR)
 *    ))
 *    .fetch();
 * </pre></code>
 * <p>
 * Note: Not all databases support row value expressions, but many row value
 * expression operations can be emulated on all databases. See relevant row
 * value expression method Javadocs for details.
 * <p>
 * Instances can be created using {@link DSL#row(Object...)} and overloads.
 *
 * @author Lukas Eder
 */
public interface Row extends FieldOrRow {

    
Get the degree of this row value expression.
/**
     * Get the degree of this row value expression.
     */
    int size();


    
Get the fields from this row as a Stream. /**
     * Get the fields from this row as a {@link Stream}.
     */
    @NotNull
    Stream<Field<?>> fieldStream();


    
Get a specific field from this row.

This will return:

A field that is the same as the argument field (by identity
comparison).
A field that is equal to the argument field (exact matching fully
qualified name).
A field that is equal to the argument field (partially matching
qualified name).
A field whose name is equal to the name of the argument field.
null otherwise.

If several fields have the same name, the first one is returned and a
warning is logged.
Params:
field – The field to fetch
Type parameters:
<T> – The generic field type
Returns:
The field itself or an aliased field/**
     * Get a specific field from this row.
     * <p>
     * This will return:
     * <ul>
     * <li>A field that is the same as the argument field (by identity
     * comparison).</li>
     * <li>A field that is equal to the argument field (exact matching fully
     * qualified name).</li>
     * <li>A field that is equal to the argument field (partially matching
     * qualified name).</li>
     * <li>A field whose name is equal to the name of the argument field.</li>
     * <li><code>null</code> otherwise.
     * </ul>
     * If several fields have the same name, the first one is returned and a
     * warning is logged.
     *
     * @param <T> The generic field type
     * @param field The field to fetch
     * @return The field itself or an aliased field
     */
    @Nullable
    <T> Field<T> field(Field<T> field);

    
Get a specific field from this row.
Params:
fieldName – The field to fetch
Returns:
The field with the given name/**
     * Get a specific field from this row.
     *
     * @param fieldName The field to fetch
     * @return The field with the given name
     */
    @Nullable
    Field<?> field(String fieldName);

    
Get a specific field from this row and coerce it to type.
Params:
fieldName – The field to fetch
type – The type to coerce the resulting field to
Returns:
The field with the given name/**
     * Get a specific field from this row and coerce it to <code>type</code>.
     *
     * @param fieldName The field to fetch
     * @param type The type to coerce the resulting field to
     * @return The field with the given name
     */
    @Nullable
    <T> Field<T> field(String fieldName, Class<T> type);

    
Get a specific field from this row and coerce it to dataType.
Params:
fieldName – The field to fetch
dataType – The type to coerce the resulting field to
Returns:
The field with the given name/**
     * Get a specific field from this row and coerce it to <code>dataType</code>.
     *
     * @param fieldName The field to fetch
     * @param dataType The type to coerce the resulting field to
     * @return The field with the given name
     */
    @Nullable
    <T> Field<T> field(String fieldName, DataType<T> dataType);

    
Get a specific field from this row.
Params:
fieldName – The field to fetch
Returns:
The field with the given name/**
     * Get a specific field from this row.
     *
     * @param fieldName The field to fetch
     * @return The field with the given name
     */
    @Nullable
    Field<?> field(Name fieldName);

    
Get a specific field from this row and coerce it to type.
Params:
fieldName – The field to fetch
type – The type to coerce the resulting field to
Returns:
The field with the given name/**
     * Get a specific field from this row and coerce it to <code>type</code>.
     *
     * @param fieldName The field to fetch
     * @param type The type to coerce the resulting field to
     * @return The field with the given name
     */
    @Nullable
    <T> Field<T> field(Name fieldName, Class<T> type);

    
Get a specific field from this row and coerce it to dataType.
Params:
fieldName – The field to fetch
dataType – The type to coerce the resulting field to
Returns:
The field with the given name/**
     * Get a specific field from this row and coerce it to <code>dataType</code>.
     *
     * @param fieldName The field to fetch
     * @param dataType The type to coerce the resulting field to
     * @return The field with the given name
     */
    @Nullable
    <T> Field<T> field(Name fieldName, DataType<T> dataType);

    
Get a specific field from this row.
Params:
fieldIndex – The field's index of the field to fetch
Returns:
The field with the given name/**
     * Get a specific field from this row.
     *
     * @param fieldIndex The field's index of the field to fetch
     * @return The field with the given name
     */
    @Nullable
    Field<?> field(int fieldIndex);

    
Get a specific field from this row and coerce it to type.
Params:
fieldIndex – The field's index of the field to fetch
type – The type to coerce the resulting field to
Returns:
The field with the given name/**
     * Get a specific field from this row and coerce it to <code>type</code>.
     *
     * @param fieldIndex The field's index of the field to fetch
     * @param type The type to coerce the resulting field to
     * @return The field with the given name
     */
    @Nullable
    <T> Field<T> field(int fieldIndex, Class<T> type);

    
Get a specific field from this row and coerce it to dataType.
Params:
fieldIndex – The field's index of the field to fetch
dataType – The type to coerce the resulting field to
Returns:
The field with the given name/**
     * Get a specific field from this row and coerce it to <code>dataType</code>.
     *
     * @param fieldIndex The field's index of the field to fetch
     * @param dataType The type to coerce the resulting field to
     * @return The field with the given name
     */
    @Nullable
    <T> Field<T> field(int fieldIndex, DataType<T> dataType);

    
Get all fields from this row.
Returns:
All available fields/**
     * Get all fields from this row.
     *
     * @return All available fields
     */
    @NotNull
    Field<?>[] fields();

    
Get all fields from this row, providing some fields.
See Also:
field(Field<Object>)
Returns:
All available fields/**
     * Get all fields from this row, providing some fields.
     *
     * @return All available fields
     * @see #field(Field)
     */
    @NotNull
    Field<?>[] fields(Field<?>... fields);

    
Get all fields from this row, providing some field names.
See Also:
field(String)
Returns:
All available fields/**
     * Get all fields from this row, providing some field names.
     *
     * @return All available fields
     * @see #field(String)
     */
    @NotNull
    Field<?>[] fields(String... fieldNames);

    
Get all fields from this row, providing some field names.
See Also:
field(Name)
Returns:
All available fields/**
     * Get all fields from this row, providing some field names.
     *
     * @return All available fields
     * @see #field(Name)
     */
    @NotNull
    Field<?>[] fields(Name... fieldNames);

    
Get all fields from this row, providing some field indexes.
See Also:
field(int)
Returns:
All available fields/**
     * Get all fields from this row, providing some field indexes.
     *
     * @return All available fields
     * @see #field(int)
     */
    @NotNull
    Field<?>[] fields(int... fieldIndexes);

    
Get a field's index from this row.
Params:
field – The field to look for
Returns:
The field's index or -1 if the field is not
        contained in this Row/**
     * Get a field's index from this row.
     *
     * @param field The field to look for
     * @return The field's index or <code>-1</code> if the field is not
     *         contained in this <code>Row</code>
     */
    int indexOf(Field<?> field);

    
Get a field's index from this row.
Params:
fieldName – The field name to look for
Returns:
The field's index or -1 if the field is not
        contained in this Row/**
     * Get a field's index from this row.
     *
     * @param fieldName The field name to look for
     * @return The field's index or <code>-1</code> if the field is not
     *         contained in this <code>Row</code>
     */
    int indexOf(String fieldName);

    
Get a field's index from this row.
Params:
fieldName – The field name to look for
Returns:
The field's index or -1 if the field is not
        contained in this Row/**
     * Get a field's index from this row.
     *
     * @param fieldName The field name to look for
     * @return The field's index or <code>-1</code> if the field is not
     *         contained in this <code>Row</code>
     */
    int indexOf(Name fieldName);

    
Get an array of types for this row.
 Entries in the resulting array correspond to Typed.getType() for the corresponding Field in fields() /**
     * Get an array of types for this row.
     * <p>
     * Entries in the resulting array correspond to {@link Field#getType()} for
     * the corresponding <code>Field</code> in {@link #fields()}
     */
    @NotNull
    Class<?>[] types();

    
Get the type for a given field index.
Params:
fieldIndex – The field's index of the field's type to fetch
Returns:
The field's type/**
     * Get the type for a given field index.
     *
     * @param fieldIndex The field's index of the field's type to fetch
     * @return The field's type
     */
    @Nullable
    Class<?> type(int fieldIndex);

    
Get the type for a given field name.
Params:
fieldName – The field's name of the field's type to fetch
Returns:
The field's type/**
     * Get the type for a given field name.
     *
     * @param fieldName The field's name of the field's type to fetch
     * @return The field's type
     */
    @Nullable
    Class<?> type(String fieldName);

    
Get the type for a given field name.
Params:
fieldName – The field's name of the field's type to fetch
Returns:
The field's type/**
     * Get the type for a given field name.
     *
     * @param fieldName The field's name of the field's type to fetch
     * @return The field's type
     */
    @Nullable
    Class<?> type(Name fieldName);

    
Get an array of data types for this row.
 Entries in the resulting array correspond to Typed.getDataType() for the corresponding Field in fields() /**
     * Get an array of data types for this row.
     * <p>
     * Entries in the resulting array correspond to {@link Field#getDataType()}
     * for the corresponding <code>Field</code> in {@link #fields()}
     */
    @NotNull
    DataType<?>[] dataTypes();

    
Get the data type for a given field index.
Params:
fieldIndex – The field's index of the field's data type to fetch
Returns:
The field's data type/**
     * Get the data type for a given field index.
     *
     * @param fieldIndex The field's index of the field's data type to fetch
     * @return The field's data type
     */
    @Nullable
    DataType<?> dataType(int fieldIndex);

    
Get the data type for a given field name.
Params:
fieldName – The field's name of the field's data type to fetch
Returns:
The field's data type/**
     * Get the data type for a given field name.
     *
     * @param fieldName The field's name of the field's data type to fetch
     * @return The field's data type
     */
    @Nullable
    DataType<?> dataType(String fieldName);

    
Get the data type for a given field name.
Params:
fieldName – The field's name of the field's data type to fetch
Returns:
The field's data type/**
     * Get the data type for a given field name.
     *
     * @param fieldName The field's name of the field's data type to fetch
     * @return The field's data type
     */
    @Nullable
    DataType<?> dataType(Name fieldName);

    // ------------------------------------------------------------------------
    // [NOT] NULL predicates
    // ------------------------------------------------------------------------

    
Check if this row value expression contains only NULL
values.

Row NULL predicates can be emulated in those databases that do not
support such predicates natively: (A, B) IS NULL is
equivalent to A IS NULL AND B IS NULL
/**
     * Check if this row value expression contains only <code>NULL</code>
     * values.
     * <p>
     * Row NULL predicates can be emulated in those databases that do not
     * support such predicates natively: <code>(A, B) IS NULL</code> is
     * equivalent to <code>A IS NULL AND B IS NULL</code>
     */
    @NotNull
    @Support
    Condition isNull();

    
Check if this row value expression contains no NULL values.

Row NOT NULL predicates can be emulated in those databases that do not
support such predicates natively: (A, B) IS NOT NULL is
equivalent to A IS NOT NULL AND B IS NOT NULL

Note that the two following predicates are NOT equivalent:

(A, B) IS NOT NULL, which is the same as
(A IS NOT NULL) AND (B IS NOT NULL)
NOT((A, B) IS NULL), which is the same as
(A IS NOT NULL) OR (B IS NOT NULL)

/**
     * Check if this row value expression contains no <code>NULL</code> values.
     * <p>
     * Row NOT NULL predicates can be emulated in those databases that do not
     * support such predicates natively: <code>(A, B) IS NOT NULL</code> is
     * equivalent to <code>A IS NOT NULL AND B IS NOT NULL</code>
     * <p>
     * Note that the two following predicates are NOT equivalent:
     * <ul>
     * <li><code>(A, B) IS NOT NULL</code>, which is the same as
     * <code>(A IS NOT NULL) AND (B IS NOT NULL)</code></li>
     * <li><code>NOT((A, B) IS NULL)</code>, which is the same as
     * <code>(A IS NOT NULL) OR (B IS NOT NULL)</code></li>
     * </ul>
     */
    @NotNull
    @Support
    Condition isNotNull();

}