cobigen javaplugin

Table of Contents

• CobiGen - Java Plug-in
  • Trigger extension
    • Matcher types
    • ContainerMatcher types
    • VariableAssignment types
    • Java input reader
  • Merger extensions

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

  <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

  <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

  <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

  <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

ContainerMatcher 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

  <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 containerMatcher semantics to get more information about containerMatchers itself.)

VariableAssignment 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

  <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

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

• 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, String>') :: 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}). doclets, which are declared multiple times, e.g., like @param are currently not handled sufficiently. By accessing you will get the value of the last occurrence.

    • comment ('String' :: javaDoc comment, which does not include any doclets)

  • 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:

1. 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)

2. 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)

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 RefelctedJava Model, which results from a Class<?>` input.

Parsed Model

• annotations of the input’s supertype are not accessible due to restrictions in the QDox library. So pojo.methodAccessibleFields[i].annotations will always be empty for super type fields.

• annotations’s 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 “supersupertypes” 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)

Reflected Model

• annotations’s 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 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)