JET Tutorial Part 1 (Introduction to JET)

Summary

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.

The Eclipse Modeling Framework (EMF) 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.

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.

Contributed by Remko Popma, Azzurri Ltd., remko.popma at azzurri dot jp, July 30, 2003. Used with permission. Last update: May 31, 2004.

Getting Started

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 2.0.0 Integration Build I200405200923.

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 .javajet implies that the template generates a .java file, .xmljet templates generate XML, templates that generate SQL have the .sqljet extension, and so on.

JET Nature and JET Builder

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:

1. Create a new Java project and give it a "src" source folder
2. Add the JET Nature to the project. This will create a folder called "templates" under the project root
3. Change the JET properties of the project to ensure that templates are translated into the "src" source folder of the project
4. Create a new file called "helloworld.txtjet" and save it in the templates folder

Step 1. Create a Project

Step 2. Convert the Project to a JET Project

After creating the project, right-click on it in the Package Explorer or Hierarchy view and select New > Other... > Java Emitter Templates > Convert Projects to JET Projects. After pressing the Next button, select the project you've created and click Finish.

The wizard adds the JET Nature to the project creating a templates 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.

Step 3. Change JET Settings

Before creating our first template, let's make sure that the src 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.

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.

Step 4. Create a JET Template File

The JET builder will now translate all templates to Java source files in the src 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 templates directory as the parent folder, and call the file helloworld.txtjet. 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.

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 Close to close the error dialog. Open the helloworld.txtjet file if it is not opened and type or cut-and-paste the following contents in the editor.

 <%@ jet package="hello" class="HelloWorldTemplate" %>

 Hello, world!

When you save the template file, it will automatically be translated by the JET Builder. Because we specified package hello and class HelloWorldTemplate in the first line of the template, the builder creates a hello package in the src folder and saves a Java file HelloWorldTemplate.java in this package, as shown in the image below.

This Java class is the result of translating the template and is called a template implementation class. This class has a method called generate. This is the method that generates the code indicated in the template.

We can create an instance of the HelloWorldTemplate template implementation class and invoke its generate method like this:

 HelloWorldTemplate helloworld = new HelloWorldTemplate();
 String result = helloworld.generate(null);
 System.out.println(result);

The code above will print the words "Hello, world!" to the console. Yay!

Passing Arguments to the Template

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.

Add a new JET template file or change the existing one to the following content:

 <%@ jet package="hello" class="GreetingTemplate" %>
 Hello, <%=argument%>!

The JET Builder will translate this template to a class GreetingTemplate in the hello package. Again we create an instance of this template class, but this time we pass a string argument to the generate method:

 GreetingTemplate sayHello = new GreetingTemplate();
 String result = sayHello.generate("Tutorial Reader");
 System.out.println(result);

The code above will print the words "Hello, Tutorial Reader!" to the console.

Importing Packages

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 java.lang package, or if your template uses any other classes not in the java.lang package, you need to import these classes in the template jet directive. A jet directive with an

imports attribute looks like this:

 <%@ jet package="hello" 
imports="java.util.*" class="ImportDemoTemplate" %>

   <%@ jet package="hello" 
imports="java.util.*" class="XMLDemoTemplate" %>


<% List elementList = (List) argument; %>
   <?xml version="1.0" encoding="UTF-8"?>
   <demo>
   <% for (Iterator i = elementList.iterator(); i.hasNext(); ) { %>

     <element><%=i.next().toString()%></element>
   <% } %>
   </demo>

List data = new ArrayList();
   data.add("first");
   data.add("second");
   data.add("third");
 
   XMLDemoTemplate generateXml = new XMLDemoTemplate();
   String result = generateXml.generate(
data);
   System.out.println(result);

 <?xml version="1.0" encoding="UTF-8"?>

 <demo>
   <element>first</element>
   <element>second</element>
   <element>third</element>

 </demo>

 <%@ jet package="tags.demo" class="JspTemplate" 
startTag="<$" 
endTag="$>" %>

 <$ String paramName = (String) argument; /* This is an executed scriptlet */ $>
 <$ if (paramName != null) { $>
 
  <%= request.getParameter("<$=paramName$>") %> <!-- this is generated JSP -->

 <$ } $>

 System.out.println(new tags.demo.JspTemplate().generate("button"));

 
  <%= request.getParameter("button") %> <!-- this is generated JSP -->

 <%@ jet package="hello" class="TranslationDemoTemplate" %>


 Hello, <%=argument%>!

 <% stringBuffer.append("Hello again!"); %>

 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 argument)
   {
     StringBuffer stringBuffer = new StringBuffer();
     stringBuffer.append(TEXT_1);

  stringBuffer.append(argument);
     stringBuffer.append(TEXT_2);


  stringBuffer.append("Hello again!");
     return stringBuffer.toString();
   }
 }

 public class CLASS
 {
   public String generate(Object argument)
   {
     return "";
   }
 }

 public interface IGenerator {
     String generate(Object argument);
 }

 public class CLASS 
implements IGenerator
 {

/* (non-javadoc)
    * @see IGenerator#generate(Object)
    */

public String generate(Object argument)
   {
     return "";
   }
 }

 <%@ jet package="hello" class="GreetingTemplate" skeleton="generator.skeleton" %>
 Hello, <%=argument%>!
 The current time is <%=new java.util.Date()%>.

 package hello;
 
 public class GreetingTemplate 
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;
 


/* (non-javadoc)
    * @see IGenerator#generate(Object)
    */

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();
   }
 }

 <%@ jet package="hello" class="HelloWorldTemplate" imports="java.io.* java.util.*" %>

 <%@ include file="copyright.jet" %>

 <% this is a scriptlet %>
 <%= this is an expression %>

 <% if (Calendar.getInstance().get(Calendar.AM_PM) == Calendar.AM) {%>
 Good Morning
 <% } else { %>
 Good Afternoon
 <% } %>

<%= (new java.util.Date()).toLocaleString() %>