1.14. Visual Paradigm Models

Text below details original ideas of how to work with Visual Paradigm when work first started using the tool, it is kept here as a reference and once more work with Visual Paramdigm is done the instructions detailed here may be selected as the best process to follow, rather than those detailed in About this document.

NB. This section of the guide is our current understanding of how Visual Paradigm may be used and therefore does not correctly represent current actuality, e.g. as regards to location of Visual Paradigm models, etc.

The tool Visual Paradigm (VP) is used to create the Class Diagrams and Sequence diagrams that feature in this document. Diamond has a license for the software and Visual Paradigm is installed under TBC.

The VP files (located in gda-documentation/GDA_Developer_Guide/vp directory) contains all the Visual Paradigm models that have been created for the guide (with extension .vpp). During the make process (see Building the GDA Developer and User Guides at Diamond) the gda-documentation/GDA_Developer_Guide/vp directory will be extracted from the tar file if Visual Paradigm is installed on the system so that the models can be accessed and used.

The gda-documentation/GDA_Developer_Guide/vp directory contains a series of Visual Paradigm files (extension .vpp) named appropriately for what they are modelling and also another subdirectory named gda-documentation/GDA_Developer_Guide/vp/generated_python_classes. Within this subdirectory are Python files files which are used as input for Visual Paradigm to create Python relation diagrams . These Python files have been generated using the scripts extractPyClasses.sh and VisParMaker.py (see description in section Scripts).

1.14.1. Using Visual Paradigm

After starting Visual Paradigm, select Open to open a project from the gda-documentation/GDA_Developer_Guide/vp directory. Using the sidebar Diagram Navigator navigate to the UML Diagrams > Class Diagram or Sequence Diagram. Here are the diagrams named as they are referred to in the documentation.

Both Class Diagrams and Sequence diagrams have been created by inputting selected source code paths (modules) that contain the source code that needs to be shown in diagram format. For example, the OldScanning_ClassDiagram in the old_scanning_vp_model.vpp requires two modules to generate the models: {workspace_git}/da-core.git/uk.ac.gda.core/src/gda and {workspace_git}/gda-core.git/uk.ac.gda.api/src.

The models have been created so that they are universal across systems by use of the User Path definition. This means that the source path inputs are actually defined as ${root}/path/to/module where ${root} is substituted by VP for the User Path variable. For example this would give ${root}/gda-core.git/uk.ac.gda.core/src/gda instead of /scatch/user/gda/workspace_git/gda-core.git/uk.ac.gda.core/src/gda and hence definite paths to not restrict people from making changes. In order to make use of this, the User path must be defined within the Visual Paradigm application. This can be done as follows:

  1. Go to Window on the top panel

  2. Select Application Options.

  3. From the sidebar select User Path

  4. Select Add > User Path. For Name enter root and for Path give the path to your workspace_git directory created after materialising GDA.

  5. Select OK on pop up window and then Apply and Apply again.

Visual Paradigm will now substitute any reference to ${root} with the path just added.

1.14.2. Creation of Diagrams

1.14.2.1. Class Diagrams

The important thing to note here is that simply inputting the source code and using a reverse engineering tool to create a Class diagram does not work as it does not produce anything meaningful. The result is a huge diagram with a web of connectors which is not useful for understanding some of the key processes. Instead after inputting the carefully selected modules, a selection of the important/key classes should be added to show a basic representation of the process.

Below are the basic steps that were carried out to produce the diagrams. These can be followed when creating new ones.

  1. Go to the tab Tools at the top of the window.

  2. Select on Code and Reverse Java Code… From there a window will pop up.

  3. Selecting the + symbol will add an input source directory. Select the module that contains the classes that should be included (e.g. see above for old style scanning example). Multiple source paths can be added to include any modules across GDA. It is recommended to be as specific as possible so as to manage the classes easily.

  4. On the sidebar tab, under Class Repository the folder Java Round-trip will now appear and underneath you can see all the modules and sub-modules imported.

  5. To create a class diagram for a particular class first find it and then right click. Select Reverse <class> to and select New Diagram.

  6. Two pop-up will show up. Answer No to the first and Show Fully Qualified Owner to the second.

  7. Visual Paradigm will create a new diagram and pull in other classes contained in the Class Repository that your selected class depends on. For example, when reversing DummyScannable (from gda.device.scannable), it created the diagram by pulling in ScannableMotionBase which subsequently references ScannableBase and ScannableMotion and so on (until it gets down to the Scannable interface).

  8. To add other classes to the diagram, simply drag them from the Class Repository menu into the current diagram. If there are connections/dependencies then the connectors will automatically be added.

  9. ALTERNATIVE: If unsure what classes exactly to include then it is possible to select multiple from the Class Repository menu (using the keyboard key Ctrl when selecting) and then right click and select Reverse to. Equally it is possible to do it for a whole module. This may produce a ‘mess’ but all dependencies will be included and you can simply delete those that are not important to show.

Adopted Naming Convention

When creating a new diagram it uses the module name of the class that is reversed. This needs to be changed to something sensible such as the process it describes with ‘_ClassDiagram’ at the end. It must match the reference to it in the documentation source as images are created from these diagrams automatically using their names.

1.14.3. Sequence Diagrams

Below are the basic steps that were carried out to produce the diagrams. These can be followed when creating new ones.

  1. Go to the tab Tools at the top of the window.

  2. Select on Code and select Instant Reverse Java to Sequence Diagram… From there a window will pop up

  3. Add all the paths to the source code that need to be included to access all the methods called by the methods you want to create the diagram for. IMPORTANT: The defined path must go down to the {$PATH}/src/ directory. I.e. all paths must end in src.

  4. Select Next and now you can see all the source directories which are now expandable.

  5. Find the class containing the method you want to display and from there find the method.

  6. Click Next and Create new sequence diagram with a sensible name (i.e. the method) ending in ‘_SeqDiagram’. Select Finish.

  7. The diagram will be created.

Troubleshooting:

If no methods appear underneath a class or a module is not expandable when trying to select the method to reverse, the usual cause is that the src path has not been defined correctly. See notes above that the path must be given to the src directory, e.g. {workspace_git}/gda-core.git/uk/ac/gda/core/src.