yosql-website/content/sql/converters.md

   1 ---
   2 title: Converters
   3 date: 2019-07-07T14:27:54+02:00
   4 menu:
   5   main:
   6     parent: SQL
   7 categories:
   8   - SQL
   9 tags:
  10   - converters
  11 ---
  12
  13 The JDBC API offers no built-in object mapping mechanism. In order to use high level types of your domain, use a **converter** to map results to your types. Converters are just plain Java classes that have at least one method that converts a `java.sql.ResultSet` into some other type. Each converter has an alias to make it easier to reference different converters without specifying their fully qualified name.
  14
  15 ## Map Converter
  16
  17 In case you do not want to use custom domain types, `YoSQL` provides a built-in default converter that returns a `Map<String, Object>`. That converter is declared as the [defaultConverter](../../configuration/converter/defaultconverter/) if not otherwise specified by yourself, thus newly generated code will always return `Map`s at first. You can disable generating the mapping converter by using [generateMapConverter](../../configuration/converter/generatemapconverter/). You can change its location with [mapConverterClass](../../configuration/converter/mapconverterclass/), its method name with [mapConverterMethod](../../configuration/converter/mapconvertermethod/) and its alias with [mapConverterAlias](../../configuration/converter/mapconverteralias/). Methods that use the mapping converter have a signature similar to this:
  18
  19 ```java
  20 Optional<Map<String, Object>> someMethod()
  21 List<Map<String, Object>> someMethod()
  22 Stream<Map<String, Object>> someMethod()
  23 ```
  24
  25 ## Default Converter
  26
  27 If not otherwise specified, generated code will use the default converter to converter between `java.sql.ResultSet` and some type declared by the configured default converter.
  28 In case you want to adjust the converter used by all your statements, set the [defaultConverter](../../configuration/converter/defaultconverter/) configuration option accordingly. By default, this points to the map converter mentioned above.
  29
  30 ## Custom Converter
  31
  32 In order to use your own domain types in generated code, write a custom converter like in the following example and register each custom converter using the [rowConverters](../../configuration/converter/rowconverters/) configuration option:
  33
  34 ```java
  35 package my.own;
  36
  37 import java.sql.ResultSet;
  38 import java.sql.SQLException;
  39
  40 import my.own.User;
  41 import my.own.persistence.util.ResultState;
  42
  43 public class UserConverter {
  44
  45     public User apply(ResultState result) throws SQLException {
  46         ResultSet resultSet = result.getResultSet();
  47         User pojo = new User();
  48         pojo.setId(resultSet.getInt("id"));
  49         pojo.setName(resultSet.getString("name"));
  50         return pojo;
  51     }
  52
  53 }
  54 ```
  55
  56 You can choose package, class name and method name at will. The converter method gives you full control about how you want to handle `ResultSet`s. You can use your own converter either by specifying it as the default converter mentioned above or by declaring it as a [resultRowConverter](../../configuration/sql/resultrowconverter) with either its fully qualified name or its alias like this in the front matter of your SQL statements:
  57
  58 ```sql
  59 -- resultRowConverter: my.own.UserConverter
  60 SELECT  *
  61 FROM    users
  62 ```
  63
  64 Generated code will now use your custom converter along with the result type configured for your converter, e.g.:
  65
  66 ```java
  67 Optional<User> someMethod()
  68 List<User> someMethod()
  69 Stream<User> someMethod()
  70 ```
  71
  72 **Tip**: In case you want to use custom types, but do not want to write your own converter, consider using [SimpleFlatMapper](https://simpleflatmapper.org/0102-getting-started-jdbc.html) with its built-in support for JDBC `ResultSet`s.