Follow this tutorial to get an Eclipse RAP web application with ACE/ANTLR running in the front-end, and Xtext in the backend.
To run the web editor on Eclipse RAP, you need to change the target platform. A target platform is a file which contains a set of URLs pointing to different update sites. When you open a target platform file (.target), the Eclipse provisioning system, P2, takes care of downloading the dependencies. You should however wait for a while, go take a coffee! Wait until the list of sites expand like this.
This process is done the first time, then P2 loads the plugins from its cache. You can export the plugins to your file system and use it offline.
To swich between targets, use Preferences>Plugin Development>Target Platform, the current target is marked as “Active”. Select Running Platform to get back to the default target.
The Statemachine Example
From the Package Explorer, select “New Project…” then expand “Xtext”, expand “Examples” then select the “State Machine Example”. Two projects are created:
Here are the steps:
- Expand org.eclipse.xtext.example.fowlerdsl,
- Navigate to the workflow file “GenerateStatemachine.mwe2” which is located in the org.eclipse.xtext.example.fowlerdsl package,
- Right click on the file then click on “Run as>Mwe2 Workflow”.
You should now have the Xtext artefacts generated in both projects; you can already create a runtime Eclipse configuration, create a general project, then create some DSL files (right click from the newly create project, select New>File, enter a file name with “statemachine” as extension, and actually play with the Statemachine RCP editor.
Generate Xtext RAP Editor
Here are the steps to get the web artefacts: In Eclipse, select New > Project, select “Generate Web Editor from Xtext”, click next, load the Xtext grammar, and click finish.
Set the Target Platform
In the generated .target project, under the folder named “statemachine”, you have a statemachine.target file,
- double click on the target definition file, and wait until the target is resolved.
- click on “Set as Target Platform” and you’re done.
When you switch to the Runtime target, the Xtext UI plugin does not compile, which is normal: the plugin has dependencies to Eclipse UI no longer resolved (you may also remove the dependency to org.eclipse.emf.mwe2.launch plugin in eclipse.xtext.example.fowlerdsl to fix possible compilation issues against the RAP target).
Exploring the Web Plugin content
The web plugin contains three source folders:
- src and src-gen contain Java classes
The Java Packages
The Java packages contain mainly the web editor, the language-specific text widget, the runtime Guice binding module, and the standalone setup. Report to Customize the editor for a detailed description of the src and the src-gen packages.
Then you have the src-js/*.web.ace package which contains the ACE files that are specific to the language, mainly:
- mode-language: ACE uses the so called “modes” to embed language-specific attributes, such as syntax highlighting, code folding, brace matching, etc.
- theme : contains the CSS theme of the editor.
In the src-js/*.web.ace.snippets, there is the templates file loaded by ACE Language Tools module, so that the templates appear in the content assist popup.
Build the DSL Grammar
ANTLR Parser Generator Version 3.3 Nov 30, 2010 12:50:56.
Total time: 604 milliseconds
Launch the Web editor
A launch configuration is already generated inside the web plugin, simply right click on the launch file and select Run as > StatemachineWebEditor.
Customize the workspace root path
The workspace is mapped by default to D:/www/dslforge/workspace. You can customize this path using the org.dslforge.workspace.config.configuration extension point. Here is an example:
In Eclipse, under Debug Configuration, run as a RAP Application, then Open in External Web browser. In the Text Editor Demo, the servlet path is /texteditor.
In the Bundles tab, make sure the imported plugins satisfy the following constraints:
- Your language plugins are selected (the original Xtext plugin and the generated web plugin),
- The text editor demo plugin is slected
- Equinox plugins are selected,
- Jetty plugins are selected,
- Felix plugins are selected,
Adjust the plugins start levels. The workspace plugin start level should be higher than the persistency unit start level, which is in turn higher than gemini.jpa start level. For example, if the default level is 4, than make sure the following order is respected.
- org.osgi.enterprise startLevel = 1
- org.eclipse.gemini.jpa startLevel = 2
- org.dslforge.workspace.jpa startLevel = 3
- org.dslforge.workspace startLevel = default
Click “Debug” now, you should have the workbench demo running with your DSL and its Xtext features (validation, code generation, content assist) already integrated with the workspace, menus, wizards, etc. Welcome on board!
Validated on Chrome, Firefox and Safari.
Jetty is preferred in Eclipse/OSGI environments. For J2EE environments, the editors can be deployed using Maven, Tycho and Jenkins on classical servlet containers (Apache Tomcat); the Equinox Servlet Bridge component being packaged with the war bundle, allows translating network requests between OSGI and the Servlet Container. Contact the support for more information about “real world” servers deployment.
 Installing RAP target: https://eclipse.org/rap/developers-guide/devguide.php?topic=target-install.html&version=2.0
 Setting up ANTLR with Eclipse: https://vimeo.com/groups/29150/videos/8001326
 ACE on GitHub: https://github.com/ajaxorg/ace/wiki/Embedding—API
 Convert range to offset: https://avalonedit.net/documentation/html/5b1854b4-884c-4713-b921-b28e96a1b43e.htm
 RAP incubator: https://eclipse.org/rap/incubator/
 Xtext: https://eclipse.org/Xtext/
 ACE: https://ace.c9.io
 ANTLR Works https://github.com/antlr/antlrworks
 ACE API https://ace.c9.io/api/selection.html
 Five minutes introduction to ANTLR 3: https://theantlrguy.atlassian.net/wiki/display/ANTLR3/Five+minute+introduction+to+ANTLR+3
 ANTLR: https://www.antlr.org/