Fortiss Eclipse Development Tools
=================================

The *Fortiss Eclipse Development Tools* bundle offers a number of
utilities to ease and accelerate the development of Java code, and to
work with EMF metamodels in particular.  
It contains the following features that will be explained below in more
detail

-   Automatic Ecore artifact generation
-   Ecore model editor additions
-   Warnings Remover
-   Code Style Checker

Installation / Updating:

-   *Fortiss Eclipse Development Tools* are installed automatically
    during the [AF3\_Developer\_Installation](AF3\_Developer\_Installation).
-   The plugins should be updated automatically, by Oomph when Eclipse
    is started. Alternatively, you can manually check for updates using
    the following update site which is already pre-configured in your
    developer installation:
    `http://download.fortiss.org/public/projects/org.eclipse.systemfocus.tooling.site/MAJOR_VERSION`
    (current major version is 1.1)
-   [Source code](https://git.fortiss.org/af4-group/sf-dev-tools)

Automatic Ecore artifact generation
-----------------------------------

This feature is implemented as an Eclipse *Ecore Builder* which
automatically generates Java code and other artifacts from `ecore`
metamodel. The usage scenarios are:

1.  If project is checked out, the Java code is generated immediately.
2.  If an ecore model is updated with incoming changes, the generated
    Java code and other generated artifacts will be updated
    automatically:
    -   Model code
    -   *Edit* code and other artifacts (icons, …) if an `.edit` plugin
        has been created for the `ecore` metamodel.
    -   Other Eclipse artifacts (`plugin.xml`, `META-INF/MANIFEST.MF`,
        …)
3.  If an ecore model contains error, a marker is added the *Problem
    View* to trace the error.

### Deployment of *Ecore Builder*

-   The *Ecore Builder* must be declared in the `<buildSpec>` of the
    `.project` file in each model project, according to the following
    template:
        <buildSpec>
            <!-- ... -->
            <buildCommand>
                <name>@org.eclipse.systemfocus.tooling.emfgeneration.git.EcoreBuilderGIT</name>
                <arguments/>
            </buildCommand>
            <!-- ... -->
        </buildSpec>
-   The declaration should be placed in front of the
    `org.eclipse.jdt.core.javabuilder`, so that the generated Java codes
    can be processed later by it.
-   The `ecore` model must be in the `model` directory.
-   The artifacts will be generated in the model code / edit code
    directory configured in the `genmodel` accompanying the `ecore`
    model.
-   Note: In order to use *Ecore Builder* to update `.edit` plugins, it
    still only has to be configured in the plugin that contains the
    corresponding `ecore` model (i.e., this builder configuration will
    handle both plugins).

### Usage

-   On project *build* (autobuild is recommended, see below), the
    builder will automatically generate codes and other artifacts from
    `ecore` models.
    -   The code generator will merge the generated code with existing
        files that might exist from previous runs.
    -   Before generating, the `genmodel` will be updated or created.
    -   After generation, references to foreign `genmodel` s will be
        converted to `platform:/resource` URLs instead of a relative
        path (`../..`) as generated by the `ecore` model editor when
        saving. This fix is essential because relative paths are known
        to cause a number of problems (e.g., unexpected modification and
        copying of metamodels in foreign plugins during build).
-   When a *clean* operation is performed for a project for which *Ecore
    Builder* has been configured, generated artifacts from previous
    generation runs will be deleted according to the following policy:
    -   Model plugins
        -   Codes that resides in packages that can be traced to the
            current version of the `ecore` model will be deleted
            automatically.
        -   For unreferenced code (typically code that resides in
            packages that have been deleted in the `ecore`), the user is
            prompted.
        -   Code that is under revision control is never deleted.
    -   Edit plugins
        -   Also artifacts (code, icons) that are under revision control
            are deleted. Rationale:
            -   Since the generated edit artifacts are often manually
                modified, the are typically kept under revision control.
            -   The implemented behavior of (locally) deleting stale
                files that are no longer required according the current
                version of the `ecore` metamodel supports in
                synchronizing the *edit* plugin with the metamodel (the
                files will be deleted on the Git master repository after
                a commit).
        -   Stale entries are removed from the `plugin.properties` file
            as well.
    -   Protection rules
        -   `META-INF/MANIFEST.MF` is never modified by *Ecore Builder*
            (for model and edit plugins)
        -   `plugin.xml` is preserved for model plugins
        -   The builder can be configured to preserve an arbitrary set
            of files and folders (see description of builder preferences
            below).
-   **Best practices for metamodel modifications**
    -   Do not manually generate code or reload the *GenModel* (from the
        *GenModel* editor), as this will annul the automatic fixes
        provided by *Ecore Builder* and introduce the following
        problems:
        -   `../..` style references in `.ecore files`: breaks continous
            build on https://jenkins.fortiss.org
        -   (Circular) self-dependency of the plugin containing the
            metamodel (in `META-INF/MANIFEST.MF`): breaks
            materialization of developer installations via Buckminster
    -   To trigger code generation, cleaning the respective project is
        recommended (with *Project menu → Build automatically* enabled).
    -   **Checklist before committing a meta-model modification**:
        -   Trigger refresh of all metamodel related artifacts using
            *clean* while autobuild is enabled.
        -   All modified files must be committed (`.ecore`, `.genmodel`,
            `plugin.xml` and `plugin.properties` if applicable)
        -   Ensure that none of the typical problems mentioned above
            have been introduced (`../..` in `.ecore`, (circular)
            self-dependency in `META-INF/MANIFEST.MF`)
        -   Ensure that generated source code is not added to the
            repository (covered by the default `.gitignore`
            configuration that includes the pattern
            `/*/generated-src/`).
    -   When a new sub-package is added to a metamodel, it must be
        checked if is correctly registered in the
        `org.eclipse.emf.ecore.generated_package` extension point:
              <extension point="org.eclipse.emf.ecore.generated_package">
                  <!-- @generated <METAMODEL> -->
                  <package
                        uri="http://www.fortiss.org/PLUGIN/PACKAGE1/PACKAGE2"
                        class="org.fortiss.af3.PUGIN.model.PACKAGE2.Package2ModelPackage"
                        genModel="model/METAMODEL.genmodel"/>
               </extension>
    -   **Addition of a dependency to another foreign metamodel
        (`.ecore`)**
        -   Committing any other changes in the workspace is recommended
            before continuing
        -   Turn off autobuild
        -   *Ecore Model Editor → Context menu → Load Ressource*
        -   Use add least one type from foreign metamodel
        -   Save modified `.ecore`
        -   Open `.ecore` in text editor and manually replace `../..`
            with `platform:/resource`
        -   Open `.genmodel` in text editor, and add the entries to the
            `usedGenPackages` attribute of the root element of the
            *GenModel* (`<genmodel:GenModel`) for the following items
            (pattern:
            `platform:/resource/org.fortiss.PLUGIN/model/FOREIGN_MM.genmodel#//model`)
            -   `.genmodel` of foreign metamodel
            -   Transitive closure of the `.genmodel` s of the
                dependencies of the new foreign metamodel
        -   Save `.genmodel` corresponding to modified `.ecore`
            metamodel
        -   Re-enable autobuild
        -   Clean project containing modified `.ecore` file
        -   **Double-check** the following before committing
            -   Changes in the `GenModel` dependency chain of the
                modified metamodel (typically caused by forgotten
                `../..`s). In this case, revert the changes to the
                respective plugins.
            -   Copies of `.ecore` files from the dependency chain of
                the modified metamodel next to the modified `.ecore`
                file. This is typically caused by incomplete or
                erroneous extensions of the `usedGenPackages` attribute.
        -   **In case there are still errors:** If there are still
            errors such as non-vanishing error markers on ecore files,
            you can try to delete the corresponding error markers from
            the problem view and clean the project again. In case they
            still appear, the errors are “valid”. Otherwise, they were
            just “dangling” and blocking the build (resolved by this ste

### Preferences

The *Fortiss Development Tools* → *Ecore Builder* preference page
provides the following options

-   The *Protected folders/files* option allows to configure the
    artifacts that should never be modified by *Ecore Builder*.
    -   Due to implementation issues, the files may be temporarily
        modified, but are restored by afterwards to the state before the
        builder started its *clean* or *build* operation.
    -   Default: no additional protected files or folders (see above
        regarding the automatic protection of `META-INF/MANIFEST.MF` and
        `plugin.xml`).

Ecore model editor additions
----------------------------

The *Fortiss EMF tools* context menu adds the following operations to
class, reference, attribute, and operation elements shown in the `ecore`
model editor

-   *Generate comment templates*:
    -   Adds a *GenModel → documentation* node template to the
        corresponding model element.
    -   The documentation provided in the `ecore` metamodel is included
        into the generated code.
    -   Hint: Start value of your *documentation* node with
        @`deprecated` to document elements that should no longer be
        used.
-   *Generate operation delegate code*:
    -   Generates the *GenModel → body* node required to link an
        eOperation with a static Java method using the following
        pattern:
    -   Instead of directly providing an implementation of the
        eOperation, the *body* node delegates to a static method in a
        utility class:
    -   The following conventions are used:
        -   The name of the utility class is derived by appending the
            suffix `StaticImpl` to the Java (interface) class name
            corresponding to the EClass that contains the eOperation
            (`FooStaticImpl` for EClass `Foo`).
        -   The utility class resides in the same package as the
            implementation class (`FooImpl` in the example) of
            corresponding to the interface class (`Foo`). That way, the
            generated code can call the utility class without importing
            the class or the method.
        -   The name of the method in the same as that of the
            eOperation.
        -   The method has the receiver of the method call (`this`) as
            first argument, potentially followed by arguments of the
            eOperation.
    -   To create the utility class, the following approach is useful:
        -   Create the eOperation *body* node using the context menu
        -   Have *Ecore Builder* generate the code. It will contain
            errors due to the missing utility class.
        -   Use the quick fix to generate the class (be sure to have it
            generated in to the `src` directory where the manually
            written code is maintained).
        -   Use the quick fix again to generate the methods
        -   Change the method signature to use the interface class
            (`Foo`) instead of the implementation class (`FooImpl`) as
            type of the first argument.

Code Review Builder
-------------------

The *Code Review Builder* updates the icon decoration according to the
[code review](Check-list\_for\_Code\_Reviews) status of the
corresponding file resource.

It enabled by declaring the following in the `<buildSpec>` of the
`.project` file in each project:

    <buildSpec>
        <!-- ... -->
        <buildCommand>
            <name>org.eclipse.systemfocus.tooling.codereview.builder.CodeReviewBuilder</name>
            <arguments/>
        </buildCommand>
        <!-- ... -->
    </buildSpec>

Further, the project needs to have the code review nature:

    <natures>
        <!-- ... -->
        <nature>org.eclipse.systemfocus.tooling.codereview.nature.CodeReviewNature</nature>
        <!-- ... -->
    </natures>

Warnings Remover
----------------

The *Warnings Remover* hides warnings in source folders that (by
convention) are known to contain generated code, or code that has been
imported from external sources.

Warnings are hidden in source folders that start with one of the
following prefixes:

-   `generated-src`
-   `external-src`

The *Warnings Remover* is enabled by declaring the following in the
`<buildSpec>` of the `.project` file in each project (after the
`org.eclipse.jdt.core.javabuilder`, and typically also after
`org.eclipse.pde.ManifestBuilder` and `org.eclipse.pde.SchemaBuilder`):

    <buildSpec>
        <!-- ... -->
        <buildCommand>
            <name>org.eclipse.systemfocus.tooling.codereview.builder.RemoveWarningsBuilder</name>
            <arguments/>
        </buildCommand>
        <!-- ... -->
    </buildSpec>

Code Style Checker
------------------

The *Code Style Checker* automates (parts of) the
[coding guidelines](Check-list\_for\_Code\_Reviews), and creates
corresponding warnings (shown the in *Problems* view and the Java code
editor).

The *Code Style Checker* is enabled by declaring the following in the
`<buildSpec>` of the `.project` file in each project (after the
`org.eclipse.systemfocus.tooling.codereview.builder.RemoveWarningsBuilder`):

    <buildSpec>
        <!-- ... -->
        <buildCommand>
            <name>org.eclipse.systemfocus.tooling.codereview.builder.GuidelinesCheckBuilder</name>
            <arguments/>
        </buildCommand>
        <!-- ... -->
    </buildSpec>