sdmetrics.app
Class DesignComparator

java.lang.Object
  |
  +--sdmetrics.app.DesignComparator

All Implemented Interfaces:

DataTable

public class DesignComparator

extends java.lang.Object

implements DataTable

Compare the design metrics for two designs. For instance, two subsequent versions of a model in an iterative development process, or two design alternatives. The two designs must use the same set of metrics and the same set of percentiles. The class maps by name each table of the new design onto a table of the old design. Within each table, each row of the new table is mapped onto a row of the old table.

Use this class as follows:

• Use two different Controller objects to obtain the metric data and descriptive statistics of the two designs to compare.
• Call setMappings() to define element mappings between the two designs to compare.
• Invoke compareDesigns() with the metric data and descriptive statistics for the two designs.
• You can then access the metric deltas via the DataTable interface. Rows are the model elements, columns are the metric deltas. The metric delta tables have an additional column "AD_Status" added as the last column, with a string to indicate the status of the design element ("A" for added in the new design, "D" for deleted from the old design, empty string if the element is present in both designs).
• You can also access the comparative descriptive statistics via getDeltaDescStats().

Field Summary

static int	ADDED Constant indicating an added element/table row.
static int	DELETED Constant indicating a deleted element/table row.
static java.lang.String	fids First line of a element mappings file, for file identification.
static int	UNCHANGED Constant indicating matched element/table row present in both designs.

Constructor Summary

DesignComparator()

Method Summary

boolean	compareDesigns(DataTable om, DescStats od, DataTable nm, DescStats nd) Perform comparison of two designs.
int	elementStatus(int index, int row) Return status (added/deleted/matched) of a design element.
java.lang.String	getColumnDescription(int index, int col) Get the description for a metric in the table.
java.lang.String	getColumnName(int index, int col) Get the name of a specific metric in the table.
DataTable	getDeltaDescStats() Provide access to descriptive statistics deltas.
java.lang.String	getErrorMsg() Obtain an error description when design comparison has failed.
int	getNumberOfColumns(int index) Get the number of metrics for a metric delta table.
int	getNumberOfRows(int index) Get the number of design elements (rows) on display in a specified table.
int	getNumberOfTables() Returns the number of available tables.
java.lang.String	getRowName(int index, int row) Get the name of the model element at a specific row.
java.lang.String	getTableName(int index) Returns the name of a table.
int	getTypeID(int index) Return the metamodel type ID of the elements of a table.
java.lang.Object	getValueAt(int index, int row, int col) Return the metric delta for a particular design element and metric.
static void	loadMappings(java.lang.String filename, java.util.ArrayList first, java.util.ArrayList second) Load an element mapping file.
static void	saveMappings(java.lang.String filename, java.util.ArrayList first, java.util.ArrayList second) Save element mappings to a file.
void	setMappings(java.util.ArrayList first, java.util.ArrayList second) Set user defined element mappings to use for design comparison.
void	setRelative(boolean b) Toggle whether to display absolute or relative metric deltas.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DELETED

public static final int DELETED

Constant indicating a deleted element/table row.

See Also:

Constant Field Values

ADDED

public static final int ADDED

Constant indicating an added element/table row.

See Also:

Constant Field Values

UNCHANGED

public static final int UNCHANGED

Constant indicating matched element/table row present in both designs.

See Also:

Constant Field Values

fids

public static final java.lang.String fids

First line of a element mappings file, for file identification.

See Also:

Constant Field Values

Constructor Detail

DesignComparator

public DesignComparator()

Method Detail

compareDesigns

public boolean compareDesigns(DataTable om,
                              DescStats od,
                              DataTable nm,
                              DescStats nd)

Perform comparison of two designs. Designs must use the same set of metrics and same set of percentiles. Upon success, metric deltas may be obtained via the DataTable interface provided by the class. Upon failure, an error description may be obtained from getErrorMsg(). A failure only occurs if the designs to compare use different metrics or percentiles.

Parameters:

om - Metric data for first or older design.

od - Descriptive statistics for first or older design.

nm - Metric data for second or newer design.

nd - Descriptive statistics for second or newer design.

Returns:

true if designs were successfully compared, false if the designs use different sets of metrics or percentiles.

getDeltaDescStats

public DataTable getDeltaDescStats()

Provide access to descriptive statistics deltas.

Returns:

An object containing the descriptive statistics deltas for output.

getErrorMsg

public java.lang.String getErrorMsg()

Obtain an error description when design comparison has failed.

Returns:

String describing the error(s) that occurred.

setRelative

public void setRelative(boolean b)

Toggle whether to display absolute or relative metric deltas.

Parameters:

b - true if relative metric deltas are to be shown, else false.

setMappings

public void setMappings(java.util.ArrayList first,
                        java.util.ArrayList second)

Set user defined element mappings to use for design comparison. The two arrays must have the same size. Elements with the same index are corresponding.

Parameters:

first - Element names to map in the first design.

second - Element names to map onto in the second design.

elementStatus

public int elementStatus(int index,
                         int row)

Return status (added/deleted/matched) of a design element.

Parameters:

index - Index of the table.

row - Row number of the design element.

Returns:

ADDED if element is only present in the second (newer) design, DELETED if element is only present in the first (older) design, UNCHANGED if element is present in both designs.

getNumberOfTables

public int getNumberOfTables()

Description copied from interface: DataTable

Returns the number of available tables.

Specified by:

getNumberOfTables in interface DataTable

Returns:

The number of tables, n. Valid table indices run from 0 to n-1.

getTableName

public java.lang.String getTableName(int index)

Description copied from interface: DataTable

Returns the name of a table.

Specified by:

getTableName in interface DataTable

Parameters:

index - Index of the table to access.

Returns:

String with the name of the table.

getTypeID

public int getTypeID(int index)

Description copied from interface: DataTable

Return the metamodel type ID of the elements of a table.

Specified by:

getTypeID in interface DataTable

Parameters:

index - Index of the table to access.

Returns:

Type ID of the model elements of that table.

getNumberOfRows

public int getNumberOfRows(int index)

Get the number of design elements (rows) on display in a specified table.

Specified by:

getNumberOfRows in interface DataTable

Parameters:

index - Index of the table to access.

Returns:

The number of rows in the table, r. Valid row indices for the table run from 0 to r-1.

getNumberOfColumns

public int getNumberOfColumns(int index)

Get the number of metrics for a metric delta table.

Specified by:

getNumberOfColumns in interface DataTable

Parameters:

index - Index of the table to access.

Returns:

Number of columns in the table, c. Valid column indices for the table run from 0 to c-1.

getValueAt

public java.lang.Object getValueAt(int index,
                                   int row,
                                   int col)

Return the metric delta for a particular design element and metric.

Specified by:

getValueAt in interface DataTable

Parameters:

index - Index of the table to access.

row - Index of the row to access.

col - Index of the column to access.

Returns:

Table cell value at the specified coordinates.

getRowName

public java.lang.String getRowName(int index,
                                   int row)

Get the name of the model element at a specific row.

Specified by:

getRowName in interface DataTable

Parameters:

index - Index of the table to access.

row - Index of the row.

Returns:

The name of the row.

getColumnName

public java.lang.String getColumnName(int index,
                                      int col)

Get the name of a specific metric in the table.

Specified by:

getColumnName in interface DataTable

Parameters:

index - Index of the table to access.

col - Index of the column.

Returns:

The name of the column to be used as column header.

getColumnDescription

public java.lang.String getColumnDescription(int index,
                                             int col)

Get the description for a metric in the table.

Specified by:

getColumnDescription in interface DataTable

Parameters:

index - Index of the table to access.

col - Index of the column.

Returns:

String with an informal description of the column.

loadMappings

public static void loadMappings(java.lang.String filename,
                                java.util.ArrayList first,
                                java.util.ArrayList second)
                         throws java.io.IOException

Load an element mapping file.

Parameters:

filename - Name of the file to read from.

first - Element mappings for the first design are added here.

second - Element mappings for the second design are added here.

Throws:

java.io.IOException - if the file could not be read.

saveMappings

public static void saveMappings(java.lang.String filename,
                                java.util.ArrayList first,
                                java.util.ArrayList second)
                         throws java.io.FileNotFoundException

Save element mappings to a file.

Parameters:

filename - Name of the file to read from.

first - Element mappings for the first design.

second - Element mappings for the second design.

Throws:

java.io.FileNotFoundException - If the file could not be opened for saving.