6 Architecture Description

This chapter provides the architectural design. It has been developed using the first steps of the method described in chapter 5. After an introductory overview, all the modules of the system are described in detail. The language used to define templates is also described, even though the final definition of this is placed in the design specification.

6.1 Overview and layering

In an architecture, one can often identify different layers. For ArgoPrint, the modules have been distributed over three layers called user interface layer, algorithm layer and data layer.

As seen on the next page, the system has been divided into eight different entities. Each module, which consists of executable code and as seen in the notation description below is denoted by an oval, is responsible for certain tasks and is described together with the pure data entities in more detail in chapter 6.2.

Figure 2:  Notation description

Figure 3:  Layers and modules.

As seen above, the Model module is considered data when it comes to layering. This is done because no ArgoPrint specific functionality is placed here and Model is used by ArgoPrint like a database, even though methods in Model are invoked.

Since the template and all output files are considered data and not user interactions, the user interface layer is defined as the GUI module only. This gives the natural definition of the data layer as the system entities Template, Files, Document and also Model.

The work horse of the system is the set of modules containing Engine, Interface and the XML-parser and together they define the algorithm layer.

6.2 Module and Architecture Entity Description

Here a more detailed description of each module and important entity of the architecture is provided. For every module, information about it's behavior and the interfaces to other modules is given.

6.2.1 Notation

The following notation is used to make the user understand the module functionalities quickly.

Table 1:  Notation of a module description.

Name	The name of the module.
Layer	The layer in which the module is placed.
Input data	What the module will be given as input.
Output data	What the module will deliver as output.

6.2.2 GUI

Table 2:  GUI description

Name	GUI
Layer	User interface layer
Input data	The interactions of the user Messages from the algorithm layer to the user
Output data	Settings of, and calls to ArgoPrint

The Graphical User Interface consists of a simple plug-in to the ArgoUML menu. From this menu, the user is able to open the ArgoPrint document generation window which will contain text boxes in which the user can set different variables, needed to generate a document.

Methods invoked in the main class of the algorithm layer are listed below. They are used to set up variables needed for the output generation and to start the actual generation.

boolean InitializeSystem(Settings)

boolean Go()

ArgoPrint can also be invoked using the command line of the operating system. This feature is described in the requirements specification as detailed as considered necessary before the more detailed design, the design specification.

6.2.3 Model

Table 3:  Model description

Name	Model
Layer	Data layer
Input data	Calls through the ModelFacade class
Output data	Internal representation of data in the model

The Model module, which actually is the ArgoUML model itself, consists of an object hierarchy, to which calls can be made through a class called ModelFacade. This works as follows.

Every object can be asked if it has a certain method or data member. When the answer is positive, the method can be invoked and the return value can be handled. If the answer is negative, no invocation will be made.

6.2.4 XML-parser

Table 4:  XML-parser description

Name	XML-parser
Layer	Algorithm layer
Input data	Template written in XML
Output data	Tree structure of Java objects

This module is the free XML-parser Xerces which will be invoked using the following methods.

DOMParser DOMParser()

parse(String xmlFile)

Document getDocument()

6.2.5 Engine

Table 5:  Engine description

Name	Engine
Layer	Algorithm layer
Input data	Tree structure of Java objects Strings from Interface User interactions from GUI
Output data	Generated document Calls to Interface

Engine's main task is to traverse the Java object tree (DOM tree) obtained from XML-parser and to generate output data. The general idea of how this works is the following. Everything in the template, which is now represented in the Java object tree, that's not recognized as ArgoPrint formatting tags is considered output text and is passed to the output document. Some of the special tags will call Model through Interface and output text is generated dynamically. See chapter 6.3 for more information on this and the template language.

6.2.6 UMLInterface

Table 6:  Interface description

Name	UMLInterface
Layer	Algorithm layer
Input data	Calls from Engine Data from Model
Output data	Calls to Model (ArgoUML specific) Strings to Engine Files from the ArgoUML model to disk

This is the only part of ArgoPrint that's specific for the ArgoUML model, hence, this is the module to build from when implementing support for other data sources than this model. One other imaginable data source is an SQL database and this would have a similar interface module as the ArgoUML model connected to it.

The main task of this module is to translate the general template call to a ArgoUML specific call and also to handle iterations over objects in the model.

A goal when designing this module is that it should have as little knowledge of ArgoUML models as possible. This is for two reasons: It is unnecessarily complicated for knowledge about models to exist both in ArgoUML and ArgoPrint and any changes made to the ArgoUML model would have to be reflected in ArgoPrint as well. The idea is instead that the author of the template should have some knowledge of the ArgoUML model and that the Interface translates information from the template in a standardized way into calls to ModelFacade.

This module will also take care of iterations over objects in the model, and let Engine call one object at a time among a whole set of objects. Sorting the objects before handling them one by one will also be possible.

6.2.6.1 ModelFacade

Currently the internal representation of an UML-model in ArgoUML is going through a change. The current model, NS UML (Novasoft), is no longer supported. ArgoUML will probably change model to a JMI compliant model instead. When the model is changed ArgoPrint, and other modules depending on the model, interface problems would cause the modules to need reprogramming. To make the change of model transparent to the modules, ArgoUML has been equipped with a generalized model interface, ModelFacade, which contains recognisers, getters and setters for most UML-objects. For a more complete reference of what to find in ModelFacade the reader should consult the class documentation which is available as JavaDocs at the official website of ArgoUML (argouml.tigris.org).

6.2.7 Files

If a call is made in the template such that the corresponding method in the ArgoUML model would return a file, for example a picture, only the file name will be sent from Interface to Engine. This is done because the output document is supposed to be text only. It may however contain file name, and therefore the file itself must be copied out from the ArgoUML model to a directory of the user's choice. Note that this file extraction is performed by Interface and not Engine, which handles text output.

6.2.8 Document

Document is the output file in which Engine writes all text. The contents of this file depend on Template and the ArgoUML model.

6.2.9 Template

Template is an XML document that may contain ArgoPrint tags. If no ArgoPrint tags are included, the output file (Document) will be the same as Template. The ArgoPrint tags can be used as stated in chapter 6.3, but for a more detailed description of the usage of them, the reader should consult the design specification, where a complete language definition of the ArgoPrint template language is provided.

6.3 ArgoPrint template language

The language in which to write the document template is XML and includes functionality as follows. Under each specific code construction explanation, an example is given to depict the main looks of the language for the reader.

6.3.1 Notation

Below, every ArgoPrint specific xml tag is described.

Where for example <if> is mentioned, what's really meant is <ap:if>. Abbreviations like this are used to make reading of the text easier.

After the definition of each tag, a textual explanation for the tag is given. After all tags have been defined, an example is provided which will depict the usage of the language to the reader.

Notice that since all system variables are set through the GUI, no special ArgoPrint tag is needed to begin the template.

6.3.2 If-Then-Else

To let the user specify filtering of data based on conditions, the if-then-else tag <if> is introduced. This looks as follows:

<ap:if cond="calledMethod()">

<ap:then>

</ap:then>

<ap:else>

</ap:else>

</ap:if>

<if> will handle the code between <then> and </then> if the condition given in the attribute cond is true. Otherwise, the code between <else> and </else> is handled. The method calledMethod() should return a Boolean.

6.3.3 Bind

To let the user create tags and bind data to its attributes, the tag <bind> is defined as follows:

<ap:bind name="tag_name">

<ap:attr name="attribute_name">
attribute_value

</ap:attr>

</ap:bind>

<bind> constructs a tag named tag_name with all attributes (can be many!) given between <bind> and </bind>. attribute_value is either a string or something that is evaluated to a string. A good way of using <bind> is together with the tag <call> which fetches data from a data source.

6.3.4 Call

<call> is introduced to let the template author fetch data from a data source. It is defined as follows:

<ap:call what="calledMethod()" iterator="iteratorName"/>

The result of <call> is always a Object but will render an exception unless it is a String and calledMethod() should be a valid call. In the ArgoPrint case, a call to the ArgoUML model.

6.3.5 Iterate

The tag <iterate> is introduced to let the user iterate over objects and sort them. Definition is as follows:

<ap:iterate what="calledMethod()" iterator="it_name" iteratorname="name" sortvalue="StringFunction()">

</ap:iterate>

Every object in the Collection returned by the call "what" to the data source will be bound as iterator named name and the code between <iterate> and </iterate> will be handled one time for each of them. If the calledMethod() returns an Object the iterator tag will construct a Collection containing that single Object. If the iterator is nested the iterator attribute can be used to specify the argument for the calledMethod(). If the sortvalue attribute is included, the objects to iterate over will be sorted in alphabetical order according to the String returned by the given method.

6.3.6 methodCalled()

Currently it is possible to call functions in the ModelFacade class. This is mostly done by specifying the method name with parentheses in the what attribute and the argument for the function in the iterator attribute. There are also some default arguments which are called by using the method name and the argument inside the parentheses.

Ex:

<ap:justanexample what="getName()" iterator="classes">

Will call the getName method in ModelFacade using the current object iterator classes as argument. Will evaluate to:

ModelFacade.getName(classes.currentObject())

<ap:justanexample what="getOwnedElements(model)">

Will call getOwnedElements using the model as argument. Useful for initially getting hold of the objects in the model.

<ap:justanexample what="getName(project)">

Can be used to call functions in the Project class. Will evaluate to:

thisProject.getName().

6.3.7 Depicting example

This example template assumes that the interface that connects ArgoPrint to ArgoUML is installed and available. It produces an HTML document, listing classes in a project and their methods.

<html>

<head>

<title><ap:call what="getName(project)"/></title>

</head>

<body>

<h1>Contents of

<ap:call what="getName(project)"/>

</h1>

<h3>Classes</h3>

<p>

<ap:iterate what="getOwnedElements(model)"

iteratorname="object"

sortvalue="getName()">

<ap:if cond="isAClass()" iterator="object">

<ap:then>

<ap:bind name="a">

<ap:attr name="href">

#<ap:call what="getName()"

iterator="object"/>

</ap:attr>

<ap:call what="getName()"

iterator="object"/><br/>

</ap:bind>

</ap:then>

</ap:if>

</ap:iterate>

</p>

<p>Class details</p>

<ap:iterate what="getOwnedElements(model)"

iteratorname="object"

sortvalue="getName()" >

<ap:if cond="isAClass()" iterator="object">

<ap:then>

<ap:bind name="a">

<ap:attr name="name">

<ap:call what="getName()"

iterator="object"/>

</ap:attr>

<h3><ap:call what="getName()"

iterator="object"/>

</h3>

</ap:bind>

<h5>Methods</h5>

<ap:iterate what="getOperations()"

iterator="object"

iteratorname="method"

sortvalue="getName()">

<ap:if cond="isAOperation()" iterator="method">

<ap:then>

<p><ap:call what="getName()"

iterator="method"/>

</p>

</ap:then>

</ap:if>

</ap:iterate>

</ap:then>

</ap:if>

</ap:iterate>

</body>

</html>

For a more detailed example walkthrough with figures showing DOM-trees for all xml snippets, see the design specification.

6.4 Reflections on properties

The architecture of ArgoPrint relates to the properties in chapter 4.3 as follows.

6.4.1 Testability

The modules of ArgoPrint have different tasks and can be tested outside the complete system.

Model

Model is already finished but tests are still necessary in order to learn exactly how it can be invoked. The invocation of Model can be done directly to the module and no other parts of the system have to be implemented for this.

Interface

Interface is a rather complex module but it can still be tested outside its' environment. Since Model is already finished, one can even let Interface invoke this and simply call Interface with what a model invocation looks like in the template, and then look at the result which should be ordinary strings.

Engine

Tests for Engine are not very hard to construct either. One can assume a certain string is sent from Interface when making an invocation and since the XML-parser doesn't have to be implemented, Engine could traverse a Java object tree, and generate an output document. This is not testing entirely outside the environment of the module but the XML-parser is already finished so it shouldn't be very complicated to get it to work properly.

XML-parser

XML-parser is easily tested by just letting it parse an XML file and look at the object structure generated. Worth mentioning is that even though ArgoPrint will contain an existing XML-parser, testing must be performed. If it turns out the parser can't be made to pass the tests it can be exchanged for another one. Since the chosen parser implements a standardized interface, this procedure is not very complicated. See chapter 4.4 about design decisions concerning the parser.

GUI

GUI can be tested by letting it call dummy methods instead of methods in Engine.

External data files

All the external data files such as templates, generated documents and other data files are not a source of errors. The templates should follow the language specification and the data files are just extracted from the ArgoUML model. Errors in the generated document most likely originate in errors in Engine.

6.4.2 Code reusability

A lot of the modules have to be written from scratch but the system also contains much reused code in the XML-parser.

6.4.3 Extendability

The main factor to give ArgoPrint this feature is the idea that only the Interface module is ArgoUML model dependent. By developing similar modules for other data sources one can extend the system in the future.

6.4.4 General solution

ArgoPrint does not define the format of the output data other than that it is XML. This gives the Document Author free hands concerning output.

Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com