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. The only valid expression currently is instanceof fqn.

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 and 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})

  • 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})

      • annotations (see pojo.annotations with the remark, that for fields all annotations of its setter and getter will also be collected)

  • 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 ('String' :: JavaDoc comment without surrounding /** */ syntax. Only set if existent in the input. Keep mind, that JavaDoc could only be retrieved from input in case of a parsed Java input like a JavaClass object due to the fact that JavaDoc will be deleted in compiled Java and thus cannot be retrieved via reflection.)

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

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)