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.
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.
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.
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!
Before you start the migration to Xtext 2.0, you should make sure that no old plug-ins are in your target platform.
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.
You should update the version constraints of the plug-in dependencies in your manifest files from version 1.0.x to 2.0 if you specified any concrete versions. Also the constraint of org.antlr.runtime must be updated from [3.0.0,3.0.2) to 3.2.0.
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.
With Xtext 2.0 an object for dealing with qualified names has been introduced: QualifiedName. 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 DefaultDeclarativeQualifiedNameProvider changed to QualifiedName qualifiedName(Object)
.
The IQualifiedNameConverter converts qualified names from/to their String 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 QualifiedName.create(String ...)
.
QualifiedName is the new type of the name properties in the IEObjectDescription. So if you have customized indexing, e.g. implemented your own Manager, you will have to create qualified names instead of strings. IEObjectDescriptions are also used in other places such as scoping, linking, serialization, content assist…
Furthermore, the method IQualifiedNameProvider.getQualifiedName(EObject) has been renamed to getFullyQualifiedName(EObject)
.
In Xtext 1.0.x the interfaces IResourceDescriptions, IResourceDescription and IContainer have several methods to query them for contained elements. In Xtext 2.0 there is a common interface ISelectable for this use case which is extended by the interfaces mentioned above. For further details have a look at the interface ISelectable.
The default indexing for Xtext resources as it is defined in DefaultResourceDescriptionManager has changed. Only cross-references pointing to elements outside the current resource are indexed. Furthermore, the DefaultResourceDescriptionManager can now be easier customized with an IDefaultResourceDescriptionStrategy.
For Ecore files only EPackages, EClassifiers and EStructuralFeatures are indexed, each with both, the nsURI and the name of the containing EPackage in their qualified name.
There is a new interface to find references to Xtext elements: IReferenceFinder. It allows to distinguish searches in the local Resource from global index searches. Local searches will yield all local cross references independent of the indexing strategy.
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.
The package org.eclipse.xtext.nodemodel now contains the relevant interfaces to program against. The new interfaces follow the naming convention of other types in the framework. They are called INode, ICompositeNode and ILeafNode. That way, most of the migration will be done by prefixing the old names with an I and use the organize imports tool. Please make sure not to program against concrete or abstract classes.
If you used the node model a lot, you should have a closer look at the new APIs. The EObject API is no longer available on the nodes. Instead, you we offer a couple of Iterables for traversing the tree. Where appropriate, helper methods of the former ParseTreeUtil and NodeUtil have become members of the nodes, e.g. NodeUtil.getAllContents(AbstractNode)
has become INode.getAsTreeIterable() The remaining methods have been converted and moved to the new NodeModelUtils.
The outline view has been completely re-implemented. To use the new one remove the following fragments from your workflow
fragment = outline.TransformerFragment{}
fragment = outline.OutlineNodeAdapterFactoryFragment{}
and add
fragment = outline.OutlineTreeProviderFragment {}
After generating a new class named MyDslOutlineTreeProvider is generated. The API changed completely. For that reason you should take a closer look at the chapter on the outline. The old classes named MyDslTransformer and MyDslOutlineNodeAdapterFactory have become obsolete and should be removed after having migrated your code to the new API.
In Xtext 1.0.x your AutoEditStrategy extends the class DefaultAutoEditStrategy which implements the interface IAutoEditStrategy. In Xtext 2.0 the DefaultAutoEditStrategyProvider should be extended instead. The only thing you have to do is to change the superclass from DefaultAutoEditStrategy to DefaultAutoEditStrategyProvider. The interface IEditStrategyAcceptor changed from accept(IAutoEditStrategy)
to accept(IAutoEditStrategy, String)
. The last parameter represents the contentType of the document. Constants could be found in the IDocument and in the TerminalsTokenTypeToPartitionMapper.
As a example the configure method could look like this one:
@Override
protected void configure(IEditStrategyAcceptor acceptor) {
super.configure(acceptor);
acceptor.accept(new YourAutoEditStrategy(),
IDocument.DEFAULT_CONTENT_TYPE);
}
The last thing you have to do is to change the binding of the IAutoEditStrategy in the MyDslUIModule from
public Class<? extends IAutoEditStrategy> bindIAutoEditStrategy()
to
public Class<? extends AbstractEditStrategyProvider>
bindAbstractEditStrategyProvider() { .. }
The src folders are generated once, so existing code will not be overwritten but has to be updated manually.
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.
getScope(EObject,EReference)
has been removed. Use getScope(Resource, EReference, Predicate<IEObjectDescription>)
instead. error(..)
and warning(..)
in the AbstractDeclarativeValidator used to accept integer constants representing the EStructuralFeature which caused the issues. These integer parameters were replaced by the feature itself, e.g. from error(String, Integer)
to error(String, EStructuralFeature)
. Use the generated EPackage.Literals to access the EStructuralFeatures. In Xtext 1.0.x the class EObjectAtOffsetHelper 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:
@Inject private EObjectAtOffsetHelper eObjectAtOffsetHelper;
resolveElementAt(XtextResource, int)
. You have to use the ILocationInFileProvider to compute the TextRegion.getSignificantTextRegion()
and getFullTextRegion()
to make the distinction between the name and the full region of an element. The old getLocation()
method was removed. If you experience further problems, please refer to the newsgroup.
After migrating, some of the new features in Xtext 2.0 will be automatically available. Others require further configuration. We recommend exploring