Using DeepLoad

The DeepLoad and DeepSave methods in NetTiers retrieve and make changes to all of the object’s associated with an instantiated object.   For example, the Employees object from Northwind includes an OrdersCollection, EmployeeTerritoriesCollection, and a TerritoriesCollection_From_EmployeeTerritories generated from a Many-Many relationship. The DeepLoad method calls DataRepository.OrdersProivider.GetByEmployeeID, DataRepository.EmployeeTerritoriesProvider.GetByEmployeeID, and DataRepository.TerritoriesProvider.GetByEmployeeIDFromEmployeeTerritories methods to populate the collection classes found in an Employees object.

There are 3 overloads to DeepLoad

• DeepLoad(Employees entity)
• DeepLoad(Employees entity, bool deep)
• DeepLoad(Employees entity, bool deep Type, DeepLoadType deepLoad,Type [] childTypes)

DeepLoad(entity) and DeepLoad(entity, false) have the same behavior. These methods will load all of the collections for the entity object one level deep.   DeepLoad(employee) will populate OrdersCollection, EmployeeTerritories, and TerritoriesCollection_From_EmployeeTerritories  will be populated. However, EmployeesCollection_From_EmployeeTerritories property of EmployeeTerritories will not be populated.

Calling DeepLoad(entity, true) will recursively call deep load for all of the collection properties in the object. This means that the entire object graph will be loaded. If you’re object model has a lot of relationships, you will be loading a lot of objects into memory. Use this overload with caution.

DeepLoad(Employees entity, bool deep, DeepLoadType deepLoadtype, Type[] childTypes) overload allows you to specifiy which collections you want to load.  The DeepLoadType enumeration has three values

• Ignore
• IncludeChildren
• ExcludeChildren. 

Choosing Ignore will cause the method to exit without doing anything. IncludeChildren and ExcludeChildren change the childTypes array to either an inclusionary list or exclusionary list. When you use DeepLoadType.IncludeChildren, the types in the the childTypes array will be loaded. With DeepLoadType.ExcludeChildren, the types in the childTypes array will not be loaded.

Let’s look at an example. This is an example console application that is attached to this post. (The deep flag for Many-Many relations is commented out when the code is generated, you need to un-comment them on to follow this example). Let’s load an employee object and Run Deep Load.

Employees emp = DataRepository.EmployeesProvider.GetByEmployeeID(9);

//this loads all child collections one level deep

//it is the same call (litrally) as DeepLoad(emp,false);

DataRepository.EmployeesProvider.DeepLoad(emp);

Console.WriteLine("Employee Orders = " + emp.OrdersCollection.Count.ToString());

Console.WriteLine("Employee Territories = " + emp.TerritoriesCollection_From_EmployeeTerritories.Count.ToString());

The Results from this call is that the OrdersCollection, TerritoriesCollection_From_EmployeeTerritories, EmployeeTerritoriesCollection are populated. The EmployeeTerritoriesCollection contains only the elements from the many-many table, EmployeeId and TerritoryId. While the TerritoriesCollection_From_EmployeeTerritories collection has the entire Territory object fore each of Territory assocatiated.

The output of this is

Employee Orders = 43

Employee Territories Collection = 7

Territories = 7

Let’s Look at the first Order in the OrdersCollection:

Orders order = emp.OrdersCollection[0];

Console.WriteLine("Order Details Count = " + order.OrderDetailsCollection.Count.ToString());

Since we didn’t set the deep flag to true, the OrdersDetailCollection count will be 0.

If we change the DeepLoad call to: DataRepository.EmployeesProvider.DeepLoad(emp, true);

every collection property for every object associated with Employee will be populated. Now,  the order.OrderDetailsCollection.Count will equal 4.

If you have a highly connected object structure, you can see how you can get into trouble quickly with the deep flag turned on. By loading all of those child collections in memory, your going to run into problems quickly.   That is why there is a third overload that allows you to specify which child types you want to load. Suppose you do need the OrdersCollection, but no other collections. You can use this call:

DataRepository.EmployeesProvider.DeepLoad(emp,true,DeepLoadType.IncludeChildren, new Type[]{typeof(OrdersCollection)});

It is important to note only OrdersCollection will be loaded, none of the child types within OrdersCollection will be loaded even though you set deep to true. You can continue along the object graph if you want by adding them to the childType array. If you want to load Orders and OrderDetails:

DataRepository.EmployeesProvider.DeepLoad(emp,true,DeepLoadType.IncludeChildren, new Type[] {typeof(OrdersCollection),typeof(OrderDetailsCollection)});

This call will load all of the OrdersCollection and all of the OrderDetails for every Order in the collection.

The opposite effect will occur if you use DeepLoadType.ExcludeChildren. 

DataRepository.EmployeesProvider.DeepLoad(emp,true,

DeepLoadType.ExcludeChildren, new Type[]{typeof(OrdersCollection)});

Will load the TerritoriesCollection_From_EmployeeTerritories, EmployeeTerritoriesCollection, but not the OrdersCollection.

I have not yet experimented with DeepSave, however I expect it to have the same behavior. If I find any differences, I will write up another article detailing any difference between DeepLoad and DeepSave