Overview of Questions
1. I have a problem with SDMetrics
2. Basic SDMetrics Usage
3. Advanced SDMetrics Usage
| Q3.1: | I want to modify the project files (metamodel, metric definitions, XMI transformations). Where are those files? |
| Q3.2: | What XMI parser does SDMetrics use? |
4. General measurement issues
Answers to the questions
1. I have a problem with SDMetrics
Q1.1: SDMetrics reports metrics to be zero
when they shouldn't be. What's the matter?
A: Most likely, SDMetrics does not properly extract some model
elements from your XMI file. This happens when the UML metamodel of
your modeling tool deviates from the official metamodels, or the modeling
tool produces non-standard XMI. In that case, SDMetrics requires special metamodel
and/or XMI transformation files that are tailored to the
idiosyncrasies of that particular modeling tool. Check the project files download page if there already
are specialized project files for your tool. If not,
contact me about it. Please enclose a small
sample XMI file and ideally a screenshot of the corresponding diagram
in your mail, as I do not have access to every UML modeling tool out
there on the market. If you wish, you can also take matters in your
own hands: Section 7 of the user
manual describes how you can write your own custom project files.
Q1.2: The UML design element names are not
displayed correctly in the views, only some weird
goobledygook. What happened?
A: Most likely this is due to the file encoding of your
XMI file. Your model element names contain characters that cannot be
represented with the XMI file's file encoding. Check the manual of
your UML modeling tool if it possible to specify a different
file encoding for the XMI export (e.g, Unicode UTF-16).
If this is not possible with your XMI exporter, you should
avoid using special characters in your element names.
Q1.3: I exported data to multiple HTML files. Why can't my web browser
display them as a frame set?
A: Up to version 2.1, SDMetrics enhanced the HTML frame set with
XML code that allows to import all data files at once in a single operation
into Microsoft Office 2002. This code, however, prevents some browsers from
displaying the frame set properly. The 'enhanced HTML' feature has been
removed in version 2.2. Use the XML output format for data export
to Excel instead.
Q1.4: Calculating a set of metrics, I get an error message "No
elements to calculate metrics for". How come?
A: Check your filter settings: maybe you filtered all elements?
A: Check your project file settings: XMI Source File, metamodel,
XMI transformations etc. correct?
Q1.5: The diagram-specific metrics for my UML design are missing from
the output. What happened to them?
A: Your UML modeling tool uses a proprietary solution to store
diagram layout information in the XMI file. SDMetrics currently
supports diagram-specific metrics for tools supporting the Diagram
Interchange format of UML2, as well as Rational Rose and compatible
tools (e.g. Together, Enterprise Architect), and MagicDraw. Unless
your modeling tool stores diagram information outside the XMI file
(e.g. Describe 6.x), there is a good chance that SDMetrics'
XMI import can be customized to support diagram-specific metrics for
your design tool, too.
Q1.6: Calculating a set of metrics, I get
an error message saying that the file "is not an XMI file", or SDMetrics
"could not determine the XMI version for file", or that there is
"no matching project file entry for XMI version XYZ". Now what?
A:
When SDMetrics reads an XMI file, it tries to determine the XMI version
of the file and selects the appropriate
project file set to process the XMI
file. In your case, SDMetrics could not determine the XMI version, or
it found no project file set for the XMI file.
- Check in the project file settings dialog that you specified the correct XMI input file.
- Specify a custom project file set to use in the project file settings dialog.
SDMetrics V2.3 and earlier do not recognize XMI 2.4 (or higher) files. To analyze such files, explicitly select the "Default UML 2.x and XMI 2.0/2.1" project file set. Or update to the current version of SDMetrics.
Q1.7: SDMetrics aborts every calculation run
with an error message "Unknown trigger type 'ignore'" or
"Unknown trigger type 'xmi2assoc'". What can I do?
A: This problem occurs with SDMetrics Versions 2.2 and 2.3 when the
default locale of the Java VM is Turkish (tr-TR). It is caused by uppercase
conversion of the character 'i', which does not yield 'I' in the Turkish locale.
Set the default locale of the VM to English when you start SDMetrics:
java -Duser.language=en -Duser.region=EN -jar SDMetrics.jar
Or update to SDMetrics 2.31 or later.
2. Basic SDMetrics Usage
Q2.1: My UML design element names contain 16-bit Unicode
characters. Can SDMetrics create Unicode output files that preserve
the element names?
A: Yes. Since SDMetrics 2.1, the output file encoding is
configurable, see the description of the
output preferences settings in the user manual.
If you are using SDMetrics 2.02 or earlier: These versions of SDMetrics create
their data output files using the default
character set of the Java Virtual Machine. You can specify the default
character set when you invoke SDMetrics with the switch
"-Dfile.encoding", for example for 16-bit Unicode:
java -Dfile.encoding=UTF-16 sdmetrics.SDMetrics
Q2.2: I stored my huge XMI file compressed in a zip file. Do I have to
uncompress it for measurement?
A: No, you can access files in a zip archive. But you have to
enter the file name manually. Start the file name with
'jar:', followed by the name of the zip archive, followed by
an exclamation mark '!', followed by the name of the XMI file
in the archive.
For example, if your zip archive resides at
/MyFiles/Design.zip and contains an XMI file
/xmi/design.xmi, enter the following file name:
jar:/MyFiles/Design.zip!/xmi/Design.xmi.
Q2.3: Where's the printing feature in SDMetrics?
A: There is none. Save the trees! If you really need
to print, spreadsheet or
statistical software packages usually provide excellent support
for printing, with many output formatting features for optimal results.
Simply import the data in such a package and print from there, using all the
bells and whistles.
Q2.4: Does SDMetrics support the Object Constraint Language
(OCL)?
A: As of yet, no. There are two aspects how SDMetrics could
incorporate the OCL:
- Consider OCL expressions for the measurement of structural properties. OCL expressions as part of the UML model being analyzed contribute to the size, cohesion, complexity, and coupling of model elements containing these expressions. SDMetrics may support this in future releases.
- Use OCL to define design rules for automated checking. OCL as part of the UML standard is naturally suited to define design rules. The well-formedness rules of the UML are mostly expressed in OCL. SDMetrics does not use OCL for performance reasons. SDMetrics' design rule definitions are prescriptive, which allows for more efficient checks than OCL's declarative nature. For example, rules involving the detection of cycles in dependency graphs use a computationally optimal algorithm that could not be expressed in OCL.
3. Advanced SDMetrics Usage
Q3.1: I want to modify the project files (metamodel, metric
definitions, XMI transformations). Where are those files?
Short A: You can download the latest version of the project files
here.
Long A: After installation of SDMetrics, those files are contained in
the SDMetrics.jar file. They are named metamodel.xml and metrics.xml
for UML 1.4, metamodel2.xml and metrics2.xml for UML 2, and
xmiTrans*.xml (* being a placeholder for the UML or XMI version). If
you don't want to download the latest files from the web, you can use
jar or your favorite zip utility to extract the files from
SDMetrics.jar.
Q3.2: What XMI parser does SDMetrics use?
A: SDMetrics uses a SAX2 compliant XML parser (provided by your JRE),
with a proprietary SAX event handler that processes the XML tags as specified in
the "XMI Transformations" and "metamodel" configuration files (see Custom XMI Import) to extract the model
elements contained in the XMI file.
The Java API
and source code of the XMI parser are available.
4. General design measurement issues
Q4.1: I measured a UML design, and now what? What am I supposed to
do with those measures?
A: Good question that should be asked even before thinking about using
design measurement. The resources section
contains a discussion of the usefulness of design measurement,
including pointers to usage scenarios and useful data analysis techniques.
Q4.2: Is there a nominal range the metrics should be in to indicate
a high quality system?
A: No. From empirical studies we know that the actual relationship
between design metrics and system quality is complex, and very context
sensitive. Depending on factors such as overall project size,
development processes, project standards, and developer experience, a
metric can be an excellent quality indicator on one project, a weak
quality indicator on another, and completely useless on a third
project. While some metrics have been shown to be consistently good
quality indicators across environments, others only work occasionally.
Therefore, it is not possible to specify a nominal range for each
metric, and expect this to always indicate a high quality system.
Q4.3: There are so many measures. Do I need them all?
A: Probably not. Expect some redundancy among the measures. The
problem is that, a priori, it is impossible to know which measures are
redundant, and this is also different from environment to environment.
You can perform a dimensional analysis to
identify a minimal, non-redundant set of measures tailored to your
development practices.
5. The even bigger picture
Q5.1: So what is it all about, I mean, life, the universe and everything?
A: While the answer to this question was for some time considered to be
inextricably involved with Jackie Robinson's jersey number, a gentleman
from Canada has finally penetrated to the very core of the matter and was kind
enough to share his findings
with the rest of us. And we at SDMetrics strongly agree. Skip to the 6:00 minute
mark if you get impatient.