How to contribute
You can contribute to AF3 in several ways:
- submit a bug report (and … even better a patch :-))
- provide us AF3-example models
- submit showcases done with AF3
- submit a change request (and … even better the change itself :-))
- help us to develop the AF3 base platform
- extend AF3 with new plugins
- … or give us any feedback (positive of negative)
New developer - Step by step
1. Get familiar with the software from the perspective of the user:
- browse the AF3 website (http://af3.fortiss.org/)
- run AF3, play with it
- open the examples (available through the menu of AF3)
- look at the help (available through the menu of AF3)
2. It is now time to build a model on your own:
- Let us study the alternating bit protocol http://en.wikipedia.org/wiki/Alternating\_bit\_protocol
- Then implement an AF3 model for the sender and the receiver components for this protocol with direct communication
channels between the two (in other words no message can be lost during the transmission).
- After having a suitable simulation of this system, replace the direct channels with intermediate media components and implement a lossy behavior, i.e. messages can get lost during transmission.
- Again, validate the proper functioning of the model by simulation.
3. Set up AF3 development environment
- Set up a development eclipse according to the Developer Installation
4. Familiarize yourself with the AF3 Development Workflow. There, you will learn to update your workspace, how to create and contribute changes, and how to perform code reviews.
5. read the following code guidelines: Checklist for code reviews
(you probably won’t understand everything since many things require to be familiar with the code in AF3, but still good to browse to get an idea)
7. You will now be done with the general AF3 developer general knowledge,
the following sections focus more on particular aspects of AF3.
This depends on what your topic and is therefore to be advised by your supervisor.
Modify a model programmatically
Say you want to do:
Then you should actually write:
ITopLevelElement modelContext = IPersistencyService.getInstance().getTopLevelElementFor(modelElement); modelContext.runAsCommand(() -> myModel.setParameter(42) ));
When changing on the metamodel, it has to made sure that old models
still load in AutoFOCUS3. Models cannot be loaded any more after
renaming or deletion of model elements such as classes or attributes.
Plugins that are part of the release have to load all models from
release n also in release n+1 (backward compatibility). Therefore the
AutoFOCUS3 kernel offers a
When you implement a new story / plugin be sure to pay attention to the following issues related to usability:
- is your plugin from the point of UI consistent with other existing plugins?
- long operations should have a timeout / cancel option
- during long operations give feedback to your users about the current state
- when external tools are called, be sure to allow the user to specify a timeout
- are all menus needed? how many mistakes can the users make?
- warn users about mistakes early
- provide a meaningful default behaviour
- each view and each window should have a meaningful and specific name — e.g. “entity name - view name” — “DistancePlausibilisation Simulator”
Workflow for model changes after release n
- Do not delete deprecated model elements (e.g. entire classes, but
also single fields) in release n+1.
- Rather, mark all concrete classes with a @
deprecatedcomment (interfaces and abstract classes cannot be instantiated and may be omitted).
- This causes the @
Deprecatedannotation to be added to the respective classes and field accessor methods in the generated source code.
ecorefile with Sample Ecore Model Editor (default editor)
- Context menu ->fortiss EMF tools ->Generate comment templates.
- Ensure that Eclipse Properties view is visible (can be opened e.g. by typing “Properties” in Quick Access control)
documentationnode that as been created for the respective
valueproperties field and change it to @
Hint: To speed up the process, you may also copy and
paste the initial
- Rather, mark all concrete classes with a @
- Write an
IMigrationProviderfor your plugin that adjusts old models to the new model (e.g. remove, rename, …). See below.
- Test model changes with all example models that are available in the file menu.
- Update the models shipped in the
test-datadirectory of the RCP plugin (can be done when all migrators required for the current release are ready).
- Actual removal of deprecated metamodel elements:
- After publishing the release n+1, the deprecated model elements and migration code written between release n and n+1 can be deleted.
- It is advised to create an issue for release n+2 to ensure that this cleanup task is actually performed.
- Option 1: Directly implement
needMigration()is a predicate that determines if the migrator has to be applied to a given model
migrate()performs the actual migration
org.fortiss.tooling.base.utils.MigrationUtilscontains useful methods to migrate Kernel / Tooling-Base based models
- Option 2: Use
getDeprecatedArtifacts(), a method that returns the
Collectionof deprecated artifact types to be removed from the model.
- Optionally also implement
getDeprecatedRootArtifacts(), a method that returns the
Collectionof deprecated root artifact types (possibly empty subset of
getDeprecatedArtifacts()) for which a comment is added to the migrated model that deprecated artifacts have been removed.
- Register migration provider
- Migration service initializes and starts very early, e.g. before the persistency service and the logging service.
- During startup, the actual migration is triggered from the
org.fortiss.tooling.kernel.internal.storage.eclipse.EclipseResourceStorageService(also very early in the AF3 initialization / startup phase).
- For this reason, operations that are based on these services may
not be used when implementing a model migrator, e.g.
- Do not use
- Do not try to acquire a model context to modify the model (not needed for migrators anyways)
- Do not use