| h1. Writing Queries and Interpreted Expressions |
| |
| {toc:style=disc|minLevel=2|maxLevel=3} |
| |
| h2(#introduction). Introduction |
| |
| Many parts of a _VSM_ require you to provide _interpreted expressions_, which will be evaluated at runtime to provide a behavior specific to your domain and representations. Some of these expressions return model elements (in which case we call them _queries_), while others simply produce text (for example the expressions used for labels), but the principles stay the same. |
| |
| Sirius does not force the use of a specific language to write these queries. Currently, three different languages are provided by default, and if you have specific needs, you can extend the system and "provide your own":#custom. You can use several different languages inside the same VSM (but only one in each expression). |
| |
| Whatever the language(s) you use, because they are all optional from Sirius's point of view, make sure the Viewpoint Specification Project which contains your VSMs explicitly depends on the Sirius plug-in which provides supports for these languages. Otherwise when you modelers are deployed to end-users you can not be sure the proper support will be available. The _Viewpoint Specification Projects_ which are created using the standard wizard are pre-configured to use AQL (_Acceleo Query Language_), which is the recommended language as of Sirius 3.1. See the sections below for each of the standard languages for the name of the Sirius support plug-ins to depend on if you use the language. |
| |
| h2(#general). General Rules |
| |
| Some general rules are independent of the language details. |
| |
| *Auto-completion.* First, in the _VSM_ editor, any field in the property view which has a yellow background is an interpreted expression. In these fields, auto-completion can be triggered by hitting _Ctrl+Space_. |
| |
| !images/emptyFieldAutoCompletion.jpg! |
| |
| The completion will correspond to the empty expression for the installed query language (e.g. **aql:** for AQL). It will also place the cursor at the expected place where it is ready to start typing the expression. |
| |
| !images/emptyExpressionCursor.jpg! |
| |
| When hitting auto-completion on an empty expression, the first completion proposal will correspond to the variables which are available in the expression's context, and the rest correspond to all the features, services, etc. which are available on the current element. |
| |
| !images/emptyExpressionAutoCompletion.jpg! |
| |
| Sometimes Sirius is not able to statically determine the precise type of the model elements on which an expression will be evaluated. In that case, it assumes a plain _EObject_. This means you will not get completion proposals specific to your custom types, and that if you use features or services which are not available on _EObject_, the VSM's validation will fail. To prevent this, if you know the precise type of the elements and the language supports it, add a cast operation to tell Sirius the actual type (e.g. <code>aql:filter(packageName::ExpectedType).theRestOfTheExpression</code> if using AQL for example. |
| |
| *The Interpreter view.* The _Interpreter_ view can be used to develop complex expressions interactively. The view can work in either the native _Acceleo_ mode (corresponding to Acceleo 3/MTL) or in the _Sirius_ mode. In the _Sirius_ mode, you can use any of the languages supported by Sirius, but you lose the benefits of syntax coloring. |
| |
| To use the _Interpreter_ view, simply open a Sirius representation, select and element in it (for example a shape on a diagram), and type some expression in the view's upper text field. The result of the expression (a set of model elements or a string) will appear in the lower part of the view. If you select a different element, the result will automatically be re-evaluated in the context of the new element. |
| |
| !images/viewpoint_interpreter.png! |
| |
| _Warning:_ When using the _Interpreter_ view from an element selected in a Sirius representation, the context of the expression is *not* the _semantic_ element, but the _view_ model element used internally by Sirius. To access the semantic element you must use the view's @target@ reference. More concretely, imagine you have a Sirius diagram representing UML classes with nodes. If you select a class and enter <code>aql:self</code> in the interpreter view, the result will not be a UML @Class@ element, but a @DNode@ (the type used internally by Sirius to represent graphical nodes). To get the UML class, you must enter <code>aql:self.target</code> (or the equivalent in other languages). Keep this in mind when using the _Interpreter_ view to develop expressions you want to use inside a VSM: most expressions defined in the VSM will be evaluated in the context of a semantic element, so you will need to add/remove @target@ references when switching between the two. |
| |
| *Determinism.* In general, you should try to ensure that your queries are deterministic, i.e. from the same input model they should always return the same result, and in the same order (if returning collections of elements). Otherwise, each time a representation is refreshed it might become dirty (as Sirius will see the order difference as a change) or even visually unstable (i.e. elements shown in a different order). There are several things to be aware of in order to ensure determinism in your queries: |
| * At the meta-model level, if you control it, make sure any derived feature always return its values in the same order. If you do not control the meta-model and it has unordered references which can cause problems (UML is an example), you can impose your own ordering by sorting the elements whenever they are used in a Sirius query. |
| * At the Sirius query level, make sure you call only operations which are deterministic in the query language(s) you use. Unfortunately, this information is not often documented in the query languages semantics, so some trial and error experimentation is required for now. |
| * At the service level, if you create your own "Java services":#service_methods, make sure to use data structures which ensure a fixed iteration order, like @LinkedHashSet@ instead of @HashSet@ for example. |
| |
| h2(#specialized). Using the Specialized interpreters |
| |
| Sirius provides several specialized interpreters to handle more efficiently some forms of simple expressions which can occur very often in a typical VSM. Each interpreter focuses on a very limited case, and none supports complex expressions. This allows them to be very fast, but it requires that you use them explicitly when possible. All these interpreters are available by default in Sirius, you do not need to declare additional dependencies in your VSM project to be able to use them. |
| |
| * *@var:@* This interpreter can only do direct access to the value of a named variable. For example, instead of <code>aql:containerView</code> (using AQL), the equivalent using the specialized interpreter would be @var:containerView@. As a special case, the pseudo-variable @self@ is available to access the current element (the evaluation context): @var:self@ is equivalent to <code>aql:self</code> in AQL. |
| * *@feature:@* This interpreter can only do direct access to a named feature of the current element. For example, instead of <code>aql:self.name</code>, the equivalent using this interpreter would be @feature:name@. Note that if your metamodel generated code was generated with feature delegation set to Reflective, the feature interpreter will return the raw value of the attribute (as seen by @eGet@), bypassing any custom getter implementation you provided. This interpreter also supports the following pseudo-features: |
| ** @feature:eContainer@ returns the container of the current element (or @null@ if there is none). This is equivalent to <code>aql:self.eContainer()</code>. |
| ** @feature:eContents@ returns the direct contents of the current element (or an empty collection if there is none). This is equivalent to <code>aql:self.eContents()</code>. |
| ** @feature:eAllContents@ returns all the elements directly and indirectly contained inside the current element (or an empty collection if there is none). This is equivalent to <code>aql:self.eAllContents()</code>. |
| ** @feature:eCrossReferences@ returns all the model elements which are directly referenced by the current element (or an empty collection if there is none). This is equivalent to <code>[self.eCrossReferences()/] using Acceleo 3/MTL</code>. |
| * *@service:@* This interpreter can be used to directly invoke a service method (i.e. a Java method that follows conventions for "service methods":#service_methods ) on the current element. For example, assuming the service class "@EcoreServices@":#ecore_services has been correctly registered in the VSM, the expression @service:getEClasses@ (note the absence of parenthesis) will invoke the @getEClasses@ on the current element if it is an instance of @EPackage@. |
| ** The service interpreter supports parameters, but only variables can be used as parameter (no literals or complex expressions), for example: @service:serviceName(view, diagram)@. |
| ** You can use the service interpreter not only on the current context by using a variable name before calling the service, for example: @service:myVariableName.serviceName@. |
| ** For efficiency reasons, if multiple services match the expression, the first one found is used. There is no real polymorphism management. |
| |
| h2(#aql). Using AQL |
| |
| Starting from Sirius 3.1, _AQL_ (Acceleo Query Language, first introduced in Sirius 3.0) is the recommended language to write queries/interpreted expressions. AQL is similar to Acceleo 3/MTL, but simpler and provides much better performance in the Sirius context. AQL expressions start with the @aql:@ prefix and have a syntax similar to Acceleo (without the enclosing @[../]@ brackets). The main differences between the two languages are: |
| * Feature access must *always* explicitly specify the target object, even if the target is @self@. This means an Acceleo expression like <code>[name/]</code> which accesses the @name@ attribute of the current element translates in AQL as @aql:self.name@. The expression @aql:name@ with no explicit receiver will always be interpreted as an access to the @name@ variable, and may result in an error if the variable in question is not defined. |
| * "Lambda" expressions must always declare their parameters and use them explicitly. Again, there is no implicit @self@ in such a context. For example: <code>[self.eContents()->select(name.startsWith('A'))/]</code> becomes <code>aql:self.eContents()->select(i | i.name.startsWith('A'))</code> with an explicit declaration and usage of @i@ in AQL. |
| * AQL is more persmissive in terms of missing/empty intermediate results in complex expressions: @aql:self.anEmptyReference.somethingElse@ will not result in an error as the equivalent Acceleo (or OCL) expression would, but simply return an empty result. |
| * AQL provides different services/methods by default compared to Acceleo. In general the set of default services in AQL is better suited to the typically use cases encountered in Sirius. |
| |
| See <a href="https://www.eclipse.org/acceleo/documentation/aql.html" target="_blank">the AQL documentation</a> for more details about the language itself, the full list of standard services, and the differences with Acceleo/MTL. |
| |
| _Note:_ Viewpoint Specification Projects created with the default wizard will be already setup to use it. Otherwise you need to add a dependency to the @org.eclipse.sirius.common.acceleo.aql@ plug-in to ensure AQL support will be available wherever your modelers are used. When *developing* new VSMs which use AQL, it is recommended to have the @org.eclipse.sirius.common.acceleo.aql.ide@ plug-in installed as it provides specification-time features like expression completion. However, @org.eclipse.sirius.common.acceleo.aql.ide@ is not needed at runtime for the resulting modelers to function. |
| |
| _Note:_ Several services like olcIsKindOf() or filter() use type literals and will require to explicitly reference the known meta-models as dependencies to work. It is recommended to add the corresponding meta-models plug-ins to the dependencies of the Viewpoint Specific Project. |
| |
| h2(#acceleo). Using Acceleo |
| |
| Acceleo 3 implements the MTL standard, and provides a query language similar to OCL (with some extensions). It provides relatively good static validation and auto-completion when editing your expressions, but AQL is even better, and faster. For new modelers, prefer AQL over Acceleo/MTL. If you have existing modelers which use Acceleo/MTL, converting them to use AQL is relatively straightforward, see <a href="https://www.eclipse.org/acceleo/documentation/aql.html#MigratingfromMTLqueries" target="_blank">the AQL documentation</a> for details. |
| |
| Acceleo expressions are enclosed in brackets: <code>[theExpression/]</code>. Inside the brackets you can write any valid Acceleo expression, including using @if@ and @let@ statements, for example. See <a href="https://wiki.eclipse.org/Acceleo" target="_blank">the Acceleo documentation</a> for the exact syntax and semantics of the language. |
| |
| Note that Acceleo expressions used inside VSMs *must* be enclosed inside a single bracket. It is not currently possible to mix Acceleo expressions and fixed text (like @"prefix[someExpression/]suffix"@). Instead, you can use Acceleo's string manipulation operations to obtain the same result: <code>['prefix' + someExpression + 'suffix'/]</code>). Related to this, auto-completion only works if you are inside a well-formed bracket (i.e. <code>[<cursor>/]</code>); if you have simply opened the bracket but not closed it (i.e. <code>[<cursor></code>), completion will not be available. |
| |
| Acceleo expressions can transparently invoke methods from Java classes which follow the "service methods":#service_methods conventions and have been properly declared in the VSM. Note that currently this only works if the Java service class is in the same project as the _VSM_. You can also invoke Acceleo _queries_ defined in @.mtl@ files in your Viewpoint Specification Project. For this to work, your Viewpoint Specification Project should be an Acceleo Generator project, you can convert the project with the _Configure > Toggle Acceleo Nature_ contextual menu. If you want to use queries from @.mtl@ files in you Sirius project, the parent _Viewpoint_ element must have a _Java Extension_ element which references the MTL file, using the @com::example::domain::design::module@ syntax. Also make sure to read <a href="http://www.obeonetwork.com/page/building-an-acceleo-generator" target="_blank">http://www.obeonetwork.com/page/building-an-acceleo-generator</a> to ensure the project is built correctly, or the queries defined in the @.mtl@ files may not be available when the project is deployed as a plug-in. |
| |
| _Note:_ due to an incompatible change in serialization format in EMF 2.9, if you use external @.mtl@ files in your modeler definitions and build your modeler plug-ins using EMF 2.9 or later, the resulting modeler will not work with previous versions of EMF (as the resulting @.emtl@ files will not load correctly with EMF 2.8 and earlier). For reference, EMF 2.9 corresponds to Eclipse 4.3 (Kepler). |
| |
| Acceleo is very precise (and very demanding) about the types of elements your queries are executed on. This generally means you get good auto-completion and useful validation and diagnostics. However sometimes Sirius is not able to statically determine the precise type of the model elements on which an expression will be evaluated. In that case, it assumes a plain _EObject_. If you know the actual type which will be used, prefix your expression with @filter(ExpectedType)@ to help Sirius. Note that if the actual type at runtime is not compatible with @ExpectedType@, the rest of your expression will silently be ignored. |
| |
| In the context of Sirius, you have access to a special feature which can be used to follow "back-links" or "cross-references". From a given model element, this allows you to easily (and efficiently) find all the elements which refer to it in the scope of the models and representations in the same modeling project. This feature is available through the @eInverse()@ method, which can be used on any model element inside an Acceleo expression. |
| |
| Note that in most cases, expressions in Sirius are evaluated in a context where _variables_ are defined. For example, most expressions inside tool definitions have access to variables telling them which elements the tool has been applied on. In some cases, the names of these variable can conflict with names of features in your meta-model. The evaluation rules of Acceleo (OCL actually) give precedence to variables, so it is recommended to always prefix accesses to your meta-model features with @self@ (or another expression) to avoid ambiguity. As a concrete example, say you have an expression @"[target/]"@ that you expect to access the @target@ feature of one of your object. If evaluated in a context where a @target@ variable exist, the value of the expression will be the value of the variable, _not_ the value of the object's property. To avoid ambiguity, always use expressions of the form @"[self.target/]"@ in such cases. |
| |
| _Note:_ Due to internal changes in the Eclipse Equinox runtime, starting with Eclipse Luna (4.4) it is impossible to evaluate Java services from an Acceleo 3 expression if the Java service is defined directly in the workspace. This only affect specifiers (not end-users). When developing modelers which use Acceleo expressions and rely on Java services, you must launch an Eclipse runtime from your development environement to test the resulting modeler in a context where the service is available as part of a deployed plug-in. Starting with Sirius 3.0 you can also use the AQL language instead, which has a syntax very similar to Acceleo 3/MTL, but does not have this limitation regarding services in the workspace. |
| |
| h2(#ocl). Using Raw OCL |
| |
| Sirius also supports raw OCL expressions, but this support is deprecated and will be removed in future versions. OCL expressions must be prefixed with @ocl:@. If you use it your Sirius project must declare a dependency to the @org.eclipse.sirius.common.ocl@ plug-in to ensure OCL support will be available wherever your modelers are used. |
| |
| It is highly recommended that you use Acceleo, which implemented the MTL standard and is a super-set of the OCL language, instead of raw OCL. |
| |
| h2(#custom). Providing a Custom Language |
| |
| Sirius allows you to provide your own language implementations, if you have very specific needs or want to reuse an existing custom language. Note that Sirius must be able to syntactically and unambiguously determine from an expression which language it is written in (to send it to the appropriate interpreter). The simplest way to achieve this is to define a prefix (like @ocl:@ for OCL) so that expressions written in your language can be distinguished from expressions written in any of the others. |
| |
| To provide your custom language, you must _at least_ implement the @org.eclipse.sirius.common.expressionInterpreter@ extension point, and provide an implementation of the @org.eclipse.sirius.common.tools.api.interpreter.IInterpreter@ interface. The example below shows how the Acceleo interpreter is registered. The @AcceleoMTLInterpreterProvider@ is the one which implements the @IInterpreter@ interface. |
| |
| bc. |
| <extension point="org.eclipse.sirius.common.expressionInterpreter" |
| id="org.eclipse.sirius.common.acceleo.mtl.AcceleoMTLInterpreter"> |
| <expressionInterpreterProvider |
| interpreterProviderClass="org.eclipse.sirius.common.acceleo.mtl.business.internal.interpreter.AcceleoMTLInterpreterProvider" /> |
| </extension> |
| |
| You can also optionally provide support for auto-completion for your language by implementing the @org.eclipse.sirius.common.proposalProvider@ extension point and providing an implementation of @org.eclipse.sirius.common.tools.api.contentassist.IProposalProvider@ interface. For example, here is how the completion support for Acceleo is registered (@AcceleoProposalProvider@ is the class which implements the @IProposalProvider@ interface): |
| |
| bc. |
| <extension point="org.eclipse.sirius.common.proposalProvider"> |
| <proposalProvider |
| class="org.eclipse.sirius.common.acceleo.mtl.ide.AcceleoProposalProvider" |
| interpreter="org.eclipse.sirius.common.acceleo.mtl.AcceleoMTLInterpreter" /> |
| </extension> |
| |
| h2(#service_methods). Writing Java Services |
| |
| Query languages may support the notion of _Java services_, which are methods written in Java that can be transparently invoked from interpreted expressions in Sirius. Acceleo 3 includes this support. All you need to do is to create a Java class whose methods follow some conventions (described below) in your Viewpoint Specification Project, and declare the class (using its fully qualified Java name) in the VSM. You can then use the services defined in that class in any of you interpreted expressions written in either Acceleo or another language which supports services (refer to the query language's documentation for details). |
| |
| A service is simply a public Java methods which follows some conventions: |
| * The class containing the method must be public and have a default constructor which takes no argument. |
| * The class can contain many public methods (static or not), each of which will be visible as a service if they follow the right conventions. |
| * A service method must take at least one parameter, which should be an EMF type (i.e. @EObject@ or a sub-type of @EObject@). |
| * A service method may take more parameters, which can be: |
| ** strings |
| ** numbers |
| ** EMF types (i.e. @EObject@ or a sub-type) |
| ** Java collections of EMF types (note that array types are *not* supported). |
| * A service method may return a value, which can have the same kinds of types as parameters. |
| |
| Here is an example of a Java service: |
| |
| bc(#ecore_services). |
| public class EObjectServices { |
| public List<EClass> getEClasses(EPackage ePackage) { |
| List<EClass> eClasses = new ArrayList<EClass>(); |
| // The service code. |
| return eClasses; |
| } |
| } |
| |
| Once a service has been defined and its class is registered in your VSM, you can invoke it in the expressions of languages which support it like this: <code>[aFamily.getFamiliesContainingParents()/]</code>. (using Acceleo syntax) The invocation looks as if the service was a normal feature of the @Family@ type. When the service is invoked, the model element on which it is invoked is used as the first argument to the Java method. If arguments are passed in the expression, they are mapped to the second, third, etc. parameters of the Java method, assuming the types are compatible. The result of evaluating a service invocation is the result of the Java method. |
| |
| _Warning:_ Java service methods should be stateless. There is no guarantee that two successive invocations of the same service method on two model elements (or even on the same one) will use the same instance of the service class. |
| |
| _Warning:_ There are currently some limitations on the use of Java services from Acceleo: |
| * primitive types can not be used as arguments or return types for service methods invoked from Acceleo 3 expressions. The workaround is to use the corresponding wrapper type (e.g. @Integer@ instead of @int@). |
| * service methods invoked from Acceleo 3 expressions can not return @void@. You can return any value instead, for example target argument (the service method's first parameter). |
