Appendix 1
Fujaba Sequence Diagram Plugin
Users Manual
Hans Nilsson, Kristofer Gusenbauer.
1.Getting Started
1.1.Installing the Plugin
1.2.Starting Fujaba
1.2.1.Using JBuilder
1.2.2.Using the Java Virtual Machine
2.Creating a Sequence Diagram
2.1.Creating the Diagram
2.2.Adding Actors, Objects and Messages
2.2.1.Adding Actors
2.2.2.Adding Objects
2.2.3.Adding Messages
3.Editing Removing and Moving Items
4.Special Features and Cases
4.1.Removing Base Classes
4.2.Removing a Constructor Message
4.3.Editing a Constructor Message
4.4.Changing Base Class of a Constructed Object
5.Code Generation
References
1.Getting Started
This chapter covers the installation of the plugin and how to start Fujaba using this plugin. Since Fujaba is a project currently under development, the sequence diagram plugin will only work with the development version of Fujaba and is not guaranteed to work with any version released after December 2002. To run Fujaba you also need JDK version 1.4.1 or later.
1.1.Installing the Plugin
The installation is simple. Find the folder where your version of Fujaba is, normally it will be called NewFujabaApp. In the subfolder named plugins you will need to create a new folder called SequenceDiagrams. Then copy the jar file (SequenceDiagrams.0.5.jar), the two xml files (stable.xml and plugin.xml) and the subfolder called images to the new folder. Now the plugin will start automatically with Fujaba.
1.2.Starting Fujaba
Since you have to be a member of the Fujaba development team to have access to the development version of Fujaba, this step may be redundant. However, a short description of the starting process will be given.
Starting Fujaba with the plugin is no different from starting Fujaba normally. There are several ways to do this, normally one would start it through JBuilder, but it can also be started with a simple command to you java virtual machine.
1.2.1.Using JBuilder
When starting the program through JBuilder, first you have to start JBuilder itself. When this is done, go to the File menu and choose “Open Project”. This should spawn a file selector, now find the “ProjectFiles” subdirectory of your Fujaba folder. In that folder, there should be a folder called “JBuilder”, in which the project files are located.
Once the project is loaded all you have to do is run the project, this is done by clicking on the Run menu and choosing “Run Project” (alternatively pressing F6, if you are using Windows).
1.2.2.Using the Java Virtual Machine
If you wish to use the Java Virtual Machine directly, what you do is open a new command line window and type in the appropriate java command. It should look something like (but not necessarily exactly like) the following.
C:\j2sdk1.4.1\bin\javaw -server -classpath CurDir\ProjectFiles\JBuilder\class;CurDir\libs\junit.jar;CurDir\libs\log4j-1.2.7.jar;
CurDir\libs\upb.jar;
CurDir\libs\OROMatcher.jar;
CurDir\libs\RuntimeTools.jar;
CurDir\libs\xerces.jar;
CurDir\libs\xalan.jar;
CurDir\libs\olddis.jar;
CurDir;
CurDir\commonslogging.jar;
C:\j2sdk1.4.1\demo\jfc\Java2D\Java2Demo.jar;
C:\j2sdk1.4.1\demo\plugin\jfc\Java2D\Java2Demo.jar;
C:\j2sdk1.4.1\jre\lib\charsets.jar;
C:\j2sdk1.4.1\jre\lib\ext\dnsns.jar;
C:\j2sdk1.4.1\jre\lib\ext\ldapsec.jar;
C:\j2sdk1.4.1\jre\lib\ext\localedata.jar;
C:\j2sdk1.4.1\jre\lib\ext\sunjce_provider.jar;
C:\j2sdk1.4.1\jre\lib\im\indicim.jar;
C:\j2sdk1.4.1\jre\lib\jaws.jar;
C:\j2sdk1.4.1\jre\lib\jce.jar;
C:\j2sdk1.4.1\jre\lib\jsse.jar;
C:\j2sdk1.4.1\jre\lib\rt.jar;
C:\j2sdk1.4.1\jre\lib\sunrsasign.jar;
C:\j2sdk1.4.1\lib\dt.jar;
C:\j2sdk1.4.1\lib\htmlconverter.jar;
C:\j2sdk1.4.1\lib\tools.jar" -mx512m de.uni_paderborn.fujaba.app.FujabaApp
In the command above, you have to substitute “c:\j2sdk1.4.1” with the folder name where you have your JDK installed. You also have to substitute “CurDir” with the folder name where you have your development version of Fujaba.
2.Creating a Sequence Diagram
In the following chapter, we will describe how a sequence diagram and its components are created. Creating a sequence diagram without having a class diagram to work with is something that rarely will be done. There is, however, support for creating classes “on the fly” when creating your sequence diagram. This is intended for use when a class was forgotten in the class diagram and not for the creation of entire diagrams. Therefore, in the following chapter, it is assumed that a class diagram exists before the creation of a sequence diagram. Instructions on how to create a class diagram can be found in the Fujaba User Documentation [Fujaba]. Unfortunately, most of these instructions are only available in German. Figure 1 shows an example of a sequence diagram created with our system. Lifelines are automatically extended when need arises. Activation boxes are also created automatically. In the following instructions, we will be using the class diagram shown in Figure 2 as basis for our sequence diagram. The class diagram we are using is a very simple one. It is not intended as a model for any actual system and lacks some elements one would really want in a library system, its only purpose is tutorial.
Figure 1 – Example of a sequence diagram.
Figure 2 – Class diagram
2.1.Creating the Diagram
After starting Fujaba and creating a class diagram, you choose the menu item “Diagrams” and then you choose “New Sequence Diagram”. You will then be prompted for a name for your new sequence diagram, it should look something like Figure 3. Just enter the name you wish for your diagram and press “ok”.
Figure 3 - Creating a sequence diagram
Once the diagram is created there will be a new entry in the tree structure to the right in the main window, it will be named “Sequence diagrams” and contains all sequence diagrams in the current Fujaba project. You now have a new, empty, sequence diagram in the following subchapters we will explain how to fill it with objects actors and messages.
2.2.Adding Actors, Objects and Messages
After creating an empty diagram you can start creating components in the diagram. To create components, you can either use the toolbar to the left of the blank diagram (Figure 4), or the “Sequence Diagram” menu. Pressing the toolbar button with the image of a stickman creates actors. The button with a box shape creates objects and the button with the arrow creates messages.
Figure 4 - The toolbar
2.2.1.Adding Actors
Actors are created and added to the diagram in the following way.
Press the stickman button on the toolbar. You will be prompted for a name to this actor.
Enter desired name of your actor
Press “ok”.
Now your actor should be created and shown in the diagram according to Figure 5.
Figure 5 - Sequence diagram with actor
2.2.2.Adding Objects
The creation of objects is somewhat more complex than that of actors since Fujaba requires that each object have a corresponding class. To begin, click the box shape button at the top of the toolbar, this should spawn a dialog looking like Figure 6.
Figure 6 - New object dialog
Here you need to specify a name for the object. Entering a name in the field named “caption” does this. Next, you have to specify a base class for the object you can do this by simply choosing a class from the list under “Class for object”. You can choose a class from any class diagram, changing class diagram is done through the list under “Choose class diagram”. If you wish to create a new class at this stage, simply click the “New Class” button. You can even create a whole new class diagram by clicking the “New Class diagram” button. Clicking any of these two buttons will spawn the same dialogs that are used when creating a class/class diagram the normal way. For help using these dialogs please refer to the Fujaba User Documentation [Fujaba]. When you are done choosing your base class, click on the “OK” button. Now you should have a new object in your sequence diagram, and the diagram will look something like Figure 7
Figure 7 – Sequence diagram with object
2.2.3.Adding Messages
To add messages between objects or actors just click the button with the arrow shape. This will spawn a new dialog (Figure 8 and Figure 9). Common for these two dialogs is that you can enter a “Conditional expression” if you so wish. If you do, this means that the message will only be executed if the expression if satisfied. Also, in both dialogs, you can choose whether this message is synchronous or not, this is done by a simple checkbox at the bottom of the dialog. Furthermore, in both cases you can choose where the message should go from using the list under “From”. You can also choose where the message should go to in the list under “To”. Those are the similarities, but there are two different dialogs depending on whether the message goes to an actor or an object. We will begin by explaining the case when a message goes to an object (Figure 8)
Figure 8 - New Message dialog (message goes to an object)
Having chosen that the message should go to some object, you will see the dialog as in Figure 8. Here you have an additional list under “Message” where you can chose what method in the base class of the object it goes to, that the message is an abstraction for. Any method specified for that class in its’ class diagram can be chosen. If you wish to, at this stage, create a new method in that class, you can do that by pressing the “New Method” button. This will spawn the same dialog as used when creating method the normal way. For help using that dialog please refer to the Fujaba User Documentation [Fujaba]. When done choosing your message, just click the “OK” button.
Figure 9 - New Message dialog (message goes to an actor)
If you chose an actor as being the target of this message, you will find that instead of the list of methods, you now have a simple line where you can enter a name for this message. It is done this way since actors do not have a base class and therefore we cannot know what methods the actor has. Simply enter a name for the message and press the “OK” button.
Now a new message has been added to your sequence diagram, a return message will also automatically be added. If you chose a normal method as base for your message this should look something like the image in Figure 10. If you chose a constructor as the base, you will notice that the object the message goes to have been moved down to signify that it was created at that time. Adding a constructor to an object that already has messages to it is a special case, it will result in the object being “reborn” and all old messages to it are removed. All new messages are added to the bottom of the diagram, if you do not wish your message to be there, simply drag and drop it to the desired location.
Figure 10 - Sequence diagram with message
3.Editing Removing and Moving Items
To edit any item on a sequence diagram, what you have to do is highlight that item by clicking on it. Then you click on the same button you used to create it. This will spawn the same dialog that was used to create it, in this dialog you can change the values to those you want. When editing, there are some special cases, for example when editing a constructor to an object. All these special cases will be dealt with in chapter 4 below.
To remove an item from the diagram you must select the item that should be removed, then you click the button in the toolbar that looks like the creation button but with an x over it. Removing an object/actor will remove all messages to and from it as well. Removing a message will remove its return arrow as well, and if the message is a constructor it will remove the constructed object.
An essential part of the diagram is the possibility to move items around. To do this simply drag and drop the item to the desired position. Note that items cannot be positioned in every way. When moving an item it will be relocated to the nearest approved location to where you dropped it.
4.Special Features and Cases
There are a couple of special cases where things are handled differently, such cases are explained in this chapter.
4.1.Removing Base Classes
If you exit the sequence diagram and go to a class diagram and delete a class or method that is used as a base class for some item in the sequence diagram it requires special treatment. What will happen is that when you return to the sequence diagram you will be faced with a dialog informing you that some base class/method has been removed (Figure 11). Then the item that used that class/method as base will be deleted since it is no longer valid.
Figure 11 - Removed base class dialog
4.2.Removing a Constructor Message
When removing a constructor message the object that is constructed will also be removed, since it cannot be known how this should be handled.
4.3.Editing a Constructor Message
Editing a constructor message can be compared to removing it and then adding a new constructor with the new values. Because of this, the edited message cannot go to the same object, because that object will be removed.
4.4.Changing Base Class of a Constructed Object
If you have an object in your diagram that has been constructed by some constructor message and decide to change base class of that object the constructor will, if possible be changed to the constructor of the new base class. If the new base class does not have a public constructor, the object will be reset to being created at the start of time, i.e. it will be moved to the top of the diagram and the constructor message will be removed. Classes without constructors do actually not exist in Java, all classes have at least a default constructor. But our plugin relies on methods specified in Fujaba class diagrams, and default constructors are not automatically included in these. Because of these circumstances, it is possible to have a class that lacks a constructor.
5.Code Generation
To generate code for any object in the diagram, (no code can be generated for actors) highlight the object and click the bottom button on the toolbar. This will spawn a text editor window containing the generated code for that object, this code can be edited as the user desires. This code is automatically saved in the form of activity diagrams in Fujaba when the editor window is closed. For more information on activity diagrams, please refer to the Fujaba User Documentation [Fujaba].
References
[Fujaba] Holger Giese, Fujaba User Documentation, 2002-04-22, Last Checked: 2003-01-10
1