Code Auditing as Part of the Build Process

Code auditing is analysis of code for adherence to programming standards. It results in better code that is easier to maintain. Oracle JDeveloper 10g comes with an extensive set of predefined rules for auditing Java code. In addition you can create your own auditing rules and add them to JDeveloper. JDeveloper let you group Auditing rules into profiles. This provides an easy mechanism to customize the rules used to validate your code.

Some examples of the areas that JDeveloper's audit rules can help enforce include:

• Proper usage of common Java APIs.
• Proper declaration of classes, methods, and fields.
• Completeness and correctness of Javadoc comments.
• Adherence to standard naming conventions
• Eliminating unused declarations.

Auditing code should be part of every project's build process, making code quality assurance an integral part of the project.

In this article we'll show you how to do this combining the power of the JDeveloper's auditing engine with the flexibility of the open source Ant build tool. We'll run the audit engine from Ant, and show how to produce an audit report of the audit results. We'll then transform the audit report to a more readable output in both an html document as well as a pdf document. The pdf will be generated using the FOP (Formatting Objects Processor) standard. FOP is a formatter driven by XSL formatting objects (XSL-FO). It is a Java application that reads a formatting object (FO) tree and renders the resulting pages to a specified output. More information about FOP can be found on the project's page on Apache.

Sample outputs

Check out these html and pdf reports of a sample audit process.

Pre-requisites

To transform the XML output from the audit process into a more readable HTML or PDF files, we'll use the Apache FOP transformation utility. Get it from the Apache FOP web site and extract it to a directory on your machine..

Running Audit on Your Project

First we'll show you how to get audit reports on your own project code.

1. Extract the files from this zip into a directory on your machine.
2. Create a new Empty project in JDeveloper.
3. In the new project choose File->open and select all the files and directories that were in the zip file. A popup will open and ask you if you want to update the source path of your project - select yes.
4. Double click on the audit.properties file to edit it. Update all the rows that are preceded by a remark line.
5. Right click on the build.xml file and choose "build default target" this will run the audit process and produce a PDF report for you to look at.

Now that you've run a sample audit process let's look at what the technical details of the process.

The Ant Build-file

Our Ant build-file is made out of several targets; these targets depend on each other. The targets are:

• The audit process, which produces an xml output as a result
• A transformation process, that would turn the xml output from the preious step into html or fo
• If pdf has been chosen as an output, we will transform the fo document generated in the previous step into the expected pdf document.

Their dependencies can be represented as follow:

Lets look at each of these target and how it works.

The audit target

Oracle JDeveloper 10g comes with an executable that allows you to run your Audit profiles in batch mode. This executable is called ojaudit, and is located in the same directory as jdev ([JDEV_HOME]/jdev/bin).
To know what parameters it can manipulate, just type on the command line:
Prompt> ojaudit -help

The audit target runs the audit analysis on a given element. In our case, this element will be a project, but it could also be a whole workspace, a file, etc.
We are going to have an ant target defined as follow:

 
  <target name="audit">
     <echo message="Auditing ${project.name}"/>
     <exec executable="${audit.exec}" 
           dir="${audit.home}"
           vmlauncher="false">
       <arg line="-profile ${profile.name}"/>
       <arg line="-output ${working.dir}/${output.name}"/>
       <arg line="-title '${report.title}'"/>
       <arg line="${project.dir}/${project.name}"/>
     </exec>
     <echo message="Generated ${working.dir}/${output.name}"/>
  </target>

 
 <property file="./audit.properties"/> 

 
# The Report Title
report.title=DOM3.0 Audit  
# Refer to the directory where the project to audit is
project.dir=C:/___myWork/CodeCamp/AdvancedXML/DOM3LoadAndSave
# This is the directory of the present project
working.dir=C:/___myWork/JDevRelated/AuditRules/AuditTest
# The directory where you've doanloaded Apache fop
apache.fop.dir=C:/__Download/XMLRelated/ApacheFOP/fop-0.20.5
# The name of the project to audit
project.name=DOM3LoadAndSave.jpr
output.name=audit.xml
profile.name=All
# The JDeveloper Home directory
audit.home=C:/JDev905.1605/jdev/bin
audit.exec=ojaudit

Those variables will have to be modified to fit your environment. With the values set in this example, the process will generate a file called "audit.xml". The next step is to transform this xml file into a more readable format.

The transformations targets

The previous target has generated an xml file as an output. We are going to use XSLT to transform this xml file into a more readable format. We'll use two different targets, one for the html and another one for the fo output. Both files will later on be processed by the FOP engine. In this example, we use Apache FOP, that can be accessed at the Apache web site.
Check out the build-file to see what the required jar files are.
Those two targets depend on the "audit" target we created in the previous step.
Ant is natively equiped for xsl transformations. You need to refer to the <style> element.
A transformation target would typically look like this:

 
  <target name="transform" depends="audit">
     <style style="${working.dir}/html.xsl" 
            in="${working.dir}/audit.xml" 
            out="${working.dir}/audit.html"/>
  </target>

The attributes include the stylesheet that will be used, the document we are going to transform, and the result document.
The FOP engine will process a fo document (containing tags belonging to the fo namespace, identified by "http://www.w3.org/1999/XSL/Format"). The transformation is semantically identical; the result is a bit more tough to read.

 
  <target name="processfo" depends="audit">
     <style style="${working.dir}/fo.xsl" 
            in="${working.dir}/audit.xml" 
            out="${working.dir}/audit.fo"/>
  </target>

The stylesheets that we use for the transformation are provided at the end of this article.

The display targets

Again, we'll use two different targets here. One for html, that just displays the file generated above, and another for pdf, that will processes the fo document produced in the previous step and will turn it into the pdf format.
The html display is just invoking the document generated during the previous step.

 
  <target name="display.html" depends="transform">
    <exec executable="${working.dir}/audit.html"
          vmlauncher="false"/>
  </target>

The pdf display will process the fo document with Apache FOP, using the ApachePDFProducer class we wrote for this purpose. The build file has a target that compiles this Java class using the JAR files from the FOP installation; and the next target displays the PDF file.

   <path id="fo.path">
    <pathelement location="${working.dir}/classes"/>
    <pathelement location="${apache.fop.dir}/lib/avalon-framework-cvs-20020806.jar"/>
    <pathelement location="${apache.fop.dir}/lib/batik.jar"/>
    <pathelement location="${apache.fop.dir}/build/fop.jar"/>
  </path>
  
  <target name="compile" depends="processfo">
     <mkdir dir="${working.dir}/classes"/>
     <javac destdir="${working.dir}/classes" srcdir="." debug="on" encoding="Cp1252">
        <classpath refid="fo.path"/>
        <include name="audit/util/ApachePDFProducer.java"/>
     </javac>
  </target> 

<target name="display.pdf" depends="compile">
    <java classname="audit.util.ApachePDFProducer"
          classpathref="fo.path"
          dir="."
          fork="true">
       <arg value="${working.dir}/audit.fo"/>
    </java>

Notice the way we invoke java to run the class that will process the fo file, it takes the fo document as a parameter.

Here is the source for the class that process the fo file.

Summary

As you can see, it is very simple to add one more step to your build process that will provide you with feedback on your code quality. Ant will even let you automate emailing the result files to whom it may concern.

Source Code

• The build file

• The properties file

• The stylesheet for html

• The stylesheet for fo

• The java class to process the fo document