The entity cache

The entity cache is an in-memory container of entity objects that belong to a specific EntityManager. Working with entities in cache requires little effort on your part. Most queries automatically put retrieved entities into the cache, and when you ask the EntityManager to save, it saves the changed entities in cache to the datastore.

DevForce automatically decides if subsequent queries can be safely satisfied from cache, and if so, this saves a trip to the server and improves performance. However, you can always refresh entities in cache if you need to.

Although you will typically work with entities that reside in an EntityManager's cache, you can work with entities that are not yet in cache and entities that were once in cache but have since been detached - but that's unusual. Many of the important features of entities, including the ability to navigate to related entities and to save changes, are only available when the entities reside in cache.

Entities in cache are unique

An entity in cache is identified by its EntityKey and type (e.g. Customer). All entities in cache have unique EntityKeys; a cache can't have two instances of Customer with the same CustomerID. Of course no one can prevent you from creating two Customer objects with the same CustomerID. But they can't both be in the same EntityManager cache at the same time.

Add entities to cache

Entities usually enter the cache as a by-product of a query. This happens automatically without any action on your part (unless you specifically want to change the behavior).

You can also add entities to cache explictly in three ways:

1. By adding it to an EntityManager with the AddEntity method. An added entity is regarded as a new entity that will be inserted into the database if saved.
   
   
2. By attaching it to an EntityManager with the AttachEntity method. An attached entity is regarded as an existing, unmodified entity like one that has been queried.
   
   
3. By importing it with the EntityManager's ImportEntities method.
   
   

Remove entities from cache

Deleting an existing entity doesn't remove it from cache but saving a deleted entity does. The save removes the deleted entity implicitly. You can remove an entity from cache explicitly as well:

Call the EntityManager's Clear method to remove every entity from the cache.

Is the entity in cache or not?

In the code above, someCustomer is a reference to a Customer entity. They entity didn't disappear because we removed it from cache. It's still an entity. It's now a Detached entity.

We can ask the entity if it is in cache or Detached by inquiring about its entitystate. The following line verifies that someCustomer was detached after we removed it.

EntityState can tell us more than whether the entity is attached or detached.
 

Find entities in cache

You can explicitly query the cache by using a CacheOnly QueryStrategy .

You can also use FindEntities or FindEntityGraph to search the cache.

Unlike a query, you can find an entity in cache even if it is deleted.

You can also find entities in cache using LINQ for objects:

Notice that

• FindEntities filters by entitystate; here we ask for all cached states (AllButDetached).

• FindEntities returns an IEnumerable; we cast it to IEnumerable of Customer in order to query it with LINQ.
• FindEntities won't return any Detached entities because Detached entities are not associated with an EntityManager.
  
  

Export cache as an EntityCacheState

The EntityManager itself is not serializable. But its cache contents are serializable when in the form of an EntityCacheState . An EntityCacheState is a snapshot of the entities in cache. This snapshot can be handed around inside the client application, serialized to file, restored from file, even sent to the server as a parameter in a remote server method call. 

To get an EntityCacheState, start with the manager's CacheStateManager . Its GetCacheState method can return an EntityCacheState with all or only some of the entities in cache. 

In the following unrealistic example, we use an EntityCacheState to copy a cache from one manager to another:

A CacheStateManager can also save or restore an EntityCacheState from a file.

Entity cache structure

You rarely need to probe around inside the entity cache itself. Most of the time, the cache works transparently and if you need to be explicit, the cache-only query and the Find methods are the preferred ways to retrieve entities from cache.

When you need to watch the cache for activity regarding a particular type, it helps to know about EntityGroups . The cache is organized a collection of EntityGroups. Each group holds the cached entities for a particular type of entity.

You can discover what entity types the manager has seen by asking for its EntityGroups

A new manager's cache has no groups. It acquires groups as different entity types are added to the cache or are referred to by an entity that was queried into cache.

You can ask for a specific EntityGroup:

Clearing the manager's cache (manager.Clear()) removes all groups.

Listen to cache changes

The cache can tell you when an entity has been attached, changed, or detached.

The following fragment shows how to listen for any change to the cache or to cache changes for a particular entity type.