Module org.jooq

Package org.jooq

Interface Binding<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:

AbstractBinding, AbstractXMLasObjectBinding, BlobBinding, ClobBinding, DateAsTimestampBinding, DefaultBinding, LocalDateAsLocalDateTimeBinding, NClobBinding, XMLasDOMBinding

public interface Binding<T,U>
extends Serializable

An SPI (Service Provider Interface) that exposes all low-level interactions with JDBC bind variables.

This SPI is used by jOOQ users to implement support for custom data types that would otherwise not be supported by jOOQ and/or JDBC. All of jOOQ's internal support for bind variable types is implemented in DefaultBinding.

When Binding is invoked

A Binding is invoked whenever jOOQ interacts with JDBC's various types, including:

• get(BindingGetResultSetContext): To read from a JDBC ResultSet
• get(BindingGetStatementContext): To read from a JDBC CallableStatement (OUT parameters). register(BindingRegisterContext) may be needed to declare OUT parameters beforehand.
• get(BindingGetSQLInputContext): To read from a JDBC SQLInput (UDT attributes)
• set(BindingSetStatementContext): To write to a JDBC PreparedStatement (sql(BindingSQLContext) may be needed to specify the bind value syntax)
• set(BindingSetSQLOutputContext): To read from a JDBC SQLOutput (UDT attributes)

Unlike a Converter, a Binding applies only to JDBC interactions. It does not influence how nested data structures (such as DSL.multiset(TableLike) or DSL.row(SelectField...)) are mapped to Java objects, for example.

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, see the Converter Javadoc for more details.

Author:

Lukas Eder

Method Summary

Modifier and Type	Method	Description
default @Nullable Binding<T[],U[]>	arrayBinding()	Get an array binding for this binding, or null if no such array binding is available.
default @Nullable Binding<?,?>	arrayComponentBinding()	Get an array component binding for this binding, or null if this binding isn't for an array type.
@NotNull Converter<T,U>	converter()	A converter that can convert between the database type and the custom type.
default @Nullable Formatter	formatter()	Get an optional Formatter implementation, instructing jOOQ on how to embed the user type in SQLDataType.JSON, SQLDataType.JSONB, and SQLDataType.XML contexts.
void	get(BindingGetResultSetContext<U> ctx)	Get a ResultSet's OUT value.
void	get(BindingGetSQLInputContext<U> ctx)	Get a SQLInput's OUT value.
void	get(BindingGetStatementContext<U> ctx)	Get a CallableStatement's OUT value.
static <T, U> @NotNull Binding<T,U>	of(Converter<T,U> converter, Consumer<? super BindingSQLContext<U>> sqlContext, Consumer<? super BindingGetResultSetContext<U>> getResultSetContext, Consumer<? super BindingSetStatementContext<U>> setStatementContext)	Construct a binding from functions.
static <T, U> @NotNull Binding<T,U>	of(Converter<T,U> converter, Consumer<? super BindingSQLContext<U>> sqlContext, Consumer<? super BindingGetResultSetContext<U>> getResultSetContext, Consumer<? super BindingSetStatementContext<U>> setStatementContext, Consumer<? super BindingRegisterContext<U>> registerContext, Consumer<? super BindingGetStatementContext<U>> getStatementContext)	Construct a binding from functions.
static <T, U> @NotNull Binding<T,U>	of(Converter<T,U> converter, Consumer<? super BindingSQLContext<U>> sqlContext, Consumer<? super BindingGetResultSetContext<U>> getResultSetContext, Consumer<? super BindingSetStatementContext<U>> setStatementContext, Consumer<? super BindingRegisterContext<U>> registerContext, Consumer<? super BindingGetStatementContext<U>> getStatementContext, Consumer<? super BindingGetSQLInputContext<U>> getSqlInputContext, Consumer<? super BindingSetSQLOutputContext<U>> setSqlOutputContext)	Construct a binding from functions.
void	register(BindingRegisterContext<U> ctx)	Register a CallableStatement's OUT parameter.
void	set(BindingSetSQLOutputContext<U> ctx)	Set a SQLOutput's IN parameter.
void	set(BindingSetStatementContext<U> ctx)	Set a PreparedStatement's IN parameter.
void	sql(BindingSQLContext<U> ctx)	Generate SQL code for the bind variable.

Method Details

converter

@NotNull
@NotNull Converter<T,U> converter()

A converter that can convert between the database type and the custom type.

While the Converter property of a binding is not optional (Converter.fromType() and Converter.toType() are needed by jOOQ's internals), the conversion implementation (i.e. Converter.from(Object) and Converter.to(Object)) isn't strictly required if implementations don't rely on it. If these conversion implementations are non-functional, it is advised to hint at this fact in Converter.fromSupported() and Converter.toSupported().

formatter

@Nullable
default @Nullable Formatter formatter()

Get an optional Formatter implementation, instructing jOOQ on how to embed the user type in SQLDataType.JSON, SQLDataType.JSONB, and SQLDataType.XML contexts.

This may be necessary when embedding user-defined types in DSL.multiset(TableLike) queries, when the user-defined type serialises differently in a NestedCollectionEmulation.JSONB emulation than standalone, for example.

A null formatter will have no effect on generated SQL.

Note: while it is possible to implement a custom formatter for array types, it is usually simpler to just delegate to the arrayComponentBinding() for this, and let jOOQ's internals handle the intricate mapping of generic arrays to XML or JSON.

arrayBinding

@Nullable
default @Nullable Binding<T[],U[]> arrayBinding()

Get an array binding for this binding, or null if no such array binding is available.

arrayComponentBinding

@Nullable
default @Nullable Binding<?,?> arrayComponentBinding()

Get an array component binding for this binding, or null if this binding isn't for an array type.

Implementations must ensure that the resulting type is Binding<X, Y>, if this Binding's type variables resolve to T = X[] and U = Y[], as this cannot be enforced by the Java compiler.

sql

void sql(BindingSQLContext<U> ctx)
  throws SQLException

Generate SQL code for the bind variable.

Implementations should generate SQL code onto BindingSQLContext.render(), given the context's bind variable located at BindingSQLContext.value(). Examples of such SQL code are:

• "?": Default implementations can simply generate a question mark.
  
  
• "123": Implementations may choose to inline bind variables to influence execution plan generation.
  
  Context.paramType() contains information whether inlined bind variables are expected in the current context.
  
  
• "CAST(? AS DATE)": Cast a database to a more specific type. This can be useful in databases like Oracle, which map both DATE and TIMESTAMP SQL types to Timestamp.
  
  Context.castMode() may contain some hints about whether casting is suggested in the current context.
  
  
• "?::json": Vendor-specific bind variables can be supported, e.g. SQLDialect.POSTGRES's JSON data type.

Implementations must provide consistent behaviour between sql(BindingSQLContext) and set(BindingSetStatementContext), i.e. when bind variables are inlined, then they must not be bound to the PreparedStatement in set(BindingSetStatementContext)

Parameters:

ctx - The context object containing all argument objects.

Throws:

SQLException - Implementations are allowed to pass on all SQLExceptions to the caller to be wrapped in DataAccessExceptions.

register

void register(BindingRegisterContext<U> ctx)
       throws SQLException

Register a CallableStatement's OUT parameter.

Parameters:

ctx - The context object containing all argument objects.

Throws:

SQLException - Implementations are allowed to pass on all SQLExceptions to the caller to be wrapped in DataAccessExceptions.

set

void set(BindingSetStatementContext<U> ctx)
  throws SQLException

Set a PreparedStatement's IN parameter.

Parameters:

ctx - The context object containing all argument objects.

Throws:

SQLException - Implementations are allowed to pass on all SQLExceptions to the caller to be wrapped in DataAccessExceptions.

set

void set(BindingSetSQLOutputContext<U> ctx)
  throws SQLException

Set a SQLOutput's IN parameter.

Parameters:

ctx - The context object containing all argument objects.

Throws:

SQLException - Implementations are allowed to pass on all SQLExceptions to the caller to be wrapped in DataAccessExceptions.

get

void get(BindingGetResultSetContext<U> ctx)
  throws SQLException

Get a ResultSet's OUT value.

Implementations are expected to produce a value by calling BindingGetResultSetContext.value(Object), passing the resulting value to the method.

Parameters:

ctx - The context object containing all argument objects.

Throws:

SQLException - Implementations are allowed to pass on all SQLExceptions to the caller to be wrapped in DataAccessExceptions.

get

void get(BindingGetStatementContext<U> ctx)
  throws SQLException

Get a CallableStatement's OUT value.

Implementations are expected to produce a value by calling BindingGetStatementContext.value(Object), passing the resulting value to the method.

Parameters:

ctx - The context object containing all argument objects.

Throws:

SQLException - Implementations are allowed to pass on all SQLExceptions to the caller to be wrapped in DataAccessExceptions.

get

void get(BindingGetSQLInputContext<U> ctx)
  throws SQLException

Get a SQLInput's OUT value.

Implementations are expected to produce a value by calling BindingGetSQLInputContext.value(Object), passing the resulting value to the method.

Parameters:

ctx - The context object containing all argument objects.

Throws:

SQLException - Implementations are allowed to pass on all SQLExceptions to the caller to be wrapped in DataAccessExceptions.

of

@NotNull
static <T,
U> @NotNull Binding<T,U> of(Converter<T,U> converter,
 Consumer<? super BindingSQLContext<U>> sqlContext,
 Consumer<? super BindingGetResultSetContext<U>> getResultSetContext,
 Consumer<? super BindingSetStatementContext<U>> setStatementContext)

Construct a binding from functions.

of

@NotNull
static <T,
U> @NotNull Binding<T,U> of(Converter<T,U> converter,
 Consumer<? super BindingSQLContext<U>> sqlContext,
 Consumer<? super BindingGetResultSetContext<U>> getResultSetContext,
 Consumer<? super BindingSetStatementContext<U>> setStatementContext,
 Consumer<? super BindingRegisterContext<U>> registerContext,
 Consumer<? super BindingGetStatementContext<U>> getStatementContext)

Construct a binding from functions.

of

@NotNull
static <T,
U> @NotNull Binding<T,U> of(Converter<T,U> converter,
 Consumer<? super BindingSQLContext<U>> sqlContext,
 Consumer<? super BindingGetResultSetContext<U>> getResultSetContext,
 Consumer<? super BindingSetStatementContext<U>> setStatementContext,
 Consumer<? super BindingRegisterContext<U>> registerContext,
 Consumer<? super BindingGetStatementContext<U>> getStatementContext,
 Consumer<? super BindingGetSQLInputContext<U>> getSqlInputContext,
 Consumer<? super BindingSetSQLOutputContext<U>> setSqlOutputContext)

Construct a binding from functions.