We identify three types of control flow models.
1 Single-threaded. This is the basic model where no concurrency is present; at any time there is only one instruction that is being executed. Only one component at a time is active and it has to yield control to other components (usually by method invocation).
2 Virtual processes. This is based on a single threaded model but gives the appearance of concurrent execution. In this approach a controller com- ponent schedules the execution of the other components and gives them control. The scheduling can be performed periodically or based on events. The components whose execution is scheduled are responsible for performing the scheduled activity and returning the control back to the controller. This model is based on a logical decomposition of activities in simple steps whose execution requires only short intervals of time. The programmer has the responsibility of decomposing the components’ activities according to the application requirements.
3 Multithreaded. This approach allows real concurrency; it is based on the concurrency mechanisms of the operating system. Several threads can be running at the same time in an application. Even in this case, only one component has control over the application execution. In contrast to the virtual processes approach, the decomposition of components’ activities in simple steps is performed by the operating system at a lower granu- larity. The main disadvantage is that the threads management raises the computational load.
7.4
■
Part overview
The second part of this book is organized in four case studies. They present object architectures that implement different architectural styles, communication mechanisms and concurrency models. The case studies use different methods to synthesize generic components (see Table 7.1).
The case study presented in Chapter 8 (Code documentation) deals with the development of a graphical application that parses a source Java code Table 7.1 Architectures adopted in the case studies
Architectural Communication Concurrency
Case study style mechanism models
8 Code documentation Data-centred Method invocation Single-thread
9 Work cell Virtual machine Event-driven Virtual processes
10 Mobile robot Master–slave Message-oriented Multithread
11 Car Parking Layered Method invocation and Multithread
file and formats the code structure in HTML. It emphasizes the role of association and relationships between application components.
The other three case studies discuss three different software control architectures that model the interaction between controller and controlled system.
Chapter 9 (Manufacturing work cell) deals with prototyping and simu- lation of a manufacturing work cell. The control system is simulated as a discrete event dynamic system, where system components are modelled as finite state automata. A centralized event clock schedules events that trigger state transitions. The control behaviour emerges from the event-based interaction among the simulated devices. The architecture is single threaded and supports the broadcaster–listener communication model.
Chapter 10 (Mobile robot exploration) deals with simulation of a robotic system. The system is structured according to the master–slave architec- ture. A software controller plays the role of master and sends commands (e.g. “move forward” or “get sensor measurements”) to a mobile robot. The mobile robot is a multithreaded component made up of independent modules that simulate sensors and actuators and play the role of slaves. The communication between master and slaves is asynchronous and message- based and is implemented using the pipe mechanism.
Chapter 11 (Car parking) deals with simulation of an access control system for car parking. The software architecture is multithreaded and event-based. The system is organized in a client–server hierarchy of control modules. The clients send commands to the servers according to the caller– provider paradigm. The servers notify state changes using the observer– observable mechanism offered by the java.utilpackage.
7.5
■
References
Abowd, G., Allen, R. and Garlan, D. (1993) “Using Style to Give Meaning to Software Architecture”, in Proc. of SIGSOFT ’93: Foundations of Software Engineering,
Software Engineering Notes, Vol. 118, No. 3, 9–20, ACM Press.
Garlan, D. (1995) “What is Style?”, in Proceedings of Dagshtul Workshop on
Software Architecture, February.
Shaw, M. and Garlan, D. (1996) Software Architecture: Perspectives on an Emerging
Synthesis
The application developed throughout this chapter is aimed at generating customizable documentation for source code. The format chosen for the documentation is HTML (HyperText Markup Language). The architecture of the application mainly addresses extensibility requirements.
■ Focus: this case study exemplifies the application of the Composite design pattern which is widely used when representation of hierarchical struc- ture is required.
■ OO techniques: separation of concerns and delegation.
■ Java features: a graphical user interface is developed to provide ease of use for the application. The GUI is developed by means of the swing set of components; in particular a component that is able to render HTML code is used.
■ Background: the reader is required to know the basic OO concepts and fundamental Java programming techniques and to have a basic knowledge of HTML.
8.1
■
Specifications
Understanding programs written in a high-level programming language is one of the main problems arising when maintenance and reuse are con- cerned. While some pretty printing programs are available on the market- place, they are often not customizable and it is difficult to fine-tune their output.
We want to develop an application that is able automatically to produce the documentation of a program in source code. The documentation generated by the application must use a standard and widely adopted format. A documentation schema specifies both the information to be extracted from the source code and how it should be presented.
In summary, the application must be able to read one or more source code files and generate an HTML file for each of them containing formatted documentation. The application should initially be able to analyse and document Java code. The application must be easily extensible in order to accommodate new documentation schemas and possibly new languages.
8.1.1 Example of Java documentation
As a first proof of concept implementation, we choose Java as the source code programming language. We will consider a simple documentation that simply lists the public members of the program classes.
In particular, for each Java class an HTML page should be generated with the following characteristics: the title of the page should be the name of the class, the name of the class should also appear as a level 1 heading at the top of the page, then the page should contain a list of the public members.
The public members of the class conform to the following guidelines:
■ public attributes will appear as they are written in the class, without the terminating “;”;
■ for each public method only the signature will be presented;
■ in both cases, the keyword “public” will be omitted.
An additional requirement is on the fonts used in the page. The list of public members should use a Courier-like mono-spaced font. The heading at the top of the page and the rest of the text in the page should use a sans-serif font. Figure 8.1 shows an example of source code and the corresponding documentation.
8.2
■
Problem analysis
The problem of generating the documentation for a program is very complex if considered in the most general setting. Fortunately the specification of the application introduces several assumptions that make the problem much easier.
We can identify three main elements, which are addressed throughout the specification: the source code, the documentation and the transformation of one into the other (i.e. the core functionality of the application). The overall functionality of the system can be described by the use case diagram, shown in Figure 8.2.
Figure 8.1 An example of code documentation
a_ p ublic_attribute
void int a_method(int a_ p arameter) class Example {
public int a_public_attribute;
public void a_method (int a_parameter){ //...
} }
Example
When analysing the specification, two main issues arise concerning the input language: first we have to parse source code written in a high-level programming language (Java in the example), second the application should be easily adaptable to new languages. The parsing of a programming lan- guage is usually a non-trivial task, but many tools are available that simplify this task. In addition, from the reference example we can note that a very simple analysis of the source code is required, Therefore the implemen- tation of the proof of concept does not require a fully fledged parser. The adaptability issue must be carefully addressed by the architecture of the application, since no simplification can be found reading the specification.
The selection of HTML as the format for the documentation has a twofold advantage: first we have to take into consideration only one output language, second HTML is based on a hierarchical structure, which helps in assem- bling several pieces of information in a single document. The example provides a good overview of the features of HTML that should be used for generating the documentation.
8.2.1 Domain models
The application exhibits a set of functionalities that are similar to the ones provided by the javadoc program, which is part of the Sun JDK, but javadoc requires the programmer to furnish the code with additional comments.
The approach taken with this application is more general and it is intended to be more customizable; moreover it is applicable to languages other than Java.
The system we want to develop is in essence a translator from an input language (the source code language) to output language (the documentation language). We can borrow many ideas regarding the architecture of such a system from the mature toolbox of compilers and formal languages.
The structure of a compiler, or more generally a translator, can be split into three main components:
■ a front end, responsible for the lexical and syntactical analysis of the input language (the programming language);
Figure 8.2 Use case of the application
User
Generate Documentation source code
■ an intermediate representation, with related processing modules;
■ a back end, which is in charge of generating the output in the final language (documentation language).
This architecture provides a high degree of flexibility, since the internal processing components are independent of both the input and output languages. If the input language changes only the front-end component needs to be modified. If a different output language is required, changes are confined to the back-end component.
8.2.2 Main Features
We can now summarize the main features that the system shall exhibit:
■ Intermediate representation. Support an object-oriented intermediate representation of HTML pages; this representation enables an easy mani- pulation and construction of the pages.
■ Source code parsing. Parse the source language, focusing on the identi- fication of the basic syntactic elements of the language such as class declaration and member definition.
■ HTML documentation. Generate the HTML documentation for the source code. This is a bridge between the previous two features, since it is about relating the elements of the programming language to the operations required to generate the corresponding HTML documentation.
8.2.3 Test
For the test case at system level we use a simple class derived from the one presented as an example in the requirements specifications. This class represents the input code that will be documented with the application under development. In order to make the test case significant, we need to add other elements to the example class in order to test if the application picks up only the required parts and correctly ignores the rest.
Moreover the application must allow the selection of text colour and style, and the colour of the background. In this example we will adopt a colour schema, which is not mandatory; its purpose is to demonstrate how colours and other features can be used.
// this is a test class... class TestClass {
String an_attribute;
public int a_public_attribute;
public void a_method(int a_parameter){ String s;
s # "string content"; }
abstract private int another_method(); }
The class TestClasscontains a total of four members, two attributes and two methods. Two attributes are public: the attribute an_attributeand the method a_method.
The application should produce an HTML page that looks like that shown in Figure 8.3. It is what a web browser shows (in colour) when we process the HTML code shown in Figure 8.4.
The title of the page, defined in the second line of Figure 8.4, is Class:fol- lowed by the name of the class. Then we see the body of the page that spec- ifies a cyan background colour. The heading consisting of the name of the class is decorated with some extra attributes: the size of the font is increased by two points, the colour of the characters will be navy (dark blue), and the font is “Tahoma”, which is a common sans-serif font. The list of the public members is preceded by the plain text Public members:, which is formatted in “Arial”, navy colour and increased size. The list of public members is presented using an increased size, green, “Courier New” font. At the bottom of the page there is a link to the home page for the Java language. This last line is inserted in order to provide an example of an HTML item that can be useful when representing complex documentation.
Figure 8.3 An example of HTML page. Copyright © 2005 Sun Microsystems, Inc. All rights reserved. Reproduced by permission of Sun Microsystems, Inc.
int a_ p ublic_attribute
void a_method(int a_ p arameter)
TestClass
Public members:
Java © Sun
Figure 8.4 An example of HTML code
<HTML>
<head><title>Class: TestClass</title></head> <BODY bgcolor#"cyan" >
<H1><FONT size#"!2" color#"navy" face#"Tahoma" >TestClass </FONT> </H1><FONT size#"!2" color#"navy" face#"Arial" >Public members: <BR> </FONT><FONT size#"!2" color#"green" face#"Courier New" >
<UL>
<LI>int a_public_attribute <BR> </LI>
<LI>void a_method(int a_parameter) <BR></LI> </UL>
</FONT>
<A href#"http://java.sun.com" >Java © Sun </A> </BODY></HTML>