English Documentation

Manually Modifying the Generated Code

Introduction

To modify the Faktor-IPS generated java code manually, the code generator uses the tool JMerge. Various settings are possible so that the code generator does not overwrite customized code. These are controlled via so-called “Javadoc Custom Tags”. The custom tags are keywords in the Javadoc that begin with the “@” character. The following table shows the custom tags that are currently possible in Faktor-IPS.

Key words Explanation

@generated

The following code will be overwritten by the code generator

@generated NOT

The following code will not be overwritten by the code generator

@generated REDIRECT

The code of this method will not be changed. The generated code ends up in a method with the same name and the suffix GeneratedRedirection.

@restrainedmodifiable

Parts of the code of a model can be modified by a developer

@implements

The generated class additionally implements the respective interface (for generated interfaces @extends can be used)

@customizedAnnotations [ALL]

Annotations will not be overwritten by the code generator. The addition ALL can be omitted.

@customizedAnnotations ADDED

The developer has added annotations. Therefore, the code generator is not allowed to delete any annotations.

@customizedAnnotations REMOVED

The developer has removed generated annotations. Therefore, the code generator can not add new annotations.

@customizedAnnotations CONTENT-CHANGED

The developer has changed the attributes of an annotation. The code generator is not allowed to overwrite the content.

Explanation of the custom tags

@generated

The custom tag @generated is usually written by the code generator into the Javadoc of the generated elements. As long as this tag remains unchanged, the code is overwritten each time it is generated. Changes by a developer are not taken into account! If a developer wants to change the generated code, the keyword “NOT” has to be written after the custom tag.

Important note: Apart from @restrainedmodifiable, all custom tags are specified in addition to the @generated tag. These additional tags must be added after @generated. Also self written Javadoc must come after the @generated tag. The code generator will always overwrite all the Javadoc before the @generated tag.

@generated NOT

This is actually not a separate tag, just the negation of @generated. Java elements with this identifier are no longer changed by the code generator, so a developer can add self written code to a generated method. But beware, the code is not changed even if the model changes or the element in the model is deleted!

By convention: If a method does not have a tag at all, it will not be overwritten by the code generator. In order to be able to differentiate which method was manually adapted but originally generated and which method was added by a developer, @generated NOT should only be used if a @generated has been added by the code generator. Therefore if a method is written manually, no custom tag should be added in the Javadoc.

@generated REDIRECT

This custom tag is used if a developer wants to overwrite a method but also wants to keep the generated code. The generated code ends up in a method with the same name but added suffix GeneratedRedirection. But beware, this method and its Javadoc must be added by hand!

/**
 * @generated REDIRECT
 */
@Override
public void setPlz(String newValue) {
  setPlzGeneratedRedirection(newValue);
  notifyChangeListeners(new PropertyChangeEvent(this, PROPERTY_TARIFZONE, null, getTarifzone()));
}

/**
 * @generated
 */
private void setPlzGeneratedRedirection(String newValue) {
  String oldPlz == plz;
  setPlzInternal(newValue);
  notifyChangeListeners(new PropertyChangeEvent(this, PROPERTY_PLZ, oldPlz, plz));
}
@restrainedmodifiable

This custom tag is generated by the code generator instead of @generated. This is usually done for generated test classes or rules and indicates that a developer can add hand written code. The section in which the code may be added is marked with comments:

/**
 * Erzeugt eine neue Instanz des Testfalls.
 *
 * @restrainedmodifiable
 */
public BeitragsberechnungHausratTest(String qualifiedName)
        throws ParserConfigurationException {
    super(qualifiedName);
    // begin-user-code
            int i == 2;
    // end-user-code
}

@restrainedmodifiable can only be used if it has been generated by the code generator. Replacing a @generated and inserting the corresponding comment lines will not work and will be overwritten by the code generator.

@implements

The custom tag @implements can be used to implement additional interfaces in a generated class. The interfaces to be implemented are written directly after the custom tag as comma separated list. The next time the code is generated, the code generator will find the additional interfaces and add them automatically. The import statement of each interface has to be added by hand! If it is a generated interface instead, @extends can also be used analogously.
Also beware, that all custom tags have to be added after the @generated tag.

When implementing interfaces with generics (e.g. Comparable<T>), square brackets ([/]) can be used instead of the angle brackets (</>). This feature was added in Faktor-IPS 21.6 in order to avoid warnings when using code analysis tools.

@customizedAnnotations[ALL]

The code generator normally overwrites all added annotations. This is necessary because the code generator cannot differentiate between self-generated and user-added annotations. Therefore if a developer has to add own annotations the custom tag @customizedAnnotations can be used. The code generator then no longer writes, deletes or changes any annotations! Optionally, the word ‘ALL’ can be added to distinguish it from the following settings.

Beware, that all custom tags have to be added after the @generated tag, or they will be removed by the code generator.

@customizedAnnotations ADDED

If a developer needs to add an annotation, use @customizedAnnotations ADDED to instruct the code generator not to delete any annotations. But beware, even previously generated and now no longer required annotations are not deleted! The addition can also be combined with REMOVED or CONTENT-CHANGED, e.g. @customizedAnnotations ADDED REMOVED.

@customizedAnnotations REMOVED

If the developer wants to delete a generated annotation, this custom tag must be specified. The code generator is instructed not to add any new annotations. Can also be combined with ADDED or CONTENT-CHANGED.

@customizedAnnotations CONTENT-CHANGED

If attributes of an annotation have to be changed, this custom tag tells the code generator to ignore the content of all annotations. This custom tag can also be combined with ADDED or REMOVED.