Show:

EntityAspect Class

An EntityAspect instance is associated with every attached entity and is accessed via the entity's 'entityAspect' property.

The EntityAspect itself provides properties to determine and modify the EntityState of the entity and has methods that provide a variety of services including validation and change tracking.

An EntityAspect will almost never need to be constructed directly. You will usually get an EntityAspect by accessing an entities 'entityAspect' property. This property will be automatically attached when an entity is created via either a query, import or EntityManager.createEntity call.

// assume order is an order entity attached to an EntityManager.
var aspect = order.entityAspect;
var currentState = aspect.entityState;

Methods

acceptChanges

()

Returns the entity to an EntityState of 'Unchanged' by committing all changes made since the entity was last queried had 'acceptChanges' called on it.

Example:

    // assume order is an order entity attached to an EntityManager.
    order.entityAspect.acceptChanges();
    // The 'order' entity will now be in an 'Unchanged' state with any changes committed.

addValidationError

(
  • validationError
)

Adds a validation error.

Parameters:

clearValidationErrors

()

Removes all of the validation errors for a specified entity

getKey

(
  • [forceRefresh=false]
)
EntityKey

Returns the EntityKey for this Entity.

Parameters:

  • [forceRefresh=false] Boolean optional

    Forces the recalculation of the key. This should normally be unnecessary.

Returns:

EntityKey:

The EntityKey associated with this Entity.

Example:

    // assume order is an order entity attached to an EntityManager.
var entityKey = order.entityAspect.getKey();

getValidationErrors

(
  • [property]
)
Array of ValidationError

Returns the validation errors associated with either the entire entity or any specified property.

Parameters:

  • [property] DataProperty | NavigationProperty optional

    The property for which validation errors should be retrieved. If omitted, all of the validation errors for this entity will be returned.

Returns:

Array of ValidationError:

Example:

This method can return all of the errors for an Entity

// assume order is an order entity attached to an EntityManager.
var valErrors = order.entityAspect.getValidationErrors();

as well as those for just a specific property.

// assume order is an order entity attached to an EntityManager.
var orderDateErrors = order.entityAspect.getValidationErrors("OrderDate");

which can also be expressed as

// assume order is an order entity attached to an EntityManager.
var orderDateProperty = order.entityType.getProperty("OrderDate");
var orderDateErrors = order.entityAspect.getValidationErrors(orderDateProperty);

loadNavigationProperty

(
  • navigationProperty
  • [callback]
  • [errorCallback]
)
Promise async

Performs a query for the value of a specified NavigationProperty.

Parameters:

  • navigationProperty NavigationProperty | String

    The NavigationProperty or the name of the NavigationProperty to 'load'.

  • [callback] Function optional

    Function to call on success.

  • [errorCallback] Function optional

    Function to call on failure.

Returns:

Promise:
promiseData.results {Array of Entity}
promiseData.query {EntityQuery} The original query
promiseData.httpResponse {httpResponse} The HttpResponse returned from the server.

Example:

    emp.entityAspect.loadNavigationProperty("Orders")
    .then(function (data) {
        var orders = data.results;
    }).fail(function (exception) {
        // handle exception here;
    });

rejectChanges

()

Returns the entity to an EntityState of 'Unchanged' by rejecting all changes made to it since the entity was last queried had 'rejectChanges' called on it.

Example:

    // assume order is an order entity attached to an EntityManager.
    order.entityAspect.rejectChanges();
    // The 'order' entity will now be in an 'Unchanged' state with any changes rejected. 

removeValidationError

(
  • validationErrorOrKey
)

Removes a validation error.

Parameters:

  • validationErrorOrKey ValidationError | String

    Either a ValidationError or a ValidationError 'key' value

setDeleted

()

Sets the entity to an EntityState of 'Deleted'. This both marks the entity as being scheduled for deletion during the next 'Save' call but also removes the entity from all of its related entities.

Example:

// assume order is an order entity attached to an EntityManager.
order.entityAspect.setDeleted();
// The 'order' entity will now be in a 'Deleted' state and it will no longer have any 'related' entities. 

setDetached

()

Sets the entity to an EntityState of 'Detached'. This removes the entity from all of its related entities, but does NOT change the EntityState of any existing entities.

Example:

// assume order is an order entity attached to an EntityManager.
order.entityAspect.setDetached();
// The 'order' entity will now be in a 'Detached' state and it will no longer have any 'related' entities. 

setModified

()

Sets the entity to an EntityState of 'Modified'. This can also be achieved by changing the value of any property on an 'Unchanged' entity.

Example:

// assume order is an order entity attached to an EntityManager.
order.entityAspect.setModified();
// The 'order' entity will now be in a 'Modified' state. 

setUnchanged

()

Sets the entity to an EntityState of 'Unchanged'. This is also the equivalent of calling acceptChanges

Example:

    // assume order is an order entity attached to an EntityManager.
    order.entityAspect.setUnchanged();
    // The 'order' entity will now be in an 'Unchanged' state with any changes committed.

validateEntity

() Boolean

Performs validation on the entity, any errors encountered during the validation are available via the EntityAspect.getValidationErrors method. Validating an entity means executing all of the validators on both the entity itself as well as those on each of its properties.

Returns:

Boolean:

Whether the entity passed validation.

Example:

// assume order is an order entity attached to an EntityManager.
var isOk = order.entityAspect.validateEntity();
// isOk will be 'true' if there are no errors on the entity.
if (!isOk) {
    var errors = order.entityAspect.getValidationErrors();
}

validateProperty

(
  • property
  • [context]
)
Boolean

Performs validation on a specific property of this entity, any errors encountered during the validation are available via the EntityAspect.getValidationErrors method. Validating a property means executing all of the validators on the specified property. This call is also made automatically anytime a property of an entity is changed.

Parameters:

Returns:

Boolean:

Whether the entity passed validation.

Example:

// assume order is an order entity attached to an EntityManager.
var isOk = order.entityAspect.validateProperty("Order"); 

or

var orderDateProperty = order.entityType.getProperty("OrderDate");
var isOk = order.entityAspect.validateProperty(OrderDateProperty); 

Properties

entity

Entity

The Entity that this aspect is associated with.

readOnly

entityManager

EntityManager

The EntityManager that contains this entity.

readOnly

entityState

EntityState

The EntityState of this entity.

readOnly

hasValidationErrors

Boolean

Whether this entity has any validation errors.

readOnly

isBeingSaved

Boolean

Whether this entity is in the process of being saved.

readOnly

originalValues

Object

The 'original values' of this entity where they are different from the 'current values'. This is a map where the key is a property name and the value is the 'original value' of the property.

readOnly

Events

propertyChanged

An Event that fires whenever a value of one of this entity's properties change.

Event Payload:

  • entity Entity

    The entity whose property has changed.

  • property DataProperty

    The DataProperty that changed.

  • propertyName String

    The name of the property that changed. This value will be 'null' for operations that replace the entire entity. This includes queries, imports and saves that require a merge. The remaining parameters will not exist in this case either. This will actually be a "property path" for any properties of a complex type.

  • oldValue Object

    The old value of this property before the change.

  • newValue Object

    The new value of this property after the change.

  • parent Object

    The immediate parent object for the changed property. This will be different from the 'entity' for any complex type or nested complex type properties.

Example:

// assume order is an order entity attached to an EntityManager.
order.entityAspect.propertyChanged.subscribe(
    function (propertyChangedArgs) {
        // this code will be executed anytime a property value changes on the 'order' entity.
        var entity = propertyChangedArgs.entity; // Note: entity === order
        var propertyNameChanged = propertyChangedArgs.propertyName;
        var oldValue = propertyChangedArgs.oldValue;
        var newValue = propertyChangedArgs.newValue;
    });

validationErrorsChanged

An Event that fires whenever any of the validation errors on this entity change. Note that this might be the removal of an error when some data on the entity is fixed.

Event Payload:

  • entity Entity

    The entity on which the validation errors are being added or removed.

  • added Array of ValidationError

    An array containing any newly added ValidationErrors

  • removed Array of ValidationError

    An array containing any newly removed ValidationErrors. This is those errors that have been 'fixed'

Example:

// assume order is an order entity attached to an EntityManager.
order.entityAspect.validationErrorsChanged.subscribe(
    function (validationChangeArgs) {
        // this code will be executed anytime a property value changes on the 'order' entity.
        var entity == validationChangeArgs.entity; // Note: entity === order
        var errorsAdded = validationChangeArgs.added;
        var errorsCleared = validationChangeArgs.removed;
    });