Package org.apache.juneau.beanquery.sql

Interface SqlRowMapper<T>

Type Parameters:
T - The row (bean) type.
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface SqlRowMapper<T>
Turns the current ResultSet row into a bean, for BeanQuerySession.find(BeanQuery) and BeanQuerySession.stream(BeanQuery).

The result set is positioned on the row; do not call ResultSet.next(). columns lists the selected (logical) column names in SELECT order (the query's view, or every column), so column i of the result set is columns.get(i - 1) and a mapper can skip columns the query did not select.

Two built-in mappers need no dependency beyond this module:

  • map() — each row as a LinkedHashMap keyed by column name in view order.
  • bean(Class) — each row as a record (canonical constructor) or as a class with a public no-arg constructor and public setters (setX/withX, void or fluent) or public non-final fields. Columns are matched to Juneau bean property names by exact name; columns with no property are ignored, and properties with no column keep their defaults.
  • bean(BeanMeta) — the same, but using existing bean metadata, so custom property namers apply and column names match the property names a serializer built from that metadata emits.

When no mapper is set on the SqlBeanQueryContext.Builder, one is chosen from the row type: a Map type gets map(), and any other type that bean(Class) can plan gets bean(Class). Object, Map types a LinkedHashMap is not assignable to (such as TreeMap) and types that cannot be planned get none, and find/stream then throw IllegalStateException.

Example:

// Custom mapper. SqlRowMapper<Person> mapper = (rs, columns) -> new Person( columns.contains("name") ? rs.getString("full_name") : null, columns.contains("age") ? rs.getInt("age") : 0); // Rows as maps, or as a record / setter bean. SqlRowMapper<Map<String,Object>> maps = SqlRowMapper.map(); SqlRowMapper<Person> beans = SqlRowMapper.bean(Person.class); // Default selection: no rowMapper(...) call, so Person (a record) gets bean(Person.class). SqlBeanQueryContext<Person> context = SqlBeanQueryContext.create(Person.class) // ...dialect, table, columns, connection source... .build();

Since:
10.0.0

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> SqlRowMapper<T>
    bean(Class<T> type)
    A built-in row mapper that maps each row to a new instance of type: a record (via its canonical constructor) or a concrete class with a public no-arg constructor and public setters (setX/withX returning void or the bean type, so fluent setters work) or public non-final fields.
    static <T> SqlRowMapper<T>
    bean(BeanMeta<T> beanMeta)
    Same as bean(Class), but follows the bean rules of existing bean metadata, for example the metadata of the serializer that renders the rows, so column names match the property names it emits.
    static SqlRowMapper<Map<String,Object>>
    map()
    A built-in row mapper that maps each row to a new LinkedHashMap, keyed by the logical column name in SELECT order, with each value read via ResultSet.getObject(int) (the driver's natural type; null for SQL NULL).
    T
    map(ResultSet rs, List<String> columns)
    Maps the current result-set row to a bean.

  • Method Details

    • map

      T map(ResultSet rs, List<String> columns) throws SQLException
      Maps the current result-set row to a bean.
      Parameters:
      rs - The result set, positioned on the row to map. Must not be advanced.
      columns - The selected column names in SELECT order.
      Returns:
      The mapped bean.
      Throws:
      SQLException - If a column read fails.

    • map

      static SqlRowMapper<Map<String,Object>> map()
      A built-in row mapper that maps each row to a new LinkedHashMap, keyed by the logical column name in SELECT order, with each value read via ResultSet.getObject(int) (the driver's natural type; null for SQL NULL).
      Example:

      SqlRowMapper<Map<String,Object>> mapper = SqlRowMapper.map();

      Returns:
      A shared, stateless row mapper. Always the same instance.
      Since:
      10.0.0

    • bean

      static <T> SqlRowMapper<T> bean(Class<T> type)
      A built-in row mapper that maps each row to a new instance of type: a record (via its canonical constructor) or a concrete class with a public no-arg constructor and public setters (setX/withX returning void or the bean type, so fluent setters work) or public non-final fields.

      Planning happens here, once; mapping never re-inspects type. Columns match Juneau bean property names exactly (setters, public fields and record components, with @BeanIgnore, @BeanProp and the default property namer applied; see QueryModel). A column with no property is ignored; a record component with no column, or a SQL NULL for a primitive, gets the type's default. Values are read with ResultSet.getObject(i, type), except Instant (via OffsetDateTime), Date (via getTimestamp) and enums (by constant name). A failure reading or setting a column throws a BeanQueryExecutionException naming the column. The returned mapper is thread-safe.

      Example:

      record Task(String name, int age) {} SqlRowMapper<Task> mapper = SqlRowMapper.bean(Task.class);

      Type Parameters:
      T - The bean type.
      Parameters:
      type - The bean type. Must not be null.
      Returns:
      A row mapper for type.
      Throws:
      IllegalArgumentException - If type cannot be planned: an interface, abstract class, enum, array or primitive type, a class with no public no-arg constructor, or a setter bean with an ambiguous (overloaded) setter.
      Since:
      10.0.0

    • bean

      static <T> SqlRowMapper<T> bean(BeanMeta<T> beanMeta)
      Same as bean(Class), but follows the bean rules of existing bean metadata, for example the metadata of the serializer that renders the rows, so column names match the property names it emits.
      Example:

      BeanConfigContext config = BeanConfigContext.create().propertyNamer(PropertyNamerDLC.INSTANCE).build(); SqlRowMapper<Task> mapper = SqlRowMapper.bean(BeanMeta.of(Task.class, config));

      Type Parameters:
      T - The bean type.
      Parameters:
      beanMeta - The bean metadata. Must not be null.
      Returns:
      A row mapper for the bean type.
      Throws:
      IllegalArgumentException - For the same reasons as bean(Class).
      Since:
      10.0.0