SDMetrics home page
The Software Design Metrics tool for the UML
Sitemap

Overview of 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?
Q1.2:Why are my UML design element names not displayed correctly in the element and table view?
Q1.3:I exported data to multiple HTML files. Why can't my web browser display them as a frame set?
Q1.4:Calculating a set of metrics, I get an error message "No elements to calculate metrics for". How come?
Q1.5:The diagram-specific metrics for my UML design are missing from the output. What happened to them?
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?
Q1.7:SDMetics aborts every calculation run with an error message "Unknown trigger type 'ignore'" or "Unknown trigger type 'xmi2assoc'". What can I do?

2. Basic SDMetrics Usage

Q2.1:Can SDMetrics create output files that preserve element names with 16-bit Unicode characters?
Q2.2:I stored my huge XMI file compressed in a zip file. Do I have to uncompress it for measurement?
Q2.3:Where's the printing feature in SDMetrics?
Q2.4:Does SDMetrics support the Object Constraint Language (OCL)?

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

Q4.1:I measured a UML design, and now what? What am I supposed to do with those measures?
Q4.2:Is there a nominal range the metrics should be in to indicate a good system?
Q4.3:There are so many measures. Do I need them all?

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: SDMetics 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.