Mapping
When it comes to mapping, DbOom tries its best to match database types with Java types of POJO properties (i.e. mapped columns). DbOom knows how to convert between various SQL types and common Java types, including enums
. SQL types in DbOom are actually implementations of SqlType
, that defines how to convert values between SQL and Java types.
Custom Mapping
It is possible to define custom SQL types, i.e. custom type mappings. They can be defined in two ways:
globally: custom
SqlType
implementation is registered inSqlTypeManager
. Such SQL types are available all across the application.locally: defined in
@DbColumn
annotation by settingsqlType
element, this custom type applies only on annotated property.
SQL types defined in annotation are always used, even if java type of a property has its own SQL type already registered.
Naming strategies
For successful mapping and DbOom functionality, table and column naming strategies must match how used database works.
This is very important to understand! DbOom has table and column name naming strategies that define how entity/column names are converted to and from the mapped class/property names. Notice that these naming strategies are used in both directions: when converting from table/column name to class/property and vice-versa (i.e. mapping); and when converting from class/property to table/column name (i.e. resolving).
For example, if you have a table JJ_FOO_BAR
(prefix and uppercase) and column value_data
(lowercase), it may be mapped to class FooBar
(camel-case strategy) and property valueData
(again, camel-case). The opposite mapping also has to match: class UserData
may be resolved to e.g. table EX_USER_DATA_N
(uppercase with both prefix and suffix); property valueData
may be resolved to column value_date
(lowercase).
Here are the possible naming strategies options (defined in DbOomManager
):
splitCamelCase
- if camel case words should be split withseparatorChar
.separatorChar
- simple char used whensplitCamelCase
istrue
, by default its_
changeCase
- whentrue
(default) table or column names will be changed to upper or lowercase.uppercase
orlowercase
- defines it table or column name should be converted to upper case or lowercase.prefix
andsuffix
- table names may have prefix and/or a suffix.
Why naming is important? Naming strategies must match how target database works. Wrong naming strategy is the most common configuration mistake when using DbOom! {: .attn}
Therefore, when working with DbOom, please use uniform naming convention across the whole database and please match it with how JDBC drivers work! One thing that can help is to enable logging. If you see WARN message like this:
then it is a sign that mapping or naming conventions might be wrong.
Database auto-detection
Upon start, DbOom
connects to the database and detects the vendor. Depending of the used database, DbOom
should set correct naming conventions.
Mapping Example
Most of above mappings are straightforward: number fields are mapped to number java types, varchars to strings, etc. There are some useful additional mappings, like mapping String
values to integer columns - of course, it is assumed that string contains only digits. In this example you can see two explicit local mapping, when SQL type is defined in @DbColumn
annotation.
Custom mappings
Now something interesting: property boo
has a custom type Boo
, and it is also mapped to database. Of course, this mapping can't be done automatically. We must provide custom SqlType
that explains how to convert database value to and from Boo
type. Since we want to use this mapping everywhere, we might register it globally:
and BooSqlType
may look like:
In this simple example, Boo
is stored as an integer in database; however, you can create a more complex SQL type and conversion.
Enum mappings
Lets see how simple enumeration (FooColor
) can be stored to database. Enumerations, by default, are stored as strings (varchars...).
Now, enumeration may be stored as other SQL type, but it is necessary to define custom SqlType
for mapping conversion. One such implementation may look like:
If you have enumerations that are mapped to an integer, you don't even have to write custom SQL types! So above SqlType
is NOT needed if you design your enumeration like this:
The key thing here is toString()
that returns int value as a String
. When you map such enum to a column of some int type, everything will work out of box! This is because of behavior of BeanUtil tool. Note that we have cached int value for better performances, to avoid string conversion on every access.
Other mappings
Other mappings from the example are also straightforward. It is interesting to notice that LocalDateTime
is stored as number of milliseconds (compatible with System.currentTimeMillis()
).
Last updated