Extensions :: Java Source Loader

Reference - Using Reflection to Document Interfaces

JavaSourceLoader is a 'source-class' compatible helper class that loads a java class (at source level including JavaDoc) and makes the class details available to velocity templates. It can effectively be used to include content into maven sites that is similar (and in sync) with JavaDoc, with the difference that only those portions can be included that are important within a certain scope.

Use this loader when you want to access the parsed content of Java sources within velocity templates using the variables that are exposed by this loader. This extension is not needed if your aim is to include code snippets.

Usage:
%{include|source=template.vm|source-class=org.tinyjee.maven.dim.extensions.JavaSourceLoader|java-source=net.sf.MyClass}
or when using the alias:
%{include|source=template.vm|source-java=net.sf.MyClass}

Notes:
  • All lists used by this extension derive from AbstractSelectableJavaEntitiesList which means they allow chained calls to selectMatching(..), selectNonMatching(..), selectAnnotated(..), etc. in order to further limit the amount of returned java entities. Example: 
    ##Select all properties starting with "my" but not containing "Internal":
#set($myPublicProperties = $class.properties.selectMatching("..my*").selectNonMatching("..*Internal*"))
  • All maps used by this extension derive from PrintableMap which logs any failed key access including the existing map content and defines additional methods like "PrintableMap#getContentAsString()" and "PrintableMap#printContent()" that may be used print the map structure.
  • Applied doclet tags are parsed and translated to XHTML markup. Non-inline tags are stripped from the comments and copied into a map of the format Map<String,(String|Map<String,String>)>, where all tags are mapped as String key and value pair with one exception of "param" being mapped to a Map of paramName and paramDescription.
  • Applied annotations are pre-processed for simplified access within a velocity template and are stored within list rows using a map (usually referenced via "annotations"). The simple name of the mapped annotation starting with "@" is used as map key and the values are maps of annotation parameter name and value pairs. (values are always serialized to String)

Parameters:

Parameter Name Description
Input Parameters (set with the macro call)
"source-java" Defines a shortcut for the request properties 'source-class' and 'java-source'.

If this parameter is present inside the request parameters list, the system will effectively behave as if 'source-class' and 'java-source' where set separately.
"java-source" Is the expected input parameter that points to the class or interface to scan.

The class can be specified as file (with .java as extension) or as fully qualified class name. Valid examples:
  • your.package.YourJavaClass
  • your/package/YourJavaClass.java
  • src/main/java/your/package/YourJavaClass.java

If only a package name or package file path is given, the extension loads the package information instead. When this feature is used most output parameters will be empty. Valid examples:
  • your.package
  • your.package
  • your/package
  • src/main/java/your/package
"apidocs" Optional input parameter specifying the standard path to the apidocs to use when linking via {@link} or {@linkplain}.

Defaults to "./apidocs/", package specific, alternate link paths can be specified using "apidocs-my.package=http://some-host/apidocs/".
"overwrite" Optional boolean input parameter specifying whether the extension overwrites other input parameters.
If not set (=default) nothing is overwritten except "$class".
Output Parameters (set by the extension)
"name" Is filled with the fully qualified name of the specified class.
"simpleName" Is filled with the simple name of the specified class.
"class" Is filled with a map containing all other output parameters that are set by this extension. Therefore calls like $class.simpleName and $simpleName lead to exactly the same results.
"javaClass" Is filled with the JavaClass instance of the specified class and allows accessing the QDox reflection model directly.
"select" Is filled with an implementation of JavaSourceLoader$Selector that may be used to access nested, super, implemented and derived classes. Example Usage with Velocity:
#foreach($derivedClass in $class.select.derivedClasses)
    "$derivedClass.name" derives from $class.name
#end
"comment" Is filled with a the JavaDoc comment of the specified class.
"tags" Is filled with a the JavaDoc Doclet-Tags of the specified class.

The tags map has a format like 
[
    "tagName": "tagValue",
    ...
    !! Special treatment for '@param' !!
    "param": [
        "parameterName": "JavaDoc comment",
        ...
    ]
]
 Please note that any leading "@" characters are removed from the map keys, thus "@since" becomes $class.tags.since.
"annotations" Is filled with a map of annotations that are applied to the class.

Applied annotations are pre-processed for simplified access within a velocity template by translating the QDox model into a map. The simple name of the mapped annotation starting with "@" is used as map key and the values are maps of annotation parameter name and value pairs. All values are serialized to string, which includes arrays & annotation hierarchies that were set as values.

The annotation map has a format like 
[
    "@SimpleAnnotationName": [
        "parameterName": "value",
        ...
    ],
    ...
]
 Accessing the default value of an annotation works as expected, e.g.: 
Method suppresses: $class.methods.get(0).annotations.get("@SuppressWarnings").value
"fields" Is filled with a selectable list of public or protected class fields. Every list row is a map that follows the format: 
[
    "type": type (signature-string),
    "name": simple field name,
    "value": initialization expression,
    "comment": JavaDoc comment,
    "tags": Map<String,(String|Map<String,String>)>
    "field": JavaField,
    "annotations": Map<String,Map<String,String>>
]
"fieldsMap" Contains the same content as "fields" presented as Map<String,Map<?,?>> (mapping "rows" by name).
"declaredFields" Is filled with a selectable list of all class fields that are not static and final. Every list row is a map that follows the format: 
[
    "type": type (signature-string),
    "name": simple field name,
    "value": initialization expression,
    "comment": JavaDoc comment,
    "tags": Map<String,(String|Map<String,String>)>
    "field": JavaField,
    "annotations": Map<String,Map<String,String>>
]
"declaredFieldsMap" Contains the same content as "declaredFields" presented as Map<String,Map<?,?>> (mapping "rows" by name).
"constants" Is filled with a selectable list of public or protected class constants (static final fields). Every list row is a map that follows the format: 
[
    "type": type (signature-string),
    "name": simple field name,
    "value": initialization expression,
    "comment": JavaDoc comment,
    "tags": Map<String,(String|Map<String,String>)>
    "field": JavaField,
    "annotations": Map<String,Map<String,String>>
]
"constantsMap" Contains the same content as "constants" presented as Map<String,Map<?,?>> (mapping "rows" by name).
"declaredConstants" Is filled with a selectable list of all class constants (static final fields). Every list row is a map that follows the format: 
[
    "type": type (signature-string),
    "name": simple field name,
    "value": initialization expression,
    "comment": JavaDoc comment,
    "tags": Map<String,(String|Map<String,String>)>
    "field": JavaField,
    "annotations": Map<String,Map<String,String>>
]
"declaredConstantsMap" Contains the same content as "declaredConstants" presented as Map<String,Map<?,?>> (mapping "rows" by name).
"properties" Is filled with a selectable list of bean properties. Every list row is a map that follows the format: 
[
    "type": property type (signature-string),
    "name": simple property name (equals the name of the field),
    "comment": getter or field JavaDoc comment (field comment is used when getter contains no comment),
    "tags": Map<String,(String|Map<String,String>)>
    "setterComment": setter JavaDoc comment,
    "setterTags": Map<String,(String|Map<String,String>)>
    "property": BeanProperty,
    "getter": JavaMethod,
    "setter": JavaMethod,
    "field": JavaField,
    "value": field initialization expression,
    "annotations": Map<String,Map<String,String>>
]

Note: The annotations map contains a combined map of all annotations that were either specified on field, setter, or getter (using this precedence on conflicts).
"propertiesMap" Contains the same content as "properties" presented as Map<String,Map<?,?>> (mapping "rows" by name).
"interfaceMethods" Is filled with a selectable list of abstract or interface methods. Every list row is a map that follows the format: 
[
    "type": return type (signature-string),
    "name": simple method name,
    "signature": method call signature (signature-string),
    "comment": JavaDoc comment,
    "tags": Map<String,(String|Map<String,String>)>
    "method": JavaMethod,
    "annotations": Map<String,Map<String,String>>,
    "parameterAnnotations": Map<String,Map<String,Map<String,String>>>
]
"interfaceMethodsMap" Contains the same content as "interfaceMethods" presented as Map<String,Map<?,?>> (mapping "rows" by name).
"methods" Is filled with a selectable list of public or protected methods. Every list row is a map that follows the format: 
[
    "type": return type (signature-string),
    "name": simple method name,
    "signature": method call signature (signature-string),
    "comment": JavaDoc comment,
    "tags": Map<String,(String|Map<String,String>)>
    "method": JavaMethod,
    "annotations": Map<String,Map<String,String>>,
    "parameterAnnotations": Map<String,Map<String,Map<String,String>>>
]
"methodsMap" Contains the same content as "methods" presented as Map<String,Map<?,?>> (mapping "rows" by name).
Note: Output parameters are set when this extension is used and can be accessed from velocity templates using $nameOfOutputParameter
Implementation "org.tinyjee.maven.dim.extensions.JavaSourceLoader": ApiDoc | Source

Selector (Class Navigation via $select)

Property Description
SelectableMappedJavaEntitiesList packageClasses Returns a selectable list of all classes in the same package.
SelectableMappedJavaEntitiesList classesBelowPackage Returns a selectable list of all classes that are below or in the same package.
SelectableMappedJavaEntitiesList nestedClasses Returns a selectable list of nested classes (inner classes).
SelectableMappedJavaEntitiesList superClasses Returns a selectable list of all super classes (vector up to java.lang.Object).
SelectableMappedJavaEntitiesList implementedInterfaces Returns a selectable list of all implemented interfaces.

Note: Interfaces that extend other interfaces actually "implement" them and will be listed in this list instead of superClasses (even if the keyword inside the code is extends).
SelectableMappedJavaEntitiesList derivedClasses Returns a selectable list of all known classes that derive either directly or in-directly from this class.
SelectableMappedJavaEntitiesList annotatedClasses If this class is an annotation, it returns a selectable list of all known classes that are directly annotated with this class. An IllegalStateException will be thrown if the property is accessed on non-Annotation classes.

Examples

Note: All "Parameter Reference" sections are using this extension to create the documentation directly from the implementing source classes, ensuring the documentation is always in sync. with the sources.

See Real World Usage: The Usage & Reference Page