How does RoomEx work

The compilation of a Java project consists out of 3 phases:

1. Parse and enter
2. Annotation Processing
3. Analyse and Generate

Just like Room itself, RoomEx does most of its work during the "Annotation Processing" phase. During this phase, the annotation processor of RoomEx checks for the following annotations:

1. @OneToOneEx, @OneToManyEx, @ManyToOneEx, @ManyToManyEx
2. @DaoEx
3. @AutoDao
4. @RoomExDb

For every found occurrence of these annotations, RoomEx first does some validation checks. A @OneToOneEx annotation, for example, can only be used on specific properties inside a class annotated with @Entity. Should these succeed, the code generation phase will be invoked.

The annotation processing usually consists out of multiple rounds. In the initial round, all the source code from your project will be analyzed and processed. Any new file generated in the current round will be processed in a subsequent annotation processing round. This is repeated until no new files have been created.

RoomEx annotation processors

RoomEx consists out of the following annotation processors:

1. OneToOneExValidationProcessor
2. OneToManyExValidationProcessor
3. ManyToOneExValidationProcessor
4. ManyToManyExValidationProcessor
5. CollectorProcessor
6. EntityProcessor
7. AutoDaoProcessor
8. DaoExProcessor
9. RoomExDbProcessor

Relation validation processors

The relation validation processors (OneToOneExValidationProcessor, OneToManyExValidationProcessor, ManyToOneExValidationProcessor,ManyToManyExValidationProcessor) ...

CollectorProcessor

The CollectorProcessor neither generate code, nor does it run any validation checks. Its only purpose is it to collect some classes which are needed by multiple other processors.
It collects all entities, Dao's, which Dao belongs to which entity, and how to resolve any entity interface.

EntityProcessor

The EntityProcessor iterates through all the found entity classes in your project and checks for relationships. For any found relationship, a new entity will be created, which sole purpose it is to store the ids of entities which share a relation.

AutoDaoProcessor

The AutoDaoProcessor iterates through all the found entity classes annotated with @AutoDao. For each of these entities, a new DaoEx class will be generated, which extends the ICrud<T> interface. These generated DaoEx classes will then be processed by the DaoExProcessor.

DaoExProcessor

The 'DaoExProcessor' is the biggest processor which implements all the needed functionalities the operate with relations. It iterates over every found class with the @DaoEx annotation and executes the following steps:

Steps:

1. Create new Dao class
2. Add the Room @Dao annotation to the new class
3. Set the DaoEx class as base class
4. Add the database constructor argument, so that we retrieve the database from Room
5. Implement the methods from the IRoomExInternalDao<T> and the IRoomExInternalDaoRawQueries<T> interfaces
6. Implement methods from the RoomExDao base class, e.g. reading from and writing to an entity without reflection
7. Implement methods defined in the ICreate<T> interface (only if the found DaoEx class inherits it)
8. Implement methods defined in the IRead<T> interface (only if the found DaoEx class inherits it)
9. Implement methods defined in the IUpdate<T> interface (only if the found DaoEx class inherits it)
10. Implement methods defined in the IDelete<T> interface (only if the found DaoEx class inherits it)
11. Implement methods defined in the IJoins<T> interface (only if the found DaoEx class inherits it)
12. Implement the relationFields property, which contains all information about the relations of that entity
13. Inherit the IRoomExInternalDaoRawQueries<T> interface
14. Generate the new source file

RoomExDbProcessor

The RoomExDbProcessor will only start its processing phase, when no new file has been generated by any of the other annotation processors during the current round of annotation processing.

Steps:

1. Create new RoomExDatabase class
2. Implement custom database class if one exists
3. Add the Room @Database annotation and set arguments
4. Implement the fetchDaoForEntity method
5. Add the RoomDatabase base class
6. Generate the new source file