Skip to main content

Type Handlers

Hint

This article is generated by AI translation.

Type handlers read and write a database column using a specific Java type, for example using String to read and write a VARCHAR column.

Use a type handler to deal with special column types such as geospatial, currency, time zones, enums, or serialization.

When no handler is explicitly specified, dbVisitor picks one in this order:

  • 1st Java type + JDBC type
  • 2nd Java type (most common)
  • 3rd JDBC type
  • 4th UnknownTypeHandler
Example: pick handler by Java type
select * from users where name = #{name, javaType=java.lang.String}
  • Java type is java.lang.String; the basic TypeHandler table shows that StringTypeHandler is used.
Example: pick handler by Java + JDBC
select * from users where name = #{name, jdbcType=varchar, javaType=java.lang.String}
  • JDBC type VARCHAR plus Java type java.lang.String; the complex TypeHandler shows that StringTypeHandler is used.
info
  • Most handlers do not require a JDBC type when reading or writing.
  • Usually you only need the Java type for arguments and result mapping (stored procedure OUT args are the main exception).

If the built-ins are not enough, create a custom TypeHandler.

Quick guide​

  • Basic types: a large set of ready-to-use handlers.
  • Enum: EnumTypeHandler is picked automatically in most cases.
  • JSON serialization: store Java objects as JSON text.
  • Geospatial: read/write OpenGIS types like WKT/WKB via JTS.
  • Streams: read/write via InputStream/Reader handlers.
  • Arrays: read and write array columns.