5.1 Cookbooks for framework adaptation

5.1 Cookbooks for framework adaptation

Framework-centered development is an incremental, iterative process. Starting from a given framework, classes are added and changed until the desired application emerges. Applications may be seen as living and growing organisms that constantly gain functionality during the development process. Framework documentation in the form of cookbook recipes don't need to cover all aspects in detail. An appropriate cookbook should, on one hand, cover the overall picture the structure, the important collaborations, the intention, and overall functionality of its parts and on the other hand include a solid discussion of tricky and complex mechanisms of the framework.

UML-F class and object diagrams represent an appropriate mechanism to describe the static structure of a framework. UML-F sequence diagrams describe interaction patterns. Many of the UML-F tags make variation points explicit and simultaneously give hints about how to adapt those variation points. Experience has proven that marking parts of the framework with UML-F tags provides useful assistance to the application developer for locating, understanding, and adapting variation points. However, diagrams are not enough. Informal text should be used to explain the rationale behind the architecture, as well as domain-specific constraints such as which variation points are optional and which must be adapted. Thus, cookbook recipes usually intertwine diagrams with informal textual descriptions.

In order to provide adequate assistance in adapting a framework, a cookbook should provide the following (see Figure 5.1).

• A guided tour through the architecture: the guided tour is particularly useful for an understanding of the framework. It allows the application developer to gain efficient access to the key elements of the framework. The guided tour offers a path through the framework that incrementally allows a developer to understand the framework and its internal architecture.

• A collection of recipes: the recipes describe particular adaptations of the framework. Variation points are described in one or more recipes. A recipe may provide pointers to related recipes, guiding the order in which the adaptations should be performed.

• Domain-specific UML-F tags: the cookbook might introduce domain-specific UML-F tags that allow a concise description of certain aspects of the framework. These tags are used by the recipes (and therefore are not shown on Figures 5.1).

Figure 5.1. Cookbook aspects

Recipes can be classified into three categories. (The case study in Chapter 6 illustrates these recipe types.)

• Basic recipes: these focus on a particular variation point, explaining how to adapt it.

• Recipes for choosing among alternatives: these discuss issues that help to choose between alternative adaptations. Such recipes often refer to basic recipes for the actual adaptation.

• Composite recipes: these provide guidance though complex tasks, partitioning them into subtasks. Composite recipes refer to a number of other recipes and suggest a particular order. Such recipes are comparable with process patterns as proposed by Ambler (1998) which form a vital part of Catalysis (D'Souza and Wills, 1998).

Cookbook recipes, with their inherent references to other recipes, lend themselves to presentation as hypertext. Recipes do not usually explain the internal design and implementation details of a framework, only the necessary information to guide the adaptation.

Table 5.1 proposes a recipe template. However, to match specific needs, additional sections may be provided in the recipe, or given ones may be omitted. 'Sample adaptations' and 'source code samples' might be such additional sections, beefed up by UML-F diagrams.

Table 5.1. Recipe template

Recipe 'Name: Short explanation of the recipe', typically beginning with "How to "
Intent	The motivation and the intent of the recipe
Classes	Which framework classes are involved and need to be understood? Which framework classes should be adapted? UML-F diagrams are useful here.
Related recipes	Which related recipes are involved, either as subrecipes or as alternatives?
Steps to apply	The sequence of steps that must be applied, e.g. Create a new subclass of A. Override method foo() in the newly created subclass, but call super() at the end.
Discussion	Discussion of alternatives including caveats, possible problems and alternative recipes.