Entity Layer - netTiers/netTiers GitHub Wiki

///An example object graph of a customer entity looks like this.
/// Customer Parent
///   Order 1:1
///    OrderDetails //1:M
///    ProductCollection //1:M
///   CustomerDemographics //1:M
///   CustomerDemographicsCollection_From_CustomerCustomerDemo //M:M

 /// <summary>
 /// List of possible state for an entity.
 /// </summary>
 public enum EntityState
 {
     /// <summary>
     /// Entity is read in from the database, unchanged
     /// </summary>
     Unchanged=0, 

     /// <summary>
     /// Entity is new and not yet in the database
     /// </summary>
     Added=1, 

     /// <summary>
     /// Entity has been modified
     /// </summary>
     Changed=2, 

     /// <summary>
     /// Entity has been deleted
     /// </summary>
     Deleted=3
 }

    ///STAGE 1: Added
    ///Create a new entity, whose EntityState is EntityState.Added               
    Customers customer = new Customers();
    customer.Address = "102 West Main Street";
    customer.City = "Atlantis";
    customer.Region = "Sea";
    customer.Phone = "230-555-0909";
    Response.Write(customer.EntityState); // EntityState.Added;
 
    ///Persist
    DataRepository.CustomersProvider.Save(customer);


    ///STAGE 2: Unchanged
    /// The EntityState has been set to EntityState.Unchanged
    ///Once we persist the entity, it will refresh the entity from the database
    ///If there is an identity column in your table that the entity represents
    /// then the new identity of the inserted value is returned as well.
    Response.Write(customer.CustomerID);
    Response.Write(customer.EntityState); // EntityState.Unchanged;

 
    ///STAGE 3: Changed
    /// By modifying a property the entity will automatically 
    /// change state to an EntityState.Changed state.
    customer.Region = "Under The Sea";
    Response.Write(customer.EntityState); // EntityState.Changed;
    DataRepository.CustomersProvider.Save(customer);
 

    ///STAGE 4: Deleted
    /// Two ways exist being in an EntityState.Deleted state for an Entity.
    /// MarkToDelete() method, or directly calling Delete in the repository.
    /// MarkToDelete() is mainly used when using the Save() method, 
    /// wanting to delete an entity which aggregated 
    /// and part of a Collection, a TList<Entity>.
    /// If you are working with a single entity as depicted, you would  
    /// just pass the entire entity into the DataRepository for Deletion.

    ///Using Delete Method Directly on the Entity
    DataRepository.CustomersProvider.Delete(customer);     

    ///Using Save Method in DataRepository with MarkToDelete()
    customer.MarkToDelete();
    Response.Write(customer.EntityState); // EntityState.Deleted;
    DataRepository.CustomersProvider.Save(customer);
 
    ///EntityState.Unchanged
    ///Say I want to delete all customers that have a city = Atlantis
    /// Whenever you get any entity items from the Database, once created 
    /// the state is immediately changed to EntityState.Unchanged
    TList<Customers> myList = DataRepository.CustomersProvider.GetByCity("Atlantis");

    for (int i = 0; i < myList.Count; i++)
    {
        Response.Write(myList[i].EntityState); // EntityState.Unchanged;
        myList.RemoveEntity(myList[i]);

        Response.Write(myList[i].EntityState); // EntityState.Deleted;
    }

     /// Now you've actually removed the entities from the list
     Response.Write(myList.Count); // Prints 0
 
     /// They are however moved to a DeletedItems collection
     Response.Write(myList.DeletedItems.Count); //Prints 1

     ///Will delete the items from the Database
     DataRepository.CustomersProvider.Save(myList);

     ///Or you can Iterate the list calling MarkToDelete();
     myList.ForEach(
        delegate(Customers c)
            {
                     c.MarkToDelete();
            }
        );

 

    ///Will persist all of the Deleted entities.
    DataRepository.CustomersProvider.Save(myList);

        /// <summary>
        ///    True if object has been <see cref="MarkToDelete"/>. ReadOnly.
        /// </summary>
        [BrowsableAttribute(false), XmlIgnoreAttribute()]
        public bool IsDeleted
        {
            get { return this.currentEntityState == EntityState.Deleted; }
        }


        /// <summary>
        ///        Indicates if the object has been modified from its original state.
        /// </summary>
        /// <remarks>True if object has been modified; otherwise False;</remarks>
        [BrowsableAttribute(false), XmlIgnoreAttribute()]
        public bool IsDirty
        {
            get
            {
                return this.currentEntityState != EntityState.Unchanged 
                            && this.currentEntityState != EntityState.Added;
            }
        }

        /// <summary>
        ///        Indicates if the object is new.
        /// </summary>
        /// <remarks>True if objectis new; otherwise False;</remarks>
        [BrowsableAttribute(false), XmlIgnoreAttribute()]
        public bool IsNew
        {
            get { return this.currentEntityState == EntityState.Added; }
            set { this.currentEntityState = EntityState.Added; }
        }


        /// <summary>
        ///        Indicates state of object
        /// </summary>
        /// <remarks>0=Unchanged, 1=Added, 2=Changed</remarks>
        [BrowsableAttribute(false), XmlIgnoreAttribute()]
        public virtual EntityState EntityState
        {
            get { return this.currentEntityState; }
            set { this.currentEntityState = value; }
        }


        /// <summary>
        /// Accepts the changes made to this object.
        /// </summary>
        /// <remarks>
        /// After calling this method <see cref="IsDirty"/> and <see cref="IsNew"/> are false.         
        /// <see cref="IsDeleted"/> flag remain unchanged as it is handled by the parent List.
        /// </remarks>
        public virtual void AcceptChanges()
        {
            this.bindingIsNew = false;
            this.currentEntityState = EntityState.Unchanged;
            OnPropertyChanged(string.Empty);
        }

        ///<summary>
        ///  Revert all changes and restore original values.
        ///  Currently not supported.
        ///</summary>
        /// <exception cref="NotSupportedException">This method throws exception.</exception>
        public abstract void CancelChanges();

        ///<summary>
        ///   Marks entity to be deleted.
        ///</summary>
        public virtual void MarkToDelete()
        {
            if (this.currentEntityState != EntityState.Added)
                this.currentEntityState = EntityState.Deleted;
        }


        ///<summary>
        ///   Remove the "isDeleted" mark from the entity.
        ///</summary>
        public virtual void RemoveDeleteMark()
        {
            if (this.currentEntityState != EntityState.Added)
            {
                this.currentEntityState = EntityState.Changed;
            }
        }

        /// <summary>
        /// Delegate providing method sig that will process validation rules.
        /// </summary>
        /// <remarks>
        /// <para>
        /// The method handler should set the Description attribute of the 
        /// <see cref="ValidationRuleArgs"/> parameter so that a meaningful
        /// error is returned.
        /// </para><para>
        /// If the data is valid, the method must return true.  If  invalid,
        /// the Description should be set the false should be returned.
        /// </para>
        /// </remarks>
        public delegate bool ValidationRuleHandler(object target, ValidationRuleArgs e);

protected override void AddValidationRules()
{
//Validation rules based on database schema.
ValidationRules.AddRule(Validation.CommonRules.NotNull,"CustomerID");

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("CustomerID",5));

ValidationRules.AddRule(Validation.CommonRules.NotNull,"CompanyName");

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("CompanyName",40));

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("ContactName",30));

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("ContactTitle",30));

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("Address",60));

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("City",15));

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("Region",15));

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("PostalCode",10));

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("Country",15));

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("Phone",24));

ValidationRules.AddRule(Validation.CommonRules.StringMaxLength,
    new Validation.CommonRules.MaxLengthRuleArgs("Fax",24));

}

/// <summary>
/// Adds custom validation rules to this object.
/// </summary>
protected override void AddValidationRules()
{
    base.AddValidationRules();

    //Add custom validation rules
    ValidationRules.AddRule(Validation.CommonRules.StringRequired, "CustomerID");

     ValidationRules.AddRule(Validation.CommonRules.GreaterThanOrEqualToValue<Decimal?>,  new Validation.CommonRules.CompareValueRuleArgs<Decimal?> ("Freight", 0));

     ValidationRules.AddRule(
        Validation.CommonRules.LessThanOrEqualToValue<Decimal?>, 
                new    Validation.CommonRules.CompareValueRuleArgs<Decimal?>( 
                    "Freight", 200));

 
    ValidationRules.AddRule(ValidateOrderDate, "OrderDate");
}

/// <summary>
/// Validates the order date.
/// </summary>
/// <param name="target">The target.</param>
/// <param name="e">The e.</param>
/// <returns></returns>
private bool ValidateOrderDate(object target, Validation.ValidationRuleArgs e)
{
    if ((this.OrderDate ?? DateTime.MinValue) > DateTime.Today)
    {
        e.Description = "The Order Date must not be in the future.";
        return false;
    }

    return true;
}

    Orders o = new Orders();
    o.OrderDate = new DateTime(2001, 8, 29);
    o.ShipAddress = "302 West Main Street";
    o.ShipCity = "Atlantis";
    o.ShipCountry = "Anywhere";
    o.ShipName = "Frank Sanders";
    o.ShipPostalCode = "55512";
    o.ShipRegion = "Under the Sea";

 
    o.Validate();
    ///Error property is a newline delimeted list of your broken rules.
    if (!o.IsValid)
        lblMessage.Text = o.Error;

 

   ///you can actually access all of the rules that were broken on the entity.
   foreach(BrokenRule rule in o.BrokenRulesList)
   {
     lblMessage.Text = string.Format("<li>{0} - {1}</li>", 
        rule.Property, rule.Description);
   }

   /// Suppose we have a partner vendor that 
   /// processes orders for us, and we need 
   /// to validate all of today's orders. 
   /// Get today's orders and validate them.  
   TList<Orders> ordersList = GetOrdersFromVender();
    if (!ordersList.IsValid)
    {
        StringBuilder sb = new StringBuilder();
        sb.Append("<li>");
        foreach(Orders o in ordersList.InvalidItems)
        {
            sb.Append(o.Error.Replace("\n", "<li>"));
        }
        lblMessage.Text = sb.ToString();

    }

    Orders order = new Orders();
    order.OrderDate = new DateTime(2001, 8, 29);
    order.ShipAddress = "302 West Main Street";
    order.ShipCity = "Atlantis";
    order.ShipCountry = "Anywhere";
    order.ShipName = "Frank Sanders";
    order.ShipPostalCode = "55512";
    order.ShipRegion = "Under the Sea";

    ///Index Of, Get's the location of the order in the list
    int index = ordersList.IndexOf(order);

    ///FindIndex
    ///Returns the integer value if 
    ///one of the criteria matches your predicate
    ordersList.FindIndex(
        delegate(Orders orders)
        {
            return orders.RequiredDate < DateTime.Today.AddDays(2);
        });
 

    ///Insert
    ///Useful if you want to insert an order in a specific location
    if (index < 0)
        ordersList.Insert(0, order);
 
    ///Add
    ///Appends an order to the list
    ordersList.Add(order);

 
    ///AddNew
    ///Appends a new order to the list
    ordersList.AddNew();
    ordersList[ordersList.Count - 1].OrderDate = DateTime.Today;

 
    ///RemoveEntity
    ///Removes the order from the list and places it in DeletedItems
    ordersList.RemoveEntity(order);
 
    ///RemoveAt
    ///Removes the first entry of the list
    ordersList.RemoveAt(0);
 
    ///RemoveAt
    ///Removes the entity where it exists
    ordersList.Remove(order);
 
    ///ListChanged
    ///Fires an event when the list has changed
    ordersList.ListChanged += 
      new System.ComponentModel.ListChangedEventHandler(ordersList_ListChanged);

 
    ///IsDeletedCount
    ///Returns the count of the DeletedItems Collection
    int deletedCount = ordersList.IsDeletedCount;
    Debug.Assert(deletedCount == ordersList.DeletedItems.Count);
 
    ///IsDirtyCount
    ///Returns the count of the items that have an 
    ///EntityState == EntityState.Changed
    int dirtyCount = ordersList.IsDirtyCount;
    Response.Write(string.Format("You have modified {0} entities.",dirtyCount));
 
    ///IsNewCount
    ///Returns the count of the items that have an 
    ///EntityState == EntityState.Added
    int newCount  = ordersList.IsNewCount;
    Response.Write(string.Format("You have added {0} entities.", newCount));
 
    ///FindAllBy
    ///Returns a new List of Entities that 
    /// match the FindAllByType
    ///FindAllByType.Contains, FindAllBy.StartsWith, FindAllByType.EndsWith
    TList<Orders> sList = ordersList.FindAllBy(TList<Orders>.FindAllByType.StartsWith, 
                        OrdersColumn.ShipCity, "Atl");
 
    TList<Orders> cList = ordersList.FindAllBy(TList<Orders>.FindAllByType.Contains,
                        OrdersColumn.ShipCity, "ant");

     TList<Orders> eList =ordersList.FindAllBy(TList<Orders>.FindAllByType.EndsWith,
                        OrdersColumn.ShipCity, "tis");

    ///FindAll
    ///Returns a new List of Entities that match using the Table Enum Columns
    TList<Orders> eqList = 
        ordersList.FindAll(OrdersColumn.ShipCity, "Atlantis");

 
    ///FindAll
    ///Returns a new List of Entities using a predicate
    TList<Orders> eqList2 = ordersList.FindAll(
        delegate(Orders o2){
            return 
                o2.OrderDetailsCollection.Count > 0 &&
                o2.OrderDate == DateTime.Today;
        });
 
    ///Exists
    ///Returns a bool if one of the criteria matches your predicate
    if (ordersList.Exists(
        delegate(Orders o3)
        {
            return
                o3.OrderDetailsCollection.Count > 0 &&
                o3.OrderDate == DateTime.Today;
        }))
    {
        Response.Write("There are orders today");
    }
 
    ///ToArray
    ///Creates an orders array from a list
    Orders[] orderArray = ordersList.ToArray();
 
    ///ToDataSet
    ///Creates a DataSet with children relationships from your TList.
    DataSet ds = ordersList.ToDataSet(true);
 
    /// Filter as a string
    /// Creates a view inside of your list using a case sensitive filter
    /// Great for cached items that you need to show
    /// different sets of entities based on criteria.
    ordersList.Filter = "ShipCity = 'Atlantis'";
    //ApplyFilter is automatically called on the set of the Filter property 
    //ordersList.ApplyFilter();
            ordersList.ForEach(
            delegate(Orders filteredOrder)
            {
                Debug.Assert(filteredOrder.ShipCity == "Atlantis");   
            });
 
    ///To Remove the filter, you simply call ResetFilter;
    ordersList.RemoveFilter();

    /// Filter using a Predicate delegate
    /// Great for needing to filter on items that 
    /// different sets of entities based on criteria.
    ordersList.ApplyFilter(GetValidAtlantisOrders);
    ordersList.ForEach(
    delegate(Orders filteredOrder)
    {
        Debug.Assert(filteredOrder.IsValid 
            && filteredOrder.ShipCity == "Atlantis");
    });

}//End Page_Load


    /// <summary>
    /// Gets the valid atlantis orders.
    /// </summary>
    /// <param name="o">The o.</param>
    /// <returns></returns>
    public bool GetValidAtlantisOrders(Orders o)
    {
        return (o.IsValid 
                && o.ShipCity == "Atlantis" 
                && o.OrderDetailsCollection.Count > 0
                && o.OrderDetailsCollection.IsValid);
    }
 
    void ordersList_ListChanged(object sender,                                            System.ComponentModel.ListChangedEventArgs e)
    {
        throw new Exception("The method or operation is not implemented.");
    }
 
  /// <summary>
  /// Gets the orders from vendor. Stub method, does nothing. 
  /// </summary>
  /// <returns></returns>
  public TList <Orders> GetOrdersFromVendor()
  {
     //Get Some orders from a vendor
       return new TList<Orders>();
  }   
}

entityFactoryType="Northwind.Entities.EntityFactory";
// OR 
entityFactoryType="Northwind.Entities.ComponentEntityFactory";