1.9. Using Visual Paradigm

Previous text of this section kept for reference until decision on best working-practises to be adopted with Visual Paradigm are agreed.

Visual Paradigm (VP) is a cross-platform (including Linux) UML CASE (Computer Aided Software Engineering) tool adopted by the DAQ group to assist with understanding and documenting of the GDA code base and design of future developments. From Java source files it can produce UML models that can then be used to generate class and sequence diagrams, etc.

VP documentation can be found at the VP User Guide and forum. The Support page provides links to these and additional resources, including tutorials.

Details of Visual Paradigm use described in this section were created using version 16.1.

1.9.1. VP User Interface Nomenclature

In the following sections describing use of Visual Paradigm the various parts of the user interface are identified using the names used in the VP User Guide section Getting Started > User Interface, specifically the main parts of the interface as described in Exploring Visual Paradigm user interface. E.g. the top-most section of the screen containing tabs Dash, Project, ITSM, Agile, Diagram, View, etc. is called the Toolbar.

Not mentioned in the above VP user guide pages are the tabs positioned, by default, along left edge of main window, which give direct access to the Diagram Navigator, Model Explorer, Property, Diagram Backlog and Class Repository. These provide direct access to the same panels, or panes, or trees, accessible from the View toolbar tab and pushing the Panes button that shows the pull-down menu containing these items.

1.9.2. Using VP at Diamond

Diamond DAQ group have purchased the following VP floating licenses:

• 1 Enterprise

• 5 Standard

For comparison between the license types see this Visual Paradigm page.

Visual Paradigm is installed under /dls_sw/apps/VisualParadigm. This is the version used by the Jenkins documentation build job GDA.master-documentation.manuals, responsible for the nightly build and publishing of this documentation. It is not currently known (February 2021) how well a VP installation behaves when accessed simultaneously by multiple users, for this reason if you are planning to use VP routinely, for anything other than auto-generation of class and sequence diagrams (see section Auto generation of Class and Sequence diagrams) it is recommended to install a local version as detailed in the following section. Doing this has no impact on Visual Paradigm licenses; the same number and type of licenses are available irrespective of how many VP installations are made.

1.9.2.1. Installing VP

VP is installed locally, e.g. into user’s Linux home directory, by executing a script contained in /dls/science/groups/scisoft/VisualParadigm/ relating to the version of VP to be installed. You should install the latest available version e.g. as of writting the contents of the directory are:

$ ls -l /dls/science/groups/scisoft/VisualParadigm/
total 2012552
-rwxr-xr-x. 1 dos22317 dos22317 639651633 Sep 13  2019 Visual_Paradigm_16_0_20190906_Linux64.sh
-rwxrwxr-x. 1 dos22317 dos22317 690975610 Feb 26  2020 Visual_Paradigm_16_1_20200231_Linux64.sh
-rwxrwxr-x. 1 dos22317 dos22317 722126204 Oct 12 12:13 Visual_Paradigm_16_2_20201010_Linux64.sh

Therefore the latest version available is 16.2, therefore the script to be run is:

/dls/science/groups/scisoft/VisualParadigm/Visual_Paradigm_16_2_20201010_Linux64.sh

The script runs an install wizard:

• Clicking Next > displays the license agreement that must be accepted

• Clicking Next > again suggests an install location, that can be changed if required

• Clicking Next > again prompts for Select Directory for Symlinks, the default location of which is /usr/local/bin that must either be changed (unless user has required permissions) or the Create sysmlinks checkbox be unchecked

• Pushing Next > again starts the installation

Depending upon whether the user has previously installed and run VP, at the end of installation process if VP is started from the install wizard, i.e. Finish button is pushed with default Start the installed product radio button selected, you may be given the Enterprise license, for information about how to change license in use see VP License Selection below. Alternatively selecting radio-button Don’t start may provide you the ability to select the license to use on initial start of VP.

Once installed VP GUI application is started by running the Visual_Paradigm script located in the VP installation bin/ directory, e.g.:

<path-to-VP-install-dir>/bin/Visual_Paradigm

On first use of VP a window is displayed thanking you for choosing Visual Paradigm and asking you to select a license, please see VP License Selection below for instructions on how to proceed.

1.9.2.2. Updating VP version

There are 2 types of updates released by the VP developer:

1. Patch releases of the current version termed hotfix.

2. New version, e.g. update from version 16.0 to 16.1.

To discover if an update of VP is available do the following:

1. Save your work - the same model cannot be opened by multiple versions of VP. On first opening of a model in a new version you will be prompted to update it to the later version, once this is done it cannot be opened using the previous version. Updating to the latest hotfix does not require such an update to the model.

2. On Help toolbar tab push button Update

3. On warning pop-up requesting no VP product is running push button OK and close running version of VP

4. On Visual Paradigm Update window, step Configure update source, leave update source selected as Visual Paradigm update server and push button Check Updates

5. The Check updates step is displayed and if available new updates are listed, e.g. below shows hotfix 200201010 of currently in use version (16.1) is available and the new version 16.2:

1.9.2.2.1. Hotfix

To update to the latest hotfix select this (as displayed above) and push button Perform up… and follow instructions provided.

1.9.2.2.2. New Version

If wanting to update to the latest version (16.2 in above screenshot) and when this is selected a message is displayed detailing floating license server is using an old version license, as shown below, this indicates you are the first user at Diamond to update to the new version.

Before continuing you must request Diamond IT Support to do the following:

1. Install new version of VP install script in /dls/science/groups/scisoft/VisualParadigm/

2. Update Diamond’s VP License Server to provide necessary key for the new version.

If, following IT reporting the new version has been installed and the license server has been updated, the update screen still shows the message license server is using an old version license, please request IT to ensure the VP Server Administration is showing keys are available for the new version. Previously this process has been done successfully by Mart Harrow.

When no message regarding floating license is using an old license version is displayed, to update to the new version select this and push button Perform upgrade. This will install the new version in the same location as current version, i.e. previous version will no longer be available. If this is not what is required install the new version in a different location by cancelling the update and following instructions in Installing VP above, using the .sh script relating to the new version.

1.9.2.3. VP License Selection

As noted above there are a number of floating licenses available for use by DAQ developers. Following initial installation, on first starting VP a dialogue is displayed (see below) thanking you for choosing Visual Paradigm and asking you to select a license type.

To connect to the Diamond license server and select the required license do the following:

1. Under Perpetual License push button Activate

2. Under the Single Seat License grey box expand + Floating License (positioned under Configure Proxy… button)

3. In Host: text entry box enter diamvparadigm (leave http:// and Port: unchanged from default, and Access Code: empty)

4. Push button Connect to Server

5. The Product: selection pull-down becomes visible (after a few moments). By default the Visual Paradigm Enterprise license is selected, as there is only 1 of these available the license type should be changed to Visual Paradigm Standard, unless you require to use VP features only available when using the Enterprise license (for comparison between the license types see this Visual Paradigm page)

6. Push button Apply

On successful completion of the above the following window is displayed, by default the ‘I would like ot help improve Visual Paradigm’ check-box is checked, change this if desired and push the Start button to launch Visual Paradigm.

1.9.2.4. Changing the VP License Selected

The selected license can be changed at anytime while running VP by selecting the Window toolbar tab and pushing button:

On the displayed window, to change license type use the Product pull-down menu to select the required license and push button Switch. To re-run the license configuration (as detailed above) push button Change License.

1.9.3. VP GUI application vs Command-line

VP is most commonly used through its GUI application, started by running the Visual_Paradigm script located in the VP installation bin/ directory, e.g.:

<path-to-VP-install-dir>/bin/Visual_Paradigm

For software design and inspection of GDA source using a UML model the GUI application must be used, however, the VP installation also includes a number of scripts to enable use of VP capabilities from the command-line. All available scripts can be found under the <path-to-VP-install-dir>/scripts directory. Documentation for the majority of the scripts can be found in the VP User Guide section Command-line Interface.

The following sections of this page describe use of the VP GUI application, for details of how the command-line tools may be used see section Auto generation of Class and Sequence diagrams section of this document.

1.9.4. Application Options

In order to make UML models created by one user accessible and usable by others it is advised to set a VP User Path, this ensures the model will not use absolute paths to files (that are probably dependent upon user) but instead use a defined root directory. For example, this ensures ${root}/gda-core.git/uk.ac.gda.core/src/gda is used instead of /scratch/user/gda/workspace_git/gda-core.git/uk.ac.gda.core/src/gda.

To configure the root User Path do the following:

1. From Window toolbar tab select Application Options

2. On the displayed window, from the sidebar select User Path

3. Push button Add... and from displayed menu select User Path

4. In the displayed pop up in Name: text box enter root and in Path: text box enter the path to the directory containing the GDA source, e.g. workspace_git directory created after materialising GDA

5. Push button OK on Add User Path pop up and again on Application Options window.

The value of the root User Path can be modified at any time using Edit... button on the Application Options window.

1.9.4.1. Project Options

If using VP to create class diagrams, e.g. for inclusion in this or the GDA User Guide, to ensure diagrams are not visually too big and/or too cluttered it is advised to only display minimal class information, e.g. to hide field/method names and details on class associations etc. This can be done by selecting the following Project Options:

1. From Window toolbar tab select Project Options

2. On the displayed window, from the sidebar select Diagramming

3. From the available tabs select Class

4. On the Class tab select tab Presentation and set the various options as displayed in screenshot below:

5. Change from Diagramming Class tab to Association tab and set the various options as displayed in screenshot below:

6. Once all options are set as required press the OK button on the Project Options window.

1.9.5. Importing Java source code into Visual Paradigm

Visual Paradigm (all licenses) contains a code engineering tool called Instant Reverse. This can instantaneously make all GDA Java source available for use inside Visual Paradigm using on-demand reverse engineering, from the VP user guide:

Consider if you have a zip file that contains million of Java source file, like the file src.zip of Java Development Kit (JDK), and now you want to make the class java.util.Collection appear as UML class so that you can extend it when developing your own collection framework. Now, if you try to reverse the zip file it will take you a long time to complete the reverse due to the amount of classes (and relationships) is just too many. With on-demand reverse engineering, you will reverse the sources as indexes, and obtain an index tree in class repository. No actual UML classes will be reversed until you trigger the reverse manually. This reduces the processing time significantly.

As explained, the advantage of using Instant Reverse is that it enables the importing into VP of very large code bases without the significant time over-head of creating a UML model at the same time as the import, as is done during normal reverse engineering processing.

Instructions for use of Instant Reverse are given in the VP user guide section How to generate UML from Java sources and classes.

A short description of the steps used to Instant Reverse the GDA Java source is given below:

1. On the Tools toolbar tab under the Code pull-down menu select Instant Reverse as shown below

2. On the displayed Instant Reverse window push button Add Source Folder... and in the pop-up file navigation window navigate to and select the top-level directory containing the GDA source files, e.g. workspace_git and push button OK. This adds the directory to the list of instant reverse paths. The selected location will be displayed in window, e.g.:

3. Ensure check-box Reverse source on demand is checked (default) and press OK, the instantly reversed source will be presented in the Class Repository pane, expanding the workspace_git node will display the following (with workspace_git expanded):

4. To save the project select the Project toolbar tab and under the Save pull-down menu select Save as and use the pop-up Save Project window to select location and file name for the .vpp file.

1.9.5.1. VP Project Browser gotcha

Following completion of the Instant Reverse and before creation of a model (see following section) do not use the VP Project Browser accessed from View toolbar tab by pushing the Project Browser icon, beside the Panes pull-down menu:

Prior to creating a model and any diagrams this view will be empty and once selected prevents display of imported code, e.g. using the Class Repository pane, as all panes accessed from the Panes pull-down menu become greyed-out. A Visual Paradigm support request was submitted about this behaviour and the response suggests this is a feature of VP:

Thank you for your inquiry and I’m sorry that what you got is the correct behavior of the project browser. The project browser is provide similar functionalities as the trees [panes] (that’s why the trees are not showing), and you can see the model structure under Model Structure tab. If you wish to use the tree the you will need to open at least one diagram.

Moreover, the same behaviour occurs if the VP project or application is closed prior to creating a model, as on restart/re-opening the project the Project Browser view will be displayed, again preventing access to the imported code using the Class Repository or other panes.

1.9.6. Adding imported classes to model

As mentioned above Instant Reverse does not use the imported classes to automatically create a UML model, thus selecting an individual class in the Class Repository pane, right-clicking and creating a new class diagram, will produce a diagram of limited use. Not until the imported classes/packages are added to a model do their relationships become accessible.

The imported Java source classes and packages can be added to a model incrementally, e.g. to add the source contained in gda-core.git/uk.ac.gda.core/src do the following:

1. Navigate to the location in the Class Repository pane

2. Select the src folder, right-click and in menu follow Reverse “src” to > and select Class Repository

3. The pop-up Smart Reverse shows progress of the addition to the model

4. View the contents of the model using the Model Explorer pane, this can be accessed from View toolbar tab by selecting Panes and in drop-down menu selecting Model Explorer, it may also be accessible from the tabs displayed on left edge of VP window

The above can be repeated as required to add more classes to the model as and when it is recognized doing so would be useful. The following shows the Model Explorer pane after addition of gda-core.git/uk.ac.gda.core/src and gda-core.git/uk.ac.gda.api/src to a model:

Once added to a model the imported classes can be used within VP to generate class and sequence diagrams, as described in following sections.

1.9.7. Class Diagrams

Following the import of the GDA Java source into VP using Instant Reverse and addition of classes/packages to a model, as described in previous sections (Importing Java source code into Visual Paradigm and Adding imported classes to model), class diagrams can be created.

For example the following ScanBase class diagram:

The above diagram uses the VP Project Options set as described in section Project Options above and took approximately 5 minutes to create as shown, including Instant Reverse process. No manual adjustment of the diagram elements, e.g. resizing, positioning, etc. has been performed.

After Instant Reverse the following was done to create the ScanBase class diagram shown:

1. Access the Class Repository pane (from View toolbar tab by selecting Panes and in drop-down menu selecting Class Repository, or if visible from the tabs displayed on left edge of VP window)

2. Use the repository browser to navigate to location of packages relevant for the class to be the main subject of the diagram, for the ScanBase class these are:

   • gda-core.git/uk.ac.gda.core/src

   • gda-core.git/uk.ac.gda.api/src

   Select each package (multiple packages can be selected using Shift or Ctrl key/mouse combinations), right-click and in pop-up follow Reverse “<resources>” to > and select Class Repository (this step is explained in further detail in section Adding imported classes to model above)

3. Now the required packages are in the model use the Class Repository pane to navigate to location of class(es) to be included in diagram, e.g. in GDA version 9.15 ScanBase is located in workspace_git/gda-core.git/uk.ac.gda.core/src/gda/scan/

4. Select class(es) and or complete directories (multiple classes/directories can be selected using Shift or Ctrl key/mouse combinations) and right-click, in pop-up follow Reverse “<className.java>” to > and select New Class Diagram

5. On the displayed Instant Reverse pop-up push button Show Fully Qualified Owner

6. The new class diagram is displayed. To change diagram name to something meaningful select the Property pane (either by selecting from Panes drop-down menu in View toolbar tab or if visible by selecting tab on left edge of VP window). Change the Name property to name required for class diagram.

7. To minimize area required to display the class diagram on the Diagram toolbar tab select Layout and from the pull-down menu select Auto Layout, or other layout suitable for best display of information. To reduce amount of space between diagram elements from same Layout menu select Customized and on Orthogonal tab reduce the Layout Grid Size, e.g. to 30 as shown below:

Depending on the class(es) selected for inclusion in the class diagram the diagram created by the above steps may not be appropriate for inclusion in the GDA documentation, e.g. too many associations, including too many classes that make the diagram too big/complicated to be useful when not used within the dynamic context of Visual Paradigm. To assist with creation of simple diagrams, more appropriate for documentation, and to automatically create diagrams from GDA Java source code, ensuring diagram always reflects the code, a VP Plug-in and accompanying script have been developed, for details please see section Auto generation of Class and Sequence diagrams below.

Once a diagram has been created it can be exported, e.g. for use in this document, by selecting the Project toolbar tab, opening the Export pull-down menu and selecting Active Diagram as Image…. Use the pop-up Save window to select location, file name and file type. For diagrams to be included in this document please use file name ending with _ClassDiagram and file type .png.

1.9.8. Sequence Diagrams

Visual Paradigm can automatically create sequence diagrams from Java source code.

For example, the following MultiScan sequence diagram, showing operation of gda.scan.MultiScan.MultiScan(java.util.List):

Like the example ScanBase class diagram (shown in section Class Diagrams) this uses the VP Project Options set as described in section Project Options and took approximately 5 minutes to create as shown, including Instant Reverse process. No manual adjustment of the diagram elements, e.g. resizing, positioning, etc. has been performed.

In order to create sequence diagrams the src directory, containing the classes to be used must be included in the list of instant reverse paths. I.e. the addition of only workspace_git to the list of Instant Reverse Java resources, as described in section Importing Java source code into Visual Paradigm, is not sufficient to create the above sequence diagram. If an attempt is made to create a diagram without the correct source directories the following error pop-up will be displayed:

Therefore the process to create a sequence diagram starts by adding the required source directories to the instant reverse path:

1. On the Tools toolbar tab under the Code pull-down menu select Instant Reverse

2. On the displayed Instant Reverse window push button Add Source Folder... and in the pop-up file navigation window navigate to and select the src directories, containing the Java class files relevant for the sequence diagram, to add them to the list of instant reverse paths (multiple directories can be selected using Shift/Ctrl mouse/key combinations). E.g. for the above sequence diagram the following directories were added:

   • gda-core.git/uk.ac.gda.api/src

   • da-core.git/uk.ac.gda.core/src

   Resulting in the following being displayed in the Instant Reverse window (with src directories expanded to show contents), note that the two added paths both end in src: Once all required directories have been added to the path push button OK

3. For the current example, as the above directories have already been added to our model, see section Adding imported classes to model, this does not need to be repeated. (The above step has just informed VP where to find the sources for the classes we’re interested in.)

4. Access the Model Explorer pane (from View toolbar tab by selecting Panes and in drop-down menu selecting Model Explorer, or if visible from the tabs displayed on left edge of VP window)

5. In the model browser navigate to the class containing the method that is to be the subject of the sequence diagram, expand the class, select the required method and right-click, on pull-right menu select Reverse “<MethodName>” > and select Sequence Diagram…. For the example diagram the method selected is gda.scan.MultiScan.MultiScan as shown below:

6. On the displayed Instant Reverse Java to Sequence Diagram window, all default options can be left unchanged, e.g: Push button Finish to generate and display the diagram

Once a diagram has been created it can be exported, e.g. for use in this document, by selecting the Project toolbar tab, opening the Export pull-down menu and selecting Active Diagram as Image…. Use the pop-up Save window to select location, file name and file type. For diagrams to be included in this document please use file name ending with _SeqDiagram and file type .png.

1.9.9. Python ‘Class’ Diagrams - Relation Diagrams

It is possible to create class diagrams for Python code from Visual Paradigm using the Tools > Code > Instant Reverse, selecting Python Source as the language and adding the path to the python source.

However it is important to note that Visual Paradigm only picks out the classes contained within the Python files and so if a Python script only contains functions, then it will not appear in the Class Repository. In some cases this is undesirable as you may want to show the import structures for a process and what they depend on which will not be captured by Visual Paradigm. This is certainly the case for the MX Python scripts.

An alternative approach was taken. We use a script contained in the scripts directory called VisParMaker.py to extract this information. Each python script with <name> is considered the class and then the file is parsed and all of the imports are picked out as dependencies. A python file is output with all of the these and this can be used as the input file for the Instant Reverse in Visual Paradigm (see scripts section for more details).

Once imported, the classes will appear in the Class Repository and can be dragged into a New Class Diagram as needed.

NOTES

• IMPORTANT: The only thing that is captured here are the dependencies within the Python script therefore technically this is NOT a class diagram. Instead it is referred to as a Relation Diagram throughout this document. The Relation Diagram’s are identified by a light purple background (as in the example diagram below) to highlight that they are NOT class diagrams. The example shown below (captured for MX grid scan) shows that the lineScanStart_xml.py script imports factory, but it is not itself a class so the user should not go looking for a Python class of this name as it does not exist. Instead they should look for the lineScanStart_xml.py file.

  

• The VisParMaker has an extra feature in that it also picks out any classes that are contained in a Python source file. These are detailed in the diagram as attributes. For example, in the above diagram the script helical_zebra.py imports helical and is imported by factory so the relations between files are clearly demonstrated. But this diagram also shows that it itself contains two ‘real’ classes: ZebraHelicalLineScanRequestHandler and SmarGonZebraHeclicalLineScanRequestHandler which have been identified by the VisParMaker script. This is included as extra information for the user when interpreting these types of diagrams.