Stdlib extensions

Stdlib extensions

This section describes the components and extensions provided by Stdlib. We use the shortcut xpand.util.stdlib... for component classes in package org.eclipse.xtend.util.stdlib in workflow configurations for convenience.

Note that many functions of the Stdlib make use of static variables in their Java implementation, thus the values are kept through a complete MWE workflow. Also, because of the static implementation, the features are not threadsafe.

This is an extremely useful library to print information to the logging facility. It is really valuable through transformation processes or for complex expressions to know what exactly expressions are evaluated to.

Extension: org::eclipse::xtend::util::stdlib::io

import data; 
extension org.eclipse.xtend.util.stdlib::io; 
create DataModel this duplicate(DataModel s): 
  entity.addAll( s.entity.duplicate() ) -> 
  setName(s.name); 
  
create Entity this duplicate(Entity old): 
  (old.name+" has "+old.reference.size+" references").info() -> 
  old.reference.name.info() -> 
        

This leads to the following output on the console:

922  INFO  - Person has 1 references 
923  INFO  - [autos] 
926  INFO  - Vehicle has 0 references 
926  INFO  - []
        

Of course IO extension functions can also be used within Xpand, but if used for logging purposes you have to deal with one side effect: Since the functions return the passed object (the result of an expression, in the simplest case just a string) and Xpand prints out expression results to the opened file, the message will be shown on the console, but also be in the result file. This you might want to avoid, so you can use a small trick for this: after calling a log function use the chaining operator and let the result of the expression be an empty string:

«EXTENSION org::eclipse::xtend::util::stdlib::io» 
... 
«DEFINE javaClass FOR Entity» 
  «REM»The following expression will dump the feature names without producing output 
  as side effect«ENDREM» 
  «features.name.info() -> ""»

This will produce this output on the console:

1122 INFO  IOExtensions       - [name, age, address] 
1740 INFO  IOExtensions       - [street, zip, city]

Each function returns the object on which they have been called, so you can build chain expressions. Or, in other words, if you have some expression like

element.x.y.z.select(t|t.someProp).a

you can always embed one of these io functions anywhere such as in

element.x.
syserr()
.y.z.select(t|t.someProp.
info()
).a

Sometimes it is necessary to have counters within transformation code. The counter extensions enable to initialize, manipulate and retrieve counters.

Extension: org::eclipse:xtend:::util::stdlib::counter

You might want to specify configuration values from properties files from your transformation code. The Properties extensions can help you there. Before being able to access the properties through an extension function the properties files must be read and its values stored. This is done through the workflow component PropertiesReader , which is described below.

Extension: org::eclipse::xtend::util::stdlib::properties

This allows you to temporarily associate name-value pairs with any model element.

Extension: org::eclipse::xtend::util::stdlib::elementprops

In template code there is no direct access to the Issues instance of the workflow's context possible. The Issues extensions help to report warnings and errors to the Issues instance during transformation.

This should not encourage you to use constraint checking and generally raise errors directly from within the transformations. However, sometimes it is sensible and useful to be able to do that.

Extension: org::eclipse::xtend::util::stdlib::issues

The Naming extensions are only usable with EMF models. This one helps with names, qualified names and namespaces. A qualified name is defined as the seuqence of primitive names of the containment hierarchy of an element, seperated by a dot (e.g. java.lang.String). In order for this to work, model elements are expected to have a name attribute of type EString.[9]

Extension: org::eclipse::xtend::util::stdlib::naming

Sometimes you might want to share information within a transformation process. One alternative is the use of GLOBALVAR expressions, but this needs that the variables are configured in the workflow. The Globalvar extensions help to store and retrieve objects within a transformation process.

Extension: org::eclipse::xtend::util::stdlib::globalvar

The cloning utilities help you to clone a model element and all its children. The clone(Object) function clones a single object and its children, whereas the clone(List) clones a list of elements. The semantics of cloning is as follows:

  • the object passed in as a parameter is duplicated

  • all objects referenced via containment references are also duplicated, recursively

  • the values of the attributes are duplicated

  • non-containing references to other objects are copied while the target is not cloned (a reference to the original is created in the new object)

Extension: org::eclipse::xtend::util::stdlib::cloning

Sometimes there is the need to find objects that reference a specific object. This extension helps to solve this recurring task. This extension can only be used for EMF based models.

Extension: org::eclipse::xtend::util::stdlib::crossref

Often it is required to create and retrieve unique identifiers for objects through the transformation process. The UID extensions provide a simple mechanism for this task. Unique identifiers are calculated from the current system time plus an internal counter. The extensions therefore only guarantee that the identifier stays the same within one workflow execution, but will change through different runs. If you need to have unique identifiers that stay the same over every generation run (e.g. for Protected Regions Ids) then you need another mechanism.

If you are loading the model that assigns IDs to EObject (only for EMF based models) the xmlId() function will be useful. Especially when using UML2 models this function will return a unique and non-changing identifier for objects.

Extension: org::eclipse::xtend::util::stdlib::uid

These utilities help with mixin models. Mixin models are typically simple models that provide additional information about model elements in a source model of a transformation. They can be seen as annotations.

These utilities expect that the mixin models have a very specific structure: A root element, and then any subtree, where the elements have a name attribute. Here's an example:


The mixin elements are ControllingServiceRefSpec and BundleSpec. They are owned by the root element, Cbd2OsgiMixin. The name is expected to contain the qualified name of the element the annotation refers to. Once the model is set up like this, and made available to a transformation using the workflow's GLOBALVAR facilities, you can then use the extension functions.

Extension: org::eclipse::xtend::util::stdlib::mixin

The tracing extensions allow to create trace paths during your model transformations. This is done by creating a trace model which holds references from source to target elements. Traces must be added explicitly to the transformation code.

Extension: org::eclipse::xtend::util::stdlib::tracing



[9] It is intended that the uml2ecore utility can add such a name attribute to every meta class automatically.