Navigating The Source Code Model

After the source code has been parsed, the content of the files can be navigated using a simple to use and intuitive object model.

Class Description Commonly Used Methods
JavaSource

Represents a complete .java file. This contains a collection of classes.

Example Input
package com.blah.foo;

import java.awt.*;
import java.util.List;

public class Class1 {
  ...
}

class Class2 {
}

interface Interface1 {
}
Example Code
JavaDocBuilder builder = new JavaDocBuilder();
builder.addSource(myReader);

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

String pkg       = src.getPackage(); // "com.blah.foo"
String[] imports = src.getImports(); // {"java.awt.*",
                                     //  "java.util.List"}

JavaClass class1     = src.getClasses()[0];
JavaClass class2     = src.getClasses()[1];
JavaClass interface1 = src.getClasses()[2];
String getPackage()
String[] getImports()
JavaClass[] getClasses()

JavaClass

Represents a class or interface. This contains doclet tags, fields and methods. Information about the class definition is available, such as which classes are extended, which interfaces implemented and modifiers.

Example Input
package com.blah.foo;

import java.io.*;
import com.custom.*;
import com.base.SubClass;

/**
 * @author Joe
 */
public abstract class MyClass extends SubClass
            implements Serializable, CustomInterface  {

  private String name;
  public void doStuff() { ... }
  private int getNumber() { ... }

}
Example Code
JavaDocBuilder builder = new JavaDocBuilder();
builder.addSource(myReader);

JavaClass cls = builder.getClassByName("com.blah.foo.MyClass");

String pkg      = cls.getPackage();            // "com.blah.foo"
String name     = cls.getName();               // "MyClass"
String fullName = cls.getFullyQualifiedName(); // "com.blah.foo.MyClass";
boolean isInterface = cls.isInterface();       // false

boolean isPublic   = cls.isPublic();   // true
boolean isAbstract = cls.isAbstract(); // true
boolean isFinal    = cls.isFinal();    // false

Type superClass = cls.getSuperClass(); // "com.base.SubClass";
Type[] imps     = cls.getImplements(); // {"java.io.Serializable",
                                       //  "com.custom.CustomInterface"}

String author = cls.getTagByName("author").getValue(); // "joe"

JavaField nameField = cls.getFields()[0];
JavaMethod doStuff = cls.getMethods()[0];
JavaMethod getNumber = cls.getMethods()[1];
String getPackage()
String getName()
String getFullyQualifiedName()
boolean isInterface()

boolean isPublic()
boolean isAbstract()
boolean isFinal()

Type getSuperClass()
Type[] getImplements()

DocletTag[] getTags()
DocletTag[] getTagsByName(String name)
DocletTag getTagByName(String name)

JavaField[] getFields()
JavaMethod[] getMethods()

JavaField

Represents a field in a class. This has doclet tags, a name and a type.

Example Input
import java.util.Date;

public class MyClass  {

  /**
   * @magic
   */
  private String email;

  public static Date[][] dates;

}
Example Code
JavaField e = cls.getFields()[0];

Type eType     = e.getType(); // "java.lang.String";
String eName   = e.getName(); // "email";
DocletTag eTag = e.getTagsByName("magic"); // @magic
boolean eArray = e.isArray(); // false;

JavaField d = cls.getFields()[1];

Type dType     = d.getType(); // "java.util.Date";
String dName   = d.getName(); // "dates";
DocletTag dTag = d.getTagsByName("magic"); // null
boolean dArray = d.isArray(); // true;
int dDimensions= d.getDimensions(); // 2;
boolean dStatic= d.isStatic(); // true;
String getName()
Type getType()

boolean isPublic()
boolean isStatic()

DocletTag[] getTags()
DocletTag[] getTagsByName(String name)
DocletTag getTagByName(String name)

JavaMethod

Represents a method in a class. This has doclet tags, a name, return type, parameters and exceptions.

Example Input
import java.util.Date;
import java.io.*;

public class MyClass  {

  /**
   * @returns Lots of dates
   */
  public static Date[] doStuff(int number,
                               String stuff)
            throws RuntimeException, IOException {
    ...
  }

}
Example Code
JavaMethod m = cls.getMethods()[0];

String mName = m.getName(); // "doStuff";
Type mReturns = m.getReturns(); // "java.util.Date";
boolean mArray = m.getReturns().isArray(); // true
boolean mStatic = m.isStatic(); // true
boolean mPublic = m.isPublic(); // true

String doc = m.getTagByName("returns").getValue();
  // "Lots of dates"

Type[] exceptions = m.getExceptions();
  // {"java.lang.RuntimeException", "java.io.IOException"}

JavaParameter numberParam = m.getParameters()[0];
JavaParameter stuffParam = m.getParameters()[1];
String getName()
Type getReturns()
JavaParameter[] getParameters()
Type[] getExceptions()

boolean isPublic()
boolean isStatic()

DocletTag[] getTags()
DocletTag[] getTagsByName(String name)
DocletTag getTagByName(String name)

JavaParameter

Represents a parameter passed to a method. This has a name and a type.

Example Input
public class MyClass  {

  public void stuff(int n, Object[] objects) {
    ...
  }

}
Example Code
JavaMethod m = cls.getMethods()[0];

JavaParameter n = m.getParameters()[0];
String nName = n.getName(); // "n"
Type nType   = n.getType(); // "int";

JavaParameter o = m.getParameters()[1];

String oName   = o.getName(); // "objects"
Type oType     = o.getType(); // "java.lang.Object";
boolean oArray = o.getType().isArray(); // true
String getName()
Type getType()

Type

Represents a specific instance of a class used by another class (such as return value, superclass, etc). The value represents the name of the class. Array dimensions are also available. Since 1.8 it's also possible to get the generic value of the Type

Example Input
import java.util.*;

public class MyClass  {

  public void stuff(int n, Object[] objects,
	                  Date[][] dates, List stringList) {
    ...
  }

}
Example Code
JavaMethod m = cls.getMethods()[0];

Type returns = m.getReturns();
returns.getValue(); // "void"
returns.getArray(); // false
returns.getDimensions(); // 0

Type n = m.getParameters()[0].getType();
n.getValue(); // "int"
n.getArray(); // false
n.getDimensions(); // 0

Type objects = m.getParameters()[1].getType();
objects.getValue(); // "java.lang.Object"
objects.getArray(); // true
objects.getDimensions(); // 1

Type dates = m.getParameters()[2].getType();
dates.getValue(); // "java.util.Date"
dates.getArray(); // true
dates.getDimensions(); // 2

Type stringList = m.getParameters()[3].getType();
stringList.getValue(); // "java.util.List"
stringList.getGenericValue(); // "java.util.List"
stringList.getArray(); // false
stringList.getDimensions(); // 0
String getValue()
String getGenericValue()
boolean isArray()
int getDimensions()

DocletTag

Represents a JavaDoc tag. Each tag has a name and a value. Optionally, the value can be broken up into tokens accessed by index or name.

Example Input
/**
 * @ejb MyEJB MyInterface local=true version=2.0
 */
Example Code
DocletTag tag = cls.getTagByName("ejb");

String value = tag.getValue();
   // "MyEJB MyInterface local=true version=2.0"

String p1 = tag.getParameters()[0]; // "MyEJB";
String p2 = tag.getParameters()[1]; // "MyInterface";

String local = tag.getNamedParameter("local"); // "true";
String ver   = tag.getNamedParameter("version"); // "2.0";
String other = tag.getNamedParameter("blah"); // null
String getName()
String getValue()
String[] getParameters()
String getNamedParameter(String key)

Dealing With Arrays

The Type class stores array information in it. If the array is multidimensional, the dimension depth can be accessed.

Working With JavaDoc Tags

The JavaClass, JavaField and JavaMethod classes all contain the following methods:

The returned DocletTag carries the name, value and methods for breaking up the value into specific parameters.

Example Input
/**
 * This method does nothing at all.
 *
 * @returns A boolean of whether we care or not.
 * @param email Someone's email address.
 * @param dob Date of birth.
 *
 * @permission administrator full-access
 * @webservice publish=true name=myservice type=rpc
 */
boolean doWeCare(String email, Date dob);
Example Code
JavaMethod mth = cls.getMethods()[0];

// Access the JavaDoc comment
String comment = mth.getComment();
  // "This method does nothing at all."

// Access a single doclet tag
DocletTag returns = mth.getTagByName("returns");
returns.getName(); // "returns";
returns.getValue(); // "A boolean of whether we care or not."

// Access multiple doclet tags with the same name
DocletTag[] params = mth.getTagsByName("param");
params[0].getValue(); // "Someone's email address."
params[1].getValue(); // "Date of birth."

// Access specific parameters of a doclet tag by index
DocletTag returns = mth.getTagByName("permission");
permission.getParameter(0); // "administrator"
permission.getParameter(1); // "full-access"

// Access specific parameters of a doclet tag by name
DocletTag returns = mth.getTagByName("webservice");
permission.getNamedParameter("type"); // "rpc"
permission.getNamedParameter("name"); // "myservice"

Classes, Interfaces and Inheritance

The JavaClass method is used to represent both classes and interfaces. The isInterface() method allows you to distinguish between the two.

When using a class, the getSuperClass() return which class is extended. If this has not been defined in the input source code, java.lang.Object is returned. When using an interface, this method ALWAYS returns null.

When using a class, the getImplements() returns an array of the interfaces implemented by the class. If none are implemented, an empty array is returned. When using an interface, this returns an array of interfaces the current interface EXTENDS.

Navigating Up The Model

The following methods allow you to navigate back up the tree to the parent node: