| <?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> |
| <title>Model_Operations</title> |
| <link type="text/css" rel="stylesheet" href="../../resources/bootstrap.css"/> |
| <link type="text/css" rel="stylesheet" href="../../resources/custom.css"/> |
| </head> |
| <body> |
| <h1 id="SpecifyingModelOperations">Specifying Model Operations</h1> |
| <h2 id="introduction">Introduction</h2> |
| <p>Most modelers created with Sirius are not just used to view models, but also to edit them. The edition behavior is specified through different kinds of tools (e.g. |
| <em>Direct Edit</em>, |
| <em>Creation Tool</em>, etc.) which depend on the dialect. The behavior of each tool of each dialect is specified inside the VSM using a small |
| <em>Domain Specific Language</em> of model operations. This document describes all the model operations supported by this language. Unless otherwise specified, model operations can be used/composed for any tool of any dialect. |
| </p> |
| <ol class="toc" style="list-style: disc;"> |
| <li> |
| <a href="#SpecifyingModelOperations">Specifying Model Operations</a> |
| <ol style="list-style: disc;"> |
| <li> |
| <a href="#introduction">Introduction</a> |
| </li> |
| <li> |
| <a href="#flow">Flow Control Operations</a> |
| <ol style="list-style: disc;"> |
| <li> |
| <a href="#begin">Begin</a> |
| </li> |
| <li> |
| <a href="#goto">Change Context</a> |
| </li> |
| <li> |
| <a href="#if">If</a> |
| </li> |
| <li> |
| <a href="#switch">Switch/Case</a> |
| </li> |
| <li> |
| <a href="#for">For</a> |
| </li> |
| <li> |
| <a href="#let">Let</a> |
| </li> |
| </ol> |
| </li> |
| <li> |
| <a href="#model_change">Model Change Operations</a> |
| <ol style="list-style: disc;"> |
| <li> |
| <a href="#create_instance">Create Instance</a> |
| </li> |
| <li> |
| <a href="#set">Set</a> |
| </li> |
| <li> |
| <a href="#unset">Unset</a> |
| </li> |
| <li> |
| <a href="#remove">Remove</a> |
| </li> |
| <li> |
| <a href="#move">Move</a> |
| </li> |
| </ol> |
| </li> |
| <li> |
| <a href="#representations">Representations Operations</a> |
| <ol style="list-style: disc;"> |
| <li> |
| <a href="#create_view">Create View</a> |
| </li> |
| <li> |
| <a href="#created_edge_view">Create Edge View</a> |
| </li> |
| <li> |
| <a href="#delete_view">Delete View</a> |
| </li> |
| <li> |
| <a href="#navigation">Navigation</a> |
| </li> |
| </ol> |
| </li> |
| <li> |
| <a href="#dialogandwizard">Dialog & Wizard</a> |
| <ol style="list-style: disc;"> |
| <li> |
| <a href="#dialog">Open Dialog</a> |
| </li> |
| <li> |
| <a href="#wizard">Open Wizard</a> |
| </li> |
| </ol> |
| </li> |
| <li> |
| <a href="#extensions">Java Extensions</a> |
| <ol style="list-style: disc;"> |
| <li> |
| <a href="#external_java_action">External Java Action</a> |
| </li> |
| <li> |
| <a href="#external_java_action_call">External Java Action Call</a> |
| </li> |
| <li> |
| <a href="#standard_java_actions">Standard Java Actions</a> |
| </li> |
| </ol> |
| </li> |
| </ol> |
| </li> |
| </ol> |
| <h2 id="flow">Flow Control Operations</h2> |
| <h3 id="begin">Begin</h3> |
| <p>This element has no property. It only serves as an entry point to the specification of a tool’s behavior. Note that a |
| <em>Begin</em> element can only contain a single operation. It is recommended to begin a tool’s specification by creating a no-op |
| <a href="#goto"> |
| <em>Change Context</em> |
| </a> operation directly inside the |
| <em>Begin</em>, as a |
| <em>Change Context</em> can contain multiple operations. |
| </p> |
| <h3 id="goto">Change Context</h3> |
| <p>Every model operation is executed in the context of a specific model element (the equivalent of |
| <code>this</code> or |
| <code>self</code> in a programming language). Usually, at the beginning of a tool, the context is the semantic element to which the tool is applied (the actual details can vary from tool to tool, refer to their documentation). The |
| <em>Change Context</em> operation changes the context to a new element and then executes any sub-operations it contains in sequence (in the order of definition). |
| </p> |
| <p>The new context element to go to is specified by the |
| <em>Browse Expression</em> property of the |
| <em>Change Context</em> operation. It is executed in the context element of the |
| <em>Change Context</em> operation itself, and should return another model element (which will become the context for the sub-operations). If the expression does not return any element, it is not an error, but the sub-operations are not executed. If the expression returns several elements, only the first one is retained and used as the context for the sub-operations. |
| </p> |
| <p> |
| <em>Tip:</em> Using a no-op |
| <em>Change Context</em> (with a browse expression like |
| <code>aql:self</code> which does not actually change the context) can be useful to group multiple operations into a single “block”, especially in contexts where only one model operation is supported (e.g. inside a |
| <em>Begin</em> element). |
| </p> |
| <h3 id="if">If</h3> |
| <p>The |
| <em>If</em> operation is used for condition execution. It first evaluates its |
| <em>Condition Expression</em> in the current context, and if the result of this expression (interpreted as a boolean) is true then it executes any sub-operations it contains in sequence (in the order of definition). If the expression returns a false value, |
| <em>If</em> does nothing. |
| </p> |
| <p> |
| <em>Note:</em> “else” and “else if” constructs are not supported directly, but the same effect can be achieved using the |
| <a href="#switch"> |
| <em>Switch</em> |
| </a> operation with the appropriate |
| <em>Cases</em>. |
| </p> |
| <h3 id="switch">Switch/Case</h3> |
| <p>A |
| <em>Switch</em> operation is used for branching. It is a generalization of the |
| <em>If</em> constructs which supports multiple conditions. The |
| <em>Switch</em> operation itself has not property; it serves only as a container for one or more |
| <em>Case</em> elements, and an optional |
| <em>Default</em> element. Each |
| <em>Case</em> element has a |
| <em>Condition Expression</em>, and may contain sub-operations. The |
| <em>Default</em> element has no property but may contain sub-operations. |
| </p> |
| <p>When a |
| <em>Switch</em> is executed, the |
| <em>Condition Expressions</em> or each of its |
| <em>Case</em> elements is evaluated (in the current context) until one returns a true value. If one is found, the sub-operations of the |
| <em>Case</em> element are executed in sequence, and the rest of the |
| <em>Switch</em> is ignored (the remaining conditions, if any, are not tested). If none of the |
| <em>Cases</em> has an expression which returns true, then the sub-operations of the |
| <em>Default</em> element, if any, are executed in sequence. |
| </p> |
| <p>A combination of |
| <em>Switch/Case/Default</em> is equivalent to |
| <code>if (...) { ... } elsif (...) { ... } else { ... }</code> in a programming language. |
| </p> |
| <h3 id="for">For</h3> |
| <p>The |
| <em>For</em> element is used to loop over collections of model elements and execute some operations on all of them. The |
| <em>Expression</em> of the |
| <em>For</em> element is executed in the current context, and should return a collection of model elements. The |
| <em>Iterator name</em> property is a fixed string ( |
| <code>i</code> by default) which give the name of the variable used for the iteration. |
| </p> |
| <p>After evaluating the |
| <em>Expression</em>, each of the element in the returned collection will be bound in turn to a variable named as specified in |
| <em>Iterator name</em> before the sub-operations of the |
| <em>For</em> element are executed in sequence (once for each of the returned element). Inside the sub-operations, you can access the current element of the iteration using the variable named in |
| <em>Iterator name</em>. The actual syntax will vary depending on the query language you use. |
| </p> |
| <h3 id="let">Let</h3> |
| <p>The |
| <em>Let</em> operation is used in order to create a new variable which can be used by child model operations. The |
| <em>Variable name</em> is a fixed string used to access the variable in child model operation. The |
| <em>Value expression</em> is executed in order to set the value of the variable. The |
| <em>Let</em> operation is similar to a |
| <em>For</em> operation with an expression returning only one element for the iteration. If the |
| <em>Variable name</em> is “self”, the behavior of the |
| <em>Let</em> will be the same as the behavior of a |
| <em>Change Context</em>. It is not recommended to use a |
| <em>Let</em> with the |
| <em>Variable name</em> “self”, prefer the |
| <em>Change Context</em> for a better readability of your odesign. |
| </p> |
| <h2 id="model_change">Model Change Operations</h2> |
| <h3 id="create_instance">Create Instance</h3> |
| <p>The |
| <em>Create Instance</em> operation is used to create new semantic elements to be added into the user’s model. You must specify : |
| </p> |
| <ol> |
| <li>the |
| <em>Type Name</em> (using the same syntax as for |
| <em>Domain Class</em> properties) of the new object to create |
| </li> |
| <li>the |
| <em>Reference Name</em> through which the created element will be attached to the current context. |
| </li> |
| </ol> |
| <p>When the |
| <em>Create Instance</em> operation is executed, say in the context of semantic element |
| <em>S</em>, a new instance of the specified type name is created and then added to |
| <em>S</em>'s reference named in |
| <em>Reference Name</em>. The reference name must correspond to a valid containment reference for the context element of the operation, otherwise the newly created object will not be properly integrated into the semantic model. |
| </p> |
| <p>The |
| <em>Variable Name</em> property can be set to any valid variable name ( |
| <code>instance</code> by default). The named variable is assigned with the newly created object, so that it can be accessed from the remaining operations in the tool. |
| </p> |
| <p>Inside the |
| <em>Create Instance</em> element you can add sub-operations, which will be executed in sequence in the context of the newly created element. This is useful to correctly initialize the new object’s properties. |
| </p> |
| <h3 id="set">Set</h3> |
| <p>The |
| <em>Set</em> operation is used to set the value of a feature (attribute or reference) of the current element. When executed, it evaluates the |
| <em>Value Expression</em> in the current context element. The expression’s result is then |
| <em>set</em> as the new value of the feature named in |
| <em>Feature Name</em> of the current context element. The value returned by the expression must be type-compatible with the named feature. |
| </p> |
| <p>Inside the |
| <em>Set</em> element you can add sub-operations, which will be executed in sequence in the same context. |
| </p> |
| <h3 id="unset">Unset</h3> |
| <p>The |
| <em>Unset</em> operation is used to remove elements from a feature (attribute or reference) of the current element. When executed, it evaluates the |
| <em>Element Expression</em> in the current context element, which may return one or more elements. Each of the returned elements are then removed from the feature named in |
| <em>Feature Name</em> of the current context element. It is not an error if some of the returned elements are not actually part of the specified feature, they are simply ignored. |
| </p> |
| <p>Inside the |
| <em>Unset</em> element you can add sub-operations, which will be executed in sequence in the same context. |
| </p> |
| <h3 id="remove">Remove</h3> |
| <p>The |
| <em>Remove</em> operation is used to remove the current element from its parent element. It takes no parameter. When executed, it simply removes the element from its containing feature. |
| </p> |
| <h3 id="move">Move</h3> |
| <p>The |
| <em>Move</em> operation is used to move the current element from its current parent into a new one. The |
| <em>New Container Expression</em> is evaluated in the current context and should return the (single) element in which to move. The |
| <em>Feature Name</em> indicates the containment feature of the new parent in which to add the current element. |
| </p> |
| <h2 id="representations">Representations Operations</h2> |
| <h3 id="create_view">Create View</h3> |
| <p>This operation is specific to diagrams. It can be used to explicitly create a view (graphical representation) of the current element, which is mostly useful when using unsynchronized diagrams and/or mappings.</p> |
| <p>The |
| <em>Container View Expression</em> is evaluated in the context of the current semantic element, and should return the view ( |
| <code>DDiagram</code>, |
| <code>DNode</code> or |
| <code>DNodeContainer</code>) in which the new view should appear. The |
| <em>Mapping</em> indicates the kind of view to create. If the container view expression returns an element which can contain a view for the current semantic element and specified mapping (and does not already contain one), the view will be created, even if the diagram and/or mapping is not synchronized. |
| </p> |
| <p>Note that because the |
| <em>Container View Expression</em> is evaluated in the context of a semantic element and must return a view, you must use the cross-referencer to navigate from the semantic model to the view model. Using the Acceleo 3 language you can use the |
| <code>eInverse()</code> service to find which elements point to the current one and then select only those which do it through a reference named |
| <code>target</code> (the views in Sirius diagrams reference their target semantic element through this reference). |
| </p> |
| <p>The |
| <em>Variable Name</em> property can be set to any valid variable name ( |
| <code>createdView</code> by default). The named variable is assigned with the newly created view, so that it can be accessed from the remaining operations in the tool. |
| </p> |
| <h3 id="created_edge_view">Create Edge View</h3> |
| <p>This operation is specific to diagrams. It can be used to explicitly create an edge view (graphical representation) of the current element, which is mostly useful when using unsynchronized diagrams and/or mappings.</p> |
| <p>It works similarly to the |
| <a href="#create_view"> |
| <em>Create View</em> |
| </a> operation, except that in addition to the |
| <em>Container View Expression</em>, you must also provide a |
| <em>Source Expression</em> and a |
| <em>Target Expression</em>, which should return the semantic elements between which the edge should be created, if source and target views are found regarding the selected edge mapping properties. |
| </p> |
| <h3 id="delete_view">Delete View</h3> |
| <p>This operation is specific to diagrams. It can be used to explicitly remove a view (graphical representation) from the diagram, without deleting the corresponding semantic element. It is mostly useful when using unsynchronized diagrams and/or mappings.</p> |
| <p>It has no parameter and works similarly to the |
| <em>Remove</em> operation; you must already be in the context of the view element you want to delete. |
| </p> |
| <h3 id="navigation">Navigation</h3> |
| <p>This operation is specific to diagrams. It can be used to navigate to another diagram representing the current element. The |
| <em>Diagram Description</em> indicates the type of diagram to open, and the |
| <em>Create if not existent</em> flag indicates whether a new diagram of the specified type should be created on the current element if none exists. |
| </p> |
| <p>The operation does nothing if the current element is not compatible with the specified diagram type or if there is no existing diagram and the |
| <em>Create if not existent</em> flag is not set. |
| </p> |
| <h2 id="dialogandwizard">Dialog & Wizard</h2> |
| <p> |
| <strong>Warning:</strong> The model operations below are provided by the Sirius properties view plugins. To make sure those operations will be available to the end user, you should add the following plugins in your modeler dependencies: |
| </p> |
| <ul> |
| <li>org.eclipse.sirius.properties</li> |
| <li>org.eclipse.sirius.ui.properties</li> |
| </ul> |
| <p>If those plugins are missing at runtime, Open Dialog and Open Wizard operations will not be executable.</p> |
| <h3 id="dialog">Open Dialog</h3> |
| <p>The |
| <em>Open Dialog</em> model operation is used in order to open a new dialog where the end user will be able to see and manipulate some pieces of information. You can change the title of the dialog with the |
| <em>Title expression</em>. This expression must return a string. You can specify one |
| <em>Page</em> with various |
| <em>Groups</em> to specify the content of the dialog. You can leverage existing |
| <em>Pages</em> and |
| <em>Groups</em> from existing definition of your |
| <em>Properties View</em>. |
| </p> |
| <p>A dialog can contain multiple buttons. If you do not specify any button, two will be created by default. The first one, with the label “Cancel”, will close the dialog and rollback any changes made during the execution of the model operation chain. The second one, with the label “OK”, will close the dialog and execute the child model operations of the dialog. </p> |
| <p>You can create |
| <em>Dialog Buttons</em> in a dialog in order to specify the behavior of the buttons. If at least one |
| <em>Dialog Button</em> is specified, the default behavior previously described will not be used anymore. For each |
| <em>Dialog Button</em> description, a button will be added in the user interface of the dialog. The label of the button can be specified with the |
| <em>Label expression</em> which must return a string. The |
| <em>Is Enabled expression</em> is used to determine if the button must be activated or not. This can be used to prevent the end user from finishing an action. This expression must return a boolean. An |
| <em>Initial Operation</em> is available on a |
| <em>Dialog Button</em> in order to specify the behavior to execute when the user will click on the button. |
| </p> |
| <p>The specifier can indicate that a |
| <em>Dialog Button</em> should be considered by default with the |
| <em>default</em> boolean. When a |
| <em>Dialog Button</em> should be used by |
| <em>default</em>, it is focused by default when the dialog is opened. A |
| <em>Dialog Button</em> can also close the dialog by using the property |
| <em>Close Dialog On Click</em>. By specifying |
| <em>false</em> as the value for |
| <em>Close Dialog On Click</em> and by using an |
| <em>Initial Operation</em> on the button, a specifier can easily create a button to restore a default value. Finally, a boolean is available in order to |
| <em>Rollback Changes On Close</em>. By setting this value to true, when the button will be pressed, it will have the same behavior as a regular cancel button by rollbacking the whole model operation chain. |
| </p> |
| <h3 id="wizard">Open Wizard</h3> |
| <p>The |
| <em>Open Wizard</em> model operation is used in order to open a new wizard to let the end user specify some information using multiple |
| <em>Pages</em>. You can configure the title of the window by returning a string with the |
| <em>Window Title</em> expression. You can also configure the title and description of the wizard with the |
| <em>Title</em> and |
| <em>Description</em> expressions. Both expressions should also return a string. You can prevent the end user from finishing early the wizard and from switching to another page by returning false for the |
| <em>Is Page Complete</em> expression. A wizard can be closed only if all |
| <em>Pages</em> are completed. |
| </p> |
| <p>The wizard can also contain various |
| <em>Pages</em> and |
| <em>Groups</em> using the |
| <em>Properties View</em> domain specific langage available in Sirius. You can leverage existing |
| <em>Pages</em> and |
| <em>Groups</em> from existing definition of your |
| <em>Properties View</em>. A wizard can also contain an |
| <em>Initial Operation</em> used to define the child model operations to execute when the user will finish the wizard. |
| </p> |
| <h2 id="extensions">Java Extensions</h2> |
| <p>Beyond the operations which are described above, you can also execute arbitrary Java code in the context of a tool by providing an |
| <em>External Java Action</em> and invoking it with the corresponding operation. |
| </p> |
| <h3 id="external_java_action">External Java Action</h3> |
| <p>When used as a model operation (instead of as a full-blown tool), you only have to specify the |
| <em>Java Action Id</em>. It should correspond to an extension of the |
| <code>org.eclipse.sirius.externalJavaAction</code> extension point which registers a class implementing |
| <code>org.eclipse.sirius.tools.api.ui.IExternalJavaAction</code> to be executed. You may also create |
| <em>External Java Action Parameter</em> elements inside the |
| <em>External Java Action</em> element. Each one has a fixed |
| <em>Key</em> and a computed |
| <em>Value</em>, which will be evaluated before the operation is executed and made available to the Java class through the |
| <code>parameters</code> argument of the |
| <code>execute()</code> method. |
| </p> |
| <p>As the External Java Action uses the Eclipse extension point mechanism, it means you cannot use it in development mode (when the |
| <a href="../../Glossary.html#VSM"> |
| <em>Viewpoint Specification Model</em> |
| </a> you are working on is in the workspace). |
| </p> |
| <h3 id="external_java_action_call">External Java Action Call</h3> |
| <p> |
| <em>External Java Action Call</em> is simply a convenience operation to invoke an |
| <em>External Java Action</em> defined elsewhere in the VSM, with potentially different parameters. |
| </p> |
| <h3 id="standard_java_actions">Standard Java Actions</h3> |
| <p>The following External Java Actions are available in standard and can be used in |
| <a href="../../Glossary.html#VSM"> |
| <em>Viewpoint Specification Models</em> |
| </a>. Note that if you want to create your own actions, you can implement |
| <code>org.eclipse.sirius.tools.api.ui.IExternalJavaAction</code> directly or inherit from |
| <code>org.eclipse.sirius.business.api.action.AbstractExternalJavaAction</code> which provides some helper methods. |
| </p> |
| <h4 id="org.eclipse.sirius.business.api.action.moveElement">org.eclipse.sirius.business.api.action.moveElement</h4> |
| <p>This external Java action can be used to move an element to a different position inside a many-valued EReference.</p> |
| <p>Action parameters:</p> |
| <ul> |
| <li> |
| <code>referenceOwner</code> (an EObject): the owner of the EReference to edit. |
| </li> |
| <li> |
| <code>referenceName</code> (a string): the name of the EReference of the owner object to edit. This must be a many-valued, changeable reference. |
| </li> |
| <li> |
| <code>element</code> (an EObject): the element to move inside the list. It is an error if the specified element is not in the list. |
| </li> |
| <li> |
| <code>predecessor</code>: the element of the list right before which element must be moved, i.e. after the operation, predecessor will be the direct predecessor of element in the list. May be null to indicate that element should be moved at the front of the list. If not null, it is an error if predecessor is not in the list. |
| </li> |
| </ul> |
| <h4 id="org.eclipse.sirius.business.api.action.printVariables">org.eclipse.sirius.business.api.action.printVariables</h4> |
| <p>This external Java action is designed to help debugging |
| <em>Viewpoint Specification Models</em> by printing (in standard output) |
| <br/>all the variables accessible to model operations at the invocation point. |
| </p> |
| <p>Action parameters:</p> |
| <ul> |
| <li> |
| <code>title</code>: an optional string header to print before the list of variables, for example to distinguish different uses of this action in the same VSM. |
| </li> |
| <li> |
| <code>enabled</code>: an optional boolean (defaults to true) to indicate if the action should be executed or not. This is useful to quickly enable/disable an action with minimal editing of the VSM. |
| </li> |
| </ul> |
| <h4 id="org.eclipse.sirius.ui.business.api.action.openHelpSection">org.eclipse.sirius.ui.business.api.action.openHelpSection</h4> |
| <p>This external Java action can be used to open the Eclipse Help system (or actually any web page) on a specific section from inside a tool (typically a popup menu).</p> |
| <p>Action parameters:</p> |
| <ul> |
| <li> |
| <code>href</code>: the URL of the help resource. To open an Eclipse Help section, use an URI of the form |
| <code>/com.example.pluginName/path/to/document.html#sectionId</code> |
| </li> |
| </ul> |
| </body> |
| </html> |
