Framework Design and Documentation
FWF Project P11350-TEC
September 1996 - August 1998
This project aims at the development of techniques and tools for designing
and documenting frameworks. The planned work continues the fruitful co-operation
of Prof. Mössenböck and Prof. Koskimies in the context of the
project "Class Management Techniques in the Oberon-2 Environment"
supported by the "Fonds zur Förderung der wissenschaftlichen Forschung"
and the Academy of Finland ([KM95a], [KM95b], [MK95], [KM95c], [KM95d]).
A central paradigm in the research will be the active document. This concept
is supported in a simple and elegant form by the Oberon environment which
will be used as an implementation platform, but the essential results will
be independent of the language and of the environment.
The research consists of several subgoals which are elaborated partly in
Active Pictures in Framework Documentation
Technical artifacts are often described by graphical plans (e.g., circuit
diagrams, architecture plans, etc.). This is also the case in software development
(SADT diagrams, OMT diagrams, snapshots of data structures, etc.). The problem
with such diagrams is that they tend to become quite complex and difficult
to read. When presented the full picture, it is often difficult to find
out in which order to read it. Often the picture shows information that
is not relevant at the same time (e.g., different layers, different subsystems).
When a person draws such a picture on paper, one can see how the drawing
evolves, but these steps are not visible any more in the final picture.
Therefore, our idea is to store a picture not as a whole but as a sequence
of drawing steps that can be played forwards and backwards like a film.
The user can then see how the drawing evolves. At every step, he can get
explanatory comments so that he can understand what goes on. He can even
explore different alternatives which lead to different pictures. We would
also like to include animation so that it should be possible, say, to show
how a data structure smoothly changes as a result of some algorithm.
It should be possible to include active pictures in texts and even in the
source code of programs so that they can be combined with code and documentation.
The reader of a program text would then be able to get graphic comments
and even to look at a film that shows dynamic aspects of the code.
The drawing facilities should not be restricted to a certain kind of diagrams
but should be general enough so that in principle any picture can be created.
We plan to implement the drawing facilities as an extension of an existing
graphics editor so that the implementation effort should be relatively low
and the user does not have to learn a completely new tool.
In the context of the proposed project we would like to find out how well
active pictures are suited to draw and read object-oriented design diagrams
(e.g., OMT [Rum91], RDD [WWW90], Booch [Boo91]). In particular we want to
apply them to frameworks and design patterns [GHJV95]. For this purpose
we plan to make the pictures reactive and explore different kinds of reaction
(e.g., hypermedia links, on demand information, automatic generation of
code skelettons, etc.). Another interesting aspect is to integrate active
pictures with the active texts that we already developed thus leading to
general active documents.
Expected result: A tool for producing active pictures, and techniques to
use active pictures for documenting frameworks.
Extensions of the OMT Notation for Specifying the Hot Spots of Frameworks
The OMT Notation [Rum91] has become a de facto standard for the graphical
documentation of object-oriented programs. This notation provides various
kinds of diagrams that show the static and dynamic behaviour of programs
so that one can express the components of a system and their interaction.
Object-oriented software, however, is usually not designed from scratch
but derived from some existing framework. The designer of such software
must understand the framework and clearly see where it is possible to hook
in application-specific code. These hook points are often called the hot
spots of the framework since they are the places where new functionality
can be brought in. The OMT notation (or any other notation) does not convey
this information sufficiently well. We would therefore like to explore new
ways to make the hot spots explicit. This could be done by an extension
of the notation or by making use of active pictures so that the relevant
hot spots are shown and explained on demand.
Information that could be provided is among others: What classes have to
be extended in order to get some desired effect? What methods have to be
redefined for that? What are the pre and post conditions of these methods?
Using active pictures it is also possible to show how a framework works.
Several scenarios can be displayed as a set of films that can be inspected
to see in which context the redefined methods are invoked.
It is also interesting to develop tools that support the drawing of a specific
kind of diagrams, for example commands that help to draw diagram components
and to keep them consistent. These tools are of course notation-specific
(e.g. OMT tools, RDD tools) and could be seen as a layer above the general
active pictures facilities.
Expected result: A tool-supported notation for specifying and browsing
the hot spots of a framework.
Active Cookbooks for Extending Frameworks
The idea of active cookbooks has been put forward in [PPS95]. A cookbook
is a recipe that explains how to perform a certain task (e.g., how to extend
a framework). An active cookbook is not just a textual recipe but also contains
interactive elements that can provide information on demand or help to perform
certain subtasks in a (semi-) automatical way.
A cookbook for frameworks often has to reference pieces of code that should
be read or modified as a certain step of the recipe. These references should
not be copies of the code (which would soon become inconsistent) but should
refer to the actual code itself. This helps to keep the cookbook up to date
even if the framework is modified. We plan to develop new kinds of text
elements that are hypertext links which do not lead to a specific target
point but rather reference a target stretch of text, i.e., provide a window
into the framework.
Expected result: Tools to develop active cookbooks; documentation of existing
frameworks as case studies.
[Boo91] Booch G.: Object-Oriented Design with Applications. Benjamin Cummings,
[BJ94] Beck K., Johnson R.: Patterns Generate Architectures. In: ECOOP '94,
LNCS 821, 139-149.
[GHJV95] Gamma E., Helm R., Johnson R., Vlissides J.: Design Patterns: Elements
of Object-Oriented Software Architecture. Addison-Wesley 1995.
[JKN95] Järnvall E., Koskimies K., Niittymäki M.: Object-oriented
language engineering with TaLE. To appear in Object-Oriented Systems, 1995.
[Joh92] Johnson R.E.: Documenting Frameworks with Patterns. In: OOPSLA '92,
Sigplan Notices 27(10), October 1992, 63-76.
[KM95a] Koskimies K., Mössenböck H.: Designing an Object-Oriented
Framework for Language Implementation. Report 2, Department of Systems Software,
University of Linz, 1995.
[KM95b] Koskimies K., Mössenböck H.: Designing a framework by
stepwise generalizaton. To appear in ESEC '95, Barcelona 1995.
[KM95c] Koskimies K., Mössenböck H.: Viewing object-oriented programs
through scenario diagrams. In Proc. Fourth Workshop on Programming Languages
and Software Tools, Visegrad, Hungary, June 1995, 1-8.
[KM95d] Koskimies K., Mössenböck H.: SCENE: Using active text
and scenario diagrams for illustrating object-oriented programs. Manuscript,
[Knu84] Knuth D.E.: Literate Programming. The Computer Journal, vol. 27,
no.2, 1984, 97-111.
[MK95] Mössenböck H., Koskimies K.: Using active text for structuring
and understanding source code. Submitted for publication, 1995.
[Pre95] Pree W.: Design Patterns for Object-Oriented Software Development.
[PPS95] Pree W., Pomberger G., Schappert A., Sommerlad P.: Active Guidance
of Framework development. In Software - Concepts and Tools, Springer-Verlag
[Rum91] Rumbaugh J., Blaha M., Premerlani W., Eddy F., Lorensen W.: Object-Oriented
Modelling and Design. Prentice-Hall, 1991.
[WGM88] Weinand A., Gamma E., Marty R.: ET++ - An Object-Oriented Application
Framework in C++. In: OOPSLA '88, Sigplan Notices 23(11), October 1988,
[WWW90] Wirfs-Brock R., Wilkerson B., Wiener L.: Designing Object-Oriented
Software. Prentice Hall, 1990.