VP-UML Plug-in Development

Visual Paradigm provides users with an open architecture to extend the functionality of VP-UML, which allows easy retrieval and modification of model data such as diagrams and model elements, and the invocation of built-in functions. Users can develop plug-in, a set of one or more functions written in Java, that adds features or services to VP-UML.

In this tutorial, we are going to develop a plug-in that reads the flow of events of use cases and print the collected information to an HTML file. We will use Eclipse as the Java IDE for implementing the plug-in. Therefore, please get Eclipse ready. You can, however use any other Java IDE you preferred.

Gentting the Plug-in JavaDoc

The Plug-in JavaDoc provides Visual Paradigm plug-in developers with definition of classes, attributes, operations and arguments in the plug-in. We recommend users getting the JavaDoc and incorporating it into the Java project that will be created in the next section. To get the plug-in JavaDoc:

Visit the web page Plug-in API in Visual Paradigm official site.
Click on the link Download JavaDoc of Plug-in API.
Save the zip file to somewhere in your machine.
Extract the zip file.

Implementing the Plug-in

Start Eclipse.
Create a Java project sample.genflowofevents.
In the Java Settings page, set src to be the source folder and classes to be the class folder.
Open the Libraries tab. The jar file openapi.jar in %VP-SUITE-INSTALL-DIR%\lib contains the API for plug-in development. Add it as a library or else your work cannot be compiled.
Expand the node openapi.jar. Select Javadoc location.
Click Edit on the right hand side.
Click Browse in the popup window. Input the path of the extracted zip of JavaDoc. Click OK.
Click Finish in the New Java Project window.
Create a package sample.genflowofevents
In package sample.genflowofevents, create a class GenFlowOfEvents which implements interface VPPlugin. If you do this by Eclipse's code completion feature, two methods loaded an unloaded will be added automatically. If not, add it yourself. If the editor cannot identify the interface VPPlugin, make sure you have added the openapi.jar to project build path.
Create package sample.genflowofevents.actions.

In the package sample.genflowofevents.actions, create a class GenFlowOfEventsActionController which implements the interface VPActionController. This class is made for performing certain action. In this case, it implements the logic of generating flow of events to HTML report. The action can be triggered from user interface.
action controller created

Here are some of the points you should be aware of:

The performAction() method contains the logic of action you want to perform.
The update() method is called before showing the action on screen. You can make use of this method to disable the method before it get shown. In this tutorial we just leave it empty.

Let's fill in the method performAction(). First, we need to prompt user for the destination HTML path. Enter the following code inside performAction():

// get the view manager and the parent component for modal the dialog.
ViewManager viewManager = ApplicationManager.instance().getViewManager();
Component parentFrame = viewManager.getRootFrame();
	
// popup a file chooser for choosing the output file
JFileChooser fileChooser = viewManager.createJFileChooser();
fileChooser.setFileFilter(new FileFilter() {
	
	public String getDescription() {
		return "*.htm";
	}
	
	public boolean accept(File file) {
		return file.isDirectory() || file.getName().toLowerCase().endsWith(".htm");
	}
		
});
fileChooser.showSaveDialog(parentFrame);
File file = fileChooser.getSelectedFile();

As we have incorporated the JavaDoc, we can read the description of class and methods when using code completion.

Here are some of the points you should be aware of:

ViewManager is responsible for working with user interface. For example, you may call it to print data to message pane.
Instead of initiating a File Chooser directly, we recommend you use ViewManager.createJFileChooser instead.

After we have prompted the user for the path of HTML, we can proceed with retrieving the flow of events of use cases and generating the data to HTML. Fill in the remaining part of the performAction() method.

if (file!=null && !file.isDirectory()) {
	String htmlContent = "";
	String result = "";
			
	// Retrieve all use cases from project
	ProjectManager projectManager = ApplicationManager.instance().getProjectManager();
	IModelElement[] models = 
projectManager.getProject().toModelElementArray(IModelElementFactory.MODEL_TYPE_USE_CASE);

	// Retrieve an HTML string of flow of events info from every use case
	for (int i = 0; i < models.length; i++) {
		IModelElement modelElement = models[i];
		IUseCase useCase = (IUseCase)modelElement;
		htmlContent += generate(useCase);
	}
			
	// write to file
	try {
		FileWriter writer = new FileWriter(fileChooser.getSelectedFile());
		System.out.println(file.getAbsolutePath());
		writer.write(htmlContent);
		writer.close();
		result = "Success! HTML generated to "+file.getAbsolutePath();
	} catch (IOException e) {
	}
			
	// show the generation result
	viewManager.showMessageDialog(parentFrame, result);
}

Here are some of the points you should be aware of:

ProjectManager.getProject().toModelElementArray(IModelElementFactory.MODEL_TYPE_USE_CASE) enables you to get an array of specific type of model element, such as use case.
IModelElementFactory contains constants of element type names
IModelElement refers to a model element in project, such as a use case, an actor, etc.
You may type-cast an IModelElement into a concrete type class, such as IUseCase, IActor, etc.

Add and implement another method generate(), which takes IUseCase as parameter, prepares the HTML string and returns the result back to the method that calls it.

public String generate(IUseCase useCase) {
	String content = "";
		
	// Retrieve flow of events sets from use case. Each IStepContainer is a set of flow of
events
	IStepContainer[] stepContainers = useCase.toStepContainerArray();
	for (int i = 0; i < stepContainers.length; i++) {
		IStepContainer stepContainer = stepContainers[i];
			
		// Print the name of use case and flow of events to HTML string
		content += "<table border=\"1\" width=\"500\"><tr><th>" + useCase.getName()
 + " - " + stepContainer.getName() + "</th></tr>";
			
		// Print the flow of events content to HTML string
		IStep[] stepArray = stepContainer.toStepArray();
		for (int j = 0; j < stepArray.length; j++) {
			IStep step = stepArray[j];
			content += "<tr><td>"+ (j+1) + ". " + step.getName()+"</td></tr>";
		}
		content += "</table><br>";
	}
		
	return content;
		
}

Here are some of the points you should be aware of:

IStepContainer refers to a set of flow of events. Each use case can have zero or more than one set of flow of events.
IStep refers to a step (i.e. a row) inside a flow of events set.

The coding part is done. If you find the code cannot be compiled, please make sure you have added openapi.jar into the build path.

Deploying the Plug-in

Create an XML file plugin.xml under the project root.

Fill in the XML file as shown below:

<plugin
	id="sample.genflowofevents"
	name="Generate Flow of Events Report"
	description="Generate an HTML report of use case flow of events."
	provider="Visual Paradigm"
	class="sample.genflowofevents.GenFlowOfEvents">
        
	<actionSets>
		<actionSet id="sample.genflowofevents.actionset">
			<action 
				id="sample.genflowofevents.actions.GenFlowOfEventsActionController"
				actionType="generalAction"
				label="Generate Flow of Events Report"
				tooltip="Generate Flow of Events Report"
				style="normal"
				menuPath="Tools/Report">
				<actionController 
class="sample.genflowofevents.actions.GenFlowOfEventsActionController"/>
			</action>
		</actionSet>
	</actionSets>
</plugin>

Here is a description of the content of plugin.xml:
plugin xml overview

No.	Description
1	A text for identifying this plug-in. You may develop multiple plug-ins. Each plug-in must have a unique id defined.
2	The name of plug-in.
3	The description of plug-in.
4	The person/organization who develop this plug-in.
5	The fully qualified class name of the plug-in class, which is the class that implements the VPPlugin class, offering the load and unload logic.
6	Actionsets describe the possible ways of invoking the plug-in. An action can be added into MenuBar and Toolbar, by setting @menuPath=... and @toolbarPath=... If your plugin have actions on menu bar and diagram's popup menu. For menu bar's actions, the actions are defined in <actionSet>; For toolbar's actions the actions are defined in <contextSensitiveActionSet>.
7	A unique value for identifying the action set.
8	A unique value for identifying the action.
9	Define the type of action: [generalAction \| shapeAction \| connectorAction]. generalAction: The simple action that may be added on menu bar/toolbar/diagram popup menu. You are required to specify the <actionController...> for this action (ref to point 14). shapeAction: The action used to create CustomShape. You are required to specify the <shapeCreatorInfo...> connectorAction: The action used to create CustomConnector. You are required to specify a set of <connectionRule...>
10	The menu item text.
11	Tooltip is the text that display when moving mouse pointer over a toolbar button.
12	Specify the menu item is Normal button or Toggle (Checkbox) button. [normal \| toggle]
13	The position where the menu/toolbar button will be presented. In this case, the menu will be placed under the Tools menu, after the menu Report.
14	The fully qualified class name of the class that implements VPActionController, for showing what and how to perform the action.

It's time to deploy the plug-in into your VP Suite installation, to make it available in VP-UML. Create a folder plug-ins in the VP Suite installation folder. (E.g. C:\Program Files\VP Suite\plugins)
Copy the Java project folder sample.genflowofevents into the plugins folder. You should obtain folder structure like this: C:\Program Files\VP Suite\plugins\sample.genflowofevents\classes.

Running the Plug-in

Start VP-UML in a new workspace. Create a new project by selecting File > New Project from the pop-up menu. Name the project Test Plug-in and click Create Blank Project.
Draw a simple use case diagram with 2 use cases Post Topic and Reply Topic, like this:
Right click on the use case Post Topic and select Open Use Case Details... from the pop-up menu.
Open the Flow of Events tab. Enter the steps: 1. Click [New Post], 2. Enter the contents, 3. Click [Submit]
At the top right of flow of events, click the Next button to move to the use case Reply Topic.
Enter the flow of events for use case Reply Topic: 1. Open a post, 2. Click [Reply], 3. Enter the contents, 4. Click [Submit]
Let's test our plug-in. Select Tools > Generate Flow of Events Report from the main menu.
You are prompted for the output path of the HTML. Specify the file path in Save window and click Save. The HTML file will be saved to the specified location.