org.tinyjee.maven.dim.extensions
Class JavaSourceLoader

java.lang.Object
  java.util.AbstractMap<K,V>
      java.util.HashMap<String,Object>
          org.tinyjee.maven.dim.extensions.JavaSourceLoader

All Implemented Interfaces:

Serializable, Cloneable, Map<String,Object>

Direct Known Subclasses:

InterfaceScanner

public class JavaSourceLoader
extends HashMap<String,Object>

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)

Author:

Juergen_Kellerer, 2010-09-08

See Also:

Serialized Form

Nested Class Summary

static class	JavaSourceLoader.AliasHandler Implements the "PARAM_ALIAS" alias functionality.
static interface	JavaSourceLoader.Selector Defines a selector that can be used to access additional entities that relate to the loaded java class.

Nested classes/interfaces inherited from class java.util.AbstractMap

AbstractMap.SimpleEntry<K,V>, AbstractMap.SimpleImmutableEntry<K,V>

Field Summary

static String	OUT_PARAM_ANNOTATIONS Is filled with a map of annotations that are applied to the class.
static String	OUT_PARAM_CLASS Is filled with a map containing all other output parameters that are set by this extension.
static String	OUT_PARAM_COMMENT Is filled with a the JavaDoc comment of the specified class.
static String	OUT_PARAM_CONSTANTS Is filled with a selectable list of public or protected class constants (static final fields).
static String	OUT_PARAM_CONSTANTS_MAP Contains the same content as "constants" presented as Map<String,Map<?
static String	OUT_PARAM_DECLARED_CONSTANTS Is filled with a selectable list of all class constants (static final fields).
static String	OUT_PARAM_DECLARED_CONSTANTS_MAP Contains the same content as "declaredConstants" presented as Map<String,Map<?
static String	OUT_PARAM_DECLARED_FIELDS Is filled with a selectable list of all class fields that are not static and final.
static String	OUT_PARAM_DECLARED_FIELDS_MAP Contains the same content as "declaredFields" presented as Map<String,Map<?
static String	OUT_PARAM_FIELDS Is filled with a selectable list of public or protected class fields.
static String	OUT_PARAM_FIELDS_MAP Contains the same content as "fields" presented as Map<String,Map<?
static String	OUT_PARAM_INTERFACE_METHODS Is filled with a selectable list of abstract or interface methods.
static String	OUT_PARAM_INTERFACE_METHODS_MAP Contains the same content as "interfaceMethods" presented as Map<String,Map<?
static String	OUT_PARAM_JAVA_CLASS Is filled with the JavaClass instance of the specified class and allows accessing the QDox reflection model directly.
static String	OUT_PARAM_METHODS Is filled with a selectable list of public or protected methods.
static String	OUT_PARAM_METHODS_MAP Contains the same content as "methods" presented as Map<String,Map<?
static String	OUT_PARAM_NAME Is filled with the fully qualified name of the specified class.
static String	OUT_PARAM_PROPERTIES Is filled with a selectable list of bean properties.
static String	OUT_PARAM_PROPERTIES_MAP Contains the same content as "properties" presented as Map<String,Map<?
static String	OUT_PARAM_SELECTOR Is filled with an implementation of JavaSourceLoader.Selector that may be used to access nested, super, implemented and derived classes.
static String	OUT_PARAM_SIMPLE_NAME Is filled with the simple name of the specified class.
static String	OUT_PARAM_TAGS Is filled with a the JavaDoc Doclet-Tags of the specified class.
static String	PARAM_ALIAS Defines a shortcut for the request properties 'source-class' and 'java-source'.
static String	PARAM_API_DOCS Optional input parameter specifying the standard path to the apidocs to use when linking via {@link} or {@linkplain}.
static String	PARAM_JAVA_SOURCE Is the expected input parameter that points to the class or interface to scan.
static String	PARAM_OVERWRITE Optional boolean input parameter specifying whether the extension overwrites other input parameters.

Constructor Summary

	JavaSourceLoader(File baseDir, Map<String,Object> requestParams) Constructs a new interface scanner.
	JavaSourceLoader(File baseDir, String className) Constructs a new interface scanner for the given interface or abstract class.
protected	JavaSourceLoader(JavaClass javaClass, Map<String,Object> requestParams) Constructs a new interface scanner for the given java class.

Method Summary

protected static Map<String,Map>	asMap(Annotation... annotations) Converts the given set of annotations to a map, mapping the simple name of the annotation against a key=>value map of the specified parameters (the simple name starts with '@').
protected Map<String,Object>	asMap(DocletTag... tags) Converts the given doclet tags to a map of key->value pairs with any inline doclet tags being converted to XHTML markup.
protected static Map<String,Map<?,?>>	asMap(Iterable<Map<?,?>> namedRows, String nameKey) Converts the given named rows to a map by name.
protected static Map<Object,Object>	asMap(Object... keyValuePairs) Converts the given key and value pairs to a Map that is linked by key and index (=> associative array).
protected JavaPackage	getPackage(File baseDir, String packageName) Loads the given package from the module's source directory.
protected JavaSource	getSource(File baseDir, String className) Loads the given class from the module's source directory.
protected void	init(JavaClass javaClass, Map<String,Object> requestParams) Initializes the map values.
protected void	init(JavaPackage javaPackage, Map<String,Object> requestParams) Initializes the map values when loading a package.
protected void	init(JavaSource source, Map<String,Object> requestParams) Initializes the map values.
protected void	scanFieldsAndConstants(JavaClass javaClass) Scans all relevant fields and constants of the specified class and sets the results as map values.
protected void	scanMethods(JavaClass javaClass) Scans all relevant methods of the specified class and sets the results as map values.
protected void	scanProperties(JavaClass javaClass) Scans all relevant bean properties of the specified class and sets the results as map values.
protected static String	typeToString(Type type) Converts the given type to string.

Methods inherited from class java.util.HashMap

clear, clone, containsKey, containsValue, entrySet, get, isEmpty, keySet, put, putAll, remove, size, values

Methods inherited from class java.util.AbstractMap

equals, hashCode, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

equals, hashCode

Field Detail

PARAM_ALIAS

public static final String PARAM_ALIAS

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.

See Also:

Constant Field Values

PARAM_JAVA_SOURCE

public static final String PARAM_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

See Also:

Constant Field Values

PARAM_API_DOCS

public static final String PARAM_API_DOCS

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/".

See Also:

Constant Field Values

PARAM_OVERWRITE

public static final String PARAM_OVERWRITE

Optional boolean input parameter specifying whether the extension overwrites other input parameters.
If not set (=default) nothing is overwritten except "$class".

See Also:

Constant Field Values

OUT_PARAM_NAME

public static final String OUT_PARAM_NAME

Is filled with the fully qualified name of the specified class.

See Also:

Constant Field Values

OUT_PARAM_SIMPLE_NAME

public static final String OUT_PARAM_SIMPLE_NAME

Is filled with the simple name of the specified class.

See Also:

Constant Field Values

OUT_PARAM_CLASS

public static final String OUT_PARAM_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.

See Also:

Constant Field Values

OUT_PARAM_JAVA_CLASS

public static final String OUT_PARAM_JAVA_CLASS

Is filled with the JavaClass instance of the specified class and allows accessing the QDox reflection model directly.

See Also:

Constant Field Values

OUT_PARAM_SELECTOR

public static final String OUT_PARAM_SELECTOR

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
 

See Also:

Constant Field Values

OUT_PARAM_COMMENT

public static final String OUT_PARAM_COMMENT

Is filled with a the JavaDoc comment of the specified class.

See Also:

Constant Field Values

OUT_PARAM_TAGS

public static final String OUT_PARAM_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.

See Also:

Constant Field Values

OUT_PARAM_ANNOTATIONS

public static final String OUT_PARAM_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

See Also:

Constant Field Values

OUT_PARAM_FIELDS

public static final String OUT_PARAM_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>>
 ]

See Also:

Constant Field Values

OUT_PARAM_FIELDS_MAP

public static final String OUT_PARAM_FIELDS_MAP

Contains the same content as "fields" presented as Map<String,Map<?,?>> (mapping "rows" by name).

See Also:

Constant Field Values

OUT_PARAM_DECLARED_FIELDS

public static final String OUT_PARAM_DECLARED_FIELDS

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>>
 ]

See Also:

Constant Field Values

OUT_PARAM_DECLARED_FIELDS_MAP

public static final String OUT_PARAM_DECLARED_FIELDS_MAP

Contains the same content as "declaredFields" presented as Map<String,Map<?,?>> (mapping "rows" by name).

See Also:

Constant Field Values

OUT_PARAM_CONSTANTS

public static final String OUT_PARAM_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>>
 ]

See Also:

Constant Field Values

OUT_PARAM_CONSTANTS_MAP

public static final String OUT_PARAM_CONSTANTS_MAP

Contains the same content as "constants" presented as Map<String,Map<?,?>> (mapping "rows" by name).

See Also:

Constant Field Values

OUT_PARAM_DECLARED_CONSTANTS

public static final String OUT_PARAM_DECLARED_CONSTANTS

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>>
 ]

See Also:

Constant Field Values

OUT_PARAM_DECLARED_CONSTANTS_MAP

public static final String OUT_PARAM_DECLARED_CONSTANTS_MAP

Contains the same content as "declaredConstants" presented as Map<String,Map<?,?>> (mapping "rows" by name).

See Also:

Constant Field Values

OUT_PARAM_PROPERTIES

public static final String OUT_PARAM_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).

See Also:

Constant Field Values

OUT_PARAM_PROPERTIES_MAP

public static final String OUT_PARAM_PROPERTIES_MAP

Contains the same content as "properties" presented as Map<String,Map<?,?>> (mapping "rows" by name).

See Also:

Constant Field Values

OUT_PARAM_INTERFACE_METHODS

public static final String OUT_PARAM_INTERFACE_METHODS

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>>>
 ]

See Also:

Constant Field Values

OUT_PARAM_INTERFACE_METHODS_MAP

public static final String OUT_PARAM_INTERFACE_METHODS_MAP

Contains the same content as "interfaceMethods" presented as Map<String,Map<?,?>> (mapping "rows" by name).

See Also:

Constant Field Values

OUT_PARAM_METHODS

public static final String OUT_PARAM_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>>>
 ]

See Also:

Constant Field Values

OUT_PARAM_METHODS_MAP

public static final String OUT_PARAM_METHODS_MAP

Contains the same content as "methods" presented as Map<String,Map<?,?>> (mapping "rows" by name).

See Also:

Constant Field Values

Constructor Detail

JavaSourceLoader

public JavaSourceLoader(File baseDir,
                        Map<String,Object> requestParams)

Constructs a new interface scanner.

Parameters:

baseDir - the base dir to of the maven module.

requestParams - the request params of the macro call.

JavaSourceLoader

public JavaSourceLoader(File baseDir,
                        String className)

Constructs a new interface scanner for the given interface or abstract class.

Parameters:

baseDir - the base dir to of the maven module.

className - the class describing the interface.

JavaSourceLoader

protected JavaSourceLoader(JavaClass javaClass,
                           Map<String,Object> requestParams)

Constructs a new interface scanner for the given java class.

Parameters:

javaClass - the java class to scan.

requestParams - optional request params.

Method Detail

init

protected final void init(JavaSource source,
                          Map<String,Object> requestParams)

Initializes the map values.

Parameters:

source - the source to scan.

requestParams - optional additional request params.

init

protected final void init(JavaClass javaClass,
                          Map<String,Object> requestParams)

Initializes the map values.

Parameters:

javaClass - the java class to scan.

requestParams - optional additional request params.

init

protected final void init(JavaPackage javaPackage,
                          Map<String,Object> requestParams)

Initializes the map values when loading a package.

Parameters:

javaPackage - the package that is loaded.

requestParams - the request params that were specified with the macro call.

getSource

protected final JavaSource getSource(File baseDir,
                                     String className)
                              throws IOException

Loads the given class from the module's source directory.

Parameters:

baseDir - the module's base dir (containing the 'src/main/java' folder).

className - the name of the class.

Returns:

The parsed JavaSource instance.

Throws:

IOException - in case of the java source cannot be found or read.

getPackage

protected final JavaPackage getPackage(File baseDir,
                                       String packageName)
                                throws IOException

Loads the given package from the module's source directory.

Parameters:

baseDir - the module's base dir (containing the 'src/main/java' folder).

packageName - the name of the package.

Returns:

The parsed JavaPackage instance or 'null' if no java package was found.

Throws:

IOException - in case of the java source cannot be read.

scanMethods

protected void scanMethods(JavaClass javaClass)

Scans all relevant methods of the specified class and sets the results as map values.

Parameters:

javaClass - the java class to scan.

scanProperties

protected void scanProperties(JavaClass javaClass)

Scans all relevant bean properties of the specified class and sets the results as map values.

Parameters:

javaClass - the java class to scan.

scanFieldsAndConstants

protected void scanFieldsAndConstants(JavaClass javaClass)

Scans all relevant fields and constants of the specified class and sets the results as map values.

Parameters:

javaClass - the java class to scan.

asMap

protected Map<String,Object> asMap(DocletTag... tags)

Converts the given doclet tags to a map of key->value pairs with any inline doclet tags being converted to XHTML markup.

Parameters:

tags - the tags to convert.

Returns:

a key & value

typeToString

protected static String typeToString(Type type)

Converts the given type to string.

Parameters:

type - the type to convert.

Returns:

the string representation or an empty string.

asMap

protected static Map<String,Map> asMap(Annotation... annotations)

Converts the given set of annotations to a map, mapping the simple name of the annotation against a key=>value map of the specified parameters (the simple name starts with '@').

Parameters:

annotations - the annotations to convert to a map.

Returns:

a map mapping the simple name of the annotation to its parameters.

asMap

protected static Map<Object,Object> asMap(Object... keyValuePairs)

Converts the given key and value pairs to a Map that is linked by key and index (=> associative array).

Parameters:

keyValuePairs - the key and value pairs to convert.

Returns:

a Map that is linked by key and index.

asMap

protected static Map<String,Map<?,?>> asMap(Iterable<Map<?,?>> namedRows,
                                            String nameKey)

Converts the given named rows to a map by name.

Parameters:

namedRows - the named rows to map.

nameKey - the key to use to extract the name.

Returns:

the mapped rows.