Options
All
  • Public
  • Public/Protected
  • All
Menu

Class EntityAspect

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;

Hierarchy

  • EntityAspect

Index

Events

propertyChanged

A BreezeEvent that fires whenever a value of one of this entity's properties change.

eventargs

-

  • entity - The entity whose property has changed.
  • property - The DataProperty that changed.
  • propertyName - 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 - The old value of this property before the change.
  • newValue - The new value of this property after the change.
  • parent - The immediate parent object for the changed property. This will be a ComplexType instance as opposed to an Entity for any complex type or nested complex type properties.
 // 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

A BreezeEvent 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.

eventargs

-

  • entity - The entity on which the validation errors are being added or removed.
  • added - An array containing any newly added ValidationErrors
  • removed - An array containing any newly removed ValidationErrors. This is those errors that have been 'fixed'.
 // 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;
 });

Properties

Optional entity

entity: Entity

The Entity that this aspect is associated with. Read Only

Optional entityManager

entityManager: EntityManager

The EntityManager that contains this entity. Read Only

entityState

entityState: EntityState

The EntityState of this entity. Read Only

Optional extraMetadata

extraMetadata: any

Extra metadata about this entity such as the entity's etag. You may extend this object with your own metadata information. Breeze (de)serializes this object when importing/exporting the entity.

hasTempKey

hasTempKey: boolean

Whether this entity has a temporary EntityKey.

hasValidationErrors

hasValidationErrors: boolean

Whether this entity has any validation errors. Read Only

isBeingSaved

isBeingSaved: boolean

Whether this entity is in the process of being saved. Read Only

originalValues

originalValues: __type

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.

Optional wasLoaded

wasLoaded: boolean

Whether this entity was created by being loaded from the database

Methods

acceptChanges

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

     // 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.

    Returns void

addValidationError

clearValidationErrors

  • clearValidationErrors(): void
  • Removes all of the validation errors for a specified entity

    Returns void

getKey

  • Returns the EntityKey for this Entity.

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

    Parameters

    • Default value forceRefresh: boolean = false

      (boolean=false) Forces the recalculation of the key. This should normally be unnecessary.

    Returns EntityKey

    The EntityKey associated with this Entity.

getParentKey

  • Returns an EntityKey for the entity pointed to by the specified scalar NavigationProperty. This only returns an EntityKey if the current entity is a 'child' entity along the specified NavigationProperty. i.e. has a single parent.

    Parameters

    Returns EntityKey

    Either a parent EntityKey if this is a 'child' entity or null;

getPropertyValue

getValidationErrors

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

    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);

    Returns ValidationError[]

    A array of validation errors.

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

    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);

    Parameters

    • property: string

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

    Returns ValidationError[]

    A array of validation errors.

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

    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);

    Parameters

    • property: EntityProperty

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

    Returns ValidationError[]

    A array of validation errors.

isNavigationPropertyLoaded

  • isNavigationPropertyLoaded(navigationProperty: string): boolean
  • isNavigationPropertyLoaded(navigationProperty: NavigationProperty): boolean
  • Determines whether a navigationProperty on this entity has already been loaded.

    A navigation property is considered loaded when any of the following three conditions applies:

    1. It was fetched from the backend server.
      This can be the result of an expand query or a call to the EntityAspect.loadNavigationProperty method.
      Note that even if the fetch returns nothing the property is still marked as loaded in this case.
    2. The property is scalar and has been set to a nonnull value.
    3. The EntityAspect.markNavigationPropertyAsLoaded was called.
    var wasLoaded = emp.entityAspect.isNavigationPropertyLoaded("Orders");

    Parameters

    • navigationProperty: string

      The NavigationProperty or name of NavigationProperty to 'load'.

    Returns boolean

  • Determines whether a navigationProperty on this entity has already been loaded.

    A navigation property is considered loaded when any of the following three conditions applies:

    1. It was fetched from the backend server.
      This can be the result of an expand query or a call to the EntityAspect.loadNavigationProperty method.
      Note that even if the fetch returns nothing the property is still marked as loaded in this case.
    2. The property is scalar and has been set to a nonnull value.
    3. The EntityAspect.markNavigationPropertyAsLoaded was called.
    var wasLoaded = emp.entityAspect.isNavigationPropertyLoaded("Orders");

    Parameters

    • navigationProperty: NavigationProperty

      The NavigationProperty or name of NavigationProperty to 'load'.

    Returns boolean

loadNavigationProperty

  • Performs a query for the value of a specified NavigationProperty. Async

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

    Parameters

    • navigationProperty: string

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

    • Optional callback: QuerySuccessCallback

      Function to call on success.

    • Optional errorCallback: QueryErrorCallback

      Function to call on failure.

    Returns Promise<QueryResult>

    Promise with shape

    • results {Array of Entity}
    • query {EntityQuery} The original query
    • httpResponse {httpResponse} The HttpResponse returned from the server.
  • Performs a query for the value of a specified NavigationProperty. Async

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

    Parameters

    Returns Promise<QueryResult>

    Promise with shape

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

markNavigationPropertyAsLoaded

  • Marks this navigationProperty on this entity as already having been loaded.

     emp.entityAspect.markNavigationPropertyAsLoaded("Orders");

    Parameters

    • navigationProperty: NavigationProperty | string

      The NavigationProperty or name of NavigationProperty to 'load'.

    Returns void

rejectChanges

  • rejectChanges(): void
  • 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.

     // 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.

    Returns void

removeValidationError

  • removeValidationError(validationError: ValidationError): void
  • removeValidationError(validationKey: string): void

setAdded

  • setAdded(): boolean
  • Sets the entity to an EntityState of 'Added'. This is NOT the equivalent of calling EntityManager.addEntity because no key generation will occur for autogenerated keys as a result of this operation. As a result this operation can be problematic unless you are certain that the entity being marked 'Added' does not already exist in the database and does not have an autogenerated key. The same operation can be performed by calling EntityAspect.setEntityState.

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

    Returns boolean

setDeleted

  • setDeleted(): any
  • 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. The same operation can be performed by calling EntityAspect.setEntityState.

     // 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.

    Returns any

setDetached

  • setDetached(): any
  • 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. The same operation can be performed by calling EntityAspect.setEntityState.

     // 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.

    Returns any

setEntityState

  • Sets the entity to the specified EntityState. See also 'setUnchanged', 'setModified', 'setDetached', etc.

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

    Parameters

    Returns boolean

setModified

  • setModified(): any
  • Sets the entity to an EntityState of 'Modified'. This can also be achieved by changing the value of any property on an 'Unchanged' entity. The same operation can be performed by calling EntityAspect.setEntityState.

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

    Returns any

setUnchanged

  • setUnchanged(): any
  • Sets the entity to an EntityState of 'Unchanged'. This is also the equivalent of calling EntityAspect.acceptChanges. The same operation can be performed by calling EntityAspect.setEntityState.

     // 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.

    Returns any

validateEntity

  • 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.

     // 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();
     }

    Returns boolean

    Whether the entity passed validation.

validateProperty

  • validateProperty(property: string, context?: any): boolean
  • validateProperty(property: DataProperty, context?: any): boolean
  • validateProperty(property: NavigationProperty, context?: any): 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.

     // 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);

    Parameters

    • property: string

      The DataProperty or NavigationProperty to validate or a string with the name of the property or a property path with the path to a property of a complex object.

    • Optional context: any

      A context object used to pass additional information to each Validator.

    Returns boolean

    Whether the entity passed validation.

  • 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.

     // 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);

    Parameters

    • property: DataProperty

      The DataProperty or NavigationProperty to validate or a string with the name of the property or a property path with the path to a property of a complex object.

    • Optional context: any

      A context object used to pass additional information to each Validator.

    Returns boolean

    Whether the entity passed validation.

  • 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.

     // 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);

    Parameters

    • property: NavigationProperty

      The DataProperty or NavigationProperty to validate or a string with the name of the property or a property path with the path to a property of a complex object.

    • Optional context: any

      A context object used to pass additional information to each Validator.

    Returns boolean

    Whether the entity passed validation.

Static getPropertyPathValue

  • getPropertyPathValue(obj: Entity, propertyPath: string | string[]): any
  • Returns the value of a specified 'property path' for a specified entity.

    The propertyPath can be either a string delimited with '.' or a string array.

    Parameters

    • obj: Entity
    • propertyPath: string | string[]

    Returns any

Generated using TypeDoc