:toc:
toc::[]

= Java Plug-in
The CobiGen Java Plug-in comes with a new input reader for java artifacts, new java related trigger and matchers, as well as a merging mechanism for Java sources.

== Trigger extension
The Java Plug-in provides a new trigger for Java related inputs. It accepts different representations as inputs (see xref:java-input-reader[Java input reader]) and provides additional matching and variable assignment mechanisms. The configuration in the `context.xml` for this trigger looks like this:

* type 'java'
+
.Example of a java trigger definition
[source,xml]
----
<trigger id="..." type="java" templateFolder="...">
    ...
</trigger>
----
+

This trigger type enables Java elements as inputs.

=== Matcher types
With the trigger you might define matchers, which restrict the input upon specific aspects:

* type `fqn` -> full qualified name matching
+
.Example of a java trigger definition with a full qualified name matcher
[source,xml]
----
<trigger id="..." type="java" templateFolder="...">
    <matcher type="fqn" value="(.+)\.persistence\.([^\.]+)\.entity\.([^\.]+)">
        ...
    </matcher>
</trigger>
----
+

This trigger will be enabled if the full qualified name (`fqn`) of the declaring input class matches the given regular expression (`value`). 

* type 'package' -> package name of the input
+
.Example of a java trigger definition with a package name matcher
[source,xml]
----
<trigger id="..." type="java" templateFolder="...">
    <matcher type="package" value="(.+)\.persistence\.([^\.]+)\.entity">
        ...
    </matcher>
</trigger>
----
+

This trigger will be enabled if the package name (`package`) of the declaring input class matches the given regular expression (`value`). 

* type 'expression'
+
.Example of a java trigger definition with a package name matcher
[source,xml]
----
<trigger id="..." type="java" templateFolder="...">
    <matcher type="expression" value="instanceof java.lang.String">
        ...
    </matcher>
</trigger>
----
+

This trigger will be enabled if the expression evaluates to true. Valid expressions are

* `instanceof fqn`: checks an 'is a' relation of the input type
* `isAbstract`: checks, whether the input type is declared abstract

=== Container Matcher types
Additionally, the java plugin provides the ability to match packages (containers) as follows:

* type 'package'
+
.Example of a java trigger definition with a container matcher for packages
[source,xml]
----
<trigger id="..." type="java" templateFolder="...">
    <containerMatcher type="package" value="com\.example\.app\.component1\.persistence.entity" />
</trigger>
----
+

The container matcher matches packages provided by the type `com.capgemini.cobigen.javaplugin.inputreader.to.PackageFolder` with a regular expression stated in the `value` attribute. (See link:cobigen-core_configuration#containermatcher-node[`containerMatcher` semantics] to get more information about `containerMatchers` itself.)


=== Variable Assignment types
Furthermore, it provides the ability to extract information from each input for further processing in the templates. The values assigned by variable assignments will be made available in template and the `destinationPath` of `context.xml` through the namespace `variables.<key>`. The Java Plug-in currently provides two different mechanisms:

* type 'regex' -> regular expression group
+
[source,xml]
----
<trigger id="..." type="java" templateFolder="...">
    <matcher type="fqn" value="(.+)\.persistence\.([^\.]+)\.entity\.([^\.]+)">
        <variableAssignment type="regex" key="rootPackage" value="1" />
        <variableAssignment type="regex" key="component" value="2" />
        <variableAssignment type="regex" key="pojoName" value="3" />
    </matcher>
</trigger>
----

This variable assignment assigns the value of the given regular expression group number to the given `key`.

* type 'constant' -> constant parameter
+
[source,xml]
----
<trigger id="..." type="java" templateFolder="...">
    <matcher type="fqn" value="(.+)\.persistence\.([^\.]+)\.entity\.([^\.]+)">
        <variableAssignment type="constant" key="domain" value="restaurant" />
    </matcher>
</trigger>
----

This variable assignment assigns the `value` to the `key` as a constant.

=== Java input reader
The CobiGen Java Plug-in implements an input reader for parsed java sources as well as for java `Class<?>` objects (loaded by reflection). So API user can pass `Class<?>` objects as well as `JavaClass` objects for generation. The latter depends on https://github.com/paul-hammant/qdox[QDox], which will be used for parsing and merging java sources. For getting the right parsed java inputs you can easily use the `JavaParserUtil`, which provides static functionality to parse java files and get the appropriate `JavaClass` object.

Furthermore, due to restrictions on both inputs according to model building (see below), it is also possible to provide an array of length two as an input, which contains the `Class<?>` as well as the `JavaClass` object of the same class.

==== Template object model
No matter whether you use reflection objects or parsed java classes as input, you will get the following object model for template creation:

* *`classObject`* ('Class' :: Class object of the Java input)
* *POJO*
** *name* ('String' :: Simple name of the input class)
** *package* ('String' :: Package name of the input class)
** *`canonicalName`* ('String' :: Full qualified name of the input class)
** *annotations* ('Map<String, Object>' :: Annotations, which will be represented by a mapping of the full qualified type of an annotation to its value. To gain template compatibility, the key will be stored with '_' instead of '.' in the full qualified annotation type. Furthermore, the annotation might be recursively defined and thus be accessed using the same type of mapping. Example `${pojo.annotations.javax_persistence_Id}`)
** *JavaDoc* ('Map<String, Object>') :: A generic way of addressing all available JavaDoc doclets and comments. The only fixed variable is `comment` (see below). All other provided variables depend on the doclets found while parsing. The value of a doclet can be accessed by the doclets name (e.g. `${...JavaDoc.author}`). In case of doclet tags that can be declared multiple times (currently `@param` and `@throws`), you will get a map, which you access in a specific way (see below).
*** *comment* ('String' :: JavaDoc comment, which does not include any doclets)
*** *params* ('Map<String,String> :: JavaDoc parameter info. If the comment follows proper conventions, the key will be the name of the parameter and the value being its description. You can also access the parameters by their number, as in `arg0`, `arg1` etc, following the order of declaration in the signature, not in order of JavaDoc)
*** *throws* ('Map<String,String> :: JavaDoc exception info. If the comment follows proper conventions, the key will be the name of the thrown exception and the value being its description)
** *`extendedType`* ('Map<String, Object>' :: The supertype, represented by a set of mappings _(since `cobigen-javaplugin v1.1.0`)_
*** *name* ('String' :: Simple name of the supertype)
*** *`canonicalName`* ('String' :: Full qualified name of the supertype)
*** *package* ('String' :: Package name of the supertype)
** `*implementedTypes*` ('List<Map<String, Object>>' :: A list of all `implementedTypes` (interfaces) represented by a set of mappings _(since `cobigen-javaplugin v1.1.0`)_
*** *interface* ('Map<String, Object>' :: List element)
**** *name* ('String' :: Simple name of the interface)
**** *`canonicalName`* ('String' :: Full qualified name of the interface)
**** *package* ('String' :: Package name of the interface)
** *fields* ('List<Map<String, Object>>' :: List of fields of the input class) _(renamed since `cobigen-javaplugin v1.2.0`; previously *attributes*)_
*** field ('Map<String, Object>' :: List element)
**** *name* ('String' :: Name of the Java field)
**** *type* ('String' :: Type of the Java field)
**** `*canonicalType*` ('String' :: Full qualified type declaration of the Java field's type)
**** '*`isId`*' (`Deprecated` :: `boolean` :: true if the Java field or its setter or its getter is annotated with the `javax.persistence.Id` annotation, false otherwise. Equivalent to `${pojo.attributes[i].annotations.javax_persistence_Id?has_content}`)
**** *JavaDoc* (see `pojo.JavaDoc`)
**** *annotations* (see `pojo.annotations` with the remark, that for fields all annotations of its setter and getter will also be collected)
** `*methodAccessibleFields*` ('List<Map<String, Object>>' :: List of fields of the input class or its inherited classes, which are accessible using setter and getter methods)
*** same as for _field_ (but without JavaDoc!)
** *methods* ('List<Map<String, Object>>' :: The list of all methods, whereas one method will be represented by a set of property mappings)
*** method ('Map<String, Object>' :: List element)
**** *name* ('String' :: Name of the method)
**** *JavaDoc* (see `pojo.JavaDoc`)
**** *annotations* (see `pojo.annotations`)

Furthermore, when providing a `Class<?>` object as input, the Java Plug-in will provide additional functionalities as template methods _(deprecated)_: 

. `isAbstract(String fqn)` (Checks whether the type with the given full qualified name is an abstract class. Returns a Boolean value.) _(since `cobigen-javaplugin v1.1.1`)_  _(deprecated)_
. `isSubtypeOf(String subType, String superType)` (Checks whether the `subType` declared by its full qualified name is a sub type of the `superType` declared by its full qualified name. Equals the Java expression `subType instanceof superType` and so also returns a Boolean value.) _(since `cobigen-javaplugin v1.1.1`)_  _(deprecated)_


==== Model Restrictions
As stated before both inputs (`Class<?>` objects and `JavaClass` objects ) have their restrictions according to model building. In the following these restrictions are listed for both models, the `ParsedJava` Model which results from an `JavaClass` input and the `ReflectedJava` Model, which results from a Class<?> input.

It is important to understand, that these restrictions are only present if you work with either Parsed Model *OR* the Reflected Model. If you use the _Maven Build Plug-in_ or _Eclipse Plug-in_ these two models are merged together so that they can mutually compensate their weaknesses. 

===== Parsed Model
* annotations of the input's supertype are not accessible due to restrictions in the https://github.com/paul-hammant/qdox[QDox] library. So `pojo.methodAccessibleFields[i].annotations` will always be empty for super type fields.
* annotations' parameter values are available as Strings only (e.g. the Boolean value `true` is transformed into `"true"`). This also holds for the Reflected Model.
* fields of "supertypes" of the input `JavaClass` are not available at all. So `pojo.methodAccessibleFields` will only contain the input type's and the direct superclass's fields.
* [resolved, since `cobigen-javaplugin 1.3.1`] field types of supertypes are always canonical. So `pojo.methodAccessibleFields[i].type` will always provide the same value as `pojo.methodAccessibleFields[i].canonicalType` (e.g. `java.lang.String` instead of the expected `String`) for super type fields.

===== Reflected Model
* annotations' parameter values are available as Strings only (e.g. the Boolean value `true` is transformed into `"true"`). This also holds for the Parsed Model.
* annotations are only available if the respective annotation has `@Retention(value=RUNTIME)`, otherwise the annotations are to be discarded by the compiler or by the VM at run time. For more information see http://docs.oracle.com/javase/7/docs/api/java/lang/annotation/RetentionPolicy.html[RetentionPolicy].
* information about generic types is lost. E.g. a field's/ methodAccessibleField's type for `List<String>` can only be provided as `List<?>`.


== Merger extensions

The Java Plug-in provides two additional merging strategies for Java sources, which can be configured in the `templates.xml`:

* Merge strategy `javamerge` (merges two Java resources and keeps the existing Java elements on conflicts)
* Merge strategy `javamerge_override` (merges two Java resources and overrides the existing Java elements on conflicts)

In general merging of two Java sources will be processed as follows:

Precondition of processing a merge of generated contents and existing ones is a common Java root class resp. surrounding class. If this is the case this class and all further inner classes will be merged recursively. Therefore, the following Java elements will be merged and conflicts will be resolved according to the configured merge strategy:

* `extends` and `implements` relations of a class: Conflicts can only occur for the extends relation.
* Annotations of a class: Conflicted if an annotation declaration already exists.
* Fields of a class: Conflicted if there is already a field with the same name in the existing sources. (Will be replaced / ignored in total, also including annotations)
* Methods of a class: Conflicted if there is already a method with the same signature in the existing sources. (Will be replaced / ignored in total, also including annotations)