Tech Tip: Working with a ReadOnlyEntityList

direct

Level 100 
DevForce Express

View Archived Tech Tips

Working with a ReadOnlyEntityList

When the DevForce Object Mapper generates a relation property, that property returns a ReadOnlyEntityList<T>. For example, here�s the code generated by the Object Mapper for an Orders relation property of an Employee class:

C#:
public virtual ReadOnlyEntityList<Order> Orders { 
  get { 
    ReadOnlyEntityList<Order> result_; 
    if (GetInterceptor<ReadOnlyEntityList<Order>>( 
      "Orders", GetOrdersCore, out result_)) return result_; 
    return GetOrdersCore();
  }
}

private ReadOnlyEntityList<Order> GetOrdersCore() { 
  return this.GetManagedChildren <Order>(EntityRelations.Employee_Order);
} 

VB.NET: 
public Overridable _
    Readonly _
  Property Orders As ReadOnlyEntityList(Of Order)
    Get 
      Dim result_ As ReadOnlyEntityList(Of Order) = Nothing
      If GetInterceptor(Of ReadOnlyEntityList(Of Order))("Orders",
AddressOfGetOrdersCore, result_) Then Return result_
      Return GetOrdersCore()
    End Get
  End Property 

  Private Function GetOrdersCore() As ReadOnlyEntityList(Of Order)
    Return Me.GetManagedChildren(Of Order)(EntityRelations.Employee_Order)
End Function

The ReadOnlyEntityList<T> class wraps an IdeaBlade.Persistence.EntityList<T> -- the latter being the type of list you probably create most often for your own use. 
The wrapping prohibits the direct addition or removal of items from the list. In other words, you cannot execute the second of the following two statements:

C#:
Order newOrder = Order.Create(mPersMgr,mCurrentEmployee);
mCurrentEmployee.Orders.Add(newOrder); 

VB.NET:
Dim newOrder As Order = Order.Create(mPersMgr,mCurrentEmployee)
mCurrentEmployee.Orders.Add(newOrder)

Neither can you execute this statement:

C#:
mCurrentEmployee.Orders.Remove((Order)(mOrdersBS.Current));

VB.NET:
mCurrentEmployee.Orders.Remove(CType(mOrdersBS.Current, Order))

Note that the ReadOnlyEntityList wrapping does not prohibit changes to the details of a given Order included in such a list! That�s why you can change the property values of a given Order in the mCurrentEmployee.Orders list.
Inserting and Removing Items in a ReadOnlyEntityList
So, if you can�t add or remove items directly in a ReadOnlyEntityList, just how do you get a new Order into the mCurrentEmployee.Orders list, or remove an existing one from it? In the case of ReadOnlyEntityLists returned by generated relation properties, it is very easy, because it also so happens that, for these, DevForce automatically configures a ListManager for any list that is returned by a generated relation property. 
That happens in the GetManagedChildren<T> () call in the GetOrdersCore() shown above. The ListManager configured by GetManagedChildren() watches the PersistenceManager cache for Orders that should be included in the list � that is, for Orders that belong to the current Employee. When any such Order appears in the cache (whether by virtue of being newly added to the cache, or modified so that it suddenly belongs to the current Employee), the ListManager makes sure it gets included in the list. When any Order already in the list disappears from the cache, or is modified so that it no longer belongs to the current Employee, it is automatically removed from the list. 
So to add a new item to mCurrentEmployee.Orders, you simply add to the PersistenceManager�s cache an Order whose EmployeeId connects it to the current Employee:

C#:
Order newOrder = Order.Create(mPersMgr, mCurrentEmployee); 

VB.NET:
Dim newOrder As Order = Order.Create(mPersMgr, mCurrentEmployee)

or you change the EmployeeId of an existing Order so that it now points to the current Employee: 

C#:
someOrder.Employee = mCurrentEmployee; 

VB.NET:
someOrder.Employee = mCurrentEmployee

Similarly, to delete an existing Order, you do the following:

C#:
((Order)(mOrderBS.Current)).Delete(); 

VB.NET:
CType(mOrdersBS.Current, Order).Delete()

In all cases, the mCurrentEmployee.Orders ReadOnlyEntityList will get updated automatically and instantaneously to reflect the new state of the current Employee�s Orders collection. 
Converting a ReadOnlyEntityList<T> Into an EntityList<T>
On occasion you may want to convert your ReadOnlyEntityList<T> into a list to which you can directly add or remove entities. You can do that easily, as follows: 

C#:
EntityList<Order> orders =
  new EntityList<Order>(mCurrentEmployee.Orders); 

VB.NET:
Dim orders As EntityList(Of Order) = _
  New EntityList(Of Order)(mCurrentEmployee.Orders)

Now you can add and remove Orders freely and directly in your new orders collection. Note that your new list is an unmanaged one (unless and until you configure a ListManager for it), so no additional Order objects will get into it unless you expressly put them there.

Edited by IdeaBlade - 09-Jul-2007 at 12:25pm