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 contained in the org.fortiss.ide.dev_tools plugin that is shipped with dropins.zip, which developers are required to install when setting up their developer installation.
  • Be sure to keep only the latest version of the dropins/org.fortiss.ide.dev_tools plugin when updating your Eclipse installation with a new version of dropins.zip.
  • 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:
    <buildCommand>
        <name>org.fortiss.ide.dev_tools.emf.builder.EcoreBuilder</name>
        <arguments>
        </arguments>
    </buildCommand>
    
  • Pending change: For SystemFocus, the installation procedure will be changed to Oomph, where Ecore Builder has one of the following names:
    • org.eclipse.systemfocus.tooling.emfgeneration.svn.EcoreBuilderSVN
    • org.eclipse.systemfocus.tooling.emfgeneration.svn.EcoreBuilderGIT
  • 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: While Ecore Builder supports to update .edit plugins, it may only be configured for the model plugin that contains the corresponding ecore model.

Usage

  • As Ecore Builder has received a number of updates in the past, always ensure that you have the latest version (currently: eclipse/dropins/org.fortiss.ide.dev_tools_1.2.1.201701271740.jar)
  • 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 is 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 SVN server 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).
    • Committing
      • 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 (svn:ignore should be set to * for generated-src folder).
    • 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.

Preferences

The Fortiss Development ToolsEcore Builder preference page provides the following options
  • Refresh SVN synchronization data after building option
    • If enabled, Ecore Builder performs a cleanup after generating artifacts, and also updates the synchronization data from the server. Rationale:
      • The protection of the generated artifacts caused the Team Synchronization view to show stale / invalid modifications
      • Since the cleanup and synchronization operations are potentially long running, this options allows to turn off this behavior
    • Default: enabled.
  • 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.

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 model project (after the org.eclipse.jdt.core.javabuilder, and typically also after org.eclipse.pde.ManifestBuilder and org.eclipse.pde.SchemaBuilder):

<buildCommand>
    <name>org.fortiss.ide.dev_tools.warnings.RemoveWarningsBuilder</name>
    <arguments>
    </arguments>
</buildCommand>

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 model project (after the org.fortiss.ide.dev_tools.warnings.RemoveWarningsBuilder):

<buildCommand>
    <name>org.fortiss.ide.dev_tools.warnings.GuidelinesChecker</name>
    <arguments>
    </arguments>
</buildCommand>