Entities

Entity (entity type) is a class, whose instances are stored in the database. Entities correspond to a metadata object of the EleWise.ELMA.Model.Metadata.EntityMetadata class.

Each entity type has: 

  • General parameters: name (class name), display name, description, table name in database, etc. (see EntityMetadata)
  • List of entity properties. Each property has: a name (property name), display name, description, type, settings (restrictions, field name in the database and so on), see EntityPropertyMetadata class)

Entity types may also have: 

  • Filter – parameters used in search of entity instances (see EntityFilterMetadata class)
  • Actions – list of actions available for the entity (see EntityActionsMetadata class)

You can create entities using the entity editor. When declaring entity types, the following base entity interfaces are used: EleWise.ELMA.Model.Entities.IEntity and EleWise.ELMA.Model.Entities.IEntity<TId>

{

    /// <summary>
    /// Entity Base Interface
    /// </summary>
    [ExtensionPoint(false)]
    [Component]
    public interface IEntity : IIdentified
    {
        ///<summary>
        /// Returns entity value as string
        ///</summary>
        ///<param name="format">String format, properties are available through {$Property Name}</param>
        ///<returns>Entity value as string</returns>
        string ToString(string format);


        /// <summary>
        /// Get Property Value by its UID
        /// </summary>
        /// <param name="propertyUid">Property UID</param>
        /// <returns>Property value</returns>
        object GetPropertyValue(Guid propertyUid);

        /// <summary>
        /// Get Property Value by its UID
        /// </summary>
        /// <typeparam name="T">Property type</typeparam>
        /// <param name="propertyUid">Property UID</param>
        /// <returns>Property value</returns>
        T GetPropertyValue<T>(Guid propertyUid);

        /// <summary>
        /// Set Property Value by its UID
        /// </summary>
        /// <param name="propertyUid">Property UID</param>
        /// <param name="value">Property value</param>
        void SetPropertyValue(Guid propertyUid, object value);
        
        /// <summary>
        /// Get Property Settings (returns settings of this entity instance, or a copy of general settings)
        /// </summary>
        /// <param name="propertyUid">Property UID</param>
        TSettings GetPropertySettings<TSettings>(Guid propertyUid)
            where TSettings : TypeSettings;
        
        /// <summary>
        /// Get Property Settings (returns settings of this entity instance, or a copy of general settings)
        /// </summary>
        /// <param name="propertyUid">Property UID</param>
        TypeSettings GetPropertySettings(Guid propertyUid);

        /// <summary>
        /// Get Property Settings (returns settings of this entity instance, or a copy of general settings)
        /// </summary>
        /// <param name="propertyUid">Property UID</param>
        /// <param name="defaultSettings">Default settings</param>
        TypeSettings GetPropertySettings(Guid propertyUid, TypeSettings defaultSettings);

        /// <summary>
        /// Get property settings, saved for this object. If they are absent, then null is returned
        /// </summary>
        /// <param name="propertyUid">Property UID</param>
        TypeSettings LoadPropertyInstanceSettings(Guid propertyUid);

        /// <summary>
        /// Save Property Settings for this Object
        /// </summary>
        /// <param name="propertyUid">Property UID</param>
        /// <param name="settings">Settings</param>
        void SavePropertyInstanceSettings(Guid propertyUid, TypeSettings settings);

        /// <summary>
        /// Load Settings Storage of this object properties
        /// </summary>
        /// <param name="createIfNotExists">Whether to create a storage, if it does not exist</param>
        /// <param name="loadIfNotLoaded">Whether to load, if not loaded</param>
        /// <returns></returns>
        ITypeSettingsInstanceStore LoadSettingsInstanceStore(bool createIfNotExists, bool loadIfNotLoaded);

        /// <summary>
        /// Get entities, contained in this entity (e.g., table part items, entity settings)
        /// </summary>
        /// <returns></returns>
        IEnumerable<IEntity> GetContainedEntities();

        /// <summary>
        /// Get Root Entity (if it is a table part item, then the initial parent is returned)
        /// </summary>
        /// <returns></returns>
        IEntity GetRootEntity();

        /// <summary>
        /// Save entity
        /// </summary>
        void Save();

        /// <summary>
        /// Delete entity
        /// </summary>
        void Delete();

        /// <summary>
        /// Reload entity from database
        /// </summary>
        void Refresh();

        /// <summary>
        /// Entity has not been saved in the database
        /// </summary>
        /// <returns></returns>
        bool IsNew();

        /// <summary>
        /// If there are unsaved changes in the entity
        /// </summary>
        /// <returns>True, если есть</returns>
        bool IsDirty();

        /// <summary>
        /// Get UIDs of Changed Properties
        /// </summary>
        /// <returns> List of Property UIDs</returns>
        Guid[] GetDirtyPropertyUids();

    }

    /// <summary>
    /// Entity Interface with ID
    /// </summary>
    /// <typeparam name="IdT">ID Type (of the primary key)</typeparam>
    [DefaultManager(typeof(EntityManagerMaker))]
    public interface IEntity<IdT> : IEntity
    {

        /// <summary>
        /// ID (primary key)
        /// </summary>
        IdT Id { get; set; }

    }
}

You can also see the description of this interface in ELMA API help.

Entity types

ELMA has several types of entities. They differ from each other according to the extensibility type.

Entity

Standard entities are not extensible: you cannot extend them from external modules. This entity type corresponds to the EleWise.ELMA.Model.Metadata.EntityMetadata metadata object with Type property = EntityMetadataType.Entity.

It is recommended to use this entity type only if you want to forbid extending this entity from other modules. 

 Classes of these entities are generated according to metadata. Here is an example of automatically generated code:

/// <summary>
/// User
/// </summary>
[MetadataType(typeof(EntityMetadata))]
[EntityMetadataType(EntityMetadataType.Entity)]
public partial class User : Entity<long>
{
     
    /// <summary>
    /// Account name
    /// </summary>
    public string UserName { get; set; }
     
    /// <summary>
    /// Password
    /// </summary>
    public string Password { get; set; }
 
}

Entity Interface

Entities of this type can be extended (e.g. add new properties) using extension interfaces. This entity type corresponds to the EleWise.ELMA.Model.Metadata.EntityMetadata metadata object with the Type property = EntityMetadataType.Interface.

The interface is generated according to metadata. Here is an example of automatically generated code:

/// <summary>
/// User
/// </summary>
[MetadataType(typeof(EntityMetadata))]
[EntityMetadataType(EntityMetadataType.Interface)]
[Uid("04d5bcbf-4288-4d95-9745-1ebd0d690bb3")]
[ImplementationUid("18faf3ae-03c9-4e64-b02a-95dd63e54c4d")]
public partial interface IUser : IEntity<long>
{
     
    /// <summary>
    /// Account name
    /// </summary>
    string UserName { get; set; }
     
    /// <summary>
    /// Password
    /// </summary>
    string Password { get; set; }
 
}

Entity Extension Interface

Entity extension interface is an interface with additional properties of the extended entity. It corresponds to the EleWise.ELMA.Model.Metadata.EntityMetadata metadata object with the Type property = EntityMetadataType.InterfaceExtension.

The interface is generated according to metadata. Here is an example of automatically generated code:

/// <summary>
/// Extension of User interface for a ICQ module
/// </summary>
[MetadataType(typeof(EntityMetadata))]
[EntityMetadataType(EntityMetadataType.InterfaceExtension)]
[Uid("07ff5f61-f3d3-4a4b-82e8-4458520f0dcc")]
[BaseClass("04d5bcbf-4288-4d95-9745-1ebd0d690bb3")]
public partial interface IUser_ICQExt : IUser
{
     
    /// <summary>
    /// ICQ number
    /// </summary>
    string ICQ { get; set; }
 
}

Implementation of entity interface

Implementation of entity interface contains:

  • A class that implements the entity interface;
  • All interface extensions of the entity.

This entity type corresponds to the EleWise.ELMA.Model.Metadata.EntityMetadata metadata object with the Type property = EntityMetadataType.InterfaceImplementation.

This entity type cannot be created manually! It is generated automatically according to interfaces and extension interfaces when ELMA server is started.

Example of automatically generated code:

/// <summary>
/// User
/// </summary>
[MetadataType(typeof(EntityMetadata))]
[EntityMetadataType(EntityMetadataType.InterfaceImplementation)]
[Uid("18faf3ae-03c9-4e64-b02a-95dd63e54c4d")]
[ImplementationUid("04d5bcbf-4288-4d95-9745-1ebd0d690bb3")]
[Implement(typeof(IUser))]
[Implement(typeof(IUser_ICQExt))]
public partial class User : Entity<long>, IUser, IUser_ICQExt
{
     
    /// <summary>
    /// User name
    /// </summary>
    public string UserName { get; set; }
     
    /// <summary>
    /// Password
    /// </summary>
    public string Password { get; set; }
     
    /// <summary>
    /// ICQ number
    /// </summary>
    public string ICQ { get; set; }
 
}

Entity filters. Handling entity interfaces

When ELMA server is started, ELMA generates EleWise.ELMA.DynamicModel assembly with implementations of entity interfaces and entity extension interfaces.

To create an instance of entity interface/filter, we recommend using Create() method of EleWise.ELMA.Model.Services.InterfaceActivator class:

using EleWise.ELMA.Model.Services;
 
public class SomeClass
{
 
    public void SomeMethod()
    {
        var user = InterfaceActivator.Create<IUser>();
        user.UserName = "User 1";
        user.Save();
    }
 
}

If you need to get the type of entity interface implementation/filter, you can use the TypeOf method of the InterfaceActivator class:

using EleWise.ELMA.Model.Services;
 
public class SomeClass
{
 
    public void SomeMethod()
    {
        Type userType = InterfaceActivator.TypeOf<IUser>();
    }
 
}