Up Create, modify and delete

Access entity internals

Last modified on August 15, 2012 17:22

You access the internals of an entity through the entity's EntityAspect property. EntityAspect is your gateway to the DevForce infrastructure hidden within each entity. The EntityAspect tells you whether the entity has changed and how, and allows you to perform basic functions such as adding and removing the entity from its EntityManager.  This topic covers what you can do with and learn from the EntityAspect.


Hiding entity infrastructure

An entity represents a thing in the application domain. A Customer represents "customer-ness". You modeled the Customer entity to suit the needs of programmers who write code about customers. The Customer entity should exhibit "customer-ness". Here is what a Customer instance looks like in IntelliSense:

customer-intellisense.png

Almost all members are Customer-specific. They are data properties, navigation properties, and custom methods (if we had some).

A few members concern infrastructure having nothing to do with Customer per se. These are members of the Customer's base classes such as Object.GetHashCode and Object.GetType ... and Entity.EntityAspect.

They are noise when our attention is on "customer-ness". They can distract us from our primary purpose - to do business with a customer.

In an ideal world they would be invisible. In practice, we need them. At various times we have to set aside our "Customer" perspective and see the Customer entity as a .NET object. Sometimes we need to work with it as Object. Sometimes we need to work with it as an Entity. When we need to shift our perspective, we need to shift quickly.

The architect's challenge is to keep "customer-ness" on center stage and have "object-ness" and "entity-ness" quietly ready in the wings.

You have to access the entity internals of Customer from time to time. Rather than clutter Customer with lots of "entity-ness" members, DevForce wraps them in a single helper object, the EntityAspect. The EntityAspect property is the place to go for "entity-ness" - the place to go for access to the inner entity nature of a Customer.

What's in EntityAspect

You'll most often use EntityAspect to determine the state of the entity: is it Added, has it been changed, is it null or pending?  You'll also use EntityAspect to work directly with validation errors or to access entity metadata.  In general, though, you don't often need to work with the EntityAspect, as DevForce will handle the entity for you as you query, modify and save your entities.

Learn the state of the entity

Member Purpose
EntityKeyThe value that uniquely identifies this entity.
EntityStateThe state of the entity - whether unchanged, added, modified, deleted or detached.
HasChangesIf changes are pending for this entity.
IsChangedIf changes are pending for this entity, i.e., EntityState is added, modified, or deleted.
IsNullEntityIf this entity is the special "null entity" ("nullo"). A reference navigation property returns such a null entity when it can't return the related entity (rather than return null and risk an exception).
IsPendingEntityIf this entity instance is a placeholder for a real entity of this type.  An entity will be pending when using asynchronous navigation and the retrieval from the database has not completed.
PendingEntityResolvedRaised when a pending entity has been retrieved from the database.
IsNullOrPendingEntityIf this entity is either the null entity or a pending entity. A quick way to tell if the entity is real and complete.

Change the state of the entity

Other than calling Delete, in most circumstances you won't need to use the methods described below, as DevForce will automatically handle the state of the entity as it's queried, modified, and saved.  

Member Purpose
DeleteMark this entity for deletion; the entity will be deleted from the database when saved.
RejectChangesUndo pending changes.
AcceptChangesCommit pending changes locally as if the entity were saved and now unchanged. Beware! Does not update the database. You do not need to call AcceptChanges during normal save processing, as DevForce will do it for you when a save completes successfully.
SetAddedConvert the state of the entity such that it appears to have been newly created. If saved, DevForce will try to insert it into the database.  When you create a new entity and add it to an EntityManager, it will automatically be marked as Added and you do not need to call this method.
SetModifiedConvert the state of the entity such that it appears to be a modified entity that came from the database. If saved, DevForce will try to find and update the corresponding database object.  When you modify an entity in cache it will automatically be marked as Modified by DevForce and you do not need to call this method.
GetValueGet the value of the named property. Could get the current value of the property or one of the other versions.  
SetValueSet the current value of the named property.
ForcePropertyChangedRaise the entity's PropertyChanged event on demand.

Learn about the entity's validity

Member Purpose
ValidationErrorsGet a modifiable collection of the currently detected validation errors for this entity.
VerifierEngineGet the VerifierEngine used by this entity's auto-validating property setters. The engine always comes from the entity's EntityManager. It is null if the entity is detached; for this reason property setters don't validate input automatically when the entity is detached.

Work with the entity's EntityManager

Member Purpose
EntityManagerGet the EntityManager to which the entity is attached. Null if detached.
AddToManagerAdd the entity to its associated EntityManager as a new entity.  An EntityManager is associated with an entity when the entity is created with the CreateEntity method. 
RemoveFromManagerDetach the entity from its EntityManager.  Removing an entity from its EntityManager is not the same thing as deleting an entity.  The entity will not be deleted from the back end data source with RemoveFromManager.
FindRelatedEntitiesFind cached entities related to this entity by a specific link.
GetRelatedEntitiesGet entities related to this entity by a specific link; depending on circumstances and parameters DevForce could retrieve them from the database (asynchronously in Silverlight).
EntityGroupGets the collection of entities to which this entity belongs. When this entity is attached to an EntityManager, the EntityGroup contains this entity and every other entity of its type in the cache. EntityGroup events reveal when entities in the group are added, removed, or changed.

Get Metadata about the entity

Member Purpose
EntityMetadataGet model metadata about this entity's type.
GetPropertyGet an EntityProperty metadata object by name with which you can inspect or modify property values generically.
GetDataPropertyGet a data meta-property by name which you can inspect or use to get and set values generically.
GetNavigationProperty Get navigation meta-property by name which you can inspect or use to add and remove related entities generically.

EntityAspect's own stuff

Member Purpose
EntityA back-reference to get the entity for which this is the EntityAspect.
WrapperA back-reference to the EntityWrapper for which this is the EntityAspect. For a DevForce generated entity the Entity and Wrapper properties return the same entity object because the entity inherits from both Entity and EntityWrapper. The distinction between Entity and EntityWrapper is relevant only for POCOs.
PropertyChanged Raised by EntityAspect when certain of its own properties change such as EntityState, EntityKey, and HasChanges. Not to be confused with PropertyChanged event for the entity.
Created by DevForce on February 16, 2011 19:56

This wiki is licensed under a Creative Commons 2.0 license. XWiki Enterprise 3.2 - Documentation. Copyright © 2015 IdeaBlade