The Model
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 Inputpackage com.blah.foo; import java.awt.*; import java.util.List; public class Class1 { ... } class Class2 { } interface Interface1 { } Example CodeJavaDocBuilder 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]; |
|
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 Inputpackage 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 CodeJavaDocBuilder 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]; |
|
JavaField |
Represents a field in a class. This has doclet tags, a name and a type. Example Inputimport java.util.Date; public class MyClass { /** * @magic */ private String email; public static Date[][] dates; } Example CodeJavaField 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; |
|
JavaMethod |
Represents a method in a class. This has doclet tags, a name, return type, parameters and exceptions. Example Inputimport 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 CodeJavaMethod 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]; |
|
JavaParameter |
Represents a parameter passed to a method. This has a name and a type. Example Inputpublic class MyClass { public void stuff(int n, Object[] objects) { ... } } Example CodeJavaMethod 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 |
|
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. Example Inputimport java.util.*; public class MyClass { public void stuff(int n, Object[] objects, Date[][] dates) { ... } } Example CodeJavaMethod 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()[1].getType(); dates.getValue(); // "java.util.Date" dates.getArray(); // true dates.getDimensions(); // 2 |
|
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 CodeDocletTag 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 |
|
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:
String getComment()
- Get JavaDoc commentDocletTag[] getTags()
- Get all doclet tagsDocletTag[] getTagsByName()
- Get all doclet tags with a particular nameDocletTag getTagByName()
- Get first doclet tag with a particular name or null if not found
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:
JavaSource JavaClass.getParentSource()
JavaClass JavaField.getParentClass()
JavaClass JavaMethod.getParentClass()
JavaMethod JavaParameter.getParentMethod()