Garbage collection

Prior to v0.9 of Flextrine the EntityRepositories acted as a local cache of the remote database that filled up with entities over the lifetime of the application. This works great if you don't have too large a database, or are sure that you are only ever going to load a small subset of it.

Flextrine can still be run in this mode by adding the following configuration line:

configuration.entityTimeToLive = -1;

However, for larger RIA application this approach will eventually cause the Flash Player to crawl to a standstill as it uses more and more memory. Therefore since v0.9 entities in repositories becomes eligible for garbage collection after they have been in existence for a certain amount of time (by default this is 5 seconds).

This means that unless you have a reference to an entity in your application it may disappear at any moment!

Keep references to entities you are using

An entity will only ever be garbage collected if it exists in a repository and nowhere else. Therefore if you know that you want to keep a reference particular entity, simply store it in a variable somewhere within your application and it will not become eligible for garbage collection until you release it (i.e. set it to null).

Note that any entity which is being displayed in a Flex component will not be garbage collected whilst the component is displaying that entity. Note that some components (e.g. mx:ComboBox) only hold an internal reference to the currently selectedItem, so its quite possible for other, non-selected entities, to be garbage collected before a user opens the dropdown.

Note that if you want to stop a collection from being garbage collected, the correct way is to use an IResponder on the load call and assign the result to an Array in your application. Copying a repositories entities collection to a model will not stop garbage collection from taking place, as EntityCollection is a weak-key based collection.

Entity time to live

The amount of time you want an entity in a repository to live before becoming eligible for garbage collection is set in milliseconds using configuration.entityTimeToLive. This should never be set to less that 5000ms (5 seconds) otherwise entities can be garbage collected whilst Flextrine is processing them causing strange errors.

If configuration.entityTimeToLive is set to -1 entities will never be garbage collected.

Repository-based entity time to live

Sometimes you may want to disable garbage collection for a particular entity class, whilst enabling it for others. An example of this might be for a blog application where you have predefined PostCategory entities. You know that there will never be too many of these entities, so you want to load them all on application startup and know that they will not be garbage collected. However, you want garbage collection enabled for all the other repositories.

In order to implement this use-case EntityManager.getRepository takes an optional second parameter, entityTimeToLive. For example:

var postCategoryRepo:IEntityRepository = em.getRepository(PostCategory, -1);

Important: This only works on the very first call to getRepository for the particular entity class. Attempting to set entityTimeToLive on a repository which has already been retrieved will throw a run-time error.