XDoclet 2 - QDox, A parser for extracting metadata information from java source files

QDox, A parser for extracting metadata information from java source files

Quoting from the QDox website -

"QDox is a high speed, small footprint parser for extracting class/interface/method definitions from source files complete with JavaDoc @tags. It is designed to be used by active code generators or documentation tools."

QDox extracts XDoclet tags that are javadoc like @tags

The best way to understand what QDox does would be through an example.

HelloWorld.java

import java.lang.String;
import java.util.List;
import java.util.*;

/**
* @myclass name="HelloWorldClass"
*
*/
class HelloWorld{

 private List persons = Arrays.asList(new String[]{"Foo","Bar","Oof"});

 /**
 * @mymethod name="greeting"
 */

 public void greeting(String message){
  Iterator iter = persons.iterator();
  while(iter.hasNext()){
   System.out.println( message  + " " +iter.next());
  }
 }
}

This class carries 2 tags

one at the 'class level' '@myclass' with an attribute-value pair "name='HelloWorldClass'" and
another at 'method level' '@mymethod' with an attribute-value pair "name='greeting'"

This is how XDoclet/QDox tags are typically specified in the source file. The following code snippet (QDoxRunner.java) runs java source file through QDox and prints the resulting output to console. Make sure that you save both files in the same file system directory. Most of the QDox class / method names are self explanatory.

QDoxRunner.java

import com.thoughtworks.qdox.*;
import com.thoughtworks.qdox.model.*;
import java.io.*;

public class QDoxRunner{

 public static void main(String[] args) throws Exception{

  //Instantiate the builder
  JavaDocBuilder builder = new JavaDocBuilder();  

  //Supply the file that carries the metadata (QDox doclet tags)
  builder.addSource(new FileReader("HelloWorld.java")); 

  // The method typically returns an array of object 
  // representation of java source files.  
  // We have just one for now (HelloWorld.java)

  JavaSource src = builder.getSources()[0]; 
  String pkg       = src.getPackage();

  String[] imports = src.getImports();

  System.out.println("HelloWorld.java file imports the following -");

  for(int i=0; i < imports.length ; i++){
    System.out.println(imports[i]);
  }

  // A Source file might typically have multiple class declarations. 
  // In this case its just one.
  JavaClass helloWorldClass = src.getClasses()[0]; 

  //Extract the doclet tag specified at the class level

  DocletTag classTag = helloWorldClass.getTagByName("myclass");
  String nameValue = classTag.getNamedParameter("name");

  System.out.println (" Value of 'name' attribute for tag '@myclass' is " 
             + nameValue);

  JavaMethod m = helloWorldClass.getMethods()[0];

  //Extract the doclet tag specified at the method level

  DocletTag mymethodTag = m.getTagByName("mymethod");
  nameValue = mymethodTag.getNamedParameter("name");

  System.out.println (" Value of 'name' attribute for tag '@mymethod' is " 
        + nameValue);

 }

}

Running Test.java produces the following output

$ javac QDoxRunner.java

$ java QDoxRunner
Class HelloWorld.java file imports the following -
        java.lang.String
        java.util.List
        java.util.*
Value of 'name' attribute for tag '@myclass' is HelloWorldClass
Value of 'name' attribute for tag '@mymethod' is greeting

User Documentation

IDE Integration

Maven Integration

Plugins

Project Information

Developer Documentation

Feeds

QDox, A parser for extracting metadata information from java source files