HowTo program a new metric

From SONIVIS:Wiki

Jump to: navigation, search
This article is work in progress.



Contents

Getting started

The MetricManager (de.sonivis.tool.core.core.MetricManager) manages metric extensions and their configuration centrally.

AbstractMetric

abstract class AbstractMetric<ValueType, MeasurableType extends IMeasurable>

Each AbstractMetric object represents a metric in SONIVIS:Tool calculated for a measurable Object (IMeasuarable). Metrics are calculated by a class that extends the AbstractMetric and that is supplied as a plugin (de.sonivis.tool.core.metric). They're managed by the central MetricManager class. Metrics belong to one or multiple categories, which are represented by the MetricCategory class. The tool makes use of this categories for its views. The AbstractMetric class caches its calculated values itself--new subclasses just have to implement the calculateValueFor() and getValueType() method.

Kind of Metric and its measuable object

abstract class NetworkMetric<ValueType> extends AbstractMetric<ValueType, INetwork>

The Superclass NetworkMetric itself is used for arbitrary network metrics. Metrics of this type are calculated for INetwork, the Network interface for SONIVIS:Tool networks.


Methods to calculate metrics

Metrics from the database

For some metrics you have to access the database. Here you find some examples:

for HQL - Data Access Object and their properties are required

  1. final String sql = "SELECT count(*) FROM Actor a WHERE a.infoSpaceItemType=7";
  2. final org.hibernate.Session session = ModelManager.getInstance().getCurrentSession();
  3. final org.hibernate.Query query = session.createQuery(sql);
  4. final Long resultLong = (Long) query.iterate().next();
  5. final Integer resultInt = resultLong.intValue();
  • Line 1 is the String representation of the HQL-Statement
  • Line 2 get current session to get data from the database
  • Line 3 creating the query in hibernate language to get the data
  • Line 4 generating a iterator getting the first element cast to long (we know it is long because it is a normal count-SQL, be careful when using another sql statement)
  • Line 5 convert the Valuetype of the result to


for SQL - database tables and column names are required

  1. final String sql = "SELECT count(*) FROM actor a WHERE a.infospaceitemtype_id=7;";
  2. final SQLQuery test = ModelManager.getInstance().getCurrentSession().createSQLQuery(sql);
  3. final Integer result = ((BigInteger) test.uniqueResult()).intValue();
  • Line 3 uniqueResult() is a convenience method to return a single instance that matches the query, or null if the query returns no results.

Display of metrics and its results

Define as extension

HowTo implement a metric extension
HowTo implement a metric extension

First steps are shown in the image at the right.

  1. Open the plugin.xml of the package where your metric is located
  2. Open the register called Extensions
  3. Right click on the extension de.sonivis.tool.core.metic
  4. To this extension you can now add a new metric by selecting "New -> metric"
  5. now the system gives you example for the "Extension Element Details" (at the right in the same file), which you have to replace
  6. For the correct settings you can use the button Browse.., this opens a section matching the known classes and sets its class in the corresponding field
  7. Choose a name and the id for the metric on your own

Describe as metric

To describe a metric you have to document it in the predefined XML-file (at de.sonivis.tool.core -> metrics.xml). 

1 - <metrics>
2 - <metric name="Total User Count without Registration">
3 - <description>Number of users without a registration date</description>
4 - <addToCategory name="User"/>
5 - <url>http://www.sonivis.org/wiki/index.php/Total User Count without Registration</url>
6 - <addToBuiltInCategory name="Wiki-specific (Built-in)"/>
7 - </metric>
  • Line 2 defines the name of the metric (must be the same name as given in the metric class (mostly like this public static final String NAME = "Total Author Count";, also used to build the metric in super(NAME);)
  • Line 3 is used to describe the metric (equal to super.setDescription("Number of Authors"); the metric constructor)
  • Line 4 defines the category the metric belongs to and is shown in the GUI (each metric can have a variety of those categories)
  • Line 5 notes the url where to locate the description in this wiki
  • Line 6 for metrics exit so called buildInCategories, these categories are only used internal but not displayed in the GUI
Retrieved from "http://sonivis.org/wiki/index.php/HowTo_program_a_new_metric"
Personal tools