| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> | |
| <title>JET Tutorial Part 1</title> | |
| <link rel="stylesheet" href="default_style.css"> | |
| </head> | |
| <body link="#0000ff" vlink="#800080" bgcolor="#FFFFFF"> | |
| <div align="right"> <font face="Times New Roman, Times, serif" size="2">Copyright | |
| © 2003 <a href="http://www.azzurri.jp">Azzurri Ltd.</a></font> | |
| <table border=0 cellspacing=0 cellpadding=2 width="100%"> | |
| <tr> | |
| <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF"> Eclipse | |
| Corner Article</font></font></b></td> | |
| </tr> | |
| </table> | |
| </div> | |
| <div align="left"> | |
| <h1><img src="images/Idea.jpg" height=86 width=120 align=CENTER></h1> | |
| </div> | |
| <h1 align="CENTER">JET Tutorial Part 1 (Introduction to JET) </h1> | |
| <blockquote> <b>Summary</b> <br> | |
| Generating source code can save you time in your projects and can reduce the | |
| amount of tedious redundant programming. Generating source code can be powerful, | |
| but the program that writes the code can quickly become very complex and hard | |
| to understand. One way to reduce complexity and increase readability is to use | |
| templates. | |
| <p> The Eclipse Modeling Framework (<a href="http://eclipse.org/emf/" target="_blank">EMF</a>) | |
| project contains two very powerful tools for generating source code: JET (Java | |
| Emitter Templates) and JMerge (Java Merge). With JET you can use a JSP-like | |
| syntax (actually a subset of the JSP syntax) that makes it easy to write templates | |
| that express the code you want to generate. JET is a generic template engine | |
| that can be used to generate SQL, XML, Java source code and other output from | |
| templates. It is located in the org.eclipse.emf.codegen plug-in as part of | |
| the EMF runtime download. </p> | |
| <p> | |
| In this article you will learn how to create JET templates, how to use the JET | |
| Nature and JET Builder to automatically translate templates into Java classes, | |
| and how to use these classes to generate source code. This article also provides | |
| a short reference to the JET syntax. | |
| </p> | |
| <p><b>By Remko Popma, Azzurri Ltd., remko.popma@azzurri.jp</b><br> | |
| <font size="-1">July 30, 2003</font></p> | |
| </blockquote> | |
| <hr width="100%"> | |
| <h2>Getting Started</h2> | |
| <p>Before creating our first template, you'll need the EMF plug-in. If you haven't | |
| installed it yet, install it now before continuing with this tutorial. I am | |
| using EMF version 1.1.0 Build 20030513_0618VL. </p> | |
| <p>A JET template is a text file with a file name that ends with "jet". | |
| I will follow the EMF convention of appending "jet" to whatever the | |
| file extension of the generated code would be, so <i>.javajet</i> implies that | |
| the template generates a .java file, <i>.xmljet</i> templates generate XML, | |
| templates that generate SQL have the <i>.sqljet</i> extension, and so on.</p> | |
| <h3> JET Nature and JET Builder </h3> | |
| <p> | |
| Let's follow tradition and start with a template that creates the message "Hello, | |
| world". We will create our first template using the following four step process: </p> | |
| <ol> | |
| <li> Create a new Java project and give it a "<i>src</i>" source folder</li> | |
| <li> Add the JET Nature to the project. This will create a folder called "<i>templates</i>" | |
| under the project root</li> | |
| <li> Change the JET properties of the project to ensure that templates are translated | |
| into the "<i>src</i>" source folder of the project</li> | |
| <li> Create a new file called "<i>helloworld.txtjet</i>" and save | |
| it in the <i>templates</i> folder</li> | |
| </ol> | |
| <h4> Step 1. Create a Project </h4> | |
| From the workbench menu, select File > New > Project to bring up the New | |
| Project wizard. Create a new Java project and add a source folder to it named | |
| <i>src</i>. | |
| <h4> Step 2. Add JET Nature </h4> | |
| <p>After creating the project, right-click on it in the Package Explorer or Hierarchy | |
| view and select "Add JET Nature" from the popup menu as shown in the | |
| image below. </p> | |
| <img src="images/addJetNaturePopup.gif" width="186" height="438"> | |
| <p> Adding the JET Nature to the project will create a <i>templates</i> folder | |
| under the project root as shown in the image below. Also, a JET Builder is added | |
| to the project that will automatically translate every file in the templates | |
| folder with a file name ending in "jet" to a Java class. </p> | |
| <p> <img src="images/newproject.gif" width="166" height="113" border="1"> | |
| <h4> Step 3. Change JET Settings </h4> | |
| <p> Before creating our first template, let's make sure that the <i>src</i> source | |
| folder of the project is the destination folder of the translated templates. | |
| Right-click on the project and select "Properties" from the popup | |
| menu. In the Project Properties dialog, select JET Settings on the left-hand | |
| menu and enter "src" (the name of your source folder) in the "Source | |
| Container" text field. The image below shows the JET Settings properties | |
| page of the Project Properties dialog. </p> | |
| <p> | |
| <img src="images/projectProperties.gif" width="426" height="284"> | |
| </p> | |
| <p> <i><img src="images/tip.gif" width="62" height="13">Note: you can specify | |
| multiple folders in the Template Containers field, separated by a space or a | |
| semicolon. However, if templates in different folders have the same filename, | |
| only the template in the first folder will be translated automatically by the | |
| JET Builder. If you want all templates to be translated, make sure they have | |
| different file names.</i> | |
| <h4> Step 4. Create a JET Template File </h4> | |
| <p> The JET builder will now translate all templates to Java source files in the | |
| <i>src</i> folder of the project. Now we create our first template. From the | |
| workbench menu, select File > New > File to bring up the New File wizard. | |
| Select the <i>templates</i> directory as the parent folder, and call the file | |
| <i>helloworld.txtjet</i>. You will get the following error when you press the | |
| OK button: "The jet directive is missing in 'helloworld.txtjet' at line | |
| 1 column 1", as shown in the image below. </p> | |
| <p> | |
| <img src="images/missing_jet_directive.gif" width="443" height="268"> | |
| </p> | |
| <p> Fortunately, this does not mean that there is a real problem, just that the | |
| JET Builder tried to translate our template as soon as we created it, and discovered | |
| that it is still empty. Press OK to close the error dialog and Cancel to close | |
| the wizard dialog. Open the <i>helloworld.txtjet</i> file and type or cut-and-paste | |
| the following contents in the editor. </p> | |
| <pre> | |
| <span class="jet"><%@ jet package="hello" class="HelloWorldTemplate" %></span> | |
| Hello, world!</pre> | |
| <p> When you save the template file, it will automatically be translated by the | |
| JET Builder. Because we specified package <i>hello</i> and class <i>HelloWorldTemplate</i> | |
| in the first line of the template, the builder creates a <i>hello</i> package | |
| in the <i>src</i> folder and saves a Java file <i>HelloWorldTemplate.java</i> | |
| in this package, as shown in the image below.</p> | |
| <p> <img src="images/compiledTemplate.gif" width="234" height="161" border="1"> | |
| </p> | |
| <p> This Java class is the result of translating the template and is called a | |
| <i>template implementation class</i>. This class has a method called <tt>generate</tt>. | |
| This is the method that generates the code indicated in the template.</p> | |
| <p><img src="images/tryit.gif" width="61" height="13">We can create an instance | |
| of the <tt>HelloWorldTemplate</tt> template implementation class and invoke | |
| its <tt>generate</tt> method like this: </p> | |
| <pre> HelloWorldTemplate helloworld = new HelloWorldTemplate(); | |
| String result = helloworld.generate(null); | |
| System.out.println(result); | |
| </pre> | |
| <p> The code above will print the words "Hello, world!" to the console. | |
| Yay!</p> | |
| <h3> Passing Arguments to the Template </h3> | |
| <p>To recap, we just created our first template and generated some code with it. | |
| The result may not have been very impressive, but now we are all set up and | |
| we can start to explore what JET can do for you. The next step is to pass an | |
| argument to the template. </p> | |
| <p><img src="images/tryit.gif" width="61" height="13">Add a new JET template file | |
| or change the existing one to the following content: </p> | |
| <pre> | |
| <span class="jet"><%@ jet package="hello" class="GreetingTemplate" %></span> | |
| Hello, <span class="jet"><%=argument%></span>! | |
| </pre> | |
| <p> The JET Builder will translate this template to a class <tt>GreetingTemplate</tt> | |
| in the <tt>hello</tt> package. Again we create an instance of this template | |
| class, but this time we pass a string argument to the <tt>generate</tt> method: | |
| </p> | |
| <pre> GreetingTemplate sayHello = new GreetingTemplate(); | |
| String result = sayHello.generate("Tutorial Reader"); | |
| System.out.println(result); | |
| </pre> | |
| <p> | |
| The code above will print the words "Hello, Tutorial Reader!" to the | |
| console. | |
| </p> | |
| <h3> Importing Packages </h3> | |
| <p>The argument you pass to a template can be any object. In the previous example | |
| we passed a string as the argument to the generate method, but in your application | |
| you probably want to pass in your own model object. If the argument is not in | |
| the <tt>java.lang</tt> package, or if your template uses any other classes not | |
| in the <tt>java.lang</tt> package, you need to import these classes in the template | |
| <tt>jet</tt> directive. A <tt>jet</tt> directive with an <img src="images/tag_1.gif" width="24" height="13"><i>imports</i> | |
| attribute looks like this: </p> | |
| <pre> | |
| <%@ jet package="hello" <b><img src="images/tag_1.gif" width="24" height="13">imports="java.util.*"</b> class="ImportDemoTemplate" %> | |
| </pre> | |
| <p> The JET Syntax Reference section of this article gives more details on the | |
| <tt>jet</tt> directive and its attributes.</p> | |
| <p> In the next example we will create a template that generates XML code. To | |
| stick to the EMF convention of appending "jet" to whatever the file | |
| extension of the generated code would be, we will save this template to a file | |
| called <i>importdemo.xmljet</i>. Note that we pass the template a <tt>java.util.List</tt> | |
| object that contains the data to use when generating the XML.</p> | |
| <pre> | |
| <span class="jet"><%@ jet package="hello" <img src="images/tag_1.gif" width="24" height="13"><b>imports="java.util.*"</b> class="XMLDemoTemplate" %></span> | |
| <img src="images/tag_2.gif" width="24" height="13"><b class="jet"><% List elementList = (List) argument; %></b> | |
| <b> </b><?xml version="1.0" encoding="UTF-8"?> | |
| <b> </b><demo> | |
| <span class="jet"><% for (Iterator i = elementList.iterator(); i.hasNext(); ) { %></span> | |
| <element><span class="jet"><%=i.next().toString()%></span></element> | |
| <span class="jet"><% } %></span> | |
| <b> </b></demo> | |
| </pre> | |
| <p> The code below shows how to invoke the template instance. We create a <img src="images/tag_2.gif" width="24" height="13">list | |
| and <img src="images/tag_3.gif" width="24" height="13">pass it to the <tt>generate</tt> | |
| method of the template implementation class:</p> | |
| <pre><img src="images/tag_2.gif" width="24" height="13">List data = new ArrayList(); | |
| data.add("first"); | |
| data.add("second"); | |
| data.add("third"); | |
| XMLDemoTemplate generateXml = new XMLDemoTemplate(); | |
| String result = generateXml.generate(<img src="images/tag_3.gif" width="24" height="13">data); | |
| System.out.println(result); | |
| </pre> | |
| <p> | |
| This prints the following XML result to the console: | |
| </p> | |
| <pre> | |
| <?xml version="1.0" encoding="UTF-8"?> | |
| <demo> | |
| <element>first</element> | |
| <element>second</element> | |
| <element>third</element> | |
| </demo> | |
| </pre> | |
| <p> This is a very simple example that creates very simple XML. Of course you | |
| can use JET to create more complex XML, using attributes and namespaces. When | |
| you do this, you may find it more convenient to create a special class that | |
| is a better model of an XML document than a <tt>java.util.List</tt>. Generally, | |
| the more complex your JET template becomes, the more logic you will want to | |
| push into the model object that you pass to the template, to keep your templates | |
| readable. We will explore this further in Part 2 of this tutorial. </p> | |
| <h3> Changing Tags </h3> | |
| <p>A neat feature of JET is that you can change the tags that mark scriptlets | |
| in the template file. This is very convenient when the syntax of the code you | |
| generate is very similar to the default JET syntax, for example if you use JET | |
| to generate JSP pages. </p> | |
| <p>In the next example we will use JET to generate a simple JSP page. We will | |
| change the JET tags to use the "<$" character sequence to start | |
| a template tag, and "$>" to end a template tag. The template still | |
| contains "<%" and "%>" strings, but the JET engine | |
| will not see them as special anymore, and they will be written to the result | |
| like any other character sequence.</p> | |
| <p></p> | |
| <p> <img src="images/tryit.gif" width="61" height="13">To change the tag markers, | |
| add a <i><img src="images/tag_1.gif" width="24" height="13">startTag</i> and | |
| an <i><img src="images/tag_2.gif" width="24" height="13">endTag</i> attribute | |
| to the JET directive on the first line of the template, like in the example | |
| below. </p> | |
| <pre> | |
| <span class="jet"><%@ jet package="tags.demo" class="JspTemplate" <img src="images/tag_1.gif" width="24" height="13"><b>startTag="<$" <img src="images/tag_2.gif" width="24" height="13">endTag="$>"</b> %></span> | |
| <b><span class="jet"><$</span></b><span class="jet"> String paramName = (String) argument; /* This is an executed scriptlet */ <b>$></b></span> | |
| <b><span class="jet"><$</span></b><span class="jet"> if (paramName != null) { <b>$></b></span> | |
| <img src="images/tag_3.gif" width="24" height="13"> <%= request.getParameter("<b><span class="jet"><$=</span></b><span class="jet">paramName<b>$></b></span>") %> <!-- this is generated JSP --> | |
| <b><span class="jet"><$</span></b><span class="jet"> } <b>$></b></span> | |
| </pre> | |
| <p> Again, we invoke this implementation class with a string argument, like below: | |
| </p> | |
| <pre> System.out.println(new tags.demo.JspTemplate().generate("button")); | |
| </pre> | |
| The following output will appear on the console. Note that the output contains | |
| the intact JSP tag: the "<%" and "%>" character strings | |
| are not interpreted as a JET scriptlet, but are simply inserted in the generated | |
| code. | |
| <pre> | |
| <img src="images/tag_3.gif" width="24" height="13"> <%= request.getParameter("button") %> <!-- this is generated JSP --> | |
| </pre> | |
| <h1> Under the Hood </h1> | |
| <p>In the previous section we have looked at creating JET templates, how to set up | |
| the JET Nature to automatically translate templates into Java implementation classes, | |
| and how to use these Java implementation classes to generate code. | |
| </p> | |
| <p> In this section we will take a closer look at the Java implementation classes | |
| that are the result of translating a template. We will see why we can use the | |
| implicit objects <tt>argument</tt> and <tt>stringBuffer</tt> in a template, | |
| and also look at customizing the translated implementation class by providing | |
| a custom "skeleton". </p> | |
| <h3> Translated Templates </h3> | |
| <p>A JET template is translated to a Java implementation class. There are some | |
| objects in the Java implementation class that can be referenced directly in | |
| the JET template. The following example demonstrates how the implicit objects | |
| <tt>argument</tt> and <tt>stringBuffer</tt> can be used in a template.</p> | |
| <pre> | |
| <span class="jet"><%@ jet package="hello" class="TranslationDemoTemplate" %></span> | |
| <img src="images/tag_1.gif" width="24" height="13"> Hello, <span class="jet"><%=<b>argument</b>%></span>! | |
| <img src="images/tag_2.gif" width="24" height="13"> <span class="jet"><% <b>stringBuffer.append("Hello again!");</b> %></span> | |
| </pre> | |
| <p> The template above is translated to a Java implementation class like below: | |
| </p> | |
| <pre> | |
| package hello; | |
| public class TranslationDemoTemplate | |
| { | |
| protected final String NL = System.getProperties().getProperty("line.separator"); | |
| protected final String TEXT_1 = "Hello, "; | |
| protected final String TEXT_2 = "!"; | |
| public String generate(Object <b>argument</b>) | |
| { | |
| StringBuffer <b>stringBuffer</b> = new StringBuffer(); | |
| stringBuffer.append(TEXT_1); | |
| <img src="images/tag_1.gif" width="24" height="13"> stringBuffer.append(<b>argument</b>); | |
| stringBuffer.append(TEXT_2); | |
| <img src="images/tag_2.gif" width="24" height="13"> <b>stringBuffer.append("Hello again!");</b> | |
| return stringBuffer.toString(); | |
| } | |
| } | |
| </pre> | |
| <p> Notice that the <tt>generate</tt> method of the Java implementation class | |
| takes an <tt>Object</tt> parameter called <tt>argument</tt>. This is the same | |
| object as the <tt><img src="images/tag_1.gif" width="24" height="13">argument</tt> | |
| in the second line of the template. Also, notice how the Java implementation | |
| class uses a <tt>StringBuffer</tt> object to collect the resulting generated | |
| code. This object can be <img src="images/tag_2.gif" width="24" height="13">referenced | |
| directly in the template by its name <tt>stringBuffer</tt>. </p> | |
| <h3> Changing the Skeleton of the Translated Implementation Class </h3> | |
| <p>The <tt>generate</tt> method of the <tt>TranslationDemoTemplate</tt> class | |
| above is said to be part of the implementation class "skeleton". The | |
| default skeleton used by the JET engine looks like this: </p> | |
| <pre> | |
| public class CLASS | |
| { | |
| public String generate(Object argument) | |
| { | |
| return ""; | |
| } | |
| } | |
| </pre> | |
| <p> The skeleton definition looks almost like a normal Java class, except for | |
| the class name. The class name (<tt>CLASS</tt>) will be replaced by the value | |
| of the <i>class</i> attribute in the <tt>jet</tt> directive. Furthermore, the skeleton | |
| definition has the <tt>generate</tt> method that we have seen earlier. By changing | |
| the skeleton you can customize a template implementation class, for example | |
| make it implement an interface, or change any other feature of the class.</p> | |
| <p> <img src="images/tryit.gif" width="61" height="13">For example, suppose you | |
| want all your template implementation classes to implement an interface. The | |
| interface could look something like this: </p> | |
| <pre> | |
| public interface IGenerator { | |
| String generate(Object argument); | |
| }</pre> | |
| <p>We can tell the JET engine that we want to use a custom skeleton by setting | |
| the <i>skeleton</i> attribute of the <tt>jet</tt> directive on the first line of the | |
| template file. The value of the skeleton attribute is a URI that points to a | |
| file where the custom skeleton definition can be found. </p> | |
| <p>To try this, first create a new file <i>generator.skeleton</i> in the templates | |
| directory, as in the image below.</p> | |
| <p><img src="images/generator_skeleton.gif" width="251" height="321" border="1"></p> | |
| <p>Open the <i>generator.skeleton</i> file in a text editor and type or cut-and-paste | |
| the following content in it: </p> | |
| <pre> | |
| public class CLASS <img src="images/tag_1.gif" width="24" height="13">implements IGenerator | |
| { | |
| <img src="images/tag_2.gif" width="24" height="13">/* (non-javadoc) | |
| * @see IGenerator#generate(Object) | |
| */ | |
| <img src="images/tag_3.gif" width="24" height="13">public String generate(Object argument) | |
| { | |
| return ""; | |
| } | |
| } | |
| </pre> | |
| <p> This file is our custom skeleton. All templates that use this skeleton will | |
| be translated to classes that implement the <tt>IGenerator</tt> interface. To | |
| use this skeleton, add an attribute <i>skeleton</i> to the <tt>jet</tt> directive of | |
| your template, like this: </p> | |
| <pre> | |
| <span class="jet"><%@ jet package="hello" class="GreetingTemplate" <b>skeleton="generator.skeleton"</b> %></span> | |
| Hello, <span class="jet"><%=argument%></span>! | |
| The current time is <span class="jet"><%=new java.util.Date()%></span>. | |
| </pre> | |
| <p> | |
| After the JET Builder translates the template, the implementation class looks | |
| like this: | |
| </p> | |
| <pre><font color="#4444cc"> | |
| </font> package hello; | |
| public class GreetingTemplate <img src="images/tag_1.gif" width="24" height="13">implements IGenerator | |
| { | |
| protected final String NL = System.getProperties().getProperty("line.separator"); | |
| protected final String TEXT_1 = "Hello, "; | |
| protected final String TEXT_2 = "!" + NL + "The current time is "; | |
| protected final String TEXT_3 = "."; | |
| protected final String TEXT_4 = NL; | |
| <img src="images/tag_2.gif" width="24" height="13">/* (non-javadoc) | |
| * @see IGenerator#generate(Object) | |
| */ | |
| <img src="images/tag_3.gif" width="24" height="13">public String generate(Object argument) | |
| { | |
| StringBuffer stringBuffer = new StringBuffer(); | |
| stringBuffer.append(TEXT_1); | |
| stringBuffer.append(argument); | |
| stringBuffer.append(TEXT_2); | |
| stringBuffer.append(new java.util.Date()); | |
| stringBuffer.append(TEXT_3); | |
| stringBuffer.append(TEXT_4); | |
| return stringBuffer.toString(); | |
| } | |
| } | |
| </pre> | |
| <p>Note that the translated template now <img src="images/tag_1.gif" width="24" height="13">implements | |
| the <tt>IGenerator</tt> interface, and the <tt><img src="images/tag_3.gif" width="24" height="13">generate</tt> | |
| method now has <img src="images/tag_2.gif" width="24" height="13">the comments | |
| we specified in the <i>generator.skeleton</i> file. This is one example of how | |
| to customize a translated template with a skeleton definition. Skeleton definitions | |
| can also contain extra methods, inner classes, etc. You'll need to experiment | |
| a little to see what else is possible.</p> | |
| <h1> JET Syntax Reference </h1> | |
| <p>If you have used JSP technology before, the JET syntax will probably look very | |
| familiar to you. The JET syntax is a subset of the JSP syntax, so there may | |
| not be much new here for you.</p> | |
| <p>This section provides a semi-formal description and reference of the JET syntax. | |
| </p> | |
| <h2> The JET Model</h2> | |
| <p>A JET template is translated into a Java implementation class. This implementation | |
| class has a method that can be called to obtain a result string. This method | |
| is usually called <tt>generate</tt> (see also the <i>skeleton</i> attribute | |
| of the <tt>jet</tt> directive). </p> | |
| <p> If no <i>skeleton</i> attribute is specified in the <tt>jet</tt> directive, the Java | |
| implementation class has the following implicit objects, which can be referenced | |
| in the JET template: </p> | |
| <ul> | |
| <li> <b>stringBuffer</b> the <tt>java.lang.StringBuffer</tt> object | |
| used to build the result string when the <tt>generate</tt> method is invoked</li> | |
| <li> <b>argument</b> the <tt>java.lang.Object</tt> passed to the <tt>generate</tt> | |
| method</li> | |
| </ul> | |
| <h2> Directives </h2> | |
| <p>Directives are messages to the JET engine. Directives have this syntax: | |
| </p><p> | |
| <i><%@ directive { attr="value" }* %></i> | |
| </p><p> | |
| There may be optional white space after the "<%@" and before "%>". | |
| </p><p> | |
| Directives affect how a template is translated, but do not produce any output | |
| in the generated String when the template is invoked. | |
| </p> | |
| <h3> Jet Directive </h3> | |
| <p>The <tt>jet</tt> directive defines a number of attributes and communicates | |
| these to the JET engine. A JET template file must contain a <tt>jet</tt> directive | |
| on the first line of the file, or the template file cannot be translated. Any | |
| subsequent <tt>jet</tt> directives are ignored. Unrecognized attributes result | |
| in fatal translation errors. </p> | |
| <p> The following directive indicates that the template should be translated to | |
| a Java implementation class called <i>HelloWorldTemplate.java</i> in package | |
| <i>hello</i>. The implementation class should import the java.io.* and java.util.* | |
| packages. </p> | |
| <pre> | |
| <%@ jet package="hello" class="HelloWorldTemplate" imports="java.io.* java.util.*" %></pre> | |
| <p>The details of the attributes for the <tt>jet</tt> directive are as follows: | |
| </p> | |
| <table border="1" cellpadding="3" cellspacing="0"> | |
| <tr> | |
| <td><b>Attribute</b></td> | |
| <td><b>Value</b></td> | |
| </tr> | |
| <tr> | |
| <td valign="top">package</td> | |
| <td>The package name of the Java implementation class that the template is | |
| translated to. If this attribute is not present, the Java implementation | |
| class is created in the default package.</td> | |
| </tr> | |
| <tr> | |
| <td height="40" valign="top">class</td> | |
| <td height="40">The class name of the Java implementation class that the template | |
| is translated to. If not present, the Java implementation class is called | |
| <tt>CLASS</tt>.</td> | |
| </tr> | |
| <tr> | |
| <td valign="top">imports</td> | |
| <td>A space-separated list of packages and/or classes to import in the Java | |
| template class</td> | |
| </tr> | |
| <tr> | |
| <td valign="top">startTag</td> | |
| <td>The string in a JET template that signals the beginning of a scriptlet, | |
| expression, or <tt>include</tt> directive. The default is "<%". | |
| This attribute, and its cousin <i>endTag</i> can be very convenient when | |
| the syntax of the generated code is similar to the default JET syntax, for | |
| example if you use JET to generate JSP pages.</td> | |
| </tr> | |
| <tr> | |
| <td valign="top">endTag</td> | |
| <td>The string in a JET template that signals the end of a scriptlet, expression, | |
| or <tt>include</tt> directive. The default is "%>". See also | |
| <i>startTag</i>.</td> | |
| </tr> | |
| <tr> | |
| <td valign="top">skeleton</td> | |
| <td>The URI of a file with a skeleton definition of the Java implementation | |
| class that the template is translated to. This URI will be resolved similar | |
| to the way the <i>file</i> attribute value is resolved in an <tt>include</tt> | |
| directive. If no skeleton definition file is specified, the JET engine will | |
| use a default skeleton of the form "<tt>public class CLASS\n{\n public | |
| String generate(Object argument)\n {\n return \"\";\n }\n}\n</tt>". | |
| The class name in this skeleton class definition must be <tt>CLASS</tt>.</td> | |
| </tr> | |
| <tr> | |
| <td valign="top">nlString</td> | |
| <td>The newline string to use in the Java template class. The default is "System.getProperties().getProperty(\"line.separator\")"</td> | |
| </tr> | |
| </table> | |
| <h3> Include Directive </h3> | |
| <p>The <tt>include</tt> directive is used to substitute text and/or code at template | |
| translation-time. The <tt><%@ include file="urlSpec" %></tt> | |
| directive inserts the text of the specified resource into the jet template file. | |
| The included file may have JET scripting elements which will also be processed. | |
| </p> | |
| <p> This directive has one single attribute, <i>file</i>. The value of this attribute | |
| is the URI of the location of the file to include. This URI can be either an | |
| absolute path or a relative path. Relative URIs are always interpreted as relative | |
| to the folder of the template that contains the include directive.</p> | |
| <p>Example:</p> | |
| <p> The following example requests the inclusion, at translation time, of a copyright | |
| file. </p> | |
| <pre> | |
| <%@ include file="copyright.jet" %> | |
| </pre> | |
| <p><i><img src="images/tip.gif" width="62" height="13">Note: JET supports the | |
| notion of overriding template paths. It is possible to configure the JET engine | |
| to use multiple Template Containers. In that case, the first container takes | |
| precedence over the second, the second over the third, and so on. This means | |
| that if template files or include files with the same file name exist in multiple | |
| Template Containers, the file in the first folder will be used, and the other(s) | |
| will be ignored. Clients of a JET-based application can use this mechanism to | |
| provide custom include files that override the original include files without | |
| modifying the templates of the original application.</i><br> | |
| </p> | |
| <h2>JET Scripting Elements </h2> | |
| <p>JET has two scripting language elements: scriptlets and expressions. A scriptlet | |
| is a statement fragment, and an expression is a complete Java expression. | |
| </p><p> | |
| Each scripting element has a "<%"-based syntax as follows: </p> | |
| <pre> | |
| <% this is a scriptlet %> | |
| <%= this is an expression %> | |
| </pre> | |
| <p>White space is optional after "<%", and "<%=", and before | |
| "%>". | |
| </p><p> | |
| If you want to use the %> character sequence as literal characters in a scriptlet, | |
| rather than to end the scriptlet, you can escape them by typing %\>. Similarly, | |
| the <% character sequence can be escaped by using <\%. | |
| </p> | |
| <h3> Scriptlets </h3> | |
| <p>Scriptlets can contain any valid Java code fragment. </p> | |
| <p> Scriptlets are executed at template invocation time. Whether or not they produce | |
| any output into the result String depends on the actual code in the scriptlet. | |
| Scriptlets can have side effects, modifying the objects visible in them. </p> | |
| <p> When all scriptlet fragments in a given translation unit are combined in the | |
| order they appear in the JET template, they should yield a valid Java statement | |
| or sequence of statements. </p> | |
| Example: | |
| <pre> | |
| <% if (Calendar.getInstance().get(Calendar.AM_PM) == Calendar.AM) {%> | |
| Good Morning | |
| <% } else { %> | |
| Good Afternoon | |
| <% } %> | |
| </pre> | |
| <p> <b><i>Syntax</i></b> </p> | |
| <p> <i><% scriptlet %></i> </p> | |
| <h3> Expressions </h3> | |
| <p>A JET expression element is a Java expression that is evaluated and the result | |
| is appended to the <tt>StringBuffer</tt> object returned by the <tt>generate</tt> | |
| method. Expressions are evaluated at template invocation time. </p> | |
| <p> If the result of the expression cannot be appended to a <tt>StringBuffer</tt> | |
| then a translation time error occurs. The content of a JET expression must be | |
| a complete Java expression. </p> | |
| <p> Side-effects in expressions are supported. They take effect when the JET expression | |
| is evaluated. JET expressions are evaluated left-to-right in the JET template.</p> | |
| <p>In the next example, the current date is appended to the <tt>StringBuffer</tt> | |
| result.</p> | |
| <pre><%= (new java.util.Date()).toLocaleString() %> </pre> | |
| <p><b><i>Syntax</i></b> </p> | |
| <p><i><%= expression %></i> </p> | |
| <h2>Resources</h2> | |
| <p><a href="http://www.javaworld.com/javaworld/jw-11-2001/jw-1102-codegen.html" target="_blank">http://www.javaworld.com/javaworld/jw-11-2001/jw-1102-codegen.html</a> | |
| </p> | |
| <p> <a href="http://www.eclipse.org/emf/" target="_blank">http://www.eclipse.org/emf/</a> | |
| </p> | |
| <p></p> | |
| </body> | |
| </html> |