Working with UML Tools
From nUML
Contents |
Introduction
Unless you're writing your own UML diagramming tool, chances are you will want to process models created with some existing tool.
If you still have time to choose a tool, you must consider picking one that supports the XMI standard, preferably version 2.1, because that's the one nUML uses natively; if that's not possible, you will still be able to read your models, but first you will have to convert them.
Extracting the Model
Some tools, such as MonoUML, use uncompressed XMI as their native file format. However, other tools such as ArgoUML use a compressed directory to store their files. In these cases, the model must be extracted prior any conversion or processing.
If you're not sure if the model is compressed or not, try opening the file with a text editor; if you see garbage, chances are that it's a compressed file. In this case, you may try to extract the file with a zip utility, because this is the preferred file format by most diagramming tools.
Working on GNU/Linux and other Unix-like systems, you can extract the model from the command line with the "unzip" utility:
unzip path_to_file
This extracts all the files. We can extract just the file that contains the model (the rest may be diagrams and other tool-dependent content) with:
unzip path_to_file model_file.xmi
Of course you can also extract the file using a GUI tool, but using the command line is handly when you have to extract and process a model over and over again.
Converting XML files to XMI 2.1
Once the model has been extracted, it can be processed in order to convert it to XMI 2.1.
nUML provides several XSLT files, which can be used to convert models from several versions of XMI to XMI 2.1 (you will find this files in the "extras" folder, from version 0.2 onwards).
The general process, for GNU/Linux and Unix-like systems, is like this:
xsltproc template_file model_file > output_file
xsltproc is available also for MS Windows. You can find more information about xsltproc at its home page.
A better tool for editing and debugging XSLT transforms is TreeBeard. This Java based GUI tool allows you to load and edit the XMI file and the XSLT transform and execute the transform to see the output in a third pane. The output can be saved, which means you don't need xsltproc.
Converting from other file formats
Currently, we only provide import mechanisms for other versions of the XMI standard.
If you write a tool for converting from other file formats, you could share it with the rest of the community. The same applies for bug fixes and other improvements. Please use the infrastructure available at the project page to do so.
Tool specific procedures
MonoUML
MonoUML stores both, model and diagrams, in the same XMI file, which is saved uncompressed as the project file.
Note: since version 0.4, the default behavior is to ignore elements from undeclared namespaces, so the following explanation applies only if you change this setting.
Due to MonoUML uses nUML manipulate UML model data, as long as your model file doesn't contain any diagrams the procedure explained in Manipulating_Models works perfectly. However, if you do have some diagrams and try to read the model, you will get the following exception:
Unhandled Exception: NUml.Xmi2.SerializerNotFoundException: Couldn't find a serializer for namespace 'org.omg.xmi.namespace.UML'
In order to avoid this exception, you must add a serializer for diagrams and another one for the model bridge before processing the file:
using NUml.Xmi2; // ... SerializationDriver ser = new SerializationDriver (); ser.AddSerializer (new MonoUML.DI.Serialization.Serializer()); ser.AddSerializer (new MonoUML.DI.Uml2Bridge.Serialization.Serializer()); ser.AddSerializer (new NUml.Uml2.Serialization.Serializer());
This will get rid of the exception, but beware that the diagrams will appear in the list of deserialized objects.
ArgoUML
An ArgoUML model (not diagrams) can be imported into nUML by using 'Export XMI' and the fromXMI1_2.xslt transform. Code like this should work:
protected void TransformXML ( string source, string destination, string xslt )
{
StreamReader reader;
XPathDocument source_doc;
XslCompiledTransform transform;
XmlTextReader xslt_doc;
XmlTextWriter destination_doc;
reader = new StreamReader (source);
try
{
source_doc = new XPathDocument (reader);
xslt_doc = new XmlTextReader (new StreamReader (xslt));
try
{
destination_doc = new XmlTextWriter (destination, null);
try
{
transform = new XslCompiledTransform ();
transform.Load (xslt_doc);
transform.Transform (source_doc, null, destination_doc);
}
finally
{
destination_doc.Close ();
}
}
finally
{
xslt_doc.Close ();
}
}
finally
{
reader.Close ();
}
}
protected IList ReadModel ( string filename )
{
bool delete;
string transform;
string destination;
SerializationDriver ser;
IList ret;
delete = false;
if (<it_is_an_ArgoUML_file_and_you_need_to_transform>)
{
transform = <nUML_Extras_Directory> + "fromXMI1_2.xslt";
destination = System.IO.Path.GetTempFileName ();
System.IO.File.Delete (destination); // clean up... getting a temporary file name creates the actual file
destination = System.IO.Path.ChangeExtension (destination, ".xml");
TransformXML (filename, destination, transform);
filename = destination;
delete = true;
}
ser = new SerializationDriver ();
ser.AddSerializer (new NUML.Uml2.Serialization.Serializer ());
ret = ser.Deserialize (filename);
if (delete)
System.IO.File.Delete (filename);
return (ret);
}
An alternative way (in *nix systems) is to extract and transform the model directly from the .zargo file:
unzip -p <file>.zargo < <file>.xmi | xsltproc <path_to_extras_dir>/fromXMI1_2.xslt - > <file>.out.xmi
The resulting file can be read by nUML:
SerializationDriver ser = new SerializationDriver (); ser.AddSerializer (new NUml.Uml2.Serialization.Serializer ()); IList modelElements = ser.Deserialize (filename);
This requires the latest version from SVN repository, until version 0.4 is released.
Diffing Two XMI Files
Ever wanted to find out the difference between two XML files? A cool tool from Microsoft called The XML Diff and Patch GUI Tool presents a coloured diff of two XML files. This is perfect for comparing two models.
