EntityManager

The EntityManager is the client gateway to the server. The EntityManager typically handles all client communications with the application server. Queries and saves are the most common operations. The EntityManager is the most heavily used DevForce class and its presence is felt on almost every page of the documentation. This topic offers a technical introduction to the EntityManager: how to create one, how to use it, and the capabilities it offers.

EntityManager overview

The EntityManager serves three main functions:

1. Communicate with the application server
2. Query and save entities
3. Hold entities in a local container called the entity cache.

When the client code of a DevForce application requires data or other external services, it typically calls a member of an EntityManager object. Nothing prevents you from calling external services directly. But it is usually easier and safer to route those requests through an EntityManager. The EntityManager (assisted by helper components) establishes communication channels, sets up the client's security context, serializes and deserializes data, and regulates the application-level flow of traffic with the application server.

The EntityServer is its correspondent on the application server. The EntityServer screens and interprets requests coming from EntityManagers, translating them into the appropriate operations on the server.

Query and save requests are the predominant EntityManager activities. The EntityManager can login, logout, connect, disconnect, and invoke selected methods for execution on the server. But mostly it trades in queries and saves and the entity data exchanged in those two operations.

You can ask the EntityManager to query for entities in a wide variety of ways:

• with LINQ queries
• by EntityKey
• with Entity SQL (ESQL)
• with stored procedure queries
• by navigating from one entity to another (e.g., aCustomer.Orders)

However you do it, EntityManager puts the queried entity results in its entity cache. When you create new entities, you add them to that cache. When you delete entities, you are actually marking entities in the cache, scheduling them to be deleted. The inner workings of changing entities in cache is covered under Create, modify and delete.

When you eventually ask the EntityManager to save, it finds the changed entities in cache - the ones you've modified, added, and scheduled for deletion - and sends their data to the EntityServer. If all goes well, the EntityServer reports success and the EntityManager adjusts the cached entities to reflect the save by discarding deleted entities and re-setting the EntityState of the added and modified entities to Unchanged.

What next?

Drill deeper in this topic for the next level of detail about the EntityManager.