Jump to: navigation, search

Difference between revisions of "M2T-JET/Whats New in 1.0 (Galileo)"

(Compact alternative to c:get tag)
(Generating content from recursive structures is now easier)
 
(2 intermediate revisions by the same user not shown)
Line 148: Line 148:
 
</pre>
 
</pre>
  
Child content may be position inside the parent content by using the c:deepContent tag within the c:deepIterate body.
+
Child content may be position inside the parent content by using the c:deepContent tag within the c:deepIterate body. TO produce output such as:
 +
 
 +
<pre>
 +
node a {
 +
    node c {
 +
        node d {
 +
        } // d
 +
        node e {
 +
        } //e
 +
    } //c
 +
} // a
 +
node b {
 +
    node f {
 +
        node g {
 +
        } // g
 +
        node h {
 +
        } //h
 +
    } //f
 +
    node i {
 +
    } // i
 +
} //b
 +
</pre>
 +
 
 +
You could write this template:
 +
 
 +
<pre>
 +
<c:deepIterate select="node" initialContext="/root" indent="    ">
 +
node ${@name} {
 +
  <c:deepContent/>
 +
} // ${@name}
 +
</c:deepIterate>
 +
</pre>
 +
 
 +
Most attributes on c:deepIterate are optional. If not specified, '''initialContext''' determines the context from surrounding tags. For example, this code is equivalent to the above code.
 +
 
 +
<pre>
 +
<c:with select="/root">
 +
  <c:deepIterate select="node" indent="    ">
 +
node ${@name} {
 +
    <c:deepContent/>
 +
} // ${@name}
 +
  </c:deepIterate>
 +
</c:with>
 +
</pre>
  
 
The tag is also capable of doing breadth first traversals.
 
The tag is also capable of doing breadth first traversals.

Latest revision as of 21:50, 29 June 2009

Whats New in JET 1.0 (Galileo)

The following are the significant changes since the JET 0.9 (Ganymede) release. A complete list of enhancements and defect fixes for the release may be found here.

JET transformations now sensitive to Cancel

Executing JET transformations can now be canceled. Note that canceling may not terminate recursive loops.

Tag and template developers may check for cancellation by using TransformContextExtender.isCanceled() and may call TransformContextExtender.checkCanceled() to automatically abort if the transformation is canceled.

If a transformation is aborted, the JET2Platform runTransform() methods will return Status.CANCEL_STATUS.

See Bug 273913

Easily format generated Java code

A new tag <java:format> allows you to format its contents according to the Java formatting rules of the workspace or a specific project.

See Bug 262915

XPath function for accessing EMF EClass

A new XPath function, emf.eClass() will access the EClass of an object, if it has one. If object is an XPath variable referring to an EMF Object, then emf.eClass($object)/@name will return its EClass name.

If the argument is not specified, then it defaults to the current XPath context object.

See Bug 273331

XPath function for accessing UML2 Stereotypes

A new Xpath function, uml2.stereotype will access a stereotype on a UML2 Element, if it has one. If element is an XPath variable referring to a UML2 element, then uml2.stereotype($element, "Profile-name::Stereotype-name") will access the applied stereotype.

The first argument is optional. If not specified, it defaults to the current XPath context object.

See Bug 215339

The f:indent tag now preserves user regions

The f:indent tag now preserves user regions that it contains. In previous releases, information necessary to process these user regions was lost.

See Bug 272045

Improved integration with PDE build and international characters

PDE build assumes that all Java files have the same encoding (the default for the JVM executing the build). Prior to this release, JET would set the encoding a the Java class generated from each template to the same encoding as the template. This could be problematic if the selected encoding was not the one used by PDE build.

The JET compiler now compiles templates into Java classes that always have the default Java encoding. Characters that cannot be represented in that encoding are transformed into Unicode escape sequences.

In addition, a new JET template extension has been defined (.jet2) whose default encoding is UTF-8. The default encoding of files with a .jet use the platform's default encoding for text files - this can change from installation to installation.

See Bug 270985

Compact alternative to c:get tag

JET now permits the use of ${xpath-expression} within the static text as an alternative to the c:get tag. This expression form may also be used in tag attributes values as an alternative to {xpath-expression}.

The value is ${@someModelAttribute}.

For compatibility, existing JET projects will not support this unless the <transform> element in plugin.xml has the attribute enableEmbeddedExpressions="true". New JET projects are created with this attribute set.

When embedded expressions are enabled, you must escape the ${ if you want them to appear as static text in a template. Escaping is done by including the characters within a string literal inside an embedded expression.

For example, the template text

The value of ${'${@bar}'} is ${@bar}.

would expand to this text, if @bar evaluated to ABCDEF:

The value of ${@bar} is ABCDEF.

See Bug 179978

JET can now read .java files

If a JET transformation is given a .java file as input, then JET will create a JDT abstract syntax tree (AST) for the Java file, and allow templates to traverse this AST. The root element of the loaded document is typically compilationUnit.

The child steps available from any ast node are defined by the child and child list property descriptors available on the node.

The attributes available from any ast node are defined by the simple property descriptors available on the node. In addition, the following for attributes are always available:

  • offset - the 0-based offset of the node within the source
  • length - the length of the source text corresponding to the ast node
  • source - the source code corresponding to the ast node
  • nodeType - the simple class name (no package qualifier) of the AST node

An understanding of the JDT abstract syntax tree APIs is suggested.

As an example, the following XPath expression will return all fields declared in a class

/compilationUnit/types[@nodeType = 'TypeDeclaration']/bodyDeclarations[@nodeType = 'FieldDeclaration']

See the AST javadoc.

See Bug 268857

Generating content from recursive structures is now easier

JET now defines a tag c:deepIterate that allows for generation of text from a recursive structure.

For example, from a model such as:

<root description="Demo Model">
    <node name="a">
        <node name="c">
            <node name="d"/>
            <node name="e"/>
        </node> 
    </node>
    <node name="b">
        <node name="f">
            <node name="g"/>
            <node name="h"/>
        </node> 
        <node name="i"/>
    </node>
</root>

The following JET tag

<c:deepIterate select="node" initialContext="/root" indent="    ">
node ${@name}
</c:deepIterate>

would generate:

node a
    node c
        node d
        node e
node b
    node f
        node g
        node h
    node i

Child content may be position inside the parent content by using the c:deepContent tag within the c:deepIterate body. TO produce output such as:

node a {
    node c {
        node d {
        } // d
        node e {
        } //e 
    } //c
} // a
node b {
    node f {
        node g {
        } // g
        node h {
        } //h
    } //f
    node i {
    } // i
} //b

You could write this template:

<c:deepIterate select="node" initialContext="/root" indent="    ">
node ${@name} {
  <c:deepContent/>
} // ${@name}
</c:deepIterate>

Most attributes on c:deepIterate are optional. If not specified, initialContext determines the context from surrounding tags. For example, this code is equivalent to the above code.

<c:with select="/root">
  <c:deepIterate select="node" indent="    ">
node ${@name} {
    <c:deepContent/>
} // ${@name}
  </c:deepIterate>
</c:with>

The tag is also capable of doing breadth first traversals.

See Bug 268793

JET tags can now change the XPath context object, allowing for shorter expressions

The c:iterate tag will now set the XPath context object to the object of the current iteration, provided this feature is enabled.

This permits expressions relative to that object to be shorter. Instead of writing:

<c:iterate select="/root" var="root">
	Description: <c:get select="$root/@description"/>
	<c:iterate select="$root/node" var="node">
		Node: <c:get select="$node/@name"/>
	</c:iterate>
</c:iterate>

You can now write:

<c:iterate select="/root">
	Description: <c:get select="@description"/>
	<c:iterate select="node" var="node">
		Node: <c:get select="@name"/>
	</c:iterate>
</c:iterate>

And, of course, with embedded expressions, you could write:

<c:iterate select="/root">
	Description: ${@description}
	<c:iterate select="node" var="node">
		Node: ${@name}
	</c:iterate>
</c:iterate>

Note also that the var attribute on c:iterate is now optional.

Also, a new tag c:with can be used to temporarily set the XPath context object during the evaluation of the block:

<c:with select="/root">
	Description: ${@description}
	<c:iterate select="node" var="node">
		Node: ${@name}
	</c:iterate>
</c:with>

The c:with tag does not iterate. It will evaluate its block only once. If the select expression does not return a value, the c:with body is not evaluated.

For compatibility, this behavior is only enabled if the JET variable org.eclipse.jet.taglib.control.iterateSetsContext is set to true(). New JET projects have this variable set automatically in the generated main.jet template. Existing JET transformations will need to add a statement such as the following to main.jet to enable this behavior.

<c:setVariable var="org.eclipse.jet.taglib.control.iterateSetsContext" select="true()"/>

See Bug 267644

Localize template content with Java .properties bundles

A new set of tags f:message, f:bundle, f:setBundle and f:param allow you to draw template text from Java resource bundles (.properties files).

For example, this template:

<f:bundle basename="templates/demo/messages">
<c:with select="/root">
   <f:message>description</f:message>: ${@description}
      <c:iterate select="node">
         <f:message>node</f:message>: ${select="@name}
   </c:iterate>
</c:iterate>
</f:bundle>

draws messages description and node from a the properties bundle templates/demo/messages.properties

Messages can be parametrized by embedding the f:param tag within the f:message tag.

The .properties files follow the standard rules for Java resource bundles.

See Bug 267441

New XPath function for evaluating XPath expressions on the fly

The eval() XPath function allows you to evaluate an XPath expression. This can help modularize you code.

<c:setVariable var="someComplexXpathExpressionUsedOften" select="   'the XPath expression as a string literal'   "/>

... later ...
<c:get select="eval($someComplexXpathExpressionUsedOften)"/>

See Bug 258996