Module org.jooq
Package org.jooq

Interface Converter<T,U>

Type Parameters:
T - The database type - i.e. any type available from SQLDataType
U - The user type
All Superinterfaces:
Serializable
All Known Implementing Classes:
AbstractConverter, Converters, DateToLocalDateConverter, DelegatingConverter, EnumConverter, IdentityConverter, JPAConverter, TimestampToLocalDateTimeConverter, TimeToLocalTimeConverter, XMLtoJAXBConverter
public interface Converter<T,U> extends Serializable
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. Think of "FROM" = "reading".
  • to store user types converting them to database types "TO" the database. Think of "TO" = "writing". 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

Irrespective of the Converter's encoding of null values above, an implementation must be able to handle null values.

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

  • Method Summary

    Modifier and Type
    Method
    Description
    default <X> @NotNull Converter<T,X>
    andThen(Converter<? super U,X> converter)
    Chain a converter to this converter.
    default @NotNull Converter<T[],U[]>
    forArrays()
    Turn this converter into a converter for arrays.
    static <T, U> @NotNull Converter<T,U>
    from(Class<T> fromType, Class<U> toType, Function<? super T,? extends U> from)
    Construct a new read-only converter from a function.
    U
    from(T databaseObject)
    Read and convert a database object to a user object.
    static <T, U> @NotNull Converter<T,U>
    fromNullable(Class<T> fromType, Class<U> toType, Function<? super T,? extends U> from)
    Construct a new read-only converter from a function.
    @NotNull Class<T>
    fromType()
    The database type.
    default @NotNull Converter<U,T>
    inverse()
    Inverse this converter.
    static <T, U> @NotNull Converter<T,U>
    of(Class<T> fromType, Class<U> toType, Function<? super T,? extends U> from, Function<? super U,? extends T> to)
    Construct a new converter from functions.
    static <T, U> @NotNull Converter<T,U>
    ofNullable(Class<T> fromType, Class<U> toType, Function<? super T,? extends U> from, Function<? super U,? extends T> to)
    Construct a new converter from functions.
    static <T, U> @NotNull Converter<T,U>
    to(Class<T> fromType, Class<U> toType, Function<? super U,? extends T> to)
    Construct a new write-only converter from a function.
    T
    to(U userObject)
    Convert and write a user object to a database object.
    static <T, U> @NotNull Converter<T,U>
    toNullable(Class<T> fromType, Class<U> toType, Function<? super U,? extends T> to)
    Construct a new write-only converter from a function.
    @NotNull Class<U>
    toType()
    The user type.

  • Method Details

    • from

      U from(T databaseObject)
      Read and convert a database object to a user object.
      Parameters:
      databaseObject - The database object.
      Returns:
      The user object.

    • to

      T to(U userObject)
      Convert and write a user object to a database object.
      Parameters:
      userObject - The user object.
      Returns:
      The database object.

    • fromType

      @NotNull @NotNull Class<T> fromType()
      The database type.

    • toType

      @NotNull @NotNull Class<U> toType()
      The user type.

    • inverse

      @NotNull default @NotNull Converter<U,T> inverse()
      Inverse this converter.

    • andThen

      @NotNull default <X> @NotNull Converter<T,X> andThen(Converter<? super U,X> converter)
      Chain a converter to this converter.

    • forArrays

      @NotNull default @NotNull Converter<T[],U[]> forArrays()
      Turn this converter into a converter for arrays.

    • of

      @NotNull static <T, U> @NotNull Converter<T,U> of(Class<T> fromType, Class<U> toType, Function<? super T,? extends U> from, Function<? super U,? extends T> to)
      Construct a new converter from functions.
      Type Parameters:
      T - the database type.
      U - the user type.
      Parameters:
      fromType - The database type.
      toType - The user type.
      from - A function converting from T to U when reading from the database.
      to - A function converting from U to T when writing to the database.
      Returns:
      The converter.
      See Also:

    • from

      @NotNull static <T, U> @NotNull Converter<T,U> from(Class<T> fromType, Class<U> toType, Function<? super T,? extends U> from)
      Construct a new read-only converter from a function.
      Type Parameters:
      T - the database type
      U - the user type
      Parameters:
      fromType - The database type
      toType - The user type
      from - A function converting from T to U when reading from the database.
      to - A function converting from U to T when writing to the database.
      Returns:
      The converter.
      See Also:

    • to

      @NotNull static <T, U> @NotNull Converter<T,U> to(Class<T> fromType, Class<U> toType, Function<? super U,? extends T> to)
      Construct a new write-only converter from a function.
      Type Parameters:
      T - the database type
      U - the user type
      Parameters:
      fromType - The database type
      toType - The user type
      from - A function converting from T to U when reading from the database.
      to - A function converting from U to T when writing to the database.
      Returns:
      The converter.
      See Also:

    • ofNullable

      @NotNull static <T, U> @NotNull Converter<T,U> ofNullable(Class<T> fromType, Class<U> toType, Function<? super T,? extends U> from, Function<? super U,? extends T> to)
      Construct a new converter from functions.

      This works like of(Class, Class, Function, Function), 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));
      Type Parameters:
      T - the database type
      U - the user type
      Parameters:
      fromType - The database type
      toType - The user type
      from - A function converting from T to U when reading from the database.
      to - A function converting from U to T when writing to the database.
      Returns:
      The converter.
      See Also:

    • fromNullable

      @NotNull static <T, U> @NotNull Converter<T,U> fromNullable(Class<T> fromType, Class<U> toType, Function<? super T,? extends U> from)
      Construct a new read-only converter from a function.

      This works like from(Class, Class, Function), except that the conversion Function is decorated with a function that always returns null for null inputs.

      Example: 

      
 Converter<String, Integer> converter =
   Converter.fromNullable(String.class, Integer.class, Integer::parseInt);

 // No exceptions thrown
 assertNull(converter.from(null));
      Type Parameters:
      T - the database type.
      U - the user type.
      Parameters:
      fromType - The database type.
      toType - The user type.
      from - A function converting from T to U when reading from the database.
      Returns:
      The converter.
      See Also:

    • toNullable

      @NotNull static <T, U> @NotNull Converter<T,U> toNullable(Class<T> fromType, Class<U> toType, Function<? super U,? extends T> to)
      Construct a new write-only converter from a function.

      This works like to(Class, Class, Function), except that the conversion Function is decorated with a function that always returns null for null inputs.

      Example: 

      
 Converter<String, Integer> converter =
   Converter.toNullable(String.class, Integer.class, Object::toString);

 // No exceptions thrown
 assertNull(converter.to(null));
      Type Parameters:
      T - the database type
      U - the user type
      Parameters:
      fromType - The database type
      toType - The user type
      to - A function converting from U to T when writing to the database.
      Returns:
      The converter.
      See Also: