Jython - Scripting for Modelio

From Modelio Community

Jump to: navigation, search

Modelio provides integrated support of the Jython scripting language for online requests, automation of tasks and easy addition of functionalities. Generally, scripting is writing small programs to help to realize quick tasks however, scripts can also be more complex and provide larger tasks. Here, we'll learn to write Jython scripts for Modelio. It is preferable to know Python syntax and Java language.


The Jython basics

Jython is a Java implementation of Python. So, you can use the Python language to produce scripts for automate tasks, quick requests and also more elaborated programming and to manage Java objects.

Jython official homepage

Python documentation

Jython for Modelio

This documentation describes the usage of Jython for Modelio 2 (The latest version of Modelio 2.1.1 works with Jython 2.5.2). You can check the Jython version used by Modelio using this command "print(sys.version)" on the script view.

Run a Jython script

Before running a script, you need to open the script view by selecting the Views/Show script view command from the Modelio menu. Once the view opened, running a script is pretty easy. You can: - run Jython code from the Modelio commande line - load an existing script file

More information about script view and running scripts.

Reader-friendly script

When you create your own script, it should be friendly to add a header to the script code that contains useful information for those who will read your code but also for you to facilitate the script maintenance. This header should be of the following form:

  1. #
  2. # [Macro name] [Current version]
  3. # [Macro description]
  4. #
  5. # Author:  [Macro author]
  6. #
  7. # Applicable on: [Elements on which the script is applicable]
  8. #
  9. # Version history:
  10. # [Version]		[Date]	[Modifications]

Replace words between brackets by your content. This is an example from the Sort script delivered with Modelio:

  1. #
  2. # Sort  2.0
  3. # This macro sorts the model elements under a Classifier or a Package.
  4. # Classes, interfaces, component, use cases are all classifiers.
  5. #
  6. # Author:  Modeliosoft
  7. #
  8. # Applicable on: Classifier, Package
  9. #
  10. # Version history:
  11. # 1.0   3rd Sept 2009   - creation
  12. # 1.01  7th Sept 2009   - enable the macro on Classifiers
  13. # 1.02  4th March 2011  - fix associations sort to sort only modifiable ones.
  14. # 1.03  1st April 2011  - forces refresh in the explorer
  15. # 1.04  20th May 2011   - enable the macro on Dictionary and RequirementContainers.
  16. # 1.04  20th May 2011   - enable the macro on multi selection.
  17. # 2.0   09th September 2011 - update for Modelio 2.0

Modelio API

In order to work with Modelio, you need to use a specific API to manipulate the model. You can start by reading the following guide Module developer's API guide explaining how to use the different services specific to a particular part of Modelio. Actually, this guide is dedicated to Module developers working with Java but it can easily be transposed to Jython language. In the following tutorials, we will apply some examples from this guide to the Jython scripting context.

In addition to this guide, this is a Javadoc documentation of the API which is helpful to find the necessary methods and fields to work with.

It can be useful to read the metamodel documentation to learn the relations between the model elements and their structure


The "Hello, World" script

We start with the well-known "Hello, World" program. Open a text editor and save the following content into a file HelloWorld.py:

print "Hello, World."

Load the script from Modelio and see the result:

Jython helloworld.jpg

Get information from the model elements

We will see how to interact with Modelio and the UML/BPMN model. We will complete our HelloWorld.py script. First of all, add a header to this script.

  1. #
  2. # Hello World  1.0
  3. # This macro is a "Hello, World." program which permits to become familiar with Jython scripting on Modelio 
  4. #
  5. # Author:  Modelio user
  6. #
  7. # Applicable on: All
  8. #
  9. # Version history:
  10. # 1.0   22nd March 2011   - Creation for the Jython tutorial
  12. print "Hello, World."

Let's see how to get the current selected element(s). We use the selectedElements variable as it is indicated in the script view (See previous screenshot) when you open it. We output the number of selected elements. (If you copy/paste this code please take care that Python is sensitive to the indentation)

  1. if (selectedElements.size() > 0):
  2. 	# str() function is used to convert an int to string
  3. 	print "We selected " + str(selectedElements.size()) + " elements."
  4. else:
  5. 	print "No element has been selected."

Now, with a UML model it is interesting to get information from model elements. Let's continue working with selected elements. Get the metaclass and the name of these elements.

  1. if (selectedElements.size() > 0):
  2. 	# str() function is used to convert an int to string
  3. 	print "We selected " + str(selectedElements.size()) + " elements."
  4. 	for e in selectedElements:
  5. 		print "- " + e.getMetaclassName() + " '" + e.getName() + "'"
  6. else:
  7. 	print "No element has been selected."

Let's see the result if we select 3 elements in a diagram.

Get elements information result

The selectedElements is a Collection of IElement objects. From the metamodel user guide, we learn that Element is the "atomic constituent of a model" [1]. We are talking about "IElement" not "Element"!? Yes, IElement is the Java interface for the Element metaclass (See the Module developer's API guide [2] about the model API naming rules).

On the javadoc documentation, we learn that the methods getMetaclassName() and getName() are defined on IElement object [3].

Search for classes

We search for classes in a project and display their full path in the script view.

First, we create a python function returning the full path of an element by browsing its parent hierarchy.

  1. def getFullName(element):
  2. 	name = element.getName()
  3. 	owner = element.getOwner()
  4. 	if (owner is not None):
  5. 		name = getFullName(owner) + "." + name
  6. 	return name

A Class is a ModelTree (See the inheritance diagram) on which getOwner() is defined ([4]). getOwner() gets the owner association.

Use the findByClass(Class<? extends IElement> metaclass) [5] method to find all objects in the model from their metaclass

  1. elements = modelingSession.findByClass(IClass)

Then, display the results

  1. for e in elements:
  2. 	print "Metaclass: " + e.getMetaclassName() + " - full path: "+getFullName(e)

In practice, you will notice that not only Classes are returned by findByClass(IClass) but also all elements inheriting from Class metaclass. So we could filter the results before to display them:

  1. for e in elements:
  2. 	# Ignore 'Components' and other subclasses of 'Class'
  3. 	if (e.getMetaclassName() == "Class"):
  4. 		print "Metaclass: " + e.getMetaclassName() + " - full path: "+getFullName(e)

This is the complete script:

  1. #
  2. # Find Classes  1.0
  3. #
  4. # Description:
  5. # This script searches for Classes in project and display their full path in Script view.
  6. # Applicable on: Anything
  7. #
  8. # Author:  Modelio user
  9. #
  10. # Applicable on:
  11. # - Element
  12. #
  13. # Version history:
  14. # 1.0  28 Mar 2012   - Creation 
  15. #
  17. def getFullName(element):
  18. 	name = element.getName()
  19. 	owner = element.getOwner()
  20. 	if (owner is not None):
  21. 		name = getFullName(owner) + "." + name
  22. 	return name
  24. elements = modelingSession.findByClass(IClass)
  26. for e in elements:
  27. 	# Ignore 'Components' and other subclasses of 'Class'
  28. 	if (e.getMetaclassName() == "Class"):
  29. 		print "Metaclass: " + e.getMetaclassName() + " - full path: "+getFullName(e)

Get information about Stereotypes present on the selected elements

On UML model elements, we can add stereotypes. We are writing a script getting information about the stereotypes present on selected elements. Before starting we are adding stereotypes to some model elements. Create 2 Classes C1 and C2. On C1, add a Process stereotype which is delivered by default with Modelio under Extensions. For this example, create a Jython stereotype for the Class metaclass (menu MDA/Create a Stereotype...) with icons. This stereotype will appear under Local module in the Add stereotype box. Add this stereotype to C1.

Install the JavaDesigner open source module in your project. Then, on C2 add the Java Class stereotype.

The model is ready. Start writing the script. To get information about stereotypes on an element, we create a function displayStereotypes(element).

  1. def displayStereotypes(element):	
  2. 	stereotypes = element.getExtension()
  3. 	if (stereotypes.size() > 0):
  4. 		print "Stereotype(s) found on " + element.getName() + ": "
  5. 		# for each extended stereotype
  6. 		for stereotype in stereotypes:			
  7. 			print "- " + stereotype.getName() + " ( Module owner: "+ stereotype.getOwner().getOwnerModule().getName() + " )"
  8. 	else:
  9. 		print "No Stereotype found on " + element.getName() + "."
  10. 	print "---------------------------------------"

This function displays information about the Stereotypes present on the given element. Stereotypes are present on ModelElement so we use the getExtension()[6] method to get the list of Stereotypes present in element.

Stereotypes are provided by the Modelio Modeler, modules and your own extensions (present under Local module).

Now, prepare the main program.

  1. print "======== displayStereotypesInformation ========"
  2. if (selectedElements.size() > 0):
  3. 	for element in selectedElements:			
  4. 		if (isinstance(element, IModelElement)):		
  5. 			displayStereotypes(element)
  6. 		else:
  7. 			print "WARNING: The selected element " + element.getName() + "is not a ModelElement."
  8. else:
  9. 	print "No Element has been selected"

isinstance is a Jython function that determines whether an object is an instance of a given class.

This is the complete script:

  1. #
  2. # getStereotypesInformation 1.0
  3. #
  4. # Description:
  5. # This macro allows the get the Stereotypes from the selected model elements.
  6. # Applicable on: ModelElement
  7. #
  8. # Author:  Modeliosoft user
  9. #
  10. # Version history:
  11. # 1.0   28 Mar 2012   - creation
  12. #
  14. # This function displays information about the Stereotypes present on the given element.
  15. def displayStereotypes(element):
  16. 	# for each extended stereotype
  17. 	stereotypes = element.getExtension()
  18. 	if (stereotypes.size() > 0):
  19. 		print "Stereotype(s) found on " + element.getName() + ": "
  20. 		for stereotype in stereotypes:			
  21. 			print "- " + stereotype.getName() + " ( Module owner: "+ stereotype.getOwner().getOwnerModule().getName() + " )"
  22. 	else:
  23. 		print "No Stereotype found on " + element.getName() + "."
  24. 	print "---------------------------------------"
  26. #
  27. # The macro execution starts here
  28. #
  29. print "======== displayStereotypesInformation ========"
  30. if (selectedElements.size() > 0):
  31. 	for element in selectedElements:			
  32. 		if (isinstance(element, IModelElement)):		
  33. 			displayStereotypes(element)
  34. 		else:
  35. 			print "WARNING: The selected element " + element.getName() + "is not a ModelElement."
  36. else:
  37. 	print "No Element has been selected"

This is the result of this script:

Get stereotypes result.png

Distribution of scripts

Using scripts can help to perform some tasks. Several scripts already exist so you can use the existing ones and adapt them to your own needs and you can share your own scripts.

The [Modelio Store] is the main place to exchange scripts.

To submit your own scripts, you can go to the [Jython scripts submit form] and fill it with most information about your scripts. You can submit one script each time.

Get help scripting

If you need help making your scripts or using existing scripts, do not hesitate to contact the Modelio community on its forum. A specific [category is dedicated to Scripts].


Python 2.5 Quick Reference

Personal tools