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