/*
    * Copyright 2010 - org.tinyjee.maven
    *
    *    Licensed under the Apache License, Version 2.0 (the "License");
    *    you may not use this file except in compliance with the License.
    *    You may obtain a copy of the License at
    *
    *        http://www.apache.org/licenses/LICENSE-2.0
    *
   *    Unless required by applicable law or agreed to in writing, software
   *    distributed under the License is distributed on an "AS IS" BASIS,
   *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   *    See the License for the specific language governing permissions and
   *    limitations under the License.
   */
  
  package org.tinyjee.maven.dim.extensions;
  
  import com.thoughtworks.qdox.model.*;
  import org.apache.maven.doxia.logging.Log;
  import org.codehaus.plexus.util.FileUtils;
  import org.tinyjee.maven.dim.spi.Globals;
  import org.tinyjee.maven.dim.utils.AbstractAliasHandler;
  import org.tinyjee.maven.dim.utils.JavaClassLoader;
  import org.tinyjee.maven.dim.utils.PrintableMap;
  import org.tinyjee.maven.dim.utils.SelectableJavaEntitiesList;
  
  import java.io.File;
  import java.io.IOException;
  import java.net.URISyntaxException;
  import java.net.URL;
  import java.util.*;
  
  import static java.lang.Boolean.parseBoolean;
  import static java.lang.String.valueOf;
  import static java.util.Collections.emptyMap;
  import static org.tinyjee.maven.dim.spi.ResourceResolver.findAllSources;
  
  /**
   * 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.
   * <p/>
   * 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.
   * <p/>
   * <b>Usage:</b><div><code>
   * %{include|source=template.vm|source-class=org.tinyjee.maven.dim.extensions.JavaSourceLoader|java-source=net.sf.MyClass}
   * </code></div>
   * or when using the alias:<div><code>
   * %{include|source=template.vm|source-java=net.sf.MyClass}
   * </code></div>
   * <p/>
   * <b>Notes:</b><ul>
   * <li>
   * All lists used by this extension derive from {@link org.tinyjee.maven.dim.utils.AbstractSelectableJavaEntitiesList} which means
   * they allow chained calls to {@code selectMatching(..)}, {@code selectNonMatching(..)}, {@code selectAnnotated(..)}, etc. in order to
   * further limit the amount of returned java entities. Example:
   * <code><pre>##Select all properties starting with "my" but not containing "Internal":
   * #set($myPublicProperties = $class.properties.selectMatching("..my*").selectNonMatching("..*Internal*"))
   * </pre></code>
   * </li>
   * <li>
   * All maps used by this extension derive from {@link PrintableMap} which logs any failed key access including the
   * existing map content and defines additional methods like "{@link PrintableMap#getContentAsString()}" and
   * "{@link PrintableMap#printContent()}" that may be used print the map structure.
   * </li>
   * <li>
   * 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 {@code Map<String,(String|Map<String,String>)>}, where all tags are mapped as {@code String}
   * key and value pair with one exception of "{@code param}" being mapped to a Map of {@code paramName} and {@code paramDescription}.
   * </li>
   * <li>
   * 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 "{@code @}" is used as
   * map key and the values are maps of annotation parameter name and value pairs. (values are always serialized to String)
   * </li>
   * </ul>
   *
   * @author Juergen_Kellerer, 2010-09-08
   */
  public class JavaSourceLoader extends HashMap<String, Object> {
  
  	private static final long serialVersionUID = -4069212921446859127L;
  
  	private static final String JAVA_EXT = ".java";
  
  	/**
  	 * Implements the "{@link JavaSourceLoader#PARAM_ALIAS}" alias functionality.
  	 */
  	public static class AliasHandler extends AbstractAliasHandler {
  		/**
  		 * Constructs the handler (Note: Is called by
  		 * {@link org.tinyjee.maven.dim.spi.RequestParameterTransformer#TRANSFORMERS}).
  		 */
  		public AliasHandler() {
  			super(PARAM_ALIAS, PARAM_JAVA_SOURCE, JavaSourceLoader.class.getName());
  		}
 	}
 
 	/**
 	 * Defines a shortcut for the request properties 'source-class' and 'java-source'.
 	 * <p/>
 	 * 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.
 	 */
 	public static final String PARAM_ALIAS = "source-java";
 
 	/**
 	 * Is the expected input parameter that points to the class or interface to scan.
 	 * <p/>
 	 * The class can be specified as file (with .java as extension) or as fully qualified class name.
 	 * Valid examples:<ul>
 	 * <li>your.package.YourJavaClass</li>
 	 * <li>your/package/YourJavaClass.java</li>
 	 * <li>src/main/java/your/package/YourJavaClass.java</li>
 	 * </ul>
 	 * <p/>
 	 * 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:<ul>
 	 * <li>your.package</li>
 	 * <li>your.package</li>
 	 * <li>your/package</li>
 	 * <li>src/main/java/your/package</li>
 	 * </ul>
 	 */
 	public static final String PARAM_JAVA_SOURCE = "java-source";
 
 	/**
 	 * Optional input parameter specifying the standard path to the apidocs to use when linking via
 	 * {@literal {@link}} or {@literal {@linkplain}}.
 	 * <p/>
 	 * Defaults to "./apidocs/", package specific, alternate link paths can be specified using
 	 * "{@code apidocs-my.package=http://some-host/apidocs/}".
 	 */
 	public static final String PARAM_API_DOCS = "apidocs";
 
 	/**
 	 * Optional boolean input parameter specifying whether the extension overwrites other input parameters.
 	 * <br/>
 	 * If not set (=default) nothing is overwritten except "{@code $class}".
 	 */
 	public static final String PARAM_OVERWRITE = "overwrite";
 
 
 	/**
 	 * Is filled with the fully qualified name of the specified class.
 	 */
 	public static final String OUT_PARAM_NAME = "name";
 
 	/**
 	 * Is filled with the simple name of the specified class.
 	 */
 	public static final String OUT_PARAM_SIMPLE_NAME = "simpleName";
 
 	/**
 	 * Is filled with a map containing all other output parameters that are set by this extension.
 	 * Therefore calls like {@code $class.simpleName} and {@code $simpleName} lead to exactly the same results.
 	 */
 	public static final String OUT_PARAM_CLASS = "class";
 
 	/**
 	 * Is filled with the {@link com.thoughtworks.qdox.model.JavaClass} instance of the specified class and allows
 	 * accessing the QDox reflection model directly.
 	 */
 	public static final String OUT_PARAM_JAVA_CLASS = "javaClass";
 
 	/**
 	 * Is filled with an implementation of {@link Selector} that may be used to access nested, super, implemented and derived classes.
 	 * Example Usage with Velocity:<code><pre>
 	 * #foreach($derivedClass in $class.select.derivedClasses)
 	 *     "$derivedClass.name" derives from $class.name
 	 * #end
 	 * </pre></code>
 	 */
 	public static final String OUT_PARAM_SELECTOR = "select";
 
 	/**
 	 * Is filled with a the JavaDoc comment of the specified class.
 	 */
 	public static final String OUT_PARAM_COMMENT = "comment";
 
 	/**
 	 * Is filled with a the JavaDoc Doclet-Tags of the specified class.
 	 * <p/>
 	 * The tags map has a format like <code><pre>[
 	 *     "tagName": "tagValue",
 	 *     ...
 	 *     !! Special treatment for '@param' !!
 	 *     "param": [
 	 *         "parameterName": "JavaDoc comment",
 	 *         ...
 	 *     ]
 	 * ]</pre></code>
 	 * Please note that any leading "{@code @}" characters are removed from the map keys, thus "{@code @since}"
 	 * becomes {@code $class.tags.since}.
 	 */
 	public static final String OUT_PARAM_TAGS = "tags";
 
 	/**
 	 * Is filled with a map of annotations that are applied to the class.
 	 * <p/>
 	 * 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 "{@code @}" 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 &amp; annotation hierarchies that were
 	 * set as values.
 	 * <p/>
 	 * The annotation map has a format like <code><pre>[
 	 *     "@SimpleAnnotationName": [
 	 *         "parameterName": "value",
 	 *         ...
 	 *     ],
 	 *     ...
 	 * ]</pre></code>
 	 * Accessing the default value of an annotation works as expected, e.g.:
 	 * <code><pre>
 	 * Method suppresses: $class.methods.get(0).annotations.get("@SuppressWarnings").value</pre></code>
 	 */
 	public static final String OUT_PARAM_ANNOTATIONS = "annotations";
 
 	/**
 	 * Is filled with a selectable list of public or protected class fields.
 	 * Every list row is a map that follows the format:
 	 * <code><pre>[
 	 *     "type": type (signature-string),
 	 *     "name": simple field name,
 	 *     "value": initialization expression,
 	 *     "comment": JavaDoc comment,
 	 *     "tags": Map&lt;String,(String|Map&lt;String,String&gt;)&gt;
 	 *     "field": {@link com.thoughtworks.qdox.model.JavaField},
 	 *     "annotations": Map&lt;String,Map&lt;String,String&gt;&gt;
 	 * ]</pre></code>
 	 */
 	public static final String OUT_PARAM_FIELDS = "fields";
 
 	/**
 	 * Contains the same content as <code>"fields"</code> presented as Map&lt;String,Map&lt;?,?&gt;&gt; (mapping "rows" by name).
 	 */
 	public static final String OUT_PARAM_FIELDS_MAP = "fieldsMap";
 
 	/**
 	 * 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:
 	 * <code><pre>[
 	 *     "type": type (signature-string),
 	 *     "name": simple field name,
 	 *     "value": initialization expression,
 	 *     "comment": JavaDoc comment,
 	 *     "tags": Map&lt;String,(String|Map&lt;String,String&gt;)&gt;
 	 *     "field": {@link com.thoughtworks.qdox.model.JavaField},
 	 *     "annotations": Map&lt;String,Map&lt;String,String&gt;&gt;
 	 * ]</pre></code>
 	 */
 	public static final String OUT_PARAM_DECLARED_FIELDS = "declaredFields";
 
 	/**
 	 * Contains the same content as <code>"declaredFields"</code> presented as Map&lt;String,Map&lt;?,?&gt;&gt; (mapping "rows" by name).
 	 */
 	public static final String OUT_PARAM_DECLARED_FIELDS_MAP = "declaredFieldsMap";
 
 	/**
 	 * 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:
 	 * <code><pre>[
 	 *     "type": type (signature-string),
 	 *     "name": simple field name,
 	 *     "value": initialization expression,
 	 *     "comment": JavaDoc comment,
 	 *     "tags": Map&lt;String,(String|Map&lt;String,String&gt;)&gt;
 	 *     "field": {@link com.thoughtworks.qdox.model.JavaField},
 	 *     "annotations": Map&lt;String,Map&lt;String,String&gt;&gt;
 	 * ]</pre></code>
 	 */
 	public static final String OUT_PARAM_CONSTANTS = "constants";
 
 	/**
 	 * Contains the same content as <code>"constants"</code> presented as Map&lt;String,Map&lt;?,?&gt;&gt; (mapping "rows" by name).
 	 */
 	public static final String OUT_PARAM_CONSTANTS_MAP = "constantsMap";
 
 	/**
 	 * Is filled with a selectable list of all class constants (static final fields).
 	 * Every list row is a map that follows the format:
 	 * <code><pre>[
 	 *     "type": type (signature-string),
 	 *     "name": simple field name,
 	 *     "value": initialization expression,
 	 *     "comment": JavaDoc comment,
 	 *     "tags": Map&lt;String,(String|Map&lt;String,String&gt;)&gt;
 	 *     "field": {@link com.thoughtworks.qdox.model.JavaField},
 	 *     "annotations": Map&lt;String,Map&lt;String,String&gt;&gt;
 	 * ]</pre></code>
 	 */
 	public static final String OUT_PARAM_DECLARED_CONSTANTS = "declaredConstants";
 
 	/**
 	 * Contains the same content as <code>"declaredConstants"</code> presented as Map&lt;String,Map&lt;?,?&gt;&gt; (mapping "rows" by name).
 	 */
 	public static final String OUT_PARAM_DECLARED_CONSTANTS_MAP = "declaredConstantsMap";
 
 	/**
 	 * Is filled with a selectable list of bean properties.
 	 * Every list row is a map that follows the format:
 	 * <code><pre>[
 	 *     "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&lt;String,(String|Map&lt;String,String&gt;)&gt;
 	 *     "setterComment": setter JavaDoc comment,
 	 *     "setterTags": Map&lt;String,(String|Map&lt;String,String&gt;)&gt;
 	 *     "property": {@link com.thoughtworks.qdox.model.BeanProperty},
 	 *     "getter": {@link com.thoughtworks.qdox.model.JavaMethod},
 	 *     "setter": {@link com.thoughtworks.qdox.model.JavaMethod},
 	 *     "field": {@link com.thoughtworks.qdox.model.JavaField},
 	 *     "value": field initialization expression,
 	 *     "annotations": Map&lt;String,Map&lt;String,String&gt;&gt;
 	 * ]</pre></code>
 	 * <p/>
 	 * <b>Note:</b> The annotations map contains a combined map of all annotations that were either specified on field, setter,
 	 * or getter (using this precedence on conflicts).
 	 */
 	public static final String OUT_PARAM_PROPERTIES = "properties";
 
 	/**
 	 * Contains the same content as <code>"properties"</code> presented as Map&lt;String,Map&lt;?,?&gt;&gt; (mapping "rows" by name).
 	 */
 	public static final String OUT_PARAM_PROPERTIES_MAP = "propertiesMap";
 
 	/**
 	 * Is filled with a selectable list of abstract or interface methods.
 	 * Every list row is a map that follows the format:
 	 * <code><pre>[
 	 *     "type": return type (signature-string),
 	 *     "name": simple method name,
 	 *     "signature": method call signature (signature-string),
 	 *     "comment": JavaDoc comment,
 	 *     "tags": Map&lt;String,(String|Map&lt;String,String&gt;)&gt;
 	 *     "method": {@link com.thoughtworks.qdox.model.JavaMethod},
 	 *     "annotations": Map&lt;String,Map&lt;String,String&gt;&gt;,
 	 *     "parameterAnnotations": Map&lt;String,Map&lt;String,Map&lt;String,String&gt;&gt;&gt;
 	 * ]</pre></code>
 	 */
 	public static final String OUT_PARAM_INTERFACE_METHODS = "interfaceMethods";
 
 	/**
 	 * Contains the same content as <code>"interfaceMethods"</code> presented as Map&lt;String,Map&lt;?,?&gt;&gt; (mapping "rows" by name).
 	 */
 	public static final String OUT_PARAM_INTERFACE_METHODS_MAP = "interfaceMethodsMap";
 
 	/**
 	 * Is filled with a selectable list of public or protected methods.
 	 * Every list row is a map that follows the format:
 	 * <code><pre>[
 	 *     "type": return type (signature-string),
 	 *     "name": simple method name,
 	 *     "signature": method call signature (signature-string),
 	 *     "comment": JavaDoc comment,
 	 *     "tags": Map&lt;String,(String|Map&lt;String,String&gt;)&gt;
 	 *     "method": {@link com.thoughtworks.qdox.model.JavaMethod},
 	 *     "annotations": Map&lt;String,Map&lt;String,String&gt;&gt;,
 	 *     "parameterAnnotations": Map&lt;String,Map&lt;String,Map&lt;String,String&gt;&gt;&gt;
 	 * ]</pre></code>
 	 */
 	public static final String OUT_PARAM_METHODS = "methods";
 
 	/**
 	 * Contains the same content as <code>"methods"</code> presented as Map&lt;String,Map&lt;?,?&gt;&gt; (mapping "rows" by name).
 	 */
 	public static final String OUT_PARAM_METHODS_MAP = "methodsMap";
 
 
 	/**
 	 * Defines a selector that can be used to access additional entities that relate to the loaded java class.
 	 */
 	public interface Selector {
 		/**
 		 * Returns a selectable list of all classes in the same package.
 		 *
 		 * @return a selectable list of all classes in the same package.
 		 */
 		SelectableMappedJavaEntitiesList getPackageClasses();
 
 		/**
 		 * Returns a selectable list of all classes that are below or in the same package.
 		 *
 		 * @return a selectable list of all classes that are below or in the same package.
 		 */
 		SelectableMappedJavaEntitiesList getClassesBelowPackage();
 
 		/**
 		 * Returns a selectable list of nested classes (inner classes).
 		 *
 		 * @return a selectable list of nested classes (inner classes).
 		 */
 		SelectableMappedJavaEntitiesList getNestedClasses();
 
 		/**
 		 * Returns a selectable list of all super classes (vector up to java.lang.Object).
 		 *
 		 * @return a selectable list of all super classes (vector up to java.lang.Object).
 		 */
 		SelectableMappedJavaEntitiesList getSuperClasses();
 
 		/**
 		 * Returns a selectable list of all implemented interfaces.
 		 * <p/>
 		 * 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).
 		 *
 		 * @return a selectable list of all implemented interfaces.
 		 */
 		SelectableMappedJavaEntitiesList getImplementedInterfaces();
 
 		/**
 		 * Returns a selectable list of all known classes that derive either directly or in-directly from this class.
 		 *
 		 * @return a selectable list of all known classes that derive either directly or in-directly from this class.
 		 */
 		SelectableMappedJavaEntitiesList getDerivedClasses();
 
 		/**
 		 * If this class is an annotation, it returns a selectable list of all known classes that are directly annotated
 		 * with this class.
 		 * An {@link IllegalStateException} will be thrown if the property is accessed on non-Annotation classes.
 		 *
 		 * @return a selectable list of all known classes that are directly annotated with this class..
 		 */
 		SelectableMappedJavaEntitiesList getAnnotatedClasses();
 	}
 
 	JavaClass javaClass;
 	String javaDocRootPath = "./apidocs/";
 	JavaDocTagsHandler javaDocTagsHandler;
 
 	/**
 	 * Constructs a new interface scanner.
 	 *
 	 * @param baseDir       the base dir to of the maven module.
 	 * @param requestParams the request params of the macro call.
 	 */
 	public JavaSourceLoader(File baseDir, Map<String, Object> requestParams) {
 		try {
 			final String classOrPackageName = (String) requestParams.get(PARAM_JAVA_SOURCE);
 			try {
 				final JavaSource source = getSource(baseDir, classOrPackageName);
 				init(source, requestParams);
 			} catch (IllegalArgumentException e) {
 				final JavaPackage javaPackage = getPackage(baseDir, classOrPackageName);
 				if (javaPackage == null) {
 					throw new IllegalArgumentException("'" + classOrPackageName +
 							"' doesn't seem to be a valid package name nor is it a resolveable java source.", e);
 				} else
 					init(javaPackage, requestParams);
 			}
 		} catch (IOException e) {
 			throw new RuntimeException(e);
 		}
 	}
 
 	/**
 	 * Constructs a new interface scanner for the given interface or abstract class.
 	 *
 	 * @param baseDir   the base dir to of the maven module.
 	 * @param className the class describing the interface.
 	 */
 	public JavaSourceLoader(File baseDir, String className) {
 		this(baseDir, Collections.singletonMap(PARAM_JAVA_SOURCE, (Object) className));
 	}
 
 	/**
 	 * Constructs a new interface scanner for the given java class.
 	 *
 	 * @param javaClass     the java class to scan.
 	 * @param requestParams optional request params.
 	 */
 	protected JavaSourceLoader(JavaClass javaClass, Map<String, Object> requestParams) {
 		init(javaClass, requestParams);
 	}
 
 	/**
 	 * Initializes the map values.
 	 *
 	 * @param source        the source to scan.
 	 * @param requestParams optional additional request params.
 	 */
 	protected final void init(JavaSource source, Map<String, Object> requestParams) {
 		Globals.getLog().debug("About to load first java class of source '" + source.getURL() + "'.");
 
 		final JavaClass[] classes = source.getClasses();
 		if (classes.length == 0)
 			throw new IllegalArgumentException("The given source '" + source.getURL() + "' did not contain a single class.");
 		JavaClass javaClass = classes[0];
 
 		// Support direct inner class references (using the $ delimiter).
 		String className = requestParams == null ? null : (String) requestParams.get(PARAM_JAVA_SOURCE);
 		if (className != null && className.contains("$")) {
 			className = className.substring(className.indexOf('$') + 1).replace('$', '.');
 			javaClass = javaClass.getNestedClassByName(className);
 			if (javaClass == null)
 				throw new IllegalArgumentException("Did not find nested class: " + className + " in " + classes[0]);
 		}
 
 		init(javaClass, requestParams);
 	}
 
 	/**
 	 * Initializes the map values.
 	 *
 	 * @param javaClass     the java class to scan.
 	 * @param requestParams optional additional request params.
 	 */
 	protected final void init(final JavaClass javaClass, Map<String, Object> requestParams) {
 		final Log log = Globals.getLog();
 		final boolean debug = log.isDebugEnabled();
 		this.javaClass = javaClass;
 
 		Object overwrite = null;
 
 		if (requestParams != null) {
 			overwrite = requestParams.get(PARAM_OVERWRITE);
 			putAll(requestParams);
 			String apiDocsPath = (String) requestParams.get(PARAM_API_DOCS);
 			if (apiDocsPath != null && apiDocsPath.trim().length() != 0) javaDocRootPath = apiDocsPath;
 		}
 
 		javaDocTagsHandler = new JavaDocTagsHandler(javaClass, javaDocRootPath, requestParams);
 
 		if (debug) log.debug("About to load reflection details on class '" + javaClass.getFullyQualifiedName() + "'");
 
 		scanFieldsAndConstants(javaClass);
 		scanProperties(javaClass);
 		scanMethods(javaClass);
 
 		put(OUT_PARAM_NAME, javaClass.getFullyQualifiedName());
 		put(OUT_PARAM_SIMPLE_NAME, javaClass.getName());
 		put(OUT_PARAM_JAVA_CLASS, javaClass);
 		put(OUT_PARAM_COMMENT, javaDocTagsHandler.processJavaDocComment(javaClass.getComment()));
 		put(OUT_PARAM_ANNOTATIONS, asMap(javaClass.getAnnotations()));
 		put(OUT_PARAM_TAGS, asMap(javaClass.getTags()));
 		put(OUT_PARAM_SELECTOR, new SelectorImplementation(javaClass, javaClass.getPackage()));
 
 		if (overwrite == null) putAll(requestParams);
 
 		PrintableMap<String, Object> selfIntrospection = new PrintableMap<String, Object>(
 				this, "Reflection details on class '" + javaClass.getFullyQualifiedName() + '\'');
 		put(OUT_PARAM_CLASS, selfIntrospection);
 
 		if (debug) log.debug("Loaded: $" + OUT_PARAM_CLASS + '=' + selfIntrospection.getContentAsString());
 
 		if (overwrite != null && !parseBoolean(valueOf(overwrite))) putAll(requestParams);
 	}
 
 	/**
 	 * Initializes the map values when loading a package.
 	 *
 	 * @param javaPackage   the package that is loaded.
 	 * @param requestParams the request params that were specified with the macro call.
 	 */
 	protected final void init(JavaPackage javaPackage, Map<String, Object> requestParams) {
 		put(OUT_PARAM_NAME, javaPackage.getName());
 		put(OUT_PARAM_SIMPLE_NAME, javaPackage.getName());
 		put(OUT_PARAM_ANNOTATIONS, asMap(javaPackage.getAnnotations()));
 		put(OUT_PARAM_SELECTOR, new SelectorImplementation(null, javaPackage));
 	}
 
 	/**
 	 * Loads the given class from the module's source directory.
 	 *
 	 * @param baseDir   the module's base dir (containing the 'src/main/java' folder).
 	 * @param className the name of the class.
 	 * @return The parsed JavaSource instance.
 	 * @throws IOException in case of the java source cannot be found or read.
 	 */
 	protected final JavaSource getSource(File baseDir, String className) throws IOException {
 		className = className.replace('.', '/');
 		if (className.contains("$"))
 			className = className.substring(0, className.indexOf('$'));
 
 		if (className.endsWith("/java"))
 			className = className.substring(0, className.length() - 5) + JAVA_EXT;
 		else if (!className.endsWith(JAVA_EXT))
 			className += JAVA_EXT;
 
 		return JavaClassLoader.getInstance().addSource(baseDir, className);
 	}
 
 	/**
 	 * Loads the given package from the module's source directory.
 	 *
 	 * @param baseDir     the module's base dir (containing the 'src/main/java' folder).
 	 * @param packageName the name of the package.
 	 * @return The parsed JavaPackage instance or 'null' if no java package was found.
 	 * @throws IOException in case of the java source cannot be read.
 	 */
 	protected final JavaPackage getPackage(File baseDir, String packageName) throws IOException {
 		JavaPackage aPackage = null;
 		try {
 			for (URL packageUrl : findAllSources(baseDir, packageName.replace('.', File.separatorChar))) {
 				File packagePath = "file".equalsIgnoreCase(packageUrl.getProtocol()) ? new File(packageUrl.toURI()) : null;
 
 				// Note: We load all possible paths as we might end in a dead source tree if we break
 				//       the loading loop with the first match.
 				if (packagePath != null && packagePath.isDirectory()) {
 					@SuppressWarnings("unchecked")
 					final List<File> files = FileUtils.getFiles(packagePath, "**/*.java", "**/package-info.java", true);
 					if (files.isEmpty()) continue;
 
 					aPackage = JavaClassLoader.getInstance().addSource(files.get(0).toURI().toURL(), false).getPackage();
 					while (aPackage != null && aPackage.getName().startsWith(packageName) && !aPackage.getName().equals(packageName))
 						aPackage = aPackage.getParentPackage();
 				}
 			}
 		} catch (IllegalArgumentException ignore) {
 		} catch (URISyntaxException e) {
 			throw new RuntimeException(e);
 		}
 		return aPackage;
 	}
 
 	/**
 	 * Scans all relevant methods of the specified class and sets the results as map values.
 	 *
 	 * @param javaClass the java class to scan.
 	 */
 	protected void scanMethods(JavaClass javaClass) {
 		final List<Map<?, ?>> interfaceMethods = new SelectableMappedJavaEntitiesList("method");
 		put(OUT_PARAM_INTERFACE_METHODS, interfaceMethods);
 		final List<Map<?, ?>> methods = new SelectableMappedJavaEntitiesList("method");
 		put(OUT_PARAM_METHODS, methods);
 
 		for (JavaMethod method : javaClass.getMethods()) {
 			boolean nonVisibleMethod = !method.isPublic() && !method.isProtected();
 			if (nonVisibleMethod || method.isConstructor() || method.isPropertyAccessor() || method.isPropertyMutator())
 				continue;
 
 			Map<String, Map> parameterAnnotations = new PrintableMap<String, Map>("Parameter-Annotations");
 			if (method.getParameters() != null) {
 				for (JavaParameter parameter : method.getParameters())
 					parameterAnnotations.put(parameter.getName(), asMap(parameter.getAnnotations()));
 			}
 
 			Map<?, ?> row = asMap(
 					"type", typeToString(method.getReturnType()),
 					"name", method.getName(),
 					"signature", method.getCallSignature(),
 					OUT_PARAM_COMMENT, javaDocTagsHandler.processJavaDocComment(method.getComment()),
 					OUT_PARAM_TAGS, asMap(method.getTags()),
 					"method", method,
 					OUT_PARAM_ANNOTATIONS, asMap(method.getAnnotations()),
 					"parameterAnnotations", parameterAnnotations);
 
 			if (method.isAbstract())
 				interfaceMethods.add(row);
 			else
 				methods.add(row);
 		}
 
 		put(OUT_PARAM_INTERFACE_METHODS_MAP, asMap(interfaceMethods, "name"));
 		put(OUT_PARAM_METHODS_MAP, asMap(methods, "name"));
 	}
 
 	/**
 	 * Scans all relevant bean properties of the specified class and sets the results as map values.
 	 *
 	 * @param javaClass the java class to scan.
 	 */
 	protected void scanProperties(JavaClass javaClass) {
 		final List<Map<?, ?>> properties = new SelectableMappedJavaEntitiesList("property");
 		put(OUT_PARAM_PROPERTIES, properties);
 
 		for (BeanProperty property : javaClass.getBeanProperties()) {
 			final JavaMethod getter = property.getAccessor();
 			final JavaMethod setter = property.getMutator();
 			final JavaField field = javaClass.getFieldByName(property.getName());
 
 			final Map<String, Map> annotations = new PrintableMap<String, Map>("Annotations");
 			if (getter != null) annotations.putAll(asMap(getter.getAnnotations()));
 			if (setter != null) annotations.putAll(asMap(setter.getAnnotations()));
 			if (field != null) annotations.putAll(asMap(field.getAnnotations()));
 
 			final Map<?, ?> row = asMap(
 					"type", typeToString(property.getType()),
 					"name", property.getName(),
 					OUT_PARAM_COMMENT, javaDocTagsHandler.processJavaDocComment(getter == null ? "" : getter.getComment() == null ?
 					(field == null ? "" : field.getComment()) : getter.getComment()),
 					OUT_PARAM_TAGS, getter == null ? field == null ? emptyMap() : asMap(field.getTags()) : asMap(getter.getTags()),
 					"setterComment", javaDocTagsHandler.processJavaDocComment(setter == null ? "" : setter.getComment()),
 					"setterTags", setter == null ? emptyMap() : asMap(setter.getTags()),
 					"property", property,
 					"getter", getter,
 					"setter", setter,
 					"field", field,
 					"value", field == null ? "" : field.getInitializationExpression(),
 					OUT_PARAM_ANNOTATIONS, annotations);
 
 			properties.add(row);
 		}
 
 		put(OUT_PARAM_PROPERTIES_MAP, asMap(properties, "name"));
 	}
 
 	/**
 	 * Scans all relevant fields and constants of the specified class and sets the results as map values.
 	 *
 	 * @param javaClass the java class to scan.
 	 */
 	protected void scanFieldsAndConstants(JavaClass javaClass) {
 		final List<Map<?, ?>> constants = new SelectableMappedJavaEntitiesList("field"),
 				declaredConstants = new SelectableMappedJavaEntitiesList("field");
 		put(OUT_PARAM_CONSTANTS, constants);
 		put(OUT_PARAM_DECLARED_CONSTANTS, declaredConstants);
 		final List<Map<?, ?>> fields = new SelectableMappedJavaEntitiesList("field"),
 				declaredFields = new SelectableMappedJavaEntitiesList("field");
 		put(OUT_PARAM_FIELDS, fields);
 		put(OUT_PARAM_DECLARED_FIELDS, declaredFields);
 
 		boolean classIsInterface = javaClass.isInterface();
 
 		for (JavaField field : javaClass.getFields()) {
 			boolean fieldIsConstant = classIsInterface || (field.isFinal() && field.isStatic());
 
 			Map<?, ?> row = asMap(
 					"type", typeToString(field.getType()),
 					"name", field.getName(),
 					"value", field.getInitializationExpression(),
 					OUT_PARAM_COMMENT, javaDocTagsHandler.processJavaDocComment(field.getComment()),
 					OUT_PARAM_TAGS, asMap(field.getTags()),
 					"field", field,
 					OUT_PARAM_ANNOTATIONS, asMap(field.getAnnotations()));
 
 			(fieldIsConstant ? declaredConstants : declaredFields).add(row);
 
 			if (!field.isPublic() && !field.isProtected() && !classIsInterface)
 				continue;
 
 			(fieldIsConstant ? constants : fields).add(row);
 		}
 
 		put(OUT_PARAM_CONSTANTS_MAP, asMap(constants, "name"));
 		put(OUT_PARAM_DECLARED_CONSTANTS_MAP, asMap(declaredConstants, "name"));
 		put(OUT_PARAM_FIELDS_MAP, asMap(fields, "name"));
 		put(OUT_PARAM_DECLARED_FIELDS_MAP, asMap(declaredFields, "name"));
 	}
 
 	/**
 	 * Converts the given doclet tags to a map of key->value pairs with any inline doclet tags being converted to XHTML markup.
 	 *
 	 * @param tags the tags to convert.
 	 * @return a key & value
 	 */
 	@SuppressWarnings("unchecked")
 	protected Map<String, Object> asMap(DocletTag... tags) {
 		Map<String, Object> result = new PrintableMap<String, Object>("Doclet-Tags");
 		for (DocletTag tag : tags) {
 			Map targetMap = result;
 			String name = tag.getName(), value = tag.getValue();
 
 			if ("see".equalsIgnoreCase(name)) {
 				value = "{@link " + value + '}';
 			} else if ("param".equalsIgnoreCase(name)) {
 				if (tag.getParameters().length > 0) {
 					name = tag.getParameters()[0];
 					if (result.containsKey("param")) targetMap = (Map) result.get("param");
 					else result.put("param", targetMap = new PrintableMap<String, Object>("Method-Params-Tags"));
 				} else
 					continue;
 			}
 
 			targetMap.put(name, javaDocTagsHandler.processJavaDocComment(value));
 		}
 		return result;
 	}
 
 	/**
 	 * Converts the given type to string.
 	 *
 	 * @param type the type to convert.
 	 * @return the string representation or an empty string.
 	 */
 	protected static String typeToString(Type type) {
 		return type == null ? "" : type.toGenericString();
 	}
 
 	/**
 	 * 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 '@').
 	 *
 	 * @param annotations the annotations to convert to a map.
 	 * @return a map mapping the simple name of the annotation to its parameters.
 	 */
 	@SuppressWarnings("unchecked")
 	protected static Map<String, Map> asMap(Annotation... annotations) {
 		Map<String, Map> result = new PrintableMap<String, Map>("Annotations");
 		for (Annotation annotation : annotations) {
 			String name = annotation.getType().getFullyQualifiedName();
 			name = "@".concat(name.substring(name.lastIndexOf('.') + 1));
 
 			Map<Object, Object> map = new PrintableMap<Object, Object>("Annotation-Parameters");
 			map.putAll(annotation.getNamedParameterMap());
 			for (Map.Entry<Object, Object> entry : map.entrySet())
 				if (entry.getValue() != null)
 					entry.setValue(entry.getValue().toString().trim());
 
 			result.put(name, map);
 		}
 
 		return result;
 	}
 
 	/**
 	 * Converts the given key and value pairs to a Map that is linked by key and index (=> associative array).
 	 *
 	 * @param keyValuePairs the key and value pairs to convert.
 	 * @return a Map that is linked by key and index.
 	 */
 	protected static Map<Object, Object> asMap(Object... keyValuePairs) {
 		if (keyValuePairs.length % 2 != 0)
 			throw new IllegalArgumentException("The key and value input array length must be a multiple of 2.");
 
 		final Map<Object, Object> map = new PrintableMap<Object, Object>("Key-Value-Pairs"),
 				assocMap = new LinkedHashMap<Object, Object>(keyValuePairs.length / 2);
 
 		for (int i = 0; i < keyValuePairs.length; i += 2) {
 			Object key = valueOf(keyValuePairs[i]), value = keyValuePairs[i + 1];
 			map.put(i / 2, value);
 			assocMap.put(key, value);
 		}
 
 		map.putAll(assocMap);
 
 		return map;
 	}
 
 	/**
 	 * Converts the given named rows to a map by name.
 	 *
 	 * @param namedRows the named rows to map.
 	 * @param nameKey   the key to use to extract the name.
 	 * @return the mapped rows.
 	 */
 	protected static Map<String, Map<?, ?>> asMap(Iterable<Map<?, ?>> namedRows, String nameKey) {
 		final Map<String, Map<?, ?>> map = new PrintableMap<String, Map<?, ?>>("Named-Class-Elements");
 		for (Map<?, ?> namedRow : namedRows)
 			map.put((String) namedRow.get(nameKey), namedRow);
 
 		return map;
 	}
 
 	private class SelectorImplementation implements Selector {
 
 		private final JavaClass javaClass;
 		private final JavaPackage javaPackage;
 
 		SelectorImplementation(JavaClass javaClass, JavaPackage javaPackage) {
 			this.javaClass = javaClass;
 			this.javaPackage = javaPackage;
 		}
 
 		Map<String, Object> extractRequestParams() {
 			Map<String, Object> requestParams = new HashMap<String, Object>();
 			for (Map.Entry<String, Object> entry : entrySet()) {
 				if (entry.getKey().startsWith(PARAM_API_DOCS))
 					requestParams.put(entry.getKey(), entry.getValue());
 			}
 			return requestParams;
 		}
 
 		List<Map<String, ?>> convert(Collection<JavaClass> classes) {
 			return convert(classes.toArray(new JavaClass[classes.size()]));
 		}
 
 		List<Map<String, ?>> convert(JavaClass[] classes) {
 			Map<String, Object> requestParams = extractRequestParams();
 			final List<Map<String, ?>> sourceLoaders = new ArrayList<Map<String, ?>>(classes.length);
 			for (JavaClass aClass : classes)
 				sourceLoaders.add(new PrintableMap<String, Object>(new JavaSourceLoader(aClass, requestParams), aClass.toString()));
 			return sourceLoaders;
 		}
 
 		public SelectableMappedJavaEntitiesList getPackageClasses() {
 			final JavaClass[] classes = javaPackage == null ? new JavaClass[0] : javaPackage.getClasses();
 			return new SelectableMappedJavaEntitiesList(convert(classes), OUT_PARAM_JAVA_CLASS);
 		}
 
 		public SelectableMappedJavaEntitiesList getClassesBelowPackage() {
 			final List<JavaClass> classes = new ArrayList<JavaClass>();
 			if (javaPackage == null)
 				classes.addAll(JavaClassLoader.getInstance().getClasses());
 			else {
 				String prefix = javaPackage.getName() + '.';
 				for (JavaPackage candidate : JavaClassLoader.getInstance().getPackages()) {
 					if (candidate.equals(javaPackage) || candidate.getName().startsWith(prefix))
 						classes.addAll(Arrays.asList(candidate.getClasses()));
 				}
 			}
 
 			return new SelectableMappedJavaEntitiesList(convert(classes), OUT_PARAM_JAVA_CLASS);
 		}
 
 		public SelectableMappedJavaEntitiesList getNestedClasses() {
 			final JavaClass[] nestedClasses = javaClass == null ? new JavaClass[0] : javaClass.getNestedClasses();
 			return new SelectableMappedJavaEntitiesList(convert(nestedClasses), OUT_PARAM_JAVA_CLASS);
 		}
 
 		public SelectableMappedJavaEntitiesList getSuperClasses() {
 			final List<JavaClass> knownSuperClasses = new ArrayList<JavaClass>();
 			if (javaClass != null) {
 				for (JavaClass superClass = javaClass.getSuperJavaClass(); superClass != null; superClass = superClass.getSuperJavaClass())
 					knownSuperClasses.add(superClass);
 			}
 
 			final List<Map<String, ?>> mapList = convert(knownSuperClasses.toArray(new JavaClass[knownSuperClasses.size()]));
 			return new SelectableMappedJavaEntitiesList(mapList, OUT_PARAM_JAVA_CLASS);
 		}
 
 		public SelectableMappedJavaEntitiesList getImplementedInterfaces() {
 			final JavaClass[] interfaces = javaClass == null ? new JavaClass[0] : javaClass.getImplementedInterfaces();
 			return new SelectableMappedJavaEntitiesList(convert(interfaces), OUT_PARAM_JAVA_CLASS);
 		}
 
 		public SelectableMappedJavaEntitiesList getDerivedClasses() {
 			final JavaClass[] classes = javaClass == null ? new JavaClass[0] : javaClass.getDerivedClasses();
 			return new SelectableMappedJavaEntitiesList(convert(classes), OUT_PARAM_JAVA_CLASS);
 		}
 
 		public SelectableMappedJavaEntitiesList getAnnotatedClasses() {
 			if (!SelectableMappedJavaEntitiesList.isAnnotation(javaClass)) {
 				throw new IllegalStateException("Cannot look after classes that are annotated with '" + javaClass +
 						"' as this class is no annotation.");
 			}
 
 			final SortedSet<JavaClass> allClasses = JavaClassLoader.getInstance().getClasses();
 			final SelectableJavaEntitiesList<JavaClass> entitiesList = new SelectableJavaEntitiesList<JavaClass>(allClasses);
 			final List<Map<String, ?>> converted = convert(entitiesList.selectAnnotated('@' + javaClass.getFullyQualifiedName()));
 
 			return new SelectableMappedJavaEntitiesList(converted, OUT_PARAM_JAVA_CLASS);
 		}
 	}
 }