JET transformation authoring

You can create model-to-text transformations by using the Java Emitter Templates (JET) tool, and then use the transformations to automate the application of design patterns. Design patterns are proven solutions to recurring problems; the tools that automate their application are called pattern implementations. Creating JET transformations is a process, also called JET transformation authoring, that accelerates the creation of pattern implementations using JET.

Design patterns and pattern implementations

Design patterns describe a standard solution to a recurring software development problem, and provide solutions that you can apply in many situations. If you reuse designs by using design patterns, you can increase the quality and reliability of the solution.

A pattern specification describes the problem that a pattern solves, the context in which the proposed solution is appropriate, and provides an abstract description of the solution. The process of applying this abstraction to a particular problem is called pattern application. A tool that assists with pattern application is called a pattern implementation. A pattern implementation enables you to describe a pattern application in terms of the abstractions in the pattern specification. You can use the pattern implementation to generate the artifacts such as the files, folders, and projects that make up your solution. Depending on the design pattern, you might specify additional logic in the generated artifacts.

JET and the JET transformation authoring functionality support pattern implementations where the input is described in a structured model and the generated pattern solution consists of text files. These pattern implementations are also called model-to-text transformations.

JET model-to-text transformations accept Extensible Markup Language (XML) documents and Eclipse Modeling Framework (EMF) models as input, and produce Eclipse files, folders, and projects as output. The input and output types that the JET transformation produces are extensible by using the JET Software Development Kit (SDK).

Workflow for developing pattern implementations

To develop a pattern implementation, you complete the following high-level steps:
  1. Identify a recurring problem.
  2. Implement a reference solution, also called an exemplar, which serves as a model solution that others might copy and adapt.
  3. Use the JET transformation authoring functionality to create a model-to-text transformation by examining the reference solution. This process is called exemplar analysis.
  4. (Optional) Integrate the JET transformation with other transformations, user interfaces, or both.
Implementing a reference solution is the most time-consuming of these steps. The purpose of an exemplar analysis is to make the production of a pattern implementation an incremental effort, after you identify and implement a reference solution.

JET transformation authoring prerequisites

To create JET transformations, you must install the Transformation authoring component.

Workflow for authoring JET model-to-text transformations

To create a model-to-text transformation by using the JET transformation authoring functionality, you complete the following high-level steps:

  1. Create a JET transformation that specifies one or more exemplar projects.
  2. Create an input schema that describes the structure of the transformation input. The structure of the transformation input reflects the abstractions of the design pattern.
  3. Create actions that are associated with the transformation input schema. These actions are called transformation actions, or JET actions, and they create the projects, folders, and files in the solution. After you create a JET action, you should use the transformation authoring functionality to update the JET templates with the changes that you make to the transformation model.
  4. Edit the JET template that is associated with each file action to produce the content that is specific to the transformation input.

The transformation input schema and JET actions are collectively called the transformation model and are displayed in the editor area. Most JET transformations are created by repeating steps 2, 3, and 4 as necessary.

Transformation input schemas

A transformation input schema describes the structure of the input for the transformation. The input schema is displayed as a hierarchy of element types and attributes.

Although JET can read models that have very complex input schemas, to facilitate the authoring process, the functionality for authoring JET transformations is restricted to defining basic schemas.

The functionality for authoring JET transformations supports input schemas with the following characteristics:
  • Hierarchical, and contain one root element
  • Each element in the model can contain zero or more attributes that have string values
  • Each element in the model can contain zero or more child elements

    You cannot specify cardinalities with JET transformation authoring functionality. All element containment is zero-to-many. For example, an input schema can specify that books contain chapters, but the input schema cannot specify the number of chapters that books contain.

When you generate the JET templates by updating the project, two implementations of the input schema are created:
  • schema.xsd: This XML Schema Definition (XSD) file is created in the JET transformation project. You can use this file to create XML documents that comply with the input structure of the transformation.
  • input.ecore: This file is an Eclipse Modeling Framework (EMF) metamodel, which is also called an Ecore file.
You can use the Eclipse Modeling Framework to generate a Java API for the transformation input. This API enables you to write Java code to create transformation input, and then use the JET API to invoke the JET transformation. You can also use this generated Java API in a model-to-model mapping transformation.

For example, you can create a UML-to-JET transformation input mapping that invokes the JET transformation. This mapping enables you to develop a JET transformation with a basic input schema, but enables transformation users to describe the input by using Unified Modeling Language (UML).

Note: You cannot specify the UML metamodel as the source model in a mapping.

Transformation actions

When the design pattern abstractions are captured in the input schema, you must determine how the artifacts in the reference solution, also called the exemplar, derive from this schema. Transformation actions, also called JET actions, create projects, folders, and files. When the JET transformation runs, a JET action is invoked each time that an element of that type is encountered in the transformation input.

The functionality for authoring JET transformations supports the following JET actions:
  • File actions
  • Folder actions
  • Project actions
You create JET actions to correspond with exemplar artifacts. You can match a JET action to an exemplar artifact in the following ways:
  • Create a JET action that produces the artifact.
  • Create a conditional JET action.
  • Associate an artifact with an existing action.
  • Create a JET action that produces the artifact that is contained by an action that creates folders or projects.
  • Delete the artifact from the editor area if the transformation does not generate a specific type of artifact. The physical file, folder, or project that you delete is not affected.
  • Ignore the artifact. This option enables the artifact to remain in the editor area and enables you to undo the ignore action and associate the artifact with the transformation input schema.

Each JET action has action parameters that control how the action behaves. These parameters are set to values that re-create the exemplar artifact that creates the JET action. Typically, you customize these parameter values to include the values that are extracted from the transformation input.

JET file actions create file contents by evaluating a JET template. When you update the project, these templates are created if they do not exist. The initial content of the templates is the same as the content in the exemplar file that you specified when you created the corresponding file action. You can modify the generated template to generate the content that is customized for the transformation input.

When you account for exemplar artifacts in the transformation model, you can delete an artifact from the editor area if the transformation does not generate a specific type of artifact. The physical file, folder, or project that you delete is not affected. You can also ignore an artifact, which enables the artifact to remain in the editor area, and enables you to undo the ignore action and associate the artifact with the transformation input schema.

Customizing JET actions and templates

The JET actions and templates that are created when you author a transformation are copies of the exemplar artifacts. Typically, you modify the action parameters and template contents to specify the values in the transformation input.

You can replace selected text with references to the transformation input when you edit the parameter values of the JET actions.

Transformation input references are in the form of XML Path (XPath) expressions. XPath, which is a standard of the World Wide Web Consortium, is designed for XML documents; however, JET adapts this standard to support multiple input model types.

XPath expressions that are embedded in action parameter values are enclosed in braces ({ }), and when you replace variables with model references, these expressions are displayed in a {$variable/@attribute} format, where variable is the name of an input model element, and attribute is the name of an attribute in the element. Each input model element has an associated XPath variable name. By default, the authoring environment keeps the variable name synchronized with the element name.

Although the authoring functionality creates basic XPath expressions, JET provides a comprehensive implementation of the XPath 1.0 specification, and includes a suite of XPath functions that can manipulate values from the transformation input. For example, the XPath expression {lower-case($person/@name)} converts the input reference $person/@name to lowercase.

You can use XPath functions anywhere that an XPath expression is allowed.

Replaceable text in JET templates

The JET authoring editor displays markers on the template text that you can replace with model references. You can identify which templates contain JET markers by observing the JET decorations in the following locations:
  • In the editor area, on a JET action
  • In the Project Explorer or Package Explorer views, or navigator views, on the JET template file

Check the Problems view for detailed information about the JET markers.

Derived attributes

You can create derived attributes to eliminate repetitive calculations. A derived attribute is an attribute of an input schema element that is generated by a calculation instead of provided as transformation input. The calculation can reference other elements and attributes in the input schema. You can create derived attributes directly when you edit a transformation mapping model, or whenever you insert transformation model references.

JET transformation implementation and input model traversal

When you author JET transformations, the code to calculate derived attributes and perform JET actions is generated when you update the project. This code is in the main template of the transformation, which is called templates/main.jet. The main template calculates derived attributes and invokes the JET actions by completing two depth-first traversals of the transformation input. For each element in the transformation input, the following steps are performed:
  1. The transformation creates an XPath variable that represents the current input element. The variable name is derived from the properties of the corresponding input schema element.
  2. During the first traversal of the transformation input, the transformation calculates and stores the derived attribute expressions. During the second traversal, the transformation invokes the JET actions.
  3. The transformation processes the child elements in the transformation input.

During the traversal of the transformation input, the derived attribute calculations and calculations for JET action parameters that are associated with an input schema element can reference the XPath variables that refer to the current element, and each of the variables that belong to ancestor elements.

JET template customization

The final step in creating a JET transformation is editing the JET templates that are generated by running the Update Project command. This customization enables you to adapt the templates to accommodate the transformation input. Editing JET templates might involve one or more of the following steps:
  • Replacing text in the templates with references to the transformation input: This action can include creating new attributes, derived attributes, or new input schema elements. The JET c:get tag implements replacement text when you run the transformation.
  • Adding text to an iterating code block: This action causes a block of text, and any reference to transformation input, to be evaluated multiple times, based on the transformation input. Iterations are implemented by the JET c:iterate tag.
  • Adding text to a conditional block: When a specific condition in the transformation input is true, the transformation evaluates the text in the conditional code block. Conditional blocks are implemented by the JET c:if tag for single conditions. You can also use c:choose, c:when, and c:otherwise tags for alternative text sections.

To assist you to identify text in the templates that should be replaced by references to the transformation input, the text replacements that you specify are monitored. Each time that you replace a text string with a specific reference to the transformation input, this text is stored as exemplar text in the transformation input model, which you can view, add, or remove. This text is also used to create JET Replace markers, which highlight text that is similar to the text in the JET templates that the transformation generates. You can resolve JET Replace markers by using the Eclipse Quick Fix mechanism. This functionality enables you to replace the text with the appropriate JET tag, or to ignore the marker because no change to the text is necessary.

Generation of JET input models for JET transformations

You can create a UML interface and project infrastructure that transforms a UML model into a JET input model that you can use as input for a JET transformation. You can use this functionality to graphically represent non-graphical models that serve as the input to JET transformations. For example, you might create this infrastructure to create a UML interface for a non-graphical model, such as a JET-based Java bean pattern.

The project infrastructure consists of one or more of the following elements:
  • Model-to-model mapping transformation

    The model-to-model mapping transformation transforms a UML model into a JET input model.

  • UML profile project

    The UML profile in this project defines the stereotypes and extensions for the UML model that serves as input to the model-to-model transformation. The generated UML profile project is compatible with the UML profile tooling functionality.

  • Eclipse Modeling Framework (EMF) project

    This project contains the Java application programming interface (API) for the generated JET input model.

  • Eclipse feature project

    This feature project references the model-to-text JET transformation that transforms the generated JET input model, and the EMF project that contains the Java API for the generated JET input model. You can export this project by using the Eclipse Deployable Feature export functionality.


Feedback