Skill specification

XML File Structure

XTic takes as input a list of user-defined skills that are expressed in XML files. Such file must have the following structure : a root element <aptitutde>, that contains a list of patterns. A pattern contains an id and an optional description attribute desc attribute.

Here is an example of such a file :

<xtic-aptitudes>
	<aptitude id="test" desc="All the skills associated with a domain of skills">
            <pattern id="id1" desc="description of the pattern">
                <kind value="added|edited|deleted|*" /> 
                <files>
                  <file value="value" direction="source|target" />
                <files>
                <contents>
                    <content value="value" direction="source|target" presence="true|false" />
                <contents> 
                <tree parser="LANGUAGE">
                    <queries> 
                       <query value="value" direction="source|target|both">
                    </queries> 
                </tree>	
            </pattern>
		....
		<!-- as many patterns as you want -->
	</aptitude>
	....
	<aptitude>
	<!-- as many aptitudes as you want -->
	</aptitude>
</xtic-aptitudes>

There is only one root element aptitude in the file. The idea is to modularize the skills by domain, and writing new skill files should not be a matter.

We now explain how to define a skill into our XML format, using 4 different filters.

Filters

XTic allows to specify and extract technical skills directly from source files. A technical skill, or aptitude, can be defined as a set of at least one pattern. Each pattern is defined using 4 filtering types. A pattern will be validated if all the filters success for a file.

Kind

The Kind filter can be used to retain files that are either marked as added, edited or deleted.
By default, any file will be processed.

The definition in the XML file is as follows :

<kind value="added|edited|deleted|*" >

File

The File filter is applied against the full name of a file. (NB : it corresponds to the nativeId of an Item in Harmony model).
The value of such is a regular expression that XTic will try to match against the filename, and will success if one matching is found.

Two directions are permitted for such filters : source or target. Therefore, no more than 2 filters will be accepted.
If no direction is specified, the target file will be selected by default.

The definition in the XML file is as follows :

<files>
        <find value="value" direction="source|target" />
</files>

Example : filter only the Java files in the "src/main/test" directory :

<files>
        <file value="src\/main\/test/.*\.java$" direction="source|target" /> 
</files>

Content

The Content filter operates on the syntactic content of a file considered as a unique string. Similar to the File filter, it must contain a regular expression value that will be searched in the file content. Once again, a direction is associated to the filter. It can be either source, target or both. If no direction is specified, the target file will be selected by default.

There are two more particularities for this filter :

• The number of filter definitions is not restricted.
• An attribute presence indicates wether or not the expression value have to be matched or not against the file content

When no specified, the default values for presence and direction are respectively true and target.

The definition in the XML file is as follows :

<contents>
    <content value="value" presence="true" direction="target" />
<contents>

Tree

The Tree filter purpose is to query an annotated representation of either the source or target file. When a file is created or modified, a new tree representation is computed using a tree differencing technique. Consequently, we can generate for a given file two distinct trees :

• The source tree is a representation of the source version of a file, and the removed elements are annotated with a specific "removed" attribute.
• The target tree is a representation of the target version of a file, and the added elements are annotated with a specific "added" attribute.

If no direction is specified, the target file will be selected by default. A detailed example is available earlier in this tutorial.

Obviously, a parser specific to a given programming language must be provided to analyze the source files. Currently, we support three programming languages : Java, XML and Javascript.

Trees are translated into XML format to support XPath queries.

Only one query per type of direction can be specified. No more than 3 queries can be thus be expressed. To validate the aptitude, all the queries will have to return at least one result.

The definition in the XML file is as follows :

<diff parser="Java">
    <xpath query="query" direction="source|target|both" />
<diff>

It is also possible to specify some options to the component that complete the static analysis of the source code. An typical example for Java is to specify the classpath of the Eclipse JDT Parser to resolve bindings when referencing external dependencies or JAR files. For instance, assume we want to track which developers calls methods from the JUnit library. Here is the pattern we would have to specify :

<pattern id="junit" desc="calls to junit lib">
    <files>        
        <file value="\.java" />
    </files>
    <tree parser="JAVA">
	<options>
	    <option key="classpath" value="/path/to/junit-4.8.2.jar" />
	</options>
        <queries>
            <query value="//MethodInvocation[@added][matches(@label,'org.junit.*')]" />
        </queries>
    </tree>
</pattern>
			

Score Computation

A score is associated to each pattern defined in the configuration files. This score is an integer value that measures the actual number of times the pattern has been observed. The score for an aptitude is the sum of the scores of all the patterns included in the aptitude.

The resulting score depends of the pattern specification :

• If only filters Kind and/or File and/or Content are specified, the possible score are 0 and 1. 1 means that the 3 filters accepted the file.
• If the filter Tree is used :
  • If only one tree is targeted, the score will be the number of results returned by the query.
  • If queries are run against the two trees, the resulting score will be either 0 or 1. 1 will be returned if all the queries find at least 1 result in the targeted trees.
  For example, assume a filter with 2 queries running resp. against the source and both directions. If the first query fetch result in the source tree, and the other one only returns elements from the target tree, the score produced is 0. Indeed, we failed at finding results in the source tree for the both direction.

Examples

Java

We now propose different examples of skills specifications, for both Java and XML languages.

1. "Touch" on Java files which name starts with "Test".

<pattern id="touch_test_file" desc="Touch on Java files which name starts by 'Test'">
   <files>
     <file value="Test[a-zA-Z]*\.java$" />
   <files>
</pattern>

2. "Touch" of a Java file which name starts with "Test", and contains "org.testng".

<pattern id="touch_test_file" desc="Touch on Java files which name starts by 'Test' and contains 'org.testng'">
    <files>
      <file value="Test[a-zA-Z]*\.java$" />
    </files>
    <contents>
	<content value="org.testng" direction="target" />
    </contents>
</pattern>

3. Removed a "Deprecated" annotation.

<pattern id="remove_deprecated" desc="Remove deprecated">
    <files>     
        <file value="\.java$" />
     </files>
    <tree parser="JAVA">
      <queries>
	  <query value="//MarkerAnnotation[@removed]/SimpleName[@label='Deprecated'][@removed]" direction="source" />
      </queries>
    </tree>	
</pattern>

4. Removed an import declaration of "java.io" API and added an import declaration of "java.nio" API.

<pattern id="java_io_migration" desc="Replaced imports from java.io to java.nio">
    <files>        
      <file value="\.java$" />
    </files>
    <tree parser="JAVA">
      <queries>
	    <query value="//ImportDeclaration/QualifiedName[matches(@label,'java.io.*')][@removed]" direction="source" />
	    <query value="//ImportDeclaration/QualifiedName[matches(@label,'java.nio.*')][@added]" direction="target" />
      </queries>
    </tree>	
</pattern>

XML

5. Add a new "xsi:schemaLocation" attribute in a pom.xml file.

<pattern id="pom_xsi_location" desc="modify XML header">
    <files>
      <file value="pom\.xml$" />
    </files>
    <tree parser="XML">
      <queries>
       <query value="//ATTRIBUTE/NAME[@label='xsi:schemaLocation'][../VALUE[@added]]" direction="source" />
      </queries>
    </tree>	
</pattern>

6. Update the version of an existing dependency in a pom.xml file.

<pattern id="pom_update_version" desc="update version of an existing dependency">
    <files>
       <file value="pom\.xml$" />
    </files>
    <tree parser="XML">
      <queries>
	    <query value="//ELEMENT/NAME[@label='dependency'][not(@added)]
	   	    [../ELEMENT/NAME[@label='version'][../DATA[@added]]]" direction="target" />
     </queries>
    </tree>	
</pattern>