Best Practices

This page contains some tutorials and howtos for HeRA developers.

Debug HeRA Extensions

HeRA Extensions are hard to debug, because they are automatically loaded by hera.core. Therefore, we added a new parameter that allows to pass the class names of Extensions in the class path to HeRA. E.g. in the UseCaseExtension this looks like this:

import uce.Main;

public class RunHeRA {

	public static void main(String[] args) {
		args = new String[] {
				// load other extensions
				"-extensionpath", "antdirs/lib",
				// load our extension
				"-directextension", UseCaseExtension.class.getName()
		};
		// start HeRA
		Main.main(args);
	}
}

The trick is to do this in the extension, because it already references the hera.core project.

Create a HeRA Extension

PlugIn? Architectures tend to be complicated. This is, why we decided against reusing the eclipse rich client platform: The learning curve seems to be to steep for students that want to do more during their thesis than only learning how to create an eclipse plugin.

The HeRA Extension Mechanism started as a lightweight framework. The goal was to gain loose coupling with very easy to create extension mechanisms.

Sadly, the problem of PlugIn? Architectures is difficult. This tutorial shall help to get a quick start. However, there remain some unsolved problems. The worst seems to be debugging: The eclipse debugger does not play well with the extension mechanism.

Step 1: create a project

We start by creating a new eclipse project. In this example, I will create a new critique system that specializes on detecting security relevant requirements. This is based on Sinan Petrus thesis. The project is called:

hera.critiques.security

Next I create a class that will be used by HeRA to initialize the extension. Because I always forget, which interface should be implemented, I spy in one of the existing extensions. Good candidates for reuse are the UseCaseExtension and the BusinessProcessExtension?. However, the UMLExtension is much more simple. Lets have a look at the extension class:

package de.unihannover.se.uce.umlOverview.util;

[...]

public class UMLOverviewExtension implements IExtension {

So I start to create a package with a meaningful name for the new extension. The first part should identify my affiliation, the middle part should relate my work to HeRA and the last part should give a hint on the content of my work. I choose secreq as working name, because this is a research project that lead to the idea of security requirements support in HeRA. I create an extension package for my new extension class:

de.unihannover.se.hera.secreq
de.unihannover.se.hera.secreq.extension

Finally, I create an Extension class and let it implement IExtension. At first, eclipse gives an error, because it cannot find IExtension. So I right click on my new project, properties, java build path and add hera.core under projects.

Now I get an error that my new class should implement the methods. The eclipse quick-fix provides me with the following code:

package de.unihannover.se.hera.secreq.extension;

import uce.extensionpoints.IExtendableDODE;
import uce.extensionpoints.IExtension;
import de.unihannover.se.experience.gui.securityproblemview.SecurityView;
import de.unihannover.se.experience.model.ActivatedExperiences;
import de.unihannover.se.hera.secreq.i18n.SecReqi18n;

/**
 * This class is instantiated by HeRA.
 * @author Eric Knauss
 *
 */
public class SecReqExtension implements IExtension {

	@Override
	public void closeExtension() {
		// TODO Auto-generated method stub
		
	}

	@Override
	public void initExtension(IExtendableDODE dode) {
		// TODO Auto-generated method stub
		
	}

	@Override
	public String getDescription() {
		// TODO Auto-generated method stub
		return null;
	}

	@Override
	public String getName() {
		// TODO Auto-generated method stub
		return null;
	}

	@Override
	public String getVersion() {
		// TODO Auto-generated method stub
		return null;
	}


}


Step 2: Make it run and show in HeRA

So lets start with adding some functionality. Because debugging is a little bit difficult, I prefer a Test-First approach. Right-Click on the Extension class, new, Junit Test Case creates a new Test. I generally choose JUnit 4.

HeRA has already some mocks and Dummies for important classes. So lets use them to create a test:

package de.unihannover.se.hera.secreq.extension;

import static org.junit.Assert.*;

import org.junit.Before;
import org.junit.Test;

import de.unihannover.se.hera.secreq.i18n.SecReqi18n;
import de.unihannover.se.hera.testing.DODEDummy;

public class SecReqExtensionTest {

	private SecReqExtension extensionUnderTest= new SecReqExtension();

	@Test
	public void testGetVersion() {
		assertEquals("0.0.1", this.extensionUnderTest.getVersion());
	}

	@Test
	public void testInitExtension() {
		DODEDummy dode = new DODEDummy();
		this.extensionUnderTest.initExtension(dode);

		// Check, whether this extension tries to contribute to HeRA's
		// InformationComponent. The Dummy uses lazy initialization, so let's
		// see whether the informationDummy is initialized.
		assertNotNull(dode.infoDummy);
		assertNotNull(dode.infoDummy.getAddedComponent());
	}

}

The first test is pretty simple. In the second test I use the DODEDummy to test the initExtension method. In this case, I test, wheter the extension adds something to the InformationComponent? in HeRA (the problem view at the bottom). Obviously, I have to add an AbstractComponentView?, which I implement only with a HelloWorldPanel?.

Now we need to create a jar and run it in HeRA. I prefer to use ant for this task. Again, I copy from the UMLExtension. Here are the changes I had to make:

<project name="hera.usecase.diagram" basedir="." default="run">

change name.

	<property name="dir.hera.usecase" location="../hera.usecase" />

I do not need the use case extension. I can delete that property here.

	<property name="file.jar" value="hera.usecase.diagram.jar" />

I give a new name to the jar file that should be created: hera.seqreq.jar

	<path id="project.classpath">
		<pathelement location="${dir.bin}" />
		<pathelement location="${dir.dist}/hera.jar" />
		<pathelement location="${dir.dist}/libs/hera.usecase.jar" />
	</path>

I remove the last Path-Element.

	<target name="create.jar" description="Erzeugt das Jar incl. Manifest." depends="build">
		<jar destfile="${dir.lib}/${file.jar}">
			<fileset dir="${dir.bin}" includes="**/*.class" excludes="**/*Test.class" />
			<fileset dir="${dir.src}" includes="**/*.properties" />
			<manifest>
				<attribute name="Built-By" value="${user.name}" />
				<section name="uceExtensions">
					<attribute name="uceExtensionClass" value="de.unihannover.se.hera.secreq.extension.SecReqExtension" />
				</section>
			</manifest>
		</jar>
	</target>

This is important! Here the manifest of the jar will be created. This is the point, where I tell HeRA how it can initialize my extension. I have to change the attribute uceExtensionClass to point to my new Extension class by giving its fully qualified name.

	<target name="hera.local-copy" description="Erzeugt eine lokale Kopie von HeRA in 'dist'.">
		<ant antfile="build.xml" dir="${dir.hera.usecase}" target="deploy" inheritall="false">
		</ant>
		<copy todir="${dir.dist}">
			<fileset dir="${dir.hera.usecase}/${dir.dist}" />
		</copy>
		
		<ant antfile="build.xml" dir="${dir.hera.core}" target="create.dist" inheritall="false">
		</ant>
		<copy todir="${dir.dist}">
			<fileset dir="${dir.hera.core}/${dir.dist}" />
		</copy>
	</target>

This target creates a local copy of HeRA. This is only one way to get things done, but it seems to be the easiest way here. We do not need the use case extension, so we could just remove the first part.

Now we only need to run the default target and HeRA should be compiled and executed. We should have a close look on the console, because errors that occur throughtout initialization will only be showed there.

If everything is correct, you can see the HelloWorld? Panel in HeRA (and nothing else, because no other Extensions have been installed).

Compute Test Coverage

One way to compute the testcoverage for HeRA is to run the test-coverage target in the ant-files of each extension. Recently, we found an easier to use eclipse plugin that is really great:

 http://www.eclemma.org/index.html

In addition, this plugin allows to measure the codecoverage of typical usage of hera.

iCalendar and Outlook

The Trac Roadmap can be exported to iCalendar. This Calendar can be subscribed from MS Outlook. The trick is to open the Roadmap in Internet Explorer. Than just click the iCalendar link. Outlook lets you subscribe the calendar.

Note: This is not very fancy, because you only get the milestones.