The five fundamental operations of Records
The core of Records is quite simple and consists of five fundamental operations. They will be explained in detail below. All pictographs show a snapshot of the memory after the API has been called. The illustration style is a blend of an object diagram and a class diagram. It tries to emphasize when and where memory is allocated.
When calling Records.register(blueprint) for the first time the passed blueprint will be analyzed via reflection. The internal BlueprintInspector creates a BlueprintClass object containing information about methods and member variables. Identified variables have a type and allocation size in bytes to form the layout of a record. A record is therefore just a piece of memory structured in a way defined by the blueprint.
Ones the BlueprintClass object is created, the RecordClassGenerator constructs a new RecordView class out of it. This class will implement the blueprint (interface) and has methods accessing the native memory of the system to store and load member variables. All methods are declared and implemented as final.
Until the blueprint and the new RecordView class has not been registered, the Records API does not know the relation between them. The Records.register(blueprint) method will therefore perform a registration process after the two operations mentioned above have finished. The registration itself is just an entry in an association table.
The first three operations will be performed only once for each new blueprint. Afterwards new records can be created with the Records.create(blueprint) method. This creation process includes the allocation of enough memory to store the content of a record and the instantiation of a RecordView object pointing to corresponding part of memory. There exists other methods where RecordViews are reused to allocate new records.
A RecordView object is the only way to access the data of a record. Records them self can not be instantiated. Within the API docs and the code samples the naming sometimes becomes ambiguous because a RecordView looks like a Record which looks like the Blueprint. To create a new RecordView object pointing to no record the method Records.view(blueprint) can be called.
