| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| |
| <html> |
| <head> |
| <meta content="text/html; charset=ISO-8859-1" |
| http-equiv="content-type"> |
| <title>Emfatic 0.0.2 Release Note</title> |
| </head> |
| <body> |
| <h1>Emfatic 0.0.2 Release Note</h1> |
| <br> |
| The 0.0.2 release of Emfatic introduces several small changes in the |
| area of annotations and datatypes. The intent of the changes is |
| to fix problems with the mapping between Emfatic and Ecore and to |
| bring the Emfatic annotation syntax closer in line with that of Java |
| 1.5 annotations.<br> |
| <br> |
| <h3>1. Changes to Annotations</h3> |
| Following are examples that explain the use of annotations in Emfatic |
| 0.0.2 and the changes from the 0.0.1 release.<br> |
| <br> |
| In the example below, the text <span style="font-family: monospace;">ann</span> |
| is used as the <span style="font-weight: bold;">source</span> value |
| twice in the context of a single element. Previously Emfatic made |
| an attempt to combine multiple annotations with the same <span |
| style="font-weight: bold;">source</span> value into a single |
| annotation. However Ecore allows multiple annotations of a model |
| element to use the same <span style="font-weight: bold;">source</span> |
| value. So the Emfatic 0.0.1 mapping failed to allow Ecore models |
| with this pattern of annotation use to be created. With 0.0.2, |
| the code below will produce two annotations, both with <span |
| style="font-weight: bold;">source</span> set to <span |
| style="font-family: monospace;">ann</span>, for the class in the model.<br> |
| <br> |
| <table |
| style="background-color: rgb(204, 204, 255); width: 100%; text-align: left;" |
| border="1" cellpadding="2" cellspacing="2"> |
| <tbody> |
| <tr> |
| <td style="vertical-align: top;"><span |
| style="font-family: monospace;">package p;</span><br |
| style="font-family: monospace;"> |
| <br style="font-family: monospace;"> |
| <span style="font-family: monospace;">@ann(k="v")</span><br |
| style="font-family: monospace;"> |
| <span style="font-family: monospace;">@ann(k="v2")</span><br |
| style="font-family: monospace;"> |
| <span style="font-family: monospace;">class C { }</span><br> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <br> |
| <br> |
| <br> |
| Another problem with Emfatic 0.0.1 caused annotation details to be |
| written in a different order than their actual order in the Ecore model.<br> |
| <br> |
| <table |
| style="background-color: rgb(204, 204, 255); width: 100%; text-align: left;" |
| border="1" cellpadding="2" cellspacing="2"> |
| <tbody> |
| <tr> |
| <td style="vertical-align: top;"><span |
| style="font-family: monospace;">package p;</span><br |
| style="font-family: monospace;"> |
| <br style="font-family: monospace;"> |
| <span style="font-family: monospace;">@ann(k1="v1", k2="v2", |
| k3="v3")</span><br style="font-family: monospace;"> |
| <span style="font-family: monospace;">class C { }</span><br> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <br> |
| The example above shows an annotation with 3 key/value detail |
| pairs. Generating Ecore from this and then generating Emfatic |
| from the Ecore could result in the annotation details appearing in a |
| different order. With Emfatic 0.0.2 you will be able to go from |
| Emfatic to Ecore and from Ecore back to Emfatic and the order of |
| details in an annotation (as well as the order of annotations on an |
| element) will be preserved.<br> |
| <br> |
| <br> |
| <br> |
| Finally, Emfatic 0.0.2 allows a form of annotation similar to the Java |
| 1.5 annotation style where a value is indicated, but the key is not |
| named. It should be as simple as omitting the key, like this:<br> |
| <br> |
| <table |
| style="background-color: rgb(204, 204, 255); width: 100%; text-align: left;" |
| border="1" cellpadding="2" cellspacing="2"> |
| <tbody> |
| <tr> |
| <td style="vertical-align: top;"><span |
| style="font-family: monospace;">package p;</span><br |
| style="font-family: monospace;"> |
| <br style="font-family: monospace;"> |
| <span style="font-family: monospace;">@ann("hello")</span><br |
| style="font-family: monospace;"> |
| <span style="font-family: monospace;">class C { }</span><br> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <br> |
| However the above code will produce a warning. To properly use |
| this syntax you must declare the names of any "implicit" annotation |
| keys using the EmfaticAnnotationMap. The EmfaticAnnotationMap was |
| introduced for Emfatic 0.0.1 as a way to replace long source URIs with |
| short labels in Emfatic code. Now the form of |
| EmfaticAnnotationMap usage has been modified slightly to allow implicit |
| key names to be defined as well. The example below shows how to |
| create a label called "ann" with an implicit key named "key" mapped to |
| the source URI "http://ann-uri".<span style="font-family: monospace;"></span><br> |
| <br> |
| <table |
| style="background-color: rgb(204, 204, 255); width: 100%; text-align: left;" |
| border="1" cellpadding="2" cellspacing="2"> |
| <tbody> |
| <tr> |
| <td style="vertical-align: top;"><span |
| style="font-family: monospace;">@EmfaticAnnotationMap("ann(key)"="http://ann-uri")</span><br |
| style="font-family: monospace;"> |
| <span style="font-family: monospace;">package p;</span><br |
| style="font-family: monospace;"> |
| <br style="font-family: monospace;"> |
| <span style="font-family: monospace;">@ann("hello") // like |
| saying @ann(key="hello")</span><br style="font-family: monospace;"> |
| <span style="font-family: monospace;">class C { }</span><br> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <br> |
| Below is another example that shows how model documentation annotations |
| can be simplified by using this style of annotation syntax.<br> |
| <br> |
| <table |
| style="background-color: rgb(204, 204, 255); width: 100%; text-align: left;" |
| border="1" cellpadding="2" cellspacing="2"> |
| <tbody> |
| <tr> |
| <td style="vertical-align: top;"><span |
| style="font-family: monospace;">@EmfaticAnnotationMap("doc(documentation)"="http://www.eclipse.org/emf/2002/GenModel")</span><br |
| style="font-family: monospace;"> |
| <span style="font-family: monospace;">package p;</span><br |
| style="font-family: monospace;"> |
| <br style="font-family: monospace;"> |
| <span style="font-family: monospace;">@doc("my model |
| documentation")</span><br style="font-family: monospace;"> |
| <span style="font-family: monospace;">class C { }</span><br> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <br> |
| Here is a final example showing how more than one implicit annotation |
| key can be defined:<br> |
| <br> |
| <table |
| style="background-color: rgb(204, 204, 255); width: 100%; text-align: left;" |
| border="1" cellpadding="2" cellspacing="2"> |
| <tbody> |
| <tr> |
| <td style="vertical-align: top;"><span |
| style="font-family: monospace;">@EmfaticAnnotationMap("ann(key)"="http://ann-URI")</span><br |
| style="font-family: monospace;"> |
| <span style="font-family: monospace;">@EmfaticAnnotationMap("ann(a,b)"="http://ann-URI")</span><br |
| style="font-family: monospace;"> |
| <span style="font-family: monospace;">package p;</span><br |
| style="font-family: monospace;"> |
| <br style="font-family: monospace;"> |
| <span style="font-family: monospace;">@ann("hello")</span><br |
| style="font-family: monospace;"> |
| <span style="font-family: monospace;">@ann("X", "Y")</span><br |
| style="font-family: monospace;"> |
| <span style="font-family: monospace;">class C { }</span><br> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <br> |
| <br> |
| <br> |
| <h3>2. Fix for Serializable Datatypes</h3> |
| <br> |
| The following example shows how the <span |
| style="font-family: monospace;">transient</span> modifier can be used |
| to change the value of the <span style="font-weight: bold;">EDataType</span> |
| <span style="font-weight: bold;">serializable</span> attribute from the |
| default of true to false.<br> |
| <br> |
| <table |
| style="background-color: rgb(204, 204, 255); width: 100%; text-align: left;" |
| border="1" cellpadding="2" cellspacing="2"> |
| <tbody> |
| <tr> |
| <td style="vertical-align: top;"><span |
| style="font-family: monospace;">package p;</span><br |
| style="font-family: monospace;"> |
| <br style="font-family: monospace;"> |
| <span style="font-family: monospace;">datatype d1 : x;</span><br |
| style="font-family: monospace;"> |
| <span style="font-family: monospace;">transient datatype d2 : x;</span><br> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <br> |
| <br> |
| In the 0.0.1 release, the default for <span style="font-weight: bold;">serializable</span> |
| and the meaning of <span style="font-family: monospace;">transient</span> |
| were both incorrect. This has been fix for the 0.0.2 release.<br> |
| <br> |
| </body> |
| |
| </html> |
