Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

VIATRA/Releases/MigrationTo1.2

Migrating from EMF-IncQuery 1.1

From version 1.2 EMF-IncQuery is merged into the Viatra project as Viatra Query. The merge involves the complete removal of org.eclipse.incquery namespace, thus making all code depending on EMF-IncQuery incompatible with Viatra Query API. Furthermore, during the merging the existing codebase was cleaned up, removing all existing deprecated code, and a few classes were renamed to be consistent with the new naming conventions.

The migrator tool

To ease the migration process, a migrator tool is included in Viatra 1.2 to reduce manual refactoring as much as possible.

Usage

The tool can be accessed in the 'Configure' context menu on Java/EMF-IncQuery projects where it is applicable.

  • Update Viatra Query Project: Migration of query projects (EMF-IncQuery 0.8.0-1.1.0)
    • Updates project dependencies
    • Updates query description files
    • Updates query specification extensions
    • Updates usage of EMF-IncQuery API
    • Important: this item is not available in projects that are already VIATRA Query projects
  • Replace EMF-IncQuery API Usage: Migration of Java and Xtend projects
    • Updates usage of EMF-IncQuery API
    • Safe to be called multiple times

Remaining manual tasks after migration

  • Maven builds are not migrated.
  • Deprecated API [in EMF-IncQuery 1.1.0] are removed in 1.2.0. These API usages have to be migrated manually; look for the version 1.1 javadoc for hints on updating.
  • Deprecated pattern annotations and annotation parameters were removed from the language; they need either to be updated or removed manually from query definitions.
  • Generated plugin extensions other than query specifications are regenerated, but the old ones are not removed. These shall be removed manually.
  • The class name of static method calls and enum literals shall be renamed manually, e.g. AdvancedIncQueryEngine.createUnmanagedEngine()AdvancedViatraQueryEngine.createUnmanagedEngine() or IncQueryActivationStateEnum.UPDATEDCRUDActivationStateEnum.UPDATED
  • Renamed methods and fields are not migrated by the tool: (incomplete list; in general references to IncQuery were changed; in case of compile errors look for similarly named methods in content assist)
    • Schedulers.getIQEngineSchedulerFactorySchedulers.getQueryEngineSchedulerFactory
    • ExecutionSchemas.createIncQueryExecutionSchemaExecutionSchemas.createViatraQueryExecutionSchema
    • IncQueryActivationStateEnum.APPEAREDCRUDActivationStateEnum.CREATED
    • IncQueryActivationStateEnum.DISAPPEAREDCRUDActivationStateEnum.DELETED

A detailed list of changes

The changes done during the merging are documented in a spreadsheet; here we describe the main changes.

Project renaming

Projects from EMF-IncQuery projects were (a) moved from the org.eclipse.incquery to the org.eclipse.viatra namespace; and (b) subcomponents were introduced to split up into the new components of the VIATRA project to make it easier to understand. Projects with bold names in the spreadsheet had some non-trivial renames.

Class renaming

In addition to moving all projects into the org.eclipse.viatra namespace, a few classes were also renamed for several reasons:

  • All occurrences of EMF-IncQuery or IncQuery were renamed to meet the new project name.
  • Some classes in EVM related to match events were generalized into a CRUD-style event model. The semantic is the same as in previous versions, they were renamed only to suggest they can be reused in other domains.

Pattern language updates

The file extensions used by languages were updated from 'eiq' to 'vql' (VIATRA Query Language), and 'eiqgen' to 'vqgen'. The migrator tool updates these file extensions automatically.

Furthermore, a few deprecated annotations and annotation parameters were removed:

  • The @PatternUI annotation is removed, use @QueryExplorer instead.
  • Instead of the 'display' parameter of the @QueryExplorer annotation only the 'checked' parameter is available.
  • The 'location' parameter of the @Constraint annotation is replaced with the 'key' parameter.

VIATRA Databinding Addon

As detailed in the following bug, DatabindingAdapter and GenericDatabindingAdapter classes have been removed. Their functionality has been replaced by the MatcherProperties class. It has a set of static methods that enable the creation of observable values and value properties based on a query specification.

Back to the top