# Migrating Step By Step

Before you start the migration to Xtext 1.0, you should make sure that no old plug-ins are in your target platform. Some plug-ins from Xtext 0.7.x have been merged and do no longer exist.

Tip: 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.

### Update the Plug-in Dependencies and Import Statements

You should update the constraints from version 0.7.x to [1.0.0,2.0.0) in your manifest files if you specified any concrete versions. Make sure that your dsl.ui-projects do not refer to the plug-in org.eclipse.xtext.ui.common or org.eclipse.xtext.ui.core but to org.eclipse.xtext.ui instead. The arguably easiest way is a global text-based search and replace across the manifest files. The bundle org.eclipse.xtext.log4j is obsolete as well. The generator will create import-package entries in the manifests later on.

The next step is to fix the import statements in your classes to match the refactored naming scheme in Xtext. Perform a global search for " import org.eclipse.xtext.ui.common." and " import org.eclipse.xtext.ui.core." and replace the matches with " import org.eclipse.xtext.ui.". This fixes most of the problems in the manually written code.

### Rename the Packages in the dsl.ui-Plug-in

We changed the naming pattern for artifacts in the dsl.ui-plug-in to match the OSGI conventions. The easiest way to update your existing projects is to apply a “Rename Package” refactoring on the packages in the src- and src-gen folder before you re-run the workflow that regenerates your language. Make sure you ticked “Rename sub-packages” in the dialog. It is error-prone to enable the search in non-Java files as this will perform incompatible changes in the manifest files. Furthermore, it is important to perform the rename operation in the src-gen folder, too. This ensures that the references in your manually written code are properly updated.

### Update the Workflow

The JavaScopingFragment does no longer exist. It has been superseded by the ImportURIScopingFragment in combination with the SimpleNamesFragment. Please replace

`<fragment
class="org.eclipse.xtext.generator.scoping.JavaScopingFragment"/>
`

with

`<fragment
class="org.eclipse.xtext.generator.scoping.ImportURIScopingFragment"/>
<fragment
class="org.eclipse.xtext.generator.exporting.SimpleNamesFragment"/>
`

The PackratParserFragment has been abandoned as well. It is save to remove the reference to that one if it is activated in your workflow. After you’ve changed your workflow, it should be possible to regenerate your language without any errors in the console. It is ok to have compilation errors prior to executing the workflow.

### MANIFEST.MF and plugin.xml

The previous rename package refactoring updated most of the entries in the MANIFEST.MF and and some entries in the plugin.xml. Others have to be fixed manually. The Eclipse compiler will point to many of the remaining problems in the manifest files but it is unlikely that it will spot the erroneous references in the plugin.xml.

- In the generated UI plug-in’s MANIFEST.MF, remove the package exports of no longer existing packages and make sure the bundle activator points to the newly generated one (with .ui. in its package name).

- It was already mentioned that the plug-ins org.eclipse.xtext.ui.core and org.eclipse.xtext.ui.common have been merged into a new single plug-in org.eclipse.xtext.ui. The same happened to the respective Java packages. Change eventually remaining bundle-dependencies in all manifests.

- The plug-in org.eclipse.xtext.log4j no longer exists. We use a package import of org.apache.log4j instead. Also remove the buddy registration.

- Due to renamed packages, you have to fix all references to classes therein in the plugin.xml. A diff with the _plugin.xml___gen_ will be a great help. If you haven’t added a lot manually, consider merging these into the generated version instead of going the other way around. Note that warnings in the plugin.xml can be considered to be real errors most of the time. Make sure

  - the ExecutableExtensionFactory has the .ui. package prefix

  - classes from org.eclipse.xtext.ui.common and org.eclipse.xtext.ui.core are now usually somewhere in org.eclipse.xtext.ui. They are also referenced by the ExecutableExtensionFactory and thus not covered by the editor’s validation.

- A number of new features are being registered in the plugin.xml, e.g. Find references, Quick Outline, and Quick Fixes. You can enable them by manually copying the respective entries from _plugin.xml___gen_ to plugin.xml.

- To run MWE2 workflows later on, you must change the plug-in dependencies from org.eclipse.emf.mwe.core to org.eclipse.emf.mwe2.launch in your manifest. Optional resolution is fine.

### Noteworthy API Changes

The src folders are generated once, so existing code will not be overwritten but has to be updated manually. At least one new class has appeared in your src-folder of the ui plug-in. there will now be a StandaloneSetup inheriting form the generated StandaloneSetupGenerated to allow customization.

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.

- The method IScopeProvider.getScope(EObject,EClass) has been removed. Use IScopeProvider.getScope(EObject,EReference) instead.

- Renamed DefaultScopeProvider to SimpleNameScopeProvider. There have been further significant changes in the scoping API that allow for optimized implementations. Consult the section on scoping for details.

- The return type of AbstractInjectableValidator.getEPackages() was changed from List<? extends EPackage> to List&lt;EPackage>.

- The parser interfaces now use java.io.Reader instead of java.io.InputStream to explicitly address encoding. Have a look at the section on encoding for details.

- The handling of ILabelProvider in various contexts has been refactored. The former base class DefaultLabelProvider no longer exists. Use the DefaultEObjectLabelProvider instead. See the section on label providers for details.

- We have introduced a couple of new packages to better separate concerns. Most classes should be easy to relocate.

- The runtime and UI modules have separate base classes DefaultRuntimeModule and DefaultUiModule now. We use Guice’s module overrides to combine them with the newly introduced SharedModule. You have to add a constructor the your UiModule that takes an AbstractUiPlugin as argument and pass that one to the super constructor. Tip: There is an Eclipse quick fix available for that one.

- The interfaces ILexicalHighlightigConfiguration and ISemanticHighlightingConfiguration have been merged into IHighlightingConfiguration.

- The DefaultTemplateProposalProvider takes an additional, injectable constructor parameter of type ContextTypeIdHelper.

- The HyperlinkHelper uses field injection instead of constructor injection. The method createHyperlinksByOffset should be overridden instead of the former findCrossLinkedEObject.

- The API to skip a node in the outline has changed. Instead of returning the _HIDDEN_NODE_ you’ll have to implement boolean consumeNode(MyType) and return false.

- The Readonly*Storage implementations have been removed. There is a new API to open editors for objects with a given URI. Please use the IURIEditorOpener to create an editor or the IStorage2UriMapper to obtain an IStorage for a given URI.

- The interfaces IStateAccess and IEObjectHandle have been moved along with the IUnitOfWork to the package org.eclipse.xtext.util.concurrent.

- The ValidationJobFactory is gone. Please implement a custom IResourceValidator instead.

- The grammar elements Alternatives and Group have a new common super type CompoundElement. The methods getGroups and getTokens have been refactored to getElements.

- Completion proposals take a StyledString instead of a plain string as display string.

- The AbstractLabelProvider does no longer expose its IImageHelper. Use convertToImage instead or inject your own IImageHelper.

- The implementation-classes from org.eclipse.xtext.index were superseded by the builder infrastructure. Use the QualifiedNamesFragment and the ImportNamespacesScopingFragment instead of the ImportedNamespacesScopingFragment. Please refer to the section about the builder infrastructure for details.

- All the Xtend-based fragments were removed.

- ILinkingService.getLinkText was removed. Have a look at the LinkingHelper and the CrossReferenceSerializer if you relied on this method.

- The SerializerUtil was renamed to Serializer. There were other heavy refactorings that involved the serializer and its components (like e.g. the ITransientValueService) but it should be pretty straight forward to migrate existing client code.

- The method-signatures of the IFragmentProvider have changed. The documentation will give a clue on how to update existing implementations.

- Some static methods were removed from utility classes such as EcoreUtil2 and ParsetreeUtil in favor of more sophisticated implementations.