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

Reciprocity

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.

When Converter is invoked

Unlike Binding, which is limited to JDBC interactions, a Converter can be invoked also outside of the context of reading / writing data from / to the JDBC driver. This may include converting nested data structures, such as DSL.multiset(TableLike) or DSL.row(SelectField...), recursively. These two particular expression types are special cases. With other nested (but opaque to jOOQ) data structures, it is not possible to recursively apply a Converter. For example, a DSL.jsonObject(JSONEntry...), while constructed with jOOQ, produces "opaque" contents and thus cannot recursively apply Converter.

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

Ad-hoc converters allow for attaching a converter directly to a SQL expression in order to keep related logic close together. E.g.: 

 
 Result<Record1<BookId>> result =
 ctx.select(BOOK.ID.convertFrom(BookId::new))
    .from(BOOK)
    .fetch();

In the above example, a one-way only converter (only implementing from(Object), not to(Object)) is attached to the BOOK.ID Field expression in order to convert between e.g. Long and BookId. While visually embedded in the query itself, the Converter is still only applied when reading the Result, and like any other kind of Converter (including those attached to Field by the code generator) thus has no effect on the generated SQL or the contents reported by the database.

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: