Xuse User Guide: Trace report import
Xuse supports the explicit linking to artefacts beyond the scope of the Xuse model. The linking is achieved via the "trace report" - an XML format specifically designed to create the linkage.
Typically this feature could be used to link to Java classes, defects, test cases etc, although its uses are certainly not limited to this: it can be used to link to any artefact within your business domain. The external artefact relationships are imported into the Xuse model so that Requirements and Use-cases become linked to these artefacts. When the Xuse documentation is generated the relationship will be displayed and (if appropriate) a hyperlink will be created linking directly to the external artefact (or a representation of it).
"Why would I want to do this?" you might ask. The reasons for doing this may be many, however typical considerations would be to:
- allow a fuller and deeper impact analysis of requirements change, or
- allow the requirements analysts to directly drill down from the requirement context into derived artefacts (such as test cases) to validate that the derivation is correct, or
- to import the status of external artefacts directly into the requirements model (Xuse support comming soon).
Trace report format
The trace report format is defined by the trace-report.xsd schema that you will find under the xusexsds directory in your local project folder. An example of the format linking Java to requirements is shown below (more on that feature later).
<?xml version="1.0" encoding="UTF-8"?>
<xtr:trace-report xmlns:xtr="http://www.xml-solutions.com/xuse/trace-report"
created="2010-05-18T13:07:36"
base-uri="../xref"
base-id="xusej">
...
<xtr:artefact type="java:method" uri="net/sourceforge/xuse/Xuse.html#472">
<xtr:id>net.sourceforge.xuse.Xuse#xuseHtml</xtr:id>
<xtr:location>
\xuse\src\java\net\sourceforge\xuse\Xuse.java:472
</xtr:location>
<xtr:trace-to class="requirement">RQ19</xtr:trace-to>
<xtr:trace-to class="requirement">RQ60</xtr:trace-to>
<xtr:status>implemented</xtr:status>
</xtr:artefact>
...
<xtr:artefact type="java:method" uri="net/sourceforge/xuse/Xuse#282">
<xtr:id>net.sourceforge.xuse.Xuse#xuseDocumentsHtml</xtr:id>
<xtr:location>
\xuse\src\java\net\sourceforge\xuse\Xuse.java:282
</xtr:location>
<xtr:traceTo class="requirement">RQ19</xtr:traceTo>
<xtr:traceTo class="requirement">RQ60</xtr:traceTo>
</xtr:artefact>
...
</xtr:trace-report>
This specific example is from the Xuse source code itself although it is just an example.
Trace report XML reference
The following table explains the XML structure for the trace report.
| Location/XPath | Cdn. | Description |
|---|---|---|
| xtr:trace-report | 1 | Container for all the traced artefacts. |
| xtr:trace-report/@created | 1 | The date and time the report was prepared or generated. |
| xtr:trace-report/@base-uri | 0..1 | The base-uri for the external resources. If present Xuse will use this information to create links to information external from the Xuse model. |
| xtr:trace-report/@base-id | 1 | The base-id for this set of artefacts. A little like XML namespaces this id will be used to ensure external artefact references are unique and thus do not collide. |
| xtr:trace-report/xtr:artefact | 1..* | Container for the trace information for the external artefact. |
| xtr:trace-report/xtr:artefact/@id | 1 | Unique Id (within the context of the base-id) for this artefact. |
| xtr:trace-report/xtr:artefact/xtr:location | 1 | Pointer to the exact artefact location - for instance it may be the local file path and line number for a file based artefact. |
| xtr:trace-report/xtr:artefact/xtr:trace-to | 1..* | Defines the trace link to the local Xuse model entity. Supports tracability to requirements and Use-cases via the class attribute. |
| xtr:trace-report/xtr:artefact/xtr:trace-to/@class | 1 | Determines whether the trace relationship is to a requirement or use-case. Posible values are requirement and usecase. |
| xtr:trace-report/xtr:artefact/xtr:status | 0..1 | Conveys the status of the external artefact (if appropriate). Xuse does not currently make use of this, however it is planned for the future. |
Importing a trace report
Once you have prepared or generated your trace report you will want to import this into the Xuse model. To do this run the import-trace-report command. This will updated or create links to the external artefacts directly within the Xuse model. An example of how this looks for a requirement is shown below.
HTML view hyperlinking
Once imported you can see the relationship in the genertated documentation - the screenshot below shows the HTML view of a requirement with hyperlinks to the external resource (in this case cross referenced HTML view of the Xuse sourcecode generated by the Maven JXR plugin).
The working example of this can be found by looking at Xuse's self-documentation and clicking on an appropriate requriement such as RQ19, or RQ60 and expanding the requirement detail.
Xuse Java Annotations
Whilst the trace report format is designed to support links to any external artefact, the Xuse team have created tooling to allow traceability to Java artefacts. Specifically this toolling allows you to annotate your Java classes to create and maintain the links to the requirements. An example annotation is shown below:
@Requirement(traceTo={"RQ19", "RQ60"},status="implemented")
@UseCase(traceTo={"UC2"})
public void xuseHtml() throws BuildException {
...
}
The associated annotation processor can then be used to generate the report as and when you want or as part of a scheduled build.
Integrating the annotation processor with maven:
- Download the latest version of the annotation processor and install it in your local repository.
- Add the following dependency to your
pom.xml:<dependency> <groupId>net.sourceforge.xuse</groupId> <artifactId>xuse-annotation-tool</artifactId> <version>01.00.00-RC2</version> </dependency> - And add the following plugin to your
pom.xml<plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>apt-maven-plugin</artifactId> <version>1.0-alpha-3</version> <configuration> <factory>com.xmlsolutions.annotation.RequirementAnnotationFactory</factory> </configuration> <executions> <execution> <goals> <goal>process</goal> <goal>test-process</goal> </goals> </execution> </executions> </plugin>
