The Entity Repository

Flextrine stores entities in Entity Repositories. You can think of an entity repository as a kind of local cache of the database. One of the main jobs of an entity repository is to make sure that you don't need to be continually querying the database; another job is to ensure that there is only ever one instance of a particular entity in existence at a time.

Internally, an entity repository stores entities in an ArrayCollection (although with some extra functionality above the standard Flex version - see advanced collections) which can be referenced by the entities attribute. An entity stored in a repository is considered MANAGED, and will be watched for modification by Flextrine as long as it exists.

Getting an Entity Repository

To retrieve an entity repository use the getRepository(entityClass:Class) method on the EntityManager. For example, if I wanted to get the User repository I would use:

var entityRepository:IEntityRepository = em.getRepository(User);

Note that the entity repository return type is IEntityRepository, not EntityRepository. In order to maintain integrity of the repository it is essential that you only use the API exposed by the IEntityRepository interface

Getting entities into the Entity Repository

There are a few ways to get entities into a repository.

Persisting a new entity

When you persist an entity with [EntityManager]::persist(entity:Object) it is automatically added to its repository. Assuming you are using an auto-incrementing id, at this point the entity will have no identify, but when flush is next called the id will be merged into the entity.

loadAll()

loadAll, as you can probably guess loads every entity of the repository class into the repository.

// Load all users
em.getRepository(User).loadAll();

load(id:Number)

Loads the entity with the given id into the repository.

// Load user 7
em.getRepository(User).load(7);

loadBy(criteria:Object)

Use a simple criteria to load matching entities into the repository. Note that the attributes you are searching on cannot be associations to other entities and must be actual values within the entity. If you want to load entities based on their associations (e.g. load all Patients who have the Doctor with id 1) you will need to use DQL. See the Complex queries and DQL documentation for details.

// Load active users of type customer
em.getRepository(User).loadBy( { active: true, type: "customer" } );

Querying existing entities in the Entity Repository

Once a repository has some entities in it you also have three methods to retrieve that data. These methods execute totally within Flex and don't involve any calls to the server. One thing to bear in mind is that Flextine has no way to know if an entity you are trying to retrieve locally does actually exist in the database and will return null - it is the responsibility of your application to ensure that anything that you expected to be loaded into the repository has been.

findAll():Array

findAll returns all items in the repository as an array. Databinding will no longer work on the array itself.

// Find all users
em.getRepository(User).findAll();

find(id:Number):Object

Find the entity with the given id.

// Find user 7
em.getRepository(User).find(7);

findBy(criteria:Object):Array

Use a simple criteria to find matching entities in the repository as an Array. Databinding will no longer work on the array itself.

// Find active users of type customer
em.getRepository(User).findBy( { active: true, type: "customer" } );

findOneBy(criteria:Object):Object

Use a simple criteria to find a single matching entity in the repository.

// Find a single active users of type customer
em.getRepository(User).findOneBy( { active: true, type: "customer" } );