blob: 7858dc4061addda218d244114e667a6e64703369 [file] [log] [blame]
<!DOCTYPE html>
<meta charset="UTF-8">
<title>Xtext - Migrating from Xtext 1.0.x to 2.0</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description"
content="The website of Eclipse Xtext, an open-source framework for development of programming languages and domain-specific languages">
<meta name="author" content="Sven Efftinge">
<meta name="author" content="Miro Spoenemann">
<!-- styles -->
<!-- Le HTML5 shim, for IE6-8 support of HTML5 elements -->
<!--[if lt IE 9]>
<script src=""></script>
<!-- Le fav and touch icons -->
<link rel="shortcut icon" href="/Xtext/images/favicon.png">
<link href="/Xtext/css/bootstrap.css" rel="stylesheet" type='text/css'>
<link href="/Xtext/css/bootstrap-responsive.css" rel="stylesheet" type='text/css'>
<link href="/Xtext/css/shield-responsive.css" rel="stylesheet" type='text/css'>
<link href='/Xtext/css/fonts.css' rel='stylesheet' type='text/css'>
<link href="/Xtext/css/prettyPhoto.css" rel="stylesheet" media="screen" type='text/css'>
<link href="/Xtext/css/prettify.css" type="text/css" rel="stylesheet"/>
<link href="/Xtext/css/style.css" rel="stylesheet" type='text/css'>
<!-- cover flow -->
<link href="/Xtext/css/coverflow.css" rel="stylesheet" type='text/css'>
<!--[if lt IE 9]>
<link href="/css/iebugs.css" rel="stylesheet" type='text/css'>
<!-- Google Tag Manager -->
<noscript><iframe src="//"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
<!-- End Google Tag Manager -->
<header class="site-header">
<!-- Navbar -->
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse"
data-target=".nav-collapse"> <span class="icon-bar"></span> <span
class="icon-bar"></span> <span class="icon-bar"></span>
</a> <a class="brand" href="/Xtext/index.html"></a>
<div class="nav-collapse collapse" style="height: 0px;">
<ul class="nav">
<!--li ><a href="/Xtext/news.html">News</a></li-->
<li ><a href="/Xtext/download.html">Download</a></li>
<li ><a href="/Xtext/documentation/index.html">Documentation</a></li>
<li ><a href="/Xtext/community.html">Community</a></li>
<li ><a href="" target="_blank">Trainings &amp; Support</a></li>
<!--div class="nav pull-right">
<li ><a><iframe src="" frameborder="0" scrolling="0" width="170px" height="20px"></iframe></a></li>
<!--/.nav-collapse -->
<!-- Navbar End -->
<div class="page-content">
function startSearch(event) {
if (event.keyCode == 13) {
var q = '' +;'' + q, "_self");
<div class="wrapper">
<div id="page">
<div class="inner">
<div id="maincontainer" class="container">
<span class="edit-on-github pull-right">
<a href="">Edit on Github</a>
<div class="span3" style="margin-left: 0px;">
<div class="search-bar">
<img src="/Xtext/images/search-gray.png"/>
<input type="search" id="google-search" onkeyup="startSearch(event);"/>
<ul id="nav-outline" style="margin-left: 0px;">
<li class="nav-part">Getting Started</li>
<!--li><a href="101_five_minutes.html">5 Minutes Tutorial</a>
<li><a href="102_domainmodelwalkthrough.html">15 Minutes Tutorial</a>
<li><a href="103_domainmodelnextsteps.html">15 Minutes Tutorial - Extended</a>
<li><a href="104_jvmdomainmodel.html">Five simple steps to your JVM language</a>
<!--li class="nav-part">Seven JVM Languages Built With Xbase</li>
<li><a href="201_sevenlang_introduction.html">Introduction</a>
<li><a href="202_scripting.html">Scripting Language</a>
<li><a href="203_builddsl.html">Build Language</a>
<li><a href="204_mongodb.html">DSL for MongoDB</a>
<li><a href="205_guice.html">DSL for Guice</a>
<li><a href="206_httprouting.html">Http Routing Language</a>
<li><a href="207_template.html">Template Language</a>
<li><a href="208_tortoise.html">Little Tortoise</a>
<li class="nav-part">Reference Documentation</li>
<li><a href="301_grammarlanguage.html">The Grammar Language</a>
<li><a href="302_configuration.html">Configuration</a>
<li><a href="303_runtime_concepts.html">Language Implementation</a>
<li><a href="305_xbase.html">Integration with Java</a>
<!--li><a href="306_mwe2.html">MWE2</a>
<!--li><a href="307_special_languages.html">Typical Language Configurations</a>
<li><a href="308_emf_integration.html">Integration with EMF</a>
<li><a href="310_eclipse_support.html">Eclipse Support</a>
<!--li><a href="320_idea_support.html">IntelliJ IDEA Support</a>
<li><a href="330_web_support.html">Web Editor Support</a>
<li><a href="350_continuous_integration.html">Continuous Integration</a>
<!--li class="nav-part">Appendix</li>
<li><a href="401_migrating_from_1_0_x.html">Migrating from Xtext 1.0.x to 2.0</a>
<li><a href="402_migrating_from_0_7.html">Migrating from Xtext 0.7.x to 1.0</a>
<li class="nav-part">Additional Resources
<li><a href="">API Documentation (JavaDoc)</a>
<div class="span8 doc-contents">
<h1 id="migrating-from-1_0_x">Migrating from Xtext 1.0.x to 2.0</h1>
<p>Most of the tasks when migrating to Xtext 2.0 can be automated. Some changes will be necessary in the manually written code where you have to carefully verify that your implementation is still working with Xtext 2.0. A reliable test-suite helps a lot. </p>
<p>The grammar language is fully backward compatible. You should not have to apply any changes in the primary artifact. However, we introduced some additional validation rules that mark inconsistencies in your grammar. If you get any warnings in the grammar editor, it should be straight forward to fix them.</p>
<p><em>Hint: You’ll learn something about the new features if you compare a freshly created Xtext project based on 1.0.x with a new Xtext project based on 2.0. Especially the new fragments in the workflow are a good indicator for useful new features.</em></p>
<h2 id="take-the-shortcut">Take the Shortcut</h2>
<p>If you haven’t made too many customizations to the generated defaults and if you’re not referencing many classes of your Xtext language from the outside, you might consider starting with a new Xtext project, copying your grammar and then manually restoring your changes step by step. If that does not work for you, go on reading!</p>
<h2 id="migrating-step-by-step">Migrating Step By Step</h2>
<p>Before you start the migration to Xtext 2.0, you should make sure that no old plug-ins are in your target platform.</p>
<p><em>Hint: The following steps try to use the Eclipse compiler to spot any source-incompatible changes while fixing them with only a few well described user actions. Doing these steps in another order causes most likely a higher effort.</em></p>
<h3 id="update-the-plug-in-dependencies-and-import-statements">Update the Plug-in Dependencies and Import Statements</h3>
<p>You should update the version constraints of the plug-in dependencies in your manifest files from version <em>1.0.x</em> to <em>2.0</em> if you specified any concrete versions. Also the constraint of <em>org.antlr.runtime</em> must be updated from <em>[3.0.0,3.0.2)</em> to <em>3.2.0</em>.</p>
<p>The next step is to fix the import statements in your classes to match the refactored naming scheme in Xtext. This fixes most of the problems in the manually written code. </p>
<h3 id="introduction-of-the-qualified-name">Introduction of the Qualified Name</h3>
<p>With Xtext 2.0 an object for dealing with qualified names has been introduced: <a href="">QualifiedName</a>. The qualified name is now split into segments which can be queried. The lower-case version of the qualified name is cached so that the performance of case insensitive languages is improved. The signature of the methods used by the <a href="">DefaultDeclarativeQualifiedNameProvider</a> changed to <code>QualifiedName qualifiedName(Object)</code>. </p>
<p>The <a href="">IQualifiedNameConverter</a> converts qualified names from/to their <a href="">String</a> representation. This is also where you specify the separator and wildcard strings. If you already know the segments of a qualified name, you can also create it using <code>QualifiedName.create(String ...)</code>. </p>
<p><a href="">QualifiedName</a> is the new type of the <em>name</em> properties in the <a href="">IEObjectDescription</a>. So if you have customized indexing, e.g. implemented your own <a href="">Manager</a>, you will have to create <a href="">qualified names</a> instead of <a href="">strings</a>. <a href="">IEObjectDescriptions</a> are also used in other places such as <a href="303_runtime_concepts.html#scoping">scoping</a>, <a href="303_runtime_concepts.html#linking">linking</a>, <a href="303_runtime_concepts.html#serialization">serialization</a>, <a href="310_eclipse_support.html#content-assist">content assist</a></p>
<p>Furthermore, the method <a href="">IQualifiedNameProvider.getQualifiedName(EObject)</a> has been renamed to <code>getFullyQualifiedName(EObject)</code>.</p>
<h3 id="changes-in-the-index-and-in-find-references">Changes in the index and in find references</h3>
<p>In Xtext 1.0.x the interfaces <a href="">IResourceDescriptions</a>, <a href="">IResourceDescription</a> and <a href="">IContainer</a> have several methods to query them for contained elements. In Xtext 2.0 there is a common interface <a href="">ISelectable</a> for this use case which is extended by the interfaces mentioned above. For further details have a look at the interface <a href="">ISelectable</a>.</p>
<p>The default indexing for Xtext resources as it is defined in <a href="">DefaultResourceDescriptionManager</a> has changed. Only cross-references pointing to elements outside the current resource are indexed. Furthermore, the <a href="">DefaultResourceDescriptionManager</a> can now be easier customized with an <a href="">IDefaultResourceDescriptionStrategy</a>. </p>
<p>For Ecore files only <a href="">EPackages</a>, <a href="">EClassifiers</a> and <a href="">EStructuralFeatures</a> are indexed, each with both, the <em>nsURI</em> and the <em>name</em> of the containing <a href="">EPackage</a> in their qualified name.</p>
<p>There is a new interface to find references to Xtext elements: <a href="">IReferenceFinder</a>. It allows to distinguish searches in the local <a href="">Resource</a> from global index searches. Local searches will yield <em>all</em> local cross references independent of the indexing strategy.</p>
<h3 id="rewritten-node-model">Rewritten Node Model</h3>
<p>To reduce memory consumption, the node model has been redesigned in Xtext 2.0. We no longer use EMF, but a chained list of compressed nodes instead. </p>
<p>The package <em>org.eclipse.xtext.nodemodel</em> now contains the relevant interfaces to program against. The new interfaces follow the naming convention of other types in the framework. They are called <a href="">INode</a>, <a href="">ICompositeNode</a> and <a href="">ILeafNode</a>. That way, most of the migration will be done by prefixing the old names with an <em>I</em> and use the organize imports tool. Please make sure not to program against concrete or abstract classes.</p>
<p>If you used the node model a lot, you should have a closer look at the new APIs. The <a href="">EObject</a> API is no longer available on the nodes. Instead, you we offer a couple of <a href="">Iterables</a> for traversing the tree. Where appropriate, helper methods of the former <em>ParseTreeUtil</em> and <em>NodeUtil</em> have become members of the nodes, e.g. <code>NodeUtil.getAllContents(AbstractNode)</code> has become <a href="">INode.getAsTreeIterable()</a> The remaining methods have been converted and moved to the new <a href="">NodeModelUtils</a>.</p>
<h3 id="new-outline">New Outline</h3>
<p>The outline view has been completely re-implemented. To use the new one remove the following fragments from your workflow </p>
<pre><code class="language-mwe2">fragment = outline.TransformerFragment{}
fragment = outline.OutlineNodeAdapterFactoryFragment{}
<p>and add </p>
<pre><code class="language-mwe2">fragment = outline.OutlineTreeProviderFragment {}
<p>After generating a new class named <em>MyDslOutlineTreeProvider</em> is generated. The API changed completely. For that reason you should take a closer look at the <a href="310_eclipse_support.html#outline">chapter on the outline</a>. The old classes named <em>MyDslTransformer</em> and <em>MyDslOutlineNodeAdapterFactory</em> have become obsolete and should be removed after having migrated your code to the new API.</p>
<h3 id="autoeditstrategy">AutoEditStrategy</h3>
<p>In Xtext 1.0.x your AutoEditStrategy extends the class <em>DefaultAutoEditStrategy</em> which implements the interface <a href="">IAutoEditStrategy</a>. In Xtext 2.0 the <a href="">DefaultAutoEditStrategyProvider</a> should be extended instead. The only thing you have to do is to change the superclass from <em>DefaultAutoEditStrategy</em> to <a href="">DefaultAutoEditStrategyProvider</a>. The interface <a href="">IEditStrategyAcceptor</a> changed from <code>accept(IAutoEditStrategy)</code> to <code>accept(IAutoEditStrategy, String)</code>. The last parameter represents the <em>contentType</em> of the document. Constants could be found in the <a href="">IDocument</a> and in the <a href="">TerminalsTokenTypeToPartitionMapper</a>. </p>
<p>As a example the configure method could look like this one: </p>
<pre><code class="language-java"> @Override
protected void configure(IEditStrategyAcceptor acceptor) {
acceptor.accept(new YourAutoEditStrategy(),
<p>The last thing you have to do is to change the binding of the <em>IAutoEditStrategy</em> in the <em>MyDslUIModule</em> from</p>
<pre><code class="language-java">public Class&lt;? extends IAutoEditStrategy&gt; bindIAutoEditStrategy()
<p>to </p>
<pre><code class="language-java">public Class&lt;? extends AbstractEditStrategyProvider&gt;
bindAbstractEditStrategyProvider() { .. }
<h3 id="other-noteworthy-api-changes">Other Noteworthy API Changes</h3>
<p>The <em>src</em> folders are generated once, so existing code will not be overwritten but has to be updated manually.</p>
<p>You will face a couple of compilation problems due to changes in the API. Here’s a list of the most prominent changes. It is usually only necessary to change your code, if you face any compilation problems. </p>
<li>In the interface <a href="">IGlobalScopeProvider</a> the method <code>getScope(EObject,EReference)</code> has been removed. Use <code>getScope(Resource, EReference, Predicate&lt;IEObjectDescription&gt;)</code> instead. </li>
<li>The interface <em>IAntlrParser</em> has been removed. Use the <a href="">IParser</a> instead.</li>
<li>The methods <code>error(..)</code> and <code>warning(..)</code> in the <a href="">AbstractDeclarativeValidator</a> used to accept integer constants representing the <a href="">EStructuralFeature</a> which caused the issues. These integer parameters were replaced by the feature itself, e.g. from <code>error(String, Integer)</code> to <code>error(String, EStructuralFeature)</code>. Use the generated <a href="">EPackage.Literals</a> to access the <a href="">EStructuralFeatures</a>. </li>
<li>The enum <em>DiagnosticSeverity</em> has been renamed to <a href="">Severity</a>.</li>
<li>The class <em>TextLocation</em> has been replaced by the interface <a href="">ITextRegion</a> with an immutable implementation <a href="">TextRegion</a>.</li>
<p>In Xtext 1.0.x the class <a href="">EObjectAtOffsetHelper</a> provided several static methods to resolve elements. In Xtext 2.0 these methods aren’t static anymore. For that reason you could create an instance of this class or let Guice do the job for you: </p>
<pre><code class="language-java"> @Inject private EObjectAtOffsetHelper eObjectAtOffsetHelper;
<li>The method <a href="">EObjectAtOffsetHelper.resolveElementAt(XtextResource, int, TextLocation)</a> changed to <code>resolveElementAt(XtextResource, int)</code>. You have to use the <a href="">ILocationInFileProvider</a> to compute the <a href="">TextRegion</a>.</li>
<li>The <a href="">ILocationInFileProvider</a> now offers methods <code>getSignificantTextRegion()</code> and <code>getFullTextRegion()</code> to make the distinction between the name and the full region of an element. The old <code>getLocation()</code> method was removed. </li>
<p>If you experience further problems, please refer to the <a href=";frm_id=27">newsgroup</a>.</p>
<h2 id="now-go-for-then-new-features">Now go for then new features</h2>
<p>After migrating, some of the new features in Xtext 2.0 will be automatically available. Others require further configuration. We recommend exploring </p>
<li>the new Xtend,</li>
<li>rename refactorings</li>
<li>the compare view,</li>
<li>rich hovers,</li>
<li>the Xtext syntax graph,</li>
<li><a href="301_grammarlanguage.html#syntactic-predicates">support for syntactic predicates</a>,</li>
<li>the generated debug grammar,</li>
<li><a href="301_grammarlanguage.html#terminal-fragment">terminal fragments</a>,</li>
<li>document partitions and auto edit</li>
<li>the redesigned <a href="310_eclipse_support.html#outline">outline view</a>,</li>
<li>and the <a href="310_eclipse_support.html#quick-fixes">quick fixes for the Xtext grammar language</a>.</li>
<hr />
<p><strong><a href="402_migrating_from_0_7.html">Next Chapter: Migrating from Xtext 0.7.x to 1.0</a></strong></p>
<footer class="site-footer">
<div id="extra">
<div class="inner">
<div class="container">
<div class="row">
<div class="span6">
<h3 class="footer-links-header">Quick Links</h3>
<ul class="footer-links clearfix">
<li><a href="">Privacy Policy</a></li>
<li><a href="">Terms of Use</a></li>
<li><a href="">Copyright Agent</a></li>
<li><a href="">Legal</a></li>
<ul class="footer-links clearfix">
<li><a href="">Eclipse Home</a></li>
<li><a href="">Market Place</a></li>
<li><a href="">Eclipse Live</a></li>
<li><a href="">Eclipse Planet</a></li>
<div class="span6">
<h3 class="footer-links-header"><a href="" style="color: white;">@Xtext</a> on Twitter</h3>
<a class="twitter-timeline" href="" data-widget-id="346625441290928128"
data-chrome="noheader nofooter transparent"
data-theme="dark">Tweets by @xtext</a>
!function(d,s,id) {
var js,fjs=d.getElementsByTagName(s)[0],p=/^http:/.test(d.location)?'http':'https';
if(!d.getElementById(id)) {
<a href="#" class="scrollup fadeOutRight animated" style="display: none;">ScrollUp</a>
<!-- Le javascript
================================================== -->
<!-- Placed at the end of the document so the pages load faster -->
<script src="/Xtext/js/jquery-1.11.3.min.js"></script>
<script src="/Xtext/js/bootstrap.min.js"></script>
<script src="/Xtext/js/jquery.easing.1.3.js" type="text/javascript"></script>
<script src="/Xtext/js/jquery.prettyPhoto.js" type="text/javascript"></script>
<script src="/Xtext/js/twitter.js" type="text/javascript"></script>
<script src="/Xtext/js/prettify.js" type="text/javascript"></script>
<script src="/Xtext/js/lang-xtend.js" type="text/javascript"></script>
<script src="/Xtext/js/lang-common.js" type="text/javascript"></script>
<script src="/Xtext/js/custom.js" type="text/javascript"></script>
<script src="" async defer></script>
<!--script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push([ '_setAccount', 'UA-2429174-3' ]);
_gaq.push([ '_trackPageview' ]);
(function() {
var ga = document.createElement('script');
ga.type = 'text/javascript';
ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl'
: 'http://www')
+ '';
var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
<script src="/Xtext/js/coverflow.min.js" type="text/javascript"></script>
$(function() {
active : 1,
visibleAside: 2,
overlap : 0.5,
scale : 0.9,
angle : 20,
trigger : {
"itemfocus" : true,
"swipe" : true,
"mousewheel" : false
$('#coverflow :hidden').toggle();
$(window).resize(function() {