XWeaver
XWeaver can be used in two different ways. First as a command line tool or by using the AXDT plug-in for Eclipse.
This page describes how XWeaver can be used as a command line tool. However the information given on this page is also helps understanding the AXDT Eclipse plug-in and its use. AXDT is described in a separate section "Eclipse Plugin (AXDT)" (See menu bar on the left). The command line tool uses Jakarta Ant and XWeaver provides a set of Ant Tasks which perform the various steps to weave a given base code. Nevertheless the user does not need to be an expert in Ant or to know how to write an Ant buildfile since XWeaver provides an automatic generation facility for the required Ant buildfile. The input for this generation process is an XWeaver Project File. The first section of this page describes the structure of the XWeaver Project File. Susequent sections describe how to generate the Ant buildfile and how the weaving process can be performed with this generated Ant buildfile.
The "XWeaver Project File" contains all information needed for the weaving process of a particular base code.
It is written in XML and is normally named xwproject.xml but can have any other name. The file should reside in the root
directory of the base code that is to be woven.
An XWeaver project file consists of an xwproject, a base code and several woven sections. Each of these sections is
described with a corresponding XML element. These are: xwproject, base and woven.
The subsequent paragraphs describe each of these elments with all their possible attributes and subelements.
An xwproject has two attributes:
| Attribute | Description | Required |
|---|---|---|
| xwhome | Relative or absolute path to the XWeaver installation direcotry. E.g: 'C:\XWeaver' | Yes |
| version | Version of the project file. ('1.0' is the only possible value for now) | Yes |
An xwproject must have a base subelement and one or more woven subelements.
This element inlcudes information the weaver needs to know about the base code. The foolwing attributes are defined for this element:
| Attribute | Description | Required |
|---|---|---|
| name | The name of the base project | Yes |
| language | The programming language the base code is written in. Possible values are: 'C', 'C++' or 'Java' | Yes |
| indentChar | The character used in the base code to do indentations. Possible values are 'tab' or 'space' | Yes |
| indentCount | Number of times the character given in
indentChar is used for one indentation. (E.g: '1') |
Yes |
The base element can have one filetypes subelement. This is only required if the language is given as 'C++'. The filetypes element has three attributes:
| Attribute | Description | Required |
|---|---|---|
| declarationSuffix | Suffix of C++ declaration/header files (E.g: '.h') | Yes |
| definitionSuffix | Suffix of C++ definition files (E.g: '.cpp') | Yes |
| inlineSuffix | Suffix of C++ inline files (E.g: '_inl.h'). If you don't declare inline functions in a special file but in the normal declaration/header files just use the same suffix here as for the declaration/header file. | Yes |
<base name="ExampleProject"
indentChar="tab"
indentCount="1"
language="C++">
<filetypes inlineSuffix=".h"
declarationSuffix=".h"
definitionSuffix=".cpp"/>
</base>
An xwproject can contain several woven elements. Each woven element describes the transformation for one modified code. The woven element has the following attributes:
| Attribute | Description | Required |
|---|---|---|
| name | The name of the woven project. Must be unique among other woven project names. | Yes |
| path | The path to the woven project, relative to the location of the base project. This is the location where the modified code is saved. | Yes |
| aspect | The location ot the AspectX file which will be used for the weaving. Instead of this attribute you can also use the subelement aspects to define more than one pointcut. | Yes, if there is no 'aspect' subelement. Otherwise it is prohibited. |
The woven element can have several subelements. Each subelement is described below:
This element is required if there is no aspect attribute defined in the woven element, otherwise it is prohibited.
It has not attributes but can have several file subelements. Each file subelement must have a href attribute which specifies one AspectX file.
This element is required.
It specifies the set of files in the base code that must be included in the weaving process. These must be files containing code in the programming language specified by the language attribute in the base element.
Valid attributes and subelements for this attribute are all the attributes and subelements which are valid for the fileset element as it is used in Ant. The only exception is the dir attribute which is prohibited in the weave element but required in the fileset element. This is because the root directory is already given by the base code directory. A descritpion of the fileset element can be found in the Ant Manual under Concepts and Types/FileSet.
This element is optional.
It specifies the set of files in the base code that should be copied to the target directory of the weaving process. The target directory is given by the path attribute of the woven element.
Valid attributes and subelement are exactly the same as for the weave element above.
This element is optional.
This element can be used to compare the woven code with a manually verified code for test purposes. This is mainly used for the Test Suite of XWeaver.
The element has two attributes:
| Attribute | Description | Required |
|---|---|---|
| src | Directroy which contains the woven source files | Yes |
| verified | Directory which contains the verified source | Yes |
This element can contain any element which is an ant task. These elements are copied to the generated ant file.
The following example weaves all file ending with '.cpp' or '.h' into the destination directory '../Example_TestAspect'. The aspect used for the weaving is located in aspects/TestAspect.xml relative to where the xwproject file is located.
<woven name="Example_TestAspect" path="../Example_TestAspect" aspect="aspects/TestAspect.xml"> <weave includes="src/**/*.cpp src/**/*.h"/> </woven>
The following example does nearly the same as the first example but does the weaving in two steps, first it weaves with the aspect TestAspect.xml and then with TestAspect_1.xml.
<woven
name="Example_TestAspect"
path="../Example_TestAspect">
<aspect>
<file href="aspects/TestAspect.xml"/>
<file href="aspects/TestAspect_1.xml"/>
</aspects>
<weave includes="src/**/*.cpp src/**/*.h"/>
</woven>
This section describes how the XWeaver project file can be transformed to an Ant buildfile. See the section above for a descritpion of the XWeaver project file.
The generation is done by an XSLT transformation. This means that you need an XSLT tranformation processor. The processor needs to be XSLT 2.0 compliant. The saxon 8.1.1 XSLT 2.0 compliant processor is included in the XWeaver delivery and was used for testing the tranformation process. Therefore it is recommended that you use the saxon processor but any other XSLT 2.0 compliant processor should work as well.
This guide will only show how to do the transformation with the saxon XSLT processor, for other processors read their user manual. If you need more information about the saxon processor see the saxon user manual.
The XSLT stylesheet which does the transformation can be found in the XWeaver delivery in the
following location: {XWeaverInstallDir}/src/xsl/xwproject2ant.xsl.
The command to perform the transformation is the following considering the command is run in the root directory of the base code and the xwproject.xml file is an XWeaver project file:
java -jar {XWeaverInstallDir}/lib/saxon8.jar -o build.xml xwproject.xml {XWeaverInstallDir}/src/xsl/xwproject2ant.xsl
Replace {XWeaverInstallDir} with the path of the XWeaver installation directory. This will generate the file build.xml.
This section assumes that Ant 1.6.2 is properly installed on your computer and can be run by from the command line. See Download/Installation page for more information.
The weaving can be done by simply run an Ant target. Ant must be run in the same directory where the Ant buildfile build.xml was generated. If run Ant with the following command you'll get all targets which can be run:
ant
There is a target for each woven element in the XWeaver project file. E.g. if a woven element had the name attribute "Foo_Trace" there will be an Ant target "Foo_Trace" that can be run. To run this target the target name must be given as the first argument to the Ant command. For the Foo_Trace example this would look like this:
ant Foo_Trace
Use the following command if the saxon8.jar and xweaver.jar files were not copied to the lib directory of the ant installation directory:
ant -lib {XWeaverInstallDir}/XWeaver/lib; Foo_Trace
If you want to weave all defined targets in one run you can use the WeaveAll target:
ant WeaveAll