A FetchPlan consists of a number of FetchGroups that are combined additively for each affected class. FetchGroups are used to identify the list of fields and their associated field recursion-depth, which will be retrieved together if the FetchGroup name is part of the actual FetchPlan configuration. The FetchPlan Browser dialog gives you the ability to configure fetch plans for your applications. The FetchPlan Browser dialog may be started via the OpenAccess -> FetchPlan Browser menu command and can be seen on the snapshot below:
The dialog contains the following options and settings:
- FetchPlan Name - a drop-down with all defined fetch plans. If you start this dialog for the first time the combobox will be empty. In order to define a new fetchplan name, you should press the Add New button, which is located right to the combobox.
- Add New button - pressing this button will open the NewFetchPlanForm dialog.
The dialog is pretty simple and offers you only two fields. You should enter a name for the fetchplan. Also you have the ability to copy the settings for the new fetchplan from any existing fetchplan.
After clicking the Ok button the new fetchplan name will be immediately added to the drop-down.
The FetchPlan Definition group contains the fetchplan definition, including setting various properties for the fetchplan such as the max depth etc. It also contains a listbox that can be filled in with the fetchgroups that would be part of the fetchplan configuration.
The following options are included in this group:
- Maximum Depth - the maximum depth helps you in controlling the amount of data retrieved from the database, in case of relationship fields, i.e., MaxDepth is the depth of references (fields of relationship types) to instantiate, starting with the root instances. You can specify the maximum depth for the fetchplan here, and if the selected persistent type contains relationship fields, you can traverse the object graph in the tree view up to the level specified. The default value for this property is 3.
- Maximum Objects Fetched - sets the number of objects that can be retrieved in one fetch operation. If nothing is specified (as shown in the image above) this means that the Limit is set to "0" (its default value) and in this case, there is no restriction on the number of objects that can be fetched together.
- FetchGroups Used - displays the fetchgroups that are part of the fetchplan configuration. You can add and/or remove fetchgroups from this box by clicking the Add/Remove button. This will open up the Add/Remove FetchGroup dialog shown on the image below:
Fields Fetched Together
This pane contains the tree view of all the fields for a specific persistent type. The view that is displayed depends on the fetchplan definition, which is specified in the above pane.
The following options are available here:
- Persistent Type - this drop-down list contains a list of all the persistent classes in your project and in its referenced assemblies. The generated tree-view is based on the persistent type that is selected.
- TreeView - the generated tree view is based on the selected persistent type. The fields of the selected persistent type appear in different colors based on whether they are part of the fetchplan or not. The fields that are retrieved using the list of fetchgroup/s specified in the FetchGroups Used listbox are highlighted in blue in the tree view.
Similarly if you want to see the fields that will be retrieved for a particular fetchgroup, you need to select that fetchgroup from the Show Specific Group drop-down list. The fields retrieved for that particular fetchgroup are highlighted in red in the view. Fields that are not retrieved appear in black.
- Show Specific Group drop down - this drop-down list contains all the fetchgroups that are defined in your project. In order to see what will happen if you add/delete a specific fetchgroup from your plan, you can select that group here. The fields retrieved for this particular fetchgroup get highlighted in red in the tree view.
- Show All Fields - all the fields, excluding reference type fields, for the selected persistent type will be displayed in the tree view, when this is checked.
- Show References - only reference type fields for the selected persistent type will be displayed in the tree view, when this is checked.
- Hide Base Type Fields in DFG - this hides the base type fields in the default fetchgroup, i.e., only single reference type fields for the selected persistent type will be displayed in the tree view, when this is checked. For example, if there is a Product class with supplier, category, name and productNo as fields, only supplier and category nodes will appear in the tree view, if this option is checked.
- Expand Tree - clicking this button expands all the nodes in the tree view up to the MaxDepth specified in the FetchPlan Definition pane.
FetchPlan Generated Code
This contains the code that needs to be added to your application if you want to add the fetchplan as per settings specified in this dialog. The code that appears here is copiable - you can copy and paste this code into the appropriate place in your project file. Please note that the default values for any property will not appear in the code.
The image below shows you a sample generated code in the FetchPlan Generage Code pane.