The home of Alitheia Core

Things to consider

• Granularity: It is better to build plug-ins that calculate lots of simple metrics which are then aggregated to a more complex one than plug-ins that just calculate a complex metric. Others might find the intermediate metrics useful. Also simpler metrics are easier to debug and validate.
• Activation types: To discover the activation types that your metric should support, the basic question to answer is what changes to the project's lifetime must be captured with the metric. It is also possible to capture changes at a low level and then aggregate them at higher level of granularity. For example, a metric that needs to calculate the average size of a module can calculate the sizes of modules using a ProjectFile activator to account for changes to files and then use the ProjectVersion activator to select all source code modules along with the results of the already calculated metric, instead of going through the project's file tree on every revision.
• Incremental calculation: It is usually better to calculate metrics incrementally than monolithically. Always use the lowest data type granularity possible, for example calculate a metric per file rather than per version.
• Data selection: Only select data that your plug-in will use; Alitheia Core can simplify this task by allowing direct access to the metadata it stores. Use the Hibernate Query Language to filter the requested files. Perform InMemoryCheckouts if you want the file hierarchy rather than on disk checkouts.

Creating a skeleton plug-in with the Maven archetype

Invoking the plug-in archetype

• Switch to the $ALITHEIA/metrics directory and invoke the provided Maven archetype as follows:

mvn archetype:generate 
    -DgroupId=your.package
    -DartifactId=pluginname
    -Dversion=0.x   #(replace x with your plug-in's version)
    -Dpackage=your.package.pluginname 
    -DarchetypeGroupId=eu.sqooss.metrics 
    -DarchetypeArtifactId=archetype 
    -DarchetypeVersion=1.0

• Add the plugin to the pom.xml file in the <modules> section, if the archetype creator does not do that for you

<modules>
  ...
  <module>pluginame</module>
    ...
</modules>

Configure the build system

• Change to the pluginame directory and edit the pom.xml file
  • Change the <name> tag to something meaningful
  • Change the <version> tag to something meaningful
  • In the <instuctions>....</instructions> section of the file, change the included tags to match your plug-in's details. Important is to set the Bundle-Activator parameter to your bundle's activator class, otherwise the plug-in will fail to start.

• If your bundle must include an external library, then you should read the documentation of the maven-bundle-plugin on how to do it. You can find it here

The above steps should produce a basic plug-in that builds, loads and can be installed. Of course, it does nothing useful.

If the plug-in must use additional tables

If your plug-in uses a custom table to store results, then it must provide its own data access objects and configuration files (JPA annotations do not work). Hibernate mapping files are called *.hbm.xml and by convention live in the same package as the Java files that define the data access objects. Alitheia Core poses the additional restriction that the private database table sources (Java and Hibernate) live in a package named db, so the .hbm.xml files should be placed in a directory like:

    eu/sqooss/metrics/your/plugin/package/db 

• To include Hibernate mapping files in the generated bundle, include the following extract in the <plugins>....</plugins> section of the generated pom.xml file.

<resources>
  <resource>
    <targetPath>eu/sqooss/service/db</targetPath>
    <directory>src/main/java/${groupId}/${artifactId}/db</directory>
    <includes>
      <include>**/*.xml</include>
    </includes>
  </resource>
  <resource>
    <directory>src/main/resources</directory>
    <includes>
      <include>**/*</include>
    </includes>
  </resource>
</resources>

• Also, the automatic import package resolution step might not work well. You should add the following line to the <instuctions> section

    <Import-Package>*, eu.sqooss.metrics.db.*</Import-Package>