View source for M2T-JET/Whats New in 1.0 (Galileo)

== 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 [http://www.eclipse.org/modeling/m2t/news/relnotes.php?project=jet&version=1.0.0 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 [http://download.eclipse.org/modeling/m2t/jet/javadoc/1.0.0/org/eclipse/jet/transform/TransformContextExtender.html#isCanceled() TransformContextExtender.isCanceled()] and may call [http://download.eclipse.org/modeling/m2t/jet/javadoc/1.0.0/org/eclipse/jet/transform/TransformContextExtender.html#checkCanceled() 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 [http://bugs.eclipse.org/273913 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 [http://bugs.eclipse.org/262915 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 [http://bugs.eclipse.org/273331 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 [http://bugs.eclipse.org/215339 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 [http://bugs.eclipse.org/272045 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 [http://bugs.eclipse.org/270985 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''}'''.

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
<pre>
The value of ${'${$foo/@bar}'} is ${$foo/@bar}.
</pre>
would expand to this text, if $foo/@bar evaluated to ABCDEF:
<pre>
The value of ${$foo/@bar} is ABCDEF.
</pre>

See [http://bugs.eclipse.org/179978 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:
<ul>
<li>'''offset''' - the 0-based offset of the node within the source</li>
<li>'''length''' - the length of the source text corresponding to the ast node </li>
<li>'''source''' - the source code corresponding to the ast node</li>
<li>'''nodeType''' - the simple class name (no package qualifier) of the AST node</li>
</ul>

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

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

See [http://help.eclipse.org/ganymede/index.jsp?topic=/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/core/dom/package-summary.html the AST javadoc].

See [http://bugs.eclipse.org/268857 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:

<pre>
<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>
</pre>

The following JET tag

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

would generate:
<pre>
node a
    node c
        node d
        node e
node b
    node f
        node g
        node h
    node i
</pre>

Child content may be position inside the parent content by using the c:deepContent tag within the c:deepIterate body.

The tag is also capable of doing breadth first traversals.

See [http://bugs.eclipse.org/268793 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:

<pre>
<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>
</pre>

You can now write:
<pre>
<c:iterate select="/root">
	Description: <c:get select="@description"/>
	<c:iterate select="node" var="node">
		Node: <c:get select="@name"/>
	</c:iterate>
</c:iterate>
</pre>

And, of course, with embedded expressions, you could write:
<pre>
<c:iterate select="/root">
	Description: ${@description}
	<c:iterate select="node" var="node">
		Node: ${@name}
	</c:iterate>
</c:iterate>
</pre>

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:
<pre>
<c:with select="/root">
	Description: ${@description}
	<c:iterate select="node" var="node">
		Node: ${@name}
	</c:iterate>
</c:with>
</pre>
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.

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

See [http://bugs.eclipse.org/267644 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:
<pre>
<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>
</pre>

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 [http://bugs.eclipse.org/267441 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.

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

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

See [http://bugs.eclipse.org/258996 Bug 258996]