mobile-logo

How to run ECP + RAP on Tomcat

Building an application to view and edit data is really simple using the EMF Client Platform. This includes form-based editors based on EMF Forms. Add EMFStore to the mix and you get collaborative editing and versioning. All of this is merely a matter of defining an EMF model for your data.

If you want to run all this as a web application, you can use the Remote Application Framework (RAP). EMF Client Platform, EMF Forms, and EMFStore support running RAP without modifications.

Finally, this all must be deployed somewhere. This is how this tutorial may serve as useful. We will describe step by step how to deploy and run a RAP application based on EMF Client Platform, EMF Forms, and EMFStore on an Apache Tomcat server.

In this tutorial we will configure an ECP demo app to run on Tomcat.

To run the ECP demo app in Tomcat there are a few issues that need to be taken care of:

  • A WAR file must be created. Currently, the best way to do this is by using the ‘WAR products’ plugin. WAR products cannot create a war file while there are dependent bundles open in the IDE, this requires closing some bundle projects in the IDE which have circular dependencies due to test fragments
  • In ECP using EMFstore and RAP, the start levels of individual plugins are important. WAR products do not retain information about start levels when it generates a config file. Consequently, they must be added manually to the config file
  • After deploying the war file in Tomcat, a ‘work’ folder is created and used. It contains a copy of the config file as well as the log file. Any changes to the main config file (such as the one mentioned above) will not take effect until the work folder has been deleted and the server restarted (which will recreate the work folder).
  • By default Tomcat and EMFStore server both use port 8080

IDE Setup

  1. Install Tomcat https://tomcat.apache.org/download-80.cgi#8.0.38
  2. In conf\server.xml change the default port from 8080 (e.g. change it to 8081):
  3. Install Eclipse Modeling Edition
  4. Install “RAP Tools” plugin using ‘Install New Software’ in the help menu of eclipse from https://download.eclipse.org/rt/rap/tools/3.0/
  5. Install “WAR Products” plugin using ‘Install New Software’ in the help menu of eclipse from https://download.eclipse.org/releases/neon/
  6. Install “API Tools Execution Environment Descriptions” plugin using ‘Install New Software’ in the help menu of eclipse from https://download.eclipse.org/eclipse/updates/4.6

Project Import

  1. Use EGit to clone and checkout the following projects. Do not immediately import the projects into the workspace. The recommend branch for the repositories is stated in square brackets.
    • https://git.eclipse.org/r/emfclient/org.eclipse.emf.ecp.core [master]
    • https://git.eclipse.org/r/emf-store/org.eclipse.emf.emfstore.core [develop]
  2. To import the projects into the workspace, right click on the repositories in the ‘Git Repositories’ view and click ‘Import Projects…’. The two repositories require different strategies in order to import the right projects.

Import of the ECP Projects

  1. Select the “bundles” folder and click next.
  2. Deselect all bundles whose names contain “fx” or “bean”
  3. Deselect the bundle org.eclipse.emf.ecp.view.model.preview.e3
  4. Deselect the bundle org.eclipse.emf.ecp.view.table.ui.nebula.grid
  5. Deselect all bundles that start with one of the following:
    • Org.eclipse.emf.ecp.cdo
    • org.eclipse.emf.ecp.emf2web
    • org.eclipse.emf.ecp.graphiti
    • org.eclipse.emf.ecp.workspace
    • org.eclipse.emfforms.spreadsheet
  6. For a cleaner workspace check “Add project to working sets” and add them to a new working set called “ECP”
  7. Import the projects by clicking “Finish”

Import of the EMFStore Projects

  1. Select the “bundles” folder and click next.
  2. Deselect the bundle org.eclipse.emf.emfstore.client.ui.rcp
  3. Deselect all bundles that start with: org.eclipse.emf.emfstore.fuzzy
  4. For a cleaner workspace check “Add project to working sets” and add them to a new working set called “EMFStore”
  5. Import the projects by clicking “Finish”

Completion of the Eclipse Configuration

  1. In Windows -> Preferences -> Plugin Developement-> Target: Choose target ’ECP_EMFStore_RAP_dev_target.target’
  2. In Windows -> Preferences -> Plugin Development -> API Baselines: Add a new baseline for the newest service release from https://eclipse.org/ecp/download.html

Creating a war file

To run our application on Tomcat we need to build a war file containing the application.

We have already created a configuration for “WAR Products” to build the war file.

  1. Go to File -> New -> Other and choose ‘WAR Product Configuration’ and click next
  2. Use the following file name: ecpemfstore
  3. Choose any folder as parent folder, click ‘Use a launch configuration’, and select ‘ecpwebemfstore’ from the org.eclipse.emf.emfstore.client.ui.rap project
  4. Open the resulting warproduct file
  5. Go to the “Configuration” tab, check if the bundle “org.eclipse.emf.emfstore.client.ui.rap” is in the list of plug-ins and fragments – if it is not present add it
  6. In the top right corner of the configuration view, click on ‘export WAR product’
  7. Choose a location to store the war file, click finish, and wait
  8. After a few minutes, the war file will have been produced

Deploying the war file

  1. Move the war file to the webapps directory of the tomcat installation
  2. Start tomcat, the war file will be deployed. An explanation on how to run tomcat can be found in RUNNING.txt in the base directory of the tomcat installation
  3. Stop tomcat and delete the directory “work\Catalina\localhost\ecpemfstore” of the tomcat installation
  4. Open the config file in “webapps\ecpemfstore\WEB-INF\configuration”
  5. Change the run levels of the following 3 bundles:
    1. org.eclipse.equinox.common@start => org.eclipse.equinox.common@2:start
    2. org.eclipse.equinox.ds@start => org.eclipse.equinox.ds@1:start
    3. org.eclipse.emf.ecp.core.rap.sessionprovider.rwt@start => org.eclipse.emf.ecp.core.rap.sessionprovider.rwt@1:start
  6. Restart Tomcat
  7. Open your web browser and go to https://localhost:8081/ecpemfstore/ecpWeb
  8. The main log file of the web app can be found in work\Catalina\localhost\ecpemfstore\eclipse\workspace\.metadata\.log

Enjoy!