Project

General

Profile

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

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

Preferences

The Fortiss Development ToolsEcore 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 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, 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>