Package sdmetrics.app

This package contains classes to calculate a set of metrics for an XMI file, check design rules, compare two designs, calculate relation matrices, and access and export the data and graphs to external files.

See:
Description

Interface Summary

DataTable	This interface is used to access all kinds of measurement data (metrics, descriptive statistics, design rule violations, relation matrices).
DiagKiviat.Listener	Listener for mouse events in the diagram.
ExportFormatter	Interface to provide file format specific text markup to export measurement data tables in a particular file format.
OverwriteConfirmation	Prompt user to confirm file overwrite.
SDMessageHandler	Interface defining callback methods used to output messages about metrics calculation progress and errors, and notify the caller when calculation has completed.

Class Summary

CalcRunner	Helper class to run a metric calculation in its own thread.
CommandLineProcessor	Class to process an SDMetrics command line, and initiate metrics calculation and data export as specified by the command line options.
Controller	An instance of Controller is used to start the metrics calculation and retrieve the metric data.
DataExporter	Class that implements the data export feature.
DescStats	Class to calculate and provide descriptive statistics for the metrics.
DesignComparator	Compare the design metrics for two designs.
DiagHistogram	Class to draw a histogram or cumulative distribution for a metric.
DiagKiviat	Class to draw a kiviat diagram for a model element.
ElementPoolAdapter	Provide a tabular view of the analyzed UML design.
ElementTreeNode	Tree node that represents a model element in a Swing JTree.
ExportFormatterFactory	Object that knows all available existing file export formats by their extensions.
GraphExporter	Class to export the JPEG, PNG, and SVG graphs and optionally create the HTML files showing the graphs.
MeasurementCatalog	Provide the information of the measurement catalog.
ProjectSettings	Class to store project settings for XMI and XML source files, filter settings.
RelMatrixAdapter	This class is an adapter to start the calculation of a set of relation matrices and present them via the DataTable interface.
RuleCheckAdapter	Class to start the rule checking and provide a tabular view of the design rule violations.
TableView	Class to provide a tabular view of the design measurement data.
TreeView	Class to generate a set of trees of ElementTreeNode that can be used to create a Swing JTree.
TreeViewCC	Class to provide the tree representations of connected components.
TreeViewCycles	Class to provide the tree representations of cycles.
XMLPeeker	Peeks into an XML file to determine if it is an SDMetrics Project File, and if so, what type of file.

Package sdmetrics.app Description

This package contains classes to calculate a set of metrics for an XMI file, check design rules, compare two designs, calculate relation matrices, and access and export the data and graphs to external files.

The following tutorial takes a "happy path" through an ongoing example, showing you step by step how to

• Calculate a set of metrics and access the metric data,
• check the design rules for a UML model,
• calculate relation matrices,
• compare two designs,
• export data tables to files.

1. Set up your project settings.

   ProjectSettings ps=new ProjectSettings();
   ps.setXMISource("your_xmi_file_to_analyze.xmi");
   // In this example, we use custom metrics and the default
   // metamodel and XMI transformations
   ps.setMetricsFile("your_metric_definition_file.xml");
   ps.useMetricsDefault(false);
   ps.useMetaDefault(true);
   ps.useTransDefault(true);
   

2. Get the object that knows the default project files. Instead of MyParameters, you would provide your own implementation of the AppParameters interface.

   AppParameters ap=MyParameters.getInstance();
   

3. Provide an object to handle progress messages and errors, e.g.:

   class MyMsgHandler implements SDMessageHandler {
   	public void finishedComputation() { } // can be empty for synchronous calls
   	public void message(String msg, int progress) {
   		if(msg!=null) {
   			System.out.print(msg);
   			if(progress>=0)
   				System.out.print(" ("+progress+"% done)");
   			System.out.println();
   		}
   	}
   	public void error(String err) { System.err.println(err); }
   }
   
   SDMessageHandler smh = new MyMsgHandler();
   

4. Create a controller object and calculate the metrics.

   Controller c = new Controller(smh,ap);
   boolean success=c.doproject(ps);
   

   This will read the XMI file and calculate the metrics. It takes a few seconds for small and mid-sized XMI files (15MB or less), and up to a minute for large XMI files (50MB).
   See the documentation of packages sdmetrics.model and sdmetrics.metrics to learn what is happening behind the scenes.

   To maintain a responsive GUI during a lengthy calculation, you may want to invoke method doproject() asynchronously in its own thread. This is easily done with the helper class CalcRunner:

   CalcRunner runner = new CalcRunner(c,ps);
   runner.run();
   

   The remainder of the code examples would then be in the method finishedComputation() of your message handler.

5. Get metric data and descriptive statistics from the controller.
   

   TableView tv = c.getMetricData();
   DescStats ds = c.getDescStats();
   

   Class TableView implements the DataTable interface; you can access its contents e.g., as follows:

   for(int table=0; table<tv.getNumberOfTables();table++) {
   	for(int row=0; row<tv.getNumberOfRows(table);row++) {
   		System.out.println("Metrics for element"+tv.getRowName(table,row));
   		for(int col=0; col<tv.getNumberOfColumns(table);col++)
   			System.out.println("Metric :"+tv.getColumnName(table,col)+
   				"Value: "+tv.getValueAt(table,row,col));
   	}
   }
   

6. Use the DataExporter to export data to a file. For instance, to write the metric data and descriptive statistics each to a single .txt file:

   ExportFormatterFactory efff=new ExportFormatterFactory(ap);
   ExportFormatter txt=efff.getExportFormatter("txt");
   DataExporter dex=new DataExporter(smh, ap);
   dex.export(tv,"Metric data","file_to_write_metrics_to",true,false,txt);
   dex.export(ds.getDataTable(),"Desc. statistics","your_ds_file",true,false,txt);
   

7. Check design rules and write violations to a file:

   RuleCheckAdapter rca = c.getRuleCheckAdapter();
   rca.setMessageHandler(smh);
   success=rca.checkRules(0,80); // Have progress bar percentages grow from 0 to 80 percent
   if(success)
   	dex.export(rca,"Design Rules","your_output_filename",true,false,txt);
   

   Design rule checking usually only takes a few seconds, even for large XMI files.
   Again, when performing the rule checking asynchronously, provide the RuleCheckAdapter with a message handler that deals with the results of the rule checking in its method finishedComputation().

8. Calculate relation matrices
   This follows the exact same scheme as the design rule checking:

   RelMatrixAdapter rma =c.getRelationMatrixAdapter();
   rma.setMessageHandler(smh);
   success=rma.calculateMatrices(80,100); // Have progress bar percentages grow from 80 to 100 percent
   dex.export(rma,"Relation Matrices","your_output_filename",true,false,txt);
   

9. Compare designs.
   To compare the metric data of two designs, calculate the metrics and descriptive statistics for the two designs, as described above.
   We assume the variables tv_first and tv_second reference the TableView objects for the first and second design, and ds_first and ds_second the DescStats objects. Then:

   DesignComparator dc = new DesignComparator();
   dc.setRelative(false); // or true for relative deltas.
   // Element mappings must always be set
   dc.setMappings(element_names_for_first_design,mapped_element_names_in_second_design);
   success=dc.compareDesigns(tv_first,ds_first,tv_second,ds_second);
   if(!success)
   	smh.error(dc.getErrorMsg());
   else {
   	dex.export(dc,"Metric deltas","your_metric_delta_file",true,false,txt);
   	dex.export(dc.getDeltaDescStats(), "Comparative descriptive statistics",
   		"your_comp_ds_file",true,false,txt);
   }
   

   Performing the design comparison usually takes less than a couple of seconds, even for large designs. The design comparator implements the DataTable interface to access the metric deltas.