/*
 * 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.io.Serializable;
import java.util.function.Function;

import org.jooq.impl.AbstractConverter;
import org.jooq.impl.SQLDataType;

import org.jetbrains.annotations.NotNull;

A Converter for data types.

A general data type conversion interface that can be provided to jOOQ at
various places in order to perform custom data type conversion. Conversion is
directed, this means that the Converter is used

to load database types converting them to user types "FROM" the database. Hence, fromType() is the type as defined in the database.
to store user types converting them to database types "TO" the database. Hence, toType() is the user-defined type

 Note: In order to avoid unwanted side-effects, it is highly recommended (yet not required) for from(Object) and to(Object) to be reciprocal. The two methods are reciprocal, if for all
X and Y, it can be said that

if Y.equals(converter.from(X)), then
X.equals(converter.to(Y)).
X.equals(converter.from(converter.to(X)))
X.equals(converter.to(converter.from(X)))


Furthermore, it is recommended (yet not required) that

converter.from(null) == null
converter.to(null) == null


Creating user defined DataTypes
 jOOQ provides built in data types through SQLDataType. Users can define their own data types programmatically by calling DataType.asConvertedDataType(Converter) or DataType.asConvertedDataType(Binding), for example. Custom data types can also be defined on generated code using the <forcedType/> configuration, see the manual for more details
Author:
Lukas Eder
Type parameters:
<T> – The database type - i.e. any type available from SQLDataType
<U> – The user type/**
 * A <code>Converter</code> for data types.
 * <p>
 * A general data type conversion interface that can be provided to jOOQ at
 * various places in order to perform custom data type conversion. Conversion is
 * directed, this means that the <code>Converter</code> is used
 * <ul>
 * <li>to load database types converting them to user types "FROM" the database.
 * Hence, {@link #fromType()} is the type as defined in the database.</li>
 * <li>to store user types converting them to database types "TO" the database.
 * Hence, {@link #toType()} is the user-defined type</li>
 * </ul>
 * <p>
 * Note: In order to avoid unwanted side-effects, it is highly recommended (yet
 * not required) for {@link #from(Object)} and {@link #to(Object)} to be
 * <strong>reciprocal</strong>. The two methods are reciprocal, if for all
 * <code>X and Y</code>, it can be said that
 * <ul>
 * <li>if <code>Y.equals(converter.from(X))</code>, then
 * <code>X.equals(converter.to(Y))</code>.</li>
 * <li><code>X.equals(converter.from(converter.to(X)))</code></li>
 * <li><code>X.equals(converter.to(converter.from(X)))</code></li>
 * </ul>
 * <p>
 * Furthermore, it is recommended (yet not required) that
 * <ul>
 * <li><code>converter.from(null) == null</code></li>
 * <li><code>converter.to(null) == null</code></li>
 * </ul>
 * <p>
 * <h3>Creating user defined {@link DataType}s</h3>
 * <p>
 * jOOQ provides built in data types through {@link SQLDataType}. Users can
 * define their own data types programmatically by calling
 * {@link DataType#asConvertedDataType(Converter)} or
 * {@link DataType#asConvertedDataType(Binding)}, for example. Custom data types
 * can also be defined on generated code using the
 * <code>&lt;forcedType/&gt;</code> configuration, see <a href=
 * "https://www.jooq.org/doc/latest/manual/code-generation/codegen-advanced/codegen-config-database/codegen-database-forced-types/">the manual for more details</a>
 *
 * @author Lukas Eder
 * @param <T> The database type - i.e. any type available from
 *            {@link SQLDataType}
 * @param <U> The user type
 */
public interface Converter<T, U> extends Serializable {

    
Convert a database object to a user object
Params:
databaseObject – The database object
Returns:
The user object/**
     * Convert a database object to a user object
     *
     * @param databaseObject The database object
     * @return The user object
     */
    U from(T databaseObject);

    
Convert a user object to a database object
Params:
userObject – The user object
Returns:
The database object/**
     * Convert a user object to a database object
     *
     * @param userObject The user object
     * @return The database object
     */
    T to(U userObject);

    
The database type
/**
     * The database type
     */
    @NotNull
    Class<T> fromType();

    
The user type
/**
     * The user type
     */
    @NotNull
    Class<U> toType();



    
Inverse this converter.
/**
     * Inverse this converter.
     */
    @NotNull
    default Converter<U, T> inverse() {
        return Converters.inverse(this);
    }

    
Chain a converter to this converter.
/**
     * Chain a converter to this converter.
     */
    @NotNull
    default <X> Converter<T, X> andThen(Converter<? super U, X> converter) {
        return Converters.of(this, converter);
    }

    
Turn this converter into a converter for arrays.
/**
     * Turn this converter into a converter for arrays.
     */
    @NotNull
    default Converter<T[], U[]> forArrays() {
        return Converters.forArrays(this);
    }

    
Construct a new converter from functions.
Params:
fromType – The database type
toType – The user type
from – A function converting from T to U
to – A function converting from U to T
Type parameters:
<T> – the database type
<U> – the user type
See Also:
Converter
Returns:
The converter./**
     * Construct a new converter from functions.
     *
     * @param <T> the database type
     * @param <U> the user type
     * @param fromType The database type
     * @param toType The user type
     * @param from A function converting from T to U
     * @param to A function converting from U to T
     * @return The converter.
     * @see Converter
     */
    @NotNull
    static <T, U> Converter<T, U> of(
        Class<T> fromType,
        Class<U> toType,
        Function<? super T, ? extends U> from,
        Function<? super U, ? extends T> to
    ) {
        return new AbstractConverter<T, U>(fromType, toType) {

            
Generated UID
/**
             * Generated UID
             */
            private static final long serialVersionUID = 8782437631959970693L;

            @Override
            public final U from(T t) {
                return from.apply(t);
            }

            @Override
            public final T to(U u) {
                return to.apply(u);
            }
        };
    }

    
Construct a new converter from functions.
 This works like of(Class<Object>, Class<Object>, Function<? super Object,? extends Object>, Function<? super Object,? extends Object>), except that both conversion Functions are decorated with a function that always returns null for null
inputs.

Example:

Converter<String, Integer> converter =
  Converter.ofNullable(String.class, Integer.class, Integer::parseInt, Object::toString);
// No exceptions thrown
assertNull(converter.from(null));
assertNull(converter.to(null));

Params:
fromType – The database type
toType – The user type
from – A function converting from T to U
to – A function converting from U to T
Type parameters:
<T> – the database type
<U> – the user type
See Also:
Converter
Returns:
The converter./**
     * Construct a new converter from functions.
     * <p>
     * This works like {@link Converter#of(Class, Class, Function, Function)},
     * except that both conversion {@link Function}s are decorated with a
     * function that always returns <code>null</code> for <code>null</code>
     * inputs.
     * <p>
     * Example:
     * <p>
     * <code><pre>
     * Converter&lt;String, Integer&gt; converter =
     *   Converter.ofNullable(String.class, Integer.class, Integer::parseInt, Object::toString);
     *
     * // No exceptions thrown
     * assertNull(converter.from(null));
     * assertNull(converter.to(null));
     * </pre></code>
     *
     * @param <T> the database type
     * @param <U> the user type
     * @param fromType The database type
     * @param toType The user type
     * @param from A function converting from T to U
     * @param to A function converting from U to T
     * @return The converter.
     * @see Converter
     */
    @SuppressWarnings("unchecked")
    @NotNull
    static <T, U> Converter<T, U> ofNullable(
        Class<T> fromType,
        Class<U> toType,
        Function<? super T, ? extends U> from,
        Function<? super U, ? extends T> to
    ) {
        Function<T, U> fromS;
        Function<U, T> toS;

        if (from instanceof Serializable)
            fromS = (Function<T, U> & Serializable) t -> t == null ? null : from.apply(t);
        else
            fromS = t -> t == null ? null : from.apply(t);

        if (to instanceof Serializable)
            toS = (Function<U, T> & Serializable) u -> u == null ? null : to.apply(u);
        else
            toS = u -> u == null ? null : to.apply(u);

        return of(fromType, toType, fromS, toS);
    }


}