vitusortner
commented
5 years ago Hi. That sounds great! If you have questions about the structure of the library, just open a PR of the current state of your development or add them here. You can find a small wiki on the feature in the following.
Type Converters
Type converters allow translating data right before inserting and after reading it in order to make the values storable in the database. For instance, an entity might hold a date in form of a DateTime object. As SQLite/sqlflite doesn't support Dart's DateTime out of the box, there is the need of converting the date into another type that is supported. In that case, it might be an int that represents the date as a timestamp. A type converter should include two simple functions that convert in both directions. When storing the date, functions would be required that translate between DateTime and int. An example can be seen in the following code snippet.
DateTime toDateTime(int milliseconds) {
return DateTime.fromMillisecondsSinceEpoch(milliseconds);
}
int toInt(DateTime date) {
return date.millisecondsSinceEpoch;
}The library has to check whether such a type converter is applied to a specific entity, DAO, DAO function or the whole database. In order a converter is found, the library has to call the previously implemented converter functions whenever a matching type should get inserted, updated or selected.
It's also required to change the field type of the entity when creating the table. In case of the DateTime example, it would be required to change the DateTime column to int.
API
The full API of the feature is visible in the following code snippet. It includes the definition of the converter itself and multiple ways for applying it to either an entity, database, DAO or DAO function.
// converter
class DateTimeConverter {
@TypeConverter
DateTime toDateTime(int milliseconds) {
return DateTime.fromMillisecondsSinceEpoch(milliseconds);
}
@TypeConverter
int toInt(DateTime date) {
return date.millisecondsSinceEpoch;
}
}
// converter applied to entity
@TypeConverters([DateTimeConverter])
@entity
class Person {
@primaryKey final int id;
final DateTime birthday;
}
// converter applied to database
@TypeConverters([DateTimeConverter])
@Database(version: 1, entities: [Person])
class MyDatabase extends FloorDatabase {
// dao retrieval
}
// converter applied to DAO
@TypeConverters([DateTimeConverter])
class PersonDao {
// dao functions
}
// converter applied to specific DAO function
class PersonDao {
@TypeConverters([DateTimeConverter])
Future<void> insertPerson(Person person);
}Room also allows applying converters to just a specific DAO function field. Let's discuss if that's required. More documentation on the feature can be found here and here.
Implementation
This feature requires changes in a couple places. But first, some explanation about the general architecture of the library. The annotation processor of it searches in the user's source code for a class annotated with @Database. In case such an annotated class is found, processors are triggered that collect all required data from the source code and map it into so-called value objects. These objects are the input of the second tier - writers. These take care of generating the actual persistence code.
When implementing the type converter functionality, it's required to check the source code for the @TypeConverters annotation. If such is found, the defined converters can be used. (Depending on the scope mentioned previously.) They might get applied at Entity.getValueMapping() for creating the function that maps entity objects into Maps. For the other way round, the converter might get applied at EntityProcessor._getConstructor().
MrMonotone
dkaera
xiprox
IanDarwin
jaredgreener
proninyaroslav
noordawod
fnicastri
marcosmko
pablo-johnson
stillie
I read a mention of this in #119. I think it's a great idea.
I will be digging the code and seeing if I can help out, but thought I'd open this issue anyway.
Also, thanks a lot for the great library!