module Athena::ORM::EntityManagerInterface
#
The interface of an entity manager, the central access point to the ORM.
See AORM::EntityManager for the default implementation.
Direct including types
Athena::ORM::EntityManager
Methods#
abstract #begin_transaction : Nil#
Starts a transaction, or a savepoint if one is already active.
It must be ended with #commit or #rollback.
em.begin_transaction
begin
# ...
em.flush
em.commit
rescue ex
em.rollback
em.close
raise ex
end
Tip
AORM::EntityManager#wrap_in_transaction takes care of flushing, committing, and handling errors.
abstract #clear : Nil#
Detaches every entity this entity manager manages, discarding any changes that weren't flushed. Afterwards, entities are loaded from the database again rather than from the identity map.
abstract #close : Nil#
Clears the entity manager and marks it closed.
A closed entity manager raises on #persist, #remove, #refresh, and #flush.
abstract #closed? : Bool#
Returns true if this entity manager was closed via #close, or by a failed flush.
abstract #commit : Nil#
Commits the innermost transaction, or releases its savepoint if it's nested.
The entity manager isn't flushed first; call #flush before committing.
abstract #connection : AORM::Connection#
Returns the connection this entity manager executes its queries on.
abstract #contains(entity : AORM::Entity) : Bool#
Returns true if entity is managed by this entity manager, i.e. it was loaded or persisted by it, and isn't removed.
abstract #find(entity_class : T.class, id : Hash(String, Int | String) | Int | String, lock_mode : AORM::LockMode = :none, lock_version : Int32 | Nil = nil) : AORM::Entity | Nil forall T#
Returns the entity of type entity_class with the identifier id, or nil if there isn't one.
abstract #find!(entity_class : T.class, id : Hash(String, Int | String) | Int | String, lock_mode : AORM::LockMode = :none, lock_version : Int32 | Nil = nil) : AORM::Entity forall T#
Returns the entity of type entity_class with the identifier id, raising if there isn't one.
abstract #flush : Nil#
Writes all of the changes to the entities this entity manager manages to the database, in a single transaction.
This inserts persisted entities, updates changed managed entities, deletes removed entities, and writes the changes to their associations. Changes are only detected on the owning side of an association, see the associations section of the manual.
Raises an exception if a new entity is found through an association that doesn't cascade "persist".
If the flush fails, its transaction is rolled back and the entity manager is closed.
abstract #persist(entity : AORM::Entity) : Nil#
Makes the new entity managed, so that it's inserted on the next #flush.
user = User.new
user.name = "George"
em.persist user
em.flush # => INSERT INTO users (name) VALUES (?)
Depending on entity's state:
- New - It becomes managed, and its
AORMA::PrePersistcallbacks run. - Managed - Nothing changes, but associated entities are still persisted if the association cascades
"persist". - Removed - It's managed again, and won't be deleted.
The operation is also applied to the associated entities of associations that cascade "persist", see the associations section of the manual.
Database generated identifiers are assigned when the entity is inserted, so they aren't available until the flush.
Warning
Don't pass detached entities. Any entity that isn't known to the entity manager is treated as new, so persisting a detached entity tries to insert it again.
abstract #refresh(entity : AORM::Entity, lock_mode : AORM::LockMode = :none) : Nil#
Reloads the managed entity's columns from the database, discarding any changes that haven't been flushed. Raises an exception if entity isn't managed.
user = em.find! User, 1
user.name = "Not saved"
em.refresh user
user.name # => "George"
Todo
Associations aren't refreshed, even if the association cascades "refresh".
Row locking isn't supported yet either, see AORM::LockMode.
abstract #remove(entity : AORM::Entity) : Nil#
Schedules the managed entity to be deleted on the next #flush.
user = em.find! User, 1
em.remove user
em.flush # => DELETE FROM users WHERE id = ?
Depending on entity's state:
- New or Removed - Nothing changes, but associated entities are still removed if the association cascades
"remove". - Managed - It becomes removed, and its
AORMA::PreRemovecallbacks run. - Detached - Raises an exception.
The operation is also applied to the associated entities of associations that cascade "remove", see the associations section of the manual.
Until it's flushed, a removed entity can still be found by queries and stays in the collections that contain it.
Once it's deleted, a database generated identifier is set back to nil, while the rest of its state stays as it was.
abstract #repository(entity_class : AORM::Entity.class) : AORM::RepositoryInterface#
Returns the repository of entity_class.
em.repository(User).find_by name: "George" # => [#<User:0x7f3a1c2b5e40 @id=1, @name="George">]
The repository is an AORM::EntityRepository of the entity, or the entity's custom repository class if it has one, see Custom Repositories.
abstract #rollback : Nil#
Rolls back the innermost transaction, or to its savepoint if it's nested.
Entities keep the state they had in memory, which may no longer match the database.
Close the entity manager via #close and discard it along with its entities.
abstract #unit_of_work#
Returns the unit of work tracking this entity manager's entities.