Getting started with EMFStore

This tutorial is outdated and will not be updated any more. EMFStore is in maintenance mode and declared end of life on December 31st 2022.

For details please see the EMFStore homepage.

EMFStore is a repository to store, distribute and collaborate on EMF-based entities (a.k.a. data or models). Entities can be shared with a server/model repository and distributed to client applications. Clients modify the entities in parallel and synchronize with the server. Clients can work offline, and conflicts in concurrent changes between different clients are detected and can be interactively resolved. The server component keeps a history of the entities, which can be queried to retrieve historical states and changes between different versions of the entities.

All EMFStore features can be used via API to integrate EMFStore into an existing application. Furthermore EMFStore integrates very well with EMF Client Platform and thereby also supplies User Interfaces for viewing and modifying entities. Additionally, EMFStore supplies UI for essentially all available functions, including a history browser and dialogs, as well as other UI contributions to synchronize entities with the server component. As a result, all you need to get started with EMFStore is your data definition, e.g., an EMF Ecore model.

The features of EMFStore are described below in more detail. To conclude, we will walk through the minimal setup to run an EMFStore client and server.


For many applications, it is important to allow users to collaborate on their entities. Multiple users will view and make changes to the same entities. This requires synchronization.

EMFStore provides the following features for collaboration:

  • Synchronization of Clients with the Server
  • Conflict Detection of Concurrent Changes
  • Interactive Merging
  • Authentication and Authorization
  • Offline Capability

EMFStore features offline collaboration similar to well-known source code versioning systems such as SVN.  In contrast to using SVN or Git to share your entities that have been serialized to files (e.g., XML), you can use EMFStore to share and checkout entities as well as commit and update changes to your entities. EMFStore understands your entities and their structure and, therefore, can support conflict detection and interactive merging on a model level as opposed to on a textual level. Invalid XML files after merging or dangling links can never happen when merging with EMFStore.

Entities are stored in projects. A project can be shared with the server by a client and checked out from the server to other clients. Changes on shared or checked-out projects can be synchronized with commit and update operations. Commit operations will push local changes made by a client to the server while update operations will pull changes made by other clients from the server to the client. Conflicts can arise during synchronization if two clients have changed exactly the same entities. These changes can be resolved in a merge UI in the client, which ships with the EMFStore client features.

In addition, EMFStore allows you to assign permissions for users to the projects containing your entities. Users are authenticated by LDAP and authorized based on permissions.

Everything from conflict detection over merging to authentication and authorization is, of course, extensible and customizable.

EMFStore commit dialog with a visualization of the changes pushed to the server


EMFStore ships with a powerful versioning system that provides the following features:

  • Fine-grained History of Versions
  • Differencing/Comparison of Versions
  • Branching
  • Tagging

Every commit operation to the EMFStore server results in a new version of your entity that is stored. Versioning allows you to retrieve any state of your entity that has ever been stored on the EMFStore server at any point in time.

Furthermore, the history of your entity contains a fine-grained change log on an attribute change level. EMFStore clients can retrieve and display differences if you want to compare different states of your entity. The change log also stores accounting information about the user, time and log message of a version.

The history of your entity, including branches, is visualized by the EMFStore history browser.

EMFStore history browser view displaying versions and branches.

 Additionally, EMFStore supports tagging to mark special versions and branching to allow concurrent development of your entities. With branching, clients can evolve different variants of the same entity in parallel and combine them later by merging. Changes can be merged both upstream and downstream in branches.

Extensible Default User Interface

To get you and your application started really quickly, EMFStore ships with default user interfaces for almost every available functionality:

  • Navigator and Editor (EMF Client Platform Integration)
  • History View
  • Synchronization and Merge UI
  • Repository Browser (EMF Client Platform Integration)

With the repository browser (integrated from EMF Client Platform), you can configure servers your client can connect to and log in to the servers. A navigator view allows you to view all your entities in your client’s local workspace and a reflective editor allows you to view and modify single entity elements — both are featured by EMF Client Platform.

To visualize synchronization with the server, there are default dialogs to share and check out entities as well as dialogs for committing and updating entities. If a conflict is detected, your entities can be interactively merged with a default merge dialog.

Finally, you can view the history of a project or of selected entities in a history view. The view also allows you to see branches and tags and the changes between versions.

Of course, all dialogs can be extended, customized and replaced as required.

Convention over Configuration

EMFStore embraces the convention-over-configuration paradigm. From server port to conflict detection, there are default values and implementations for every configuration option. This means that you have to do zero configuration and implementation to get started with EMFStore. You can still configure everything, of course, if you decide later that your EMFStore configuration should differ from the default.

As you have seen, the convention-over-configuration paradigm even extends to the user interface. No need to provide any kind of visualization by yourself. EMFStore features a reflective user interface to display and modify your entities and to synchronize your UI with the EMFStore server.

In conclusion, convention-over-configuration for EMFStore means that all you need to do to get EMFStore up and running is to provide your entity definition, a.k.a. your Ecore model.

Sounds too good to be true? OK, let’s do it!

Running EMFStore

For evaluation, it is best to start with an Eclipse Modeling Edition since it contains all required components of EMF:

Since Luna, EMFStore as well as the EMF Client Platform integration, which is needed in order to have an UI available to view your entities, are already bundled with the Eclipse Modeling Tools.

You’ll need the model plugin and the edit plugin for your application to be present in your workspace. To get a model, you can chose one of the following possibilities:

  1. You can use the “Make It Happen” example model, which can be retrieved from this repository: git://
  2. You can create the “Make It Happen” example model from scratch
  3. You can create a custom model for your own application; a general description on how to do that can be found here:

No matter which option you chose, there should be at least two plugins in your Eclipse workspace: the model and the edit plugin.

 Now you can start your model with an application by creating a run configuration. To create a run configuration, open the menu “Run” and select “Run Configurations”. Add a new run configuration by clicking on the node “Eclipse Application”. On the first tab, assign a proper name and select to run the application “org.eclipse.emf.ecp.application.e3.application”, as you can see on the screenshot below.

Select the tab “Plugin-Ins” to define, which bundles are started. Got to the “Launch with:” drop-down menu and select “Features selected below” (see screenshot below). First, deselect all features. Scroll to the feature “org.eclipse.emf.ecp.demo.e3.feature” and check it. Press on the button “Select Required” to automatically add all other required features, too.

Finally you need to add your model from the workspace to this run configuration. Click on “Add Plug-Ins” (below “Select Required”) and add the model bundle and the corresponding *.edit bundle.

 When launching your run configuration, make sure to check the ‘Clear’ checkbox on the Main tab in order to avoid any possible problems with orphan data.

It should present you with an empty workbench containing your custom model.

You can now create a new project in the context menu of the empty canvas in the Model Explorer to the left.

You can create entities in the context menu of the newly created project.

If you create a task, it will appear in the tree and in a reflective editor to the right.

For a demo, there is a neat feature in the repository browser view at the bottom. You can launch a local EMFStore server from the context menu of the item “Local EMFStore”. This will launch a local EMFStore server from your client that behaves just as a remote server would.

You can share the project with a server in the context menu of the project.

Now we can share the local project of the client with the server we just launched. In the context menu of the project, select Share Project. In the wizard, select Existing Repository and then select the “Local EMFStore” then press finish. In the login dialog, just press OK since the default demo password “super” is already set.

Once the project is shared you can make changes to the task and commit the changes from the context menu of the project.

In the repository browser you can check out another copy of the project, simulating a second client.

The second copy needs to have a different local name.

Now you change one copy of the project, commit the changes and update the other project to pull in the changes.

If both projects are changed in the same element and the same attribute, a conflict will arise and can be resolved (Keep My Change).

This concludes a quick walkthrough. All functionality in the UI is available as API. More information and documentation is available at the EMFStore website.

The Author

Jonas, Maximilian & Philip