MagicDraw QVT plugin contains jsr-223 compliant QVT script engine that lets user to run
QVT transformations from Macros Engine, Simulation plugins or script language supported by MagicDraw.
1. Installation
To install QVT plugin:
1. From the Help main menu in MagicDraw, choose Resource/Plugin Manager.
2. Check for available updates and new resources.
3. Select checkbox near the QVT Plugin and click Download/Install.
4. Restart MagicDraw.
For MagicDraw 17.0 (not MagicDraw 17.0 SP1 and higher) you should add
-Dorg.eclipse.emf.ecore.EPackage.Registry.INSTANCE=org.eclipse.emf.ecore.impl.EPackageRegistryImpl
property into mduml.properties file that can be found in <MagicDraw install dir>\bin directory. This forces EMF
to use a non-delegating global EPackage registry, otherwise transformations will fail.
To check if QVT Operational engine was installed, go to Tools->Macros->Create Macros. In Create Macros
window Macro Language drop down should contain QVT Operational as language.
2. Usage
a) From Macros Engine.
For quick start please folow the below sample.
To start QVT Change Root Element Name sample:
1)Install QVT plugin and restart MagicDraw.
2)Go to Tools > Macros > Organize Macros... The Organize Macros dialog will open.
3)Use the Add button in the Organize Macros dialog to add a macro and its information in the Macro Information dialog.
As Macro Language choose QVT Operational;
for File brows to <MagicDraw install dir>\samples\ChangeRootElementName.qvto;
click Add to specify the arguments of the macro:
Name | Type | Array
-----------------------------
model | string | false
element | string | false
Click OK to save the information.
4)Open Any MagicDraw project.
5)Click Tools > Macros > Organize Macros.... The Organize Macros dialog will open. Select a macro from the table and click Run.
6)Macro Arguments Dialog will apear. Spcify arguments for parameters:
Parameter | Value
-----------------------
model | md:model
element | md:element
7) The macro is executed and root element name is changed.
For more information how to create macro (note: QVT Operational will be used as macro) please refer to
"MagicDraw MacroEngine UserGuide.pdf" that can be found in <MagicDraw install dir>\manual directory.
Note: For macro parameter values special string ids are used to refer to actual java object that extracts model elements
used in transformation. For example parameter value 'md:model' will refer to current MagicDraw open project.
Macros parameter name must correspond to actual parameter name in script transformation(...) method signature.
Macros parameter type is String and value is special id.
There is a possibility to define your own parameters.
b) Creating script in any MagicDraw supported scripting language (most flexible way). To call QVT transformation
from script use jsr-223 ScriptEngine interface:
ScriptEngineManager manager = new ScriptEngineManager();
ScriptEngine qvtEngine = manager.getEngineByName("QVTO");
qvtEngine.put("param1", value1);
qvtEngine.put("param2", value2);
qvtEngine.put(ScriptEngine.FILENAME, "path to script file");
try
{
qvtEngine.eval((String) null);
Resource resource = resourceSet.createResource(URI.createFileURI("pim.rdb"));
List<EObject> attribute = (List<EObject>)qvtEngine.get("inout/out param name");
resource.getContents().add(attribute.get(0));
}
catch (ScriptException e)
{
e.printStackTrace();
}
You should be able to run script not only from file but by directly passing script content as
parameter to engine:
qvtEngine.eval("script content");
Parameters passed to engine are mapped to transformation parameters by name. If transformation
has parameter with name 'model', you should put value to QVT engine with same name:
qvtEngine.put("model", some value).
Following parameter value types are supported: String, EObject, Collection<EObject> and
ModelExtent. Parameter with value type string has special usage. This parameter's value is
not used directly by transformation but instead is used to locate object of type QVTParameter.
Found object will contain code to extract actual parameter value that is passed to
transformation. For example it is defined MDModelParameter class with name 'md:model' that returns
current project model as value. By putting parameter qvtEngine.put("model", "md:model")
it is told engine to locate QVTParameter in QVTParameterRegistry by 'md:model' name and call
getValue() method to extract actual parameter value. This is useful when QVT transformations
are run as macros in MagicDraw.
For QVT engine there are defined couple engine specific parameters: QVTO_EXECUTION_CONTEXT, QVTO_E_PACKAGE_REGISTRY
and QVTO_SCRIPT_NAME. You can set them as normal parameters to engine:
qvtEngine.put(QVTEngineConstants.QVTO_EXECUTION_CONTEXT, executionContext);
With QVTO_EXECUTION_CONTEXT parameter you can pass custom ExecutionContext to be used by engine.
With QVTO_E_PACKAGE_REGISTRY parameter you can set EPackage.Registry for compiler.
With QVTO_SCRIPT_NAME parameter you can set the name of in-memory script. That name will be used to construct
script URI. If you omit this property, ScriptEngine.FILENAME property will be used to determine name of
the script. If this property is null too, default value 'QVTOScript' will be used.
c) running script from Simulation toolkit plugin. It is run as any other MagicDraw supported script.
For more details please refer to Simulation toolkit plugin documentation.
3. Session handling
Every modification in MagicDraw model must be done in MagicDraw specific session. QVT transformation engine
is not an exception. Therefore it is created MagicDraw specific Script engine factory MDQVTScriptEngineFactory
that will create proxy around QVT ScriptEngine implementation. The proxy code handle all MD session details
(creates/closes/joins session). The session is handled only for QVT ScriptEngine eval(..) methods.
By default MDQVTScriptEngineFactory is created as QVT ScriptEngine factory. If you want to use factory without
MagicDraw session code, specify QVTScriptEngineFactory in javax.script.ScriptEngineFactory file.
4. Limitations
Current QVT script engine implementation binds only those parameters that are specified in
transformation definition (signature).