Telerik OpenAccess Classic

Telerik OpenAccess ORM Send comments on this topic.
How to: Use FetchPlans for Optimized Database Server Access
See Also
Programmer's Guide > OpenAccess ORM Classic (Old API) > Programming With OpenAccess > FetchPlans and FetchGroups > How to: Use FetchPlans for Optimized Database Server Access

Glossary Item Box

This documentation article is a legacy resource describing the functionality of the deprecated OpenAccess Classic only. The contemporary documentation of Telerik OpenAccess ORM is available here.

FetchPlans are very powerful feature of Telerik OpenAccess ORM. When interacting with a persistent object, they provide you with the possibility to fine-tune the fetching of the fields you are using from the database and not the whole object. This is resulting in better performance and less load on the database server.

A FetchPlan represents collection of strings. These strings are the names of the FetchGroups which includes the fetched fields for each of the persistent classes. A field can be a part of a given fetch group when marked with the FetchField attribute with the name of the desired FetchGroup given as a parameter. There can be more than one FetchField attributes assigned to a field so it can be fetched in different groups depending on your project's business logic.

C# Copy Code
[FetchField("myGroup")]  
private Employee employee;

There are different ways to define fetch groups and organize the fetch plan: defining attributes by hand, storing information in the app.config, etc. In this article however the focus is on the easier and more intuitive visual support, provided by Telerik OpenAccess ORM wizards inside Microsoft Visual Studio.

To define a fetch group you should start the Forward Mapping Wizard, choose the class that you want to define a group for, and select the FetchGroup tab. It works for reverse mapped persistent models too.

Next, click the Add/Remove button to define a new FetchGroup. The Add/Remove FetchGroup Dialog appears. Again, click the Add button and specify a name for the FetchGroup.

Click OK to close the dialog. Since you have defined a fetch group for the chosen class, a column of check boxes is displayed next to the class fields. You need to check the checkboxes next to the fields you want fetched when a plan containing your fetch group is executed.

If a given field is of reference type the following fetch group feature can be used - you can define the next fetch group that is executed when accessing the reference field/property.

That means that not all the fields from the referenced object will be fetched but only those that are specified in the fetch group of the referenced object named. To get a closer idea of this, here is a simple example to display the FetchGroup functionality. There is a fetch group defined for the Product class of the Northwind data-model called "MyFetchGroup".

The Category reference field is among the selected for fetching and a Next Fetch Group also called MyFetchGroup is defined for it:

This fetch group is also defined for the Category class and the Products reference field is selected.

To get advantage of the defined fetch groups, you need to add them to your fetch plan by calling the FetchPlan.Add method of the object scope. You can add the names of the fetch groups for the different classes, or only the name of the fetch group for the "root" class if your groups are logically connected in a hierarchy (using the Next Fetch Group feature) as it is done in the previous example. Before you add any fetch groups though, you first need to clear the scope's current fetch plan. That is done by calling the scope's FetchPlan.Clear method. The fetch plan by default contains on the "Default" fetch group. The "Default" fetch group tells the object scope to retrieve all the value fields of an object and only the ID's of the reference ones.

Here is the complete sample code:

C# Copy Code
IObjectScope objectScope = NorthwindScopeProvider.ObjectScope();
objectScope.FetchPlan.Add( "MyFetchGroup" );
var result = from p
in objectScope.Extent<Product>()
               select p;
foreach ( Product product in result.ToList() )
{
   Console.WriteLine( product.Category.CategoryName );
}

When you require access to only some of the properties of a persistent object that is few levels deeper in the object graph, using the appropriate fetch plan can be a considerable performance booster.

It is not a good practice to clear the current fetch plan before adding the new fetch groups. This is done by the scope.FetchPlan.Clear() method. The fetch plan by default contains only the "Default" fetch group. The "Default" fetch group tells the object scope to retrieve all the value fields of an object and only the ID’s of the reference ones.

In case you need to clear the current fetch plan by invoking the FetchPlan.Clear() method, the Default fetch group will be also removed. In this case you should explicitly set which fields from the reference object should be obtained from the new fetch group. Consider the Product and Category classes which are mapped to the corresponding Northwind table. A product object has reference to a category. If you want to execute the following statement:

C# Copy Code
scope.FetchPlan.Clear();
scope.FetchPlan.Add("ProductFetchGroup");
var result = scope.Extent<Product>();
foreach (Product product in result)
{
               
string categoryName = product.Category != null ? product.Category.CategoryName : string.Empty;
               Console.WriteLine(
"{0}\t{1}\t{2}", product.ProductID, categoryName, product.ProductName);
}

the ProductFetchGroup should include the Product.productId, Product.productName and Category.categoryName fields, otherwise additional calls to the database will be made.

See Also