Working with objects
This section of the documentation will explain how to work with entities (objects) in Flextrine. Specifically we will talk about how to load, save, update and delete objects with Flextrine.
Many client/server systems for reading and writing follow the CRUD paradigm (Create, Read, Update, Delete) as it maps neatly to SQL and generally allows for clean row based operations on the database. Unfortunately the simple CRUD approach starts to become more complex if you want to represent a row with an Object, and can end up very complicated indeed once you have relationships between those objects.
An ORM system like Flextrine is built from the ground up to work with objects instead of rows. In fact, the general idea is that from the perspective of your application there are no tables, rows or columns, only stores of objects. The ORM system takes care of translating operations on your objects into SQL calls, and results from SQL calls back into objects.
Flextrine and Doctrine employ a pattern called 'Transactional write-behind'. This means that any write operations (i.e. operations that will cause a change in the database) are queued up until the command is given to actually apply them. This is especially valuable for an asynchronous client/server system like Flextrine as server calls are relatively expensive. The queue is executed using the em.flush() method, or the queue can be abandoned and entities returned to their original state using em.rollback(). See the Flush-and-rollback chapter for more details.
Persisting is the ORM equivalent of Create.
An entity can be made persistent using the persist method of EntityManager. This immediately adds the entity to the appropriate EntityRepository. Note that the object's identifier field will be empty until a successful flush() call, at which point the id will automatically get filled in by Flextrine.
Only auto-generated id strategies are currently supported by Flextrine.
// This creates a NEW doctor
var doc:Doctor = new Doctor();
// This makes the doctor MANAGED, and marks it to be saved to the database on the next flush()
em.persist(doc);
// Add the doctor to the database
em.flush();The semantics of the persist operation, applied on an entity X, are as follows:
- If X is a NEW entity, it becomes MANAGED. The entity X will be entered into the database as a result of the flush operation.
- If X is a pre-existing MANAGED entity, it is ignored by the persist operation.
- If X is a REMOVED entity, it becomes MANAGED.
- If X is a DETACHED entity, an exception will be thrown.
Removing is the ORM equivalent of Delete.
An entity is removed using the remove method of EntityManager. This immediately removes the entity from the appropriate EntityRepository. The entity will be removed from the database on the next flush().
// This makes the doctor REMOVED, and marks it to be deleted from the database on the next flush()
em.remove(doc);
// Remove the doctor from the database
em.flush();The semantics of the remove operation, applied to an entity X are as follows:
- If X is a NEW entity, it is ignored by the remove operation.
- If X is a MANAGED entity, the remove operation causes it to become REMOVED.
- If X is a DETACHED entity, an exception will be thrown.
- If X is a REMOVED entity, it is ignored by the remove operation.
Once an entity is MANAGED (either because it has been loaded from the database or persisted) Flextrine will automatically watch its properties and associations for changes. This means that you don't need to do anything explicit to update an entity, except to call flush() when you want to save it.
// Change a property on the MANAGED doctor
doc.name = "Dr Different Name";
// Save changes to the database
em.flush();