New and Noteworthy

In previous versions, annotation without parameters did not support adding the parentheses in the syntax. VIATRA 2.9 extended the syntax to support such annotations, so the further code works:

Previously, to get the status of a query specification (to check whether it has been initialized correctly) was not possible from the IQuerySpecification interface, but required accessing the internal query representation. To make this access less common, two new default methods were introduced to the IQuerySpecification interface:

In order to simplify log output, the default logging configuration was updated to remove unnecessary duplication and ensure everything uses the same configuration.

Old output:

New output:

The new configuration uses org.eclipse.viatra as a common prefix, thus it is possible to turn on all debug messages with a single configuration both for the VIATRA query and transformation runtimes, while it is still possible to do it selectively by using a more specific class names in the configuration. For users who use customized log4j configurations should update them to match the new scheme.

The pattern parser infrastructure did not provide access to classes ouside the default classpath of the language runtime plugin, e.g. classes defined in plugins VIATRA does not depend on in Eclipse environments. To solve this issue, VIATRA 2.4 allows specifying a classloader for the pattern parser that gets used.

Starting with version 2.3, both the query and transformation runtime works without relying on Guava. This allows avoiding various issues in standalone applications where other users may add a different Guava version than the one used by VIATRA itself. However, there are two important cases to consider:

Starting with this version, it is possible to disable query group generation (and the validation rules related to it) via customizing the language configuration module. The built-in standalone parser modules disables query group generation, but by default this functionality will stay enabled. The simplest way to rely on this updated generator is the following:

In order to measure the effects of VIATRA, version 2.3 includes a simple profiler for the base index itself that measures the time spent inside the adapters VIATRA uses to initialize the indexes and keep them up-to-date. Given the use of the profiler results in reduced performance, it is turned off by default, but can be enabled with the appropriate base index option.

Usage:

Starting with version 2.2, VIATRA will use EPL v2.0 as its license. For details about this change look at https://www.eclipse.org/legal/epl-2.0/

VIATRA 2.2 introduces a set of code minings to provide extra inline information about the developed patterns. Currently, two information sources are enabled:

Code minings are only available if Eclipse Photon or newer is used; however, for version 2.2, we consider code minings experimental: in future versions we might update when minings are presented, both for performance and usability concerns. Because of this reason, code minings are by default turned off; in case of interest they can be turned on using an appropriate preference setting.

To ease the modification previously created patterns, the editor makes it easier to convert existing local variables to parameters easily by appropriate content assist and quick fix-based enhancements.

The batch transformation API was updated to provide better support for transformations that are almost exclusively controlled by data dependencies. The control flow for these transformations is usually trivial - the rules are executed one by one until there are no more matches left. This behavior is very similar to event-driven transformation with the main difference that these transformations are not executed on changes in the underlying model but are triggered manually.

The API received multiple small enhancements to support such transformations:

Prior to version 2.2, the filter settings of batch transformation rules were ignored by mistake, and only filters defined in statements were taken into account. In version 2.2, filters are handled the following way:

This behavior might change the behavior of existing transformations when transformation rule filters were defined but filterless statements were used: in such case, the default rule filters will be applied. In such cases, the unnecessary default filters should be removed; or if necessary, a new filter could be used to override the default filter when activating the rule.

Prior to version 2.2, the main test class ViatraQueryTest had a field accessMap for storing the mapping of plain Java types to their handler objects for snapshot creation. In version 2.2, the encouraged way of providing this and further serialization information is in form of a single SnapshotHelper instance, initialized at the same time when the test case is created.

Details: The field accessMap and the API method withClasses for updating the mapping have been removed. Instead, a SnapshotHelper can (and should) be provided while calling the first method, test, for test case initialization. Accordingly, test has a new signature now, which accepts a SnapshotHelper instance. For example, very often, a helper might be created on spot when the test case gets initialized:

VIATRA 2.1 includes an experimental graphical editor for model queries based on Sirius. The queries created by the graphical editor are translated to the existing textual syntax, then handled with the existing runtime and IDE features. See the documentation page for details.

The severity of missing variable types is increased to warning. The reason for this change is that explicitly declaring parameter types helps increases readability of patterns and helps precise error localization in case of type errors. However, to avoid breaking existing pattern declarations, such missing types are not considered as errors. However, in a future release such missing declarations might be considered as erroneous, so it is recommended to add the missing declarations (e.g. using the appropriate quick fix functionality).

The headless pattern parser component of VIATRA has been updated to be able to maintain an updatable set of query specifications, useful for integrating custom query evaluation functionality in modeling tools, where the queries are updated.

The default rule priority in InvertedDisappearancePriorityConflictResolver was changed in version 2.1 from 0 to 1. This change was motivated by the fact that in case of 0 priority additions and deletions would have the same priority that is in contrast with the goal of the resolver.

This is a breaking change as transformations using both priority '0' and '1' might change their internal behavior. To avoid this, it is recommended not to use priority '0' at all with this conflict resolver.

Before version 2.1 the createRule methods of the classes BatchTransformationRuleFactory and EventDrivenTransformationRuleFactory were parameterless and the query specification was provided in the precondition method. This worked fine when using JVM-based languages with advanced type inference, such as Xtend or Kotlin for writing transformation, but when transformations were created in Java, it became cumbersome, as some type casting was required to initialize the rules properly.

To fix this, new createRule methods were created that expect the query specification input as parameters, thus replacing both the old createRule and precondition methods. To consolidate this API, the old calls are marked as deprecated, but are still available in VIATRA 2.1.

To make behaviour more predictable, the default configuration of the Local Search query engine no longer allows hybrid pattern matching in conjuction with the incremental query backend across pattern calls, i.e. if the caller pattern is evaluated with LS, so will the callee pattern during the same matcher invocation. To enable hybrid matching, where the local search backend may request results of called patterns from the incremental backend (in case the callee is declared incremental pattern), use configurations that explicitly enable this, such as LocalSearchHints.getDefaultGenericHybrid().

To support reusing model connectors without tooling dependencies, the IModelConnector interface and all its uses have been moved to a new org.eclipse.viatra.query.runtime.ui plugin, and it has been renamed accordingly. All adapters provided by VIATRA were updated to provide the new interface, the few existing users should request instances of org.eclipse.viatra.query.runtime.ui.modelconnector.IModelConnector instead. The new implementation behaves in exactly the same way than before.

VIATRA included for a few years a component to make sure our IDE features such as the Query Results view work well with the Facet Editor, originally provided by the EMF Facet project than later the MoDisco project. Given these editors are only used sparingly, and MoDisco leaves the simultaneous release, we have decided not to support this editor anymore.

Starting with version 2.0 it is possible to calculate both the transitive closure and the reflexive transitive closure of the matches of a given pattern. Using this construct, the following two patterns are equivalent:

Another new feature is a simplified syntax for pattern calls if the called pattern only contains a single constraint. This is useful for easier negation, transitive closure calculation and aggregation as well. The following examples showcase where this feature can be used to reduce the complexity of existing patterns:

VIATRA 2.0 also introduces a new aggregator for calculating the average of numbers found in pattern matches. As an example, the following pattern can be used to calculate the average number of CPU values over a set of instances.

Hover help support was enhanced in VIATRA 2.0, specifically, a lot of elements now display hover that previously did not, including EClass and EReference types and variable references. Furthermore, calculating these hovers should be more efficient now, resulting in better performance in case of large number of patterns and/or complex metamodel hierarchies.

The pattern matcher API was updated to rely on Java 8 features such as Streams and Optionals. This allows functional-style processing of the pattern matches.

The VIATRA Query engine also supports setting the default search-based and default caching backend instances, allowing further customization of the runtime behavior of the engine. The new feature is available through the previously used ViatraQueryEngineOptions class.

For users who want to evaluate recursive queries via the Query Result View, we proudly report that the delete and rederive (DRED) evaluation mode can now be selected on the UI (specifically the Preferences page for the VIATRA Query Explorer).

The removal of various features in this release made us reconsider the contents of our p2 repository. Previously we used a composite repository with all of our releases, but the features removed from version 2.0 show up in its earlier version that can be confusing. In order to handle this case better (and also for better performance), we have introduced a /latest p2 repository, and simplified the categorization instead.

With regards to these changes, the download page was also updated.

VIATRA 2.0 updates the minimum required version of sevaral of its dependencies. This allowed to clean up some code, but might require updating target requirements. The most important updates:

In VIATRA 2.0, the default behavior of query code generator was updated to reduce the number of generated files. This means, no .util package is generated, match and matcher code is generated as embedded subclasses, and match processors are not generated anymore.

If necessary, the old generator behavior can be set by relying on the VQL Compiler settings.

All code marked as deprecated has been removed from the codebase. Additionally, further components were removed

VIATRA 2.0 removes support for query languages not relying on EMF metamodels but retaining the structure of the VQL language. This feature is not used at all, but increases language maintenance costs significantly. Most users of the VIATRA framework should not be affected at all, but all related API changes are listed below.

There were a few cases, where Guava types such as Functions or Predicates were visible in the API. In VIATRA 2.0, the trivial method calls were removed (to be handled via direct method references), while the remaining ones were replaced by the alternatives built-in to the Java 8 standard library. The following classes and methods were affected:

The transformation API used the Pair class from the Xtend standard library to rely the → (mapped to) operator to define filters based on name mappings. In version 2.0, the underlying code was changed to rely on Map.Entry classes from the Java standard library.

The following methods were affected by this change:

To migrate your code, you can do one of the following:

 If you are using Xtend code, and the "name" → value syntax does not compile anymore, add the following import declaration in the header: import static extension org.eclipse.viatra.transformation.runtime.emf.transformation.TransformationExtensions. * If you are not using Xtend, or you don’t want to rely on the mapped to operator, simply instantiate these entries with the call new SimpleEntry<>("name", value).

A few APIs in VIATRA returned null if no possible values could be found. Given VIATRA 2.0 depends on Java 8, such APIs were reworked to return Optional values instead.

The affected methods are the following:

If the old behavior of returning null values is necessary the Optional.orElse call can be used, e.g. query.getFirstAnnotationByName("Constraint").orElse(null);

The constructor of the QueryEvaluationHint class was updated: previously it was instantiated with a Map of settings and an optional query backend (that could be null). Starting with version 2.0, the constructor does not accept null for the query backend, but provides an alternative constructor where it can be selected via a new enum which default backend should be selected instead. This change was necessitated by the new search- and caching backend settings in ViatraQueryEngineOptions.

All usage of the IMatchProcessor interface was replaced with references to the Consumer type. Generated match processors (if enabled), also implement the Consumer interface.

Before VIATRA 2.0, the various APIs of the Query component threw a set of different checked exceptions: ViatraQueryException, ViatraBaseException and QueryProcessingException (and specialized versions of them). For version 2.0, these exceptions were updated in two ways:

In this version, the dependencies of the org.eclipse.viatra.query.runtime plug-in had been reorganized. This should not cause any issues for users who deploy the query runtime with the org.eclipse.viatra.query.runtime.feature (in Eclipse environment) or the viatra-query-runtime feature (available from the Maven repository), as they will deploy all required plug-ins.

In other cases, if backend-specific code is used, the org.eclipse.viatra.query.runtime.rete and the org.eclipse.viatra.query.runtime.localsearch plugins might be necessary to add as additional dependencies to the developed code; and if necessary (e.g. in a non-Equinox OSGi environment), ViatraQueryEngineOptions#setSystemDefaultBackends() might need to be called with explicitly adding the corresponding entries.

This API breaking change affects users of the org.eclipse.viatra.query.runtime.base.itc Java library for incremental transitive closure computation over custom graph data sources.

Not affected:

Details: We have internally rewritten several algorithm and data structure classes of the transitive closure service to be more memory efficient. In particular, we changed the way how the multiset of incoming/outgoing graph edges is represented, as visible in interfaces IGraphDataSource and IBiDirectionalGraphDataSource (the graph observer interface is unchanged.).

The old interfaces (since 1.6) used java.util.Map with vertices as keys, and positive integers representing the count of parallel edges as values, while in the new version, multisets are encoded as org.eclipse.viatra.query.runtime.matchers.util.IMemoryView. For easier migration of legacy clients and implementors, conversions between the old and new representations are available at org.eclipse.viatra.query.runtime.matchers.util.IMemoryView#asMap and org.eclipse.viatra.query.runtime.matchers.util.IMemoryView#fromMap.

For a complete list of fixed issues for VIATRA 1.6 consult https://projects.eclipse.org/projects/modeling.viatra/releases/1.6.0/bugs

A a new filter option was introduced in this release regarding dangling edges (i.e. references pointing to objects outside the scope of the query engine). The old version made the assumptions that there are no such dangling edges whatsoever, and thus did not apply a filter to reject query matches that would involve such a dangling edge. This led to surprising results in some cases. For more predictable results and more straightforward semantics, we now allow the user to turn off this assumption, so that the appropriate checks will be performed (at a slight cost in performance).

For new code, and for any existing users that experienced problems with the unpredictability of dangling edges, we suggest to use the newly introduced option to drop the dangling-free assumption. In a future VIATRA release this will be the new default.

This API breaking change affects users of the org.eclipse.viatra.query.runtime.base.itc Java library for incremental transitive closure computation over custom graph data sources.

Not affected:

Details: We have changed the way how the multiset of incoming/outgoing graph edges is represented in interfaces IGraphDataSource and IBiDirectionalGraphDataSource. The old interface used a java.util.List of vertices (parallel edges represented as multiple entries in the list), while the new interface uses java.util.Map with vertices as keys, and positive integers representing the count of parallel edges as values. The graph observer interface is unchanged.

In the Oxygen release train, multiple versions of Guava are available. In order to ensure VIATRA uses a single Guava version, all framework projects now import Guava with package imports, and set the corresponding ''uses'' constraints for all packages where Guava packages are exported.

For projects using the VIATRA framework everything should work as before. However, if there are issues with multiple Guava versions colliding, check whether any of your classes have Guava types on its API (e.g. check superclasses, parameter and return types; most common candidates are Predicate and Function instances). If any such case is available, the following steps are required to ensure the single Guava version:

For more details about the issue, and uses constraint violations in general, look at http://blog.springsource.com/2008/10/20/understanding-the-osgi-uses-directive/

Version 1.5 introduces greatly improved inference of functional dependencies among pattern variables, which may significantly influence query evaluation performance.

One can now also use the @FunctionalDependency annotation to manually specify additional dependency rules, in order to express domain-specific insight. See below for examples of the syntax:

More details available here.

Constant values (more precisely constant-value filtering) within patterns are now handled more efficiently in many cases. In a proprietary code base, specifically for entire query packages where this feature is heavily used, we have observed a reduction between 15-30% in the memory footprint of Rete.

As an additional minor memory improvement, the results of eval/check expressions are no longer cached in Rete by default. In case some such expressions involve particularly expensive computations, one can restore the original caching behaviour either globally or on a per-pattern basis using the appropriate hint option introduced into the ReteHints class.

The query language now allows Java type constraints, both as parameter types and as variable type constraints in pattern bodies. The recommended use case is that query parameters that are a result of (a) an eval() or (b) aggregation expression should be annotated with their Java types. Java type names can be referenced by prefixing them with the keyword java, and of course namespace imports are available. So, for example, a query parameter may be typed as follows: no: java Integer. Usage basics are explained in the query language syntax guide.

In addition to the previously supported count keyword, there are now several new aggregators available (including sum, min and max, as well as an API for user-defined aggregators) to compute an aggregated value from matches of a called pattern. Usage basics are explained in the query language syntax guide.

Parameters can optionally be marked as incoming (in), outgoing (out). Incoming parameters must be bound when the pattern matcher initializes, while outgoing parameters must not. For backwards compatibility, unmarked parameters are neither incoming nor outgoing: they might be either bound or unbound when called. In version 1.4, parameter directions are ignored by the Rete engine, but used by the local search engine to decide the set of plans to create during matcher preparation.

Patterns can optionally be declared either local search-only (search) or Rete-only (incremental), providing hints to the runtime what pattern matcher should be initialized for this pattern. If undefined, the default hints of the engine is used (by default, Rete); and can be redefined using the advanced query engine API.

It is important to note that the Query Engine may override these declarations, e.g. if they cannot be executed.

The query language introduced some new keywords, namely in, out, search and incremental. Variables and types with this name has to be escaped using the ^ symbol. On the opposite side, count is not a keyword anymore, so for future versions its references does not need to be escaped.

The query development UI is greatly updated. It might be worth checking out the new VIATRA perspective; for existing users of the perspective it may make sense to reset the perspective as it has been redesigned in version 1.4.

We have introduced a completely new Query Specification Registry and deprecated the old version. Users of the org.eclipse.viatra.query.runtime.extensibility.QuerySpecificationRegistry class should read the JavaDoc for details on how to migrate to the new org.eclipse.viatra.query.runtime.registry.QuerySpecificationRegistry implementation.

Read http://wiki.eclipse.org/VIATRA/Query/UserDocumentation/API/Advanced#Query_specification_registry for details on the new registry.

The type inferrer of the VIATRA Query Language was rewritten; in most cases, it should behave exactly the same as the previous version, with the following differences:

The problem can be worked around using a typecast in the expression. See the following (artificial) example:

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

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

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