5 Running SDMetrics from the Command Line

You can run SDMetrics from the command line or a shell script. This is useful to integrate SDMetrics as part of an automated process.

The command line syntax is:

java sdmetrics.SDMetrics  -xmi xmifile [-proj projfile]  [-customPF pfsetname]
           [-meta mmfile] [-trans transformationfile] [-metrics metricsfile]
           [-filter filterstring]* [-nonmatching] [-ignore]
           [-compare 2ndxmifile] [-mapping mapfile] [-relative]
           [-gHisto] [-gCumDist] [-gKiviat] [-gFormat format]
             [-gHTMLPerDiag] [-gHTMLPerType] [-gHTMLForAll]
             [-gUseFrames] [-gWidth width] [-gHeight height]
           [-model] [-stats] [-relmat] [-rules [-rulefilter filter]] 
           [-nometrics] [-s] [-one] [-f format] basename

The arguments in square brackets [] are optional. When followed by an asterisk (*), the bracket contents can be repeated an arbitrary number of times, otherwise, zero or one occurrences are allowed. The meaning of the arguments is as follows.

Project file settings:

xmi xmifile: XMI file for the design to be analyzed.
proj projfile: name of a project settings file created via the GUI.
SDMetrics reads the project settings file and processes the project files as specified in there.
customPF pfsetname: specifies the name of the project files set to use for the analysis. If not specified, SDMetrics will automatically determine a project file set to use
meta mmfile: file containing the SDMetrics metamodel.
If you do not specify a meta model definition file, the meta model of the project file set is used.
trans transformationfile: file containing the XMI transformations to be used to read the XMI file.
If you do not specify a transformation file, the transformation file of the project file set is used.
metrics metricsfile: file containing the definition of the metrics.
If you do not specify a metrics definition file, the metrics definition of the project file set are used.

Filter Settings:

filter filterstring: adds filter filterstring to the list of filters to apply.
nonmatching: When set, SDMetrics rejects elements that match none of the filters. The default (switch not set) is to reject elements that match at least one of the filter strings.
ignore: When set, links to rejected elements are not considered during metric calculation. The default (switch not set) is to consider links to rejected elements.

Design comparison settings:

compare 2ndxmifile: perform a design comparison with the design specified via the -xmifile or -proj switch, and output the metric deltas. Note that 2ndxmifile contains the second or newer design.
mapping mapfile: file with element mappings to use for the design comparison.
relative: Show deltas as relative percentages in output.

Output file settings:

basename: Base name of the file(s) the output will be written to.
model: additionally create a set of tables containing the UML model. Files will have suffix "MODEL" appended to the base name.
stats: additionally create a set of tables containing the descriptive statistics. Files will have suffix "SD" appended to the base name.
relmat: additionally create a set of tables containing the relation matrices. Files will have suffix "RM" appended to the base name.
rules: additionally create a set of tables containing the design rule violations. Files will have suffix "RULES" appended to the base name.
- rulefilter filter an optional rule filter string specifying the rules to apply.
nometrics: suppress export of metric data. Metric data tables are always created by default, unless you set this switch.
s: sanitized output; when set, model element names are not written to the output files (metric data tables only).
one: one file; when set, each set of tables is written to one file, otherwise each data table is written to a separate file.
f format: format of the output file(s). Admissible formats:
txt: Tab-separated text tables. This is the default if no format is specified.
csv: Comma-separated text tables.
html: HTML files containing the data in HTML tables.
sxc: OpenOffice.org Calc files.
xml: XML spreadsheet files for Microsoft Excel XP.

Graph export settings:

gHisto: additionally export metric histograms. Files will have suffix "HISTO" appended to the base name.
gCumDist: additionally export cumulative distribution graphs for metrics. Files will have suffix "CUMDIST" appended to the base name.
gKiviat: additionally export kiviat diagrams for model elements. Files will have suffix "KIVIAT" appended to the base name.
gFormat format: format for the graphs to generate: SVG (default), PNG, or JPG
gHTMLPerDiag: create one HTML page for each individual graph
gHTMLPerType: create one HTML page for each element type
gHTMLForAll: create one HTML page for all graphs
gUseFrames: use frames for HTML graph pages
gWidth width: width of the graphs in pixels (default: 640)
gHeight height height of the graphs in pixels (default: 400)

Examples:

java sdmetrics.SDMetrics -proj mypsettings.txt -s -f html outfile
Reads the project files and filter settings from file mypsettings.txt and writes the sanitized output to separate HTML files.
java sdmetrics.SDMetrics -xmi myDesign.xmi data
Reads XMI file myDesign.xmi with standard XMI transformations, metamodel, and metrics, and writes the output in separate text files with tab-separated tables (output files start with name data).
java sdmetrics.SDMetrics -xmi myDesign.xmi -rules -rulefilter design -format html data
Reads XMI file myDesign.xmi with standard XMI transformations, metamodel, and metrics, writes the metric data to separate HTML files (output files start with name data), checks the design rules and writes the design rule violations to separate HTML files (output files start with name dataRULES).
java sdmetrics.SDMetrics -xmi myDesign.xmi -metrics myMetrics.xml -filter #.java -filter #.javax -nometrics -stats -one -f sxc dstats
Reads XMI file myDesign.xmi with standard XMI transformations and metamodel, calculates metrics defined in myMetrics.xml, filters element defined in the java and javax packages, and writes the descriptive statistics for the metrics to an OpenOffice.org Calc workbook file named dstats.sxc.
(Note: on some platforms, the # character may have a special meaning and needs to be protected from the shell, usually by preceding it with a backslash or enclosing the filter name in quotes).
java sdmetrics.SDMetrics -xmi myDesign.xmi -filter MyModel.MyPackage -nonmatching -model -one -f csv myDes
Reads XMI file myDesign.xmi with standard XMI transformation and metamodel, filters all elements outside package MyPackage, and writes the metric data to file myDes.csv, and dumps the model to file myDesMODEL.csv.
java sdmetrics.SDMetrics -xmi myOldDesign.xmi -compare myNewDesign.xmi -mappings MyMappings.txt -stats -one -f xml deltas
Reads XMI files myOldDesign.xmi and myNewDesign.xmi, calculates the metric deltas using the element mappings from file MyMappings.txt, and writes the metric deltas and comparison of descriptive statistics to files deltas.xml and deltasDS.xml, respectively.
java sdmetrics.SDMetrics -xmi myDesign.xmi -one -f xml -gHisto -CumDist -gFormat PNG -gHTMLforall -gUseFrames myDes
Reads XMI file myDesign.xmi, writes the metric data to file myDes.xml, creates a set of PNG files with histograms (myDesHISTO_*.png) and cumulative distributions (myDesCUMDIST_*.png) for all metrics, and creates a set of HTML pages with frames that show the graphs (myDesHISTO_index.html, myDesCUMDIST_index.html plus additional HTML navigation pages).

Section 4.16.5 "Behavior"

Contents

Section 6 "Design Measurement"