Concepts - Templates and Template groups

Included template files

LLBLGen Pro Framework ships with two Template groups of template files: "SelfServicing" and "Adapter". All templates of these groups are either contained in one template directory per driver (the driver specific templates, e.g. SqlServerSpecific) or the SharedTemplates folder, all located in the Templates folder in the LLBLGen Pro installation folder. SelfServicing and Adapter templates are stored in the same folder since some template files are shared among the two template groups. Each template group generates code which is different in style, functionality and paradigm from the other. Which template group to use is selected by the template group combo box on the first tab in the generator configuration window. Per template group you can have different scenario's, like 'General' and 'Two classes', which can be selected by picking the right preset in the third tab of the generator configuration window.

Below are short descriptions of the template groups' typical aspects, so you can better decide which template group to choose for your project.

SelfServicing

SelfServicing is the template group which was initially shipped with LLBLGen Pro and it's named SelfServicing because the entity, typed list and typed view classes contain all the logic and data to help themselves interacting with the persistent storage. This means that there is no extra object instance required, like a broker, to fetch entity data from the persistent storage or save data into the persistent storage. This can be very handy if you don't want to be bothered with the hassle of extra objects to fetch data related to an instance you hold or you want to traverse relations like myCustomer.Orders[0].Products[0].ShipperName in a class that potentially doesn't have database access like a gui. This traversal fetches data on the fly with lazy loading (load on demand) using logic that is controlled by code inside the entities itself: the entities instantiate the required DAO objects to retrieve the data and to instantiate the related objects. This is transparent for the developer and is easy to use.

The presence of persistence logic inside the entity, typed list and typed view classes can in, some situations, be a disadvantage of the SelfServicing code. For example if you as a project manager do not want to have your GUI developers call myEntity.Save(), you have to add extra code to the generated classes to prevent any save action from happening and even then, the logic is exposed to the developer. The template group called Adapter solves this. In short, SelfServicing is about the paradigm that object persistence is something about the objects being persisted, so an entity object should know how to persist itself. SelfServicing's code is generated for one database type (e.g. Sqlserver / Oracle).

An example piece of SelfServicing code is the following. This code reads an Order entity from the persistent storage, alters its EmployeeID field and saves it back.

SelfServicing comes in two variants: General and TwoClasses. The General variant, formulated in the General preset generates one class per entity. The TwoClasses variant generates two classes per entity: entityNameEntityBase, which contains the generated plumbing code and entityNameEntity, which derives from that class and which is for your business logic.

Adapter

Adapter is called Adapter because all persistence actions are performed by an 'Adapter' object, similar to the DataAdapter in .NET. Adapter's entities don't have persistence information, nor do they contain persistence action logic. Because it uses adapter objects, called DataAccessAdapter, you can choose the adapter you want to use to persist the entity object when you actually need it. Adapter uses a single point where the persistence data is stored, hidden away from the developer. The DataAccessAdapter itself has access to the persistence information in code, which is at runtime constructed in a cache with persistence info objects.

Adapter's generated code is not 'selfservicing', which means that you have to pull data from the database up front or consult a DataAccessAdapter object to read data again later because there is no logic inside the entity objects to control persistence actions like reading related entities from the database through lazy loading. This can be perfect for projects where it is mandatory that every database action is started and controlled by a selected piece of code, for example a selected set of Business Logic classes in a middle tier. It can however be a bit cumbersome for projects where selfservicing aspects of an entity should be utilized. It is therefore important to understand how you look at what persistence of objects means to your code.

Adapter is about the paradigm that persistence is a 'service' provided by an object or group of objects and which is provided by logic outside the objects affected by the service. As an illustration of this, the same functionality provided as an example with the SelfServicing explanation above is written using the Adapter logic:
Adapter requires more lines of code when fetching data, however it also gives more control over the steps taken, for example it allows you to specify whether the connection should stay open so actions taken after the current action will be faster, because an open connection is already available (the connection is closed otherwise after each action), or which connection string to use for this particular action. It is therefore key to first determine what kind of paradigm you want to use before generating code.

Adapter also comes in two variants: General and TwoClasses. The General variant, formulated in the General preset generates one class per entity. The TwoClasses variant generates two classes per entity: entityNameEntity, which contains the generated plumbing code and MyentityNameEntity, which derives from that class and which is for your business logic. The TwoClasses variant is this add-on, but now included in the standard templates shipped with LLBLGen Pro.

All template groups are fully supported and have the same basic persistence options, however one template group can have more sophisticated persistence options than the other while the other template group might have more functionality on board for ease of use.

When to use which template group?
Both template groups offer a wide set of functionality, but do that in a different way. This difference makes it important for you to know when to pick which template group for a given project. Below are two short lists which sum up some reasons for choosing each template group and which will help you with the decision which template group to take.

When to use SelfServicing

• When the project targets a single database type.
• When you are not using a distributed scenario like remoting or webservices.
• When you need navigation through your object model in a databinding scenario and you want to load the data using lazy loading.
• When you don't need to extend the framework.
• When you like to have the persistence logic into the entity classes.
• When you do not require fine grained database access control, like targeting per call another database.

When to use Adapter

• When the project targets multiple database types or would be able to do that in the future.
• When you are using a distributed scenario like remoting or webservices.
• When you don't need lazy loading scenarios in relation traversals. You can still navigate relations but you have to fetch the data up-front.
• When you need to extend the framework with derived classes.
• When you like to see persistence logic as a 'service', which is offered by an external object (broker, adapter).
• When you require fine grained database access control.
• When you want to convert Entities to XML and back and performance and XML size are important.