#

# JET Comprehensive Overview

> Summary

> Java Emitter Templates, JET, provides an expressive and powerful mechanism for generating arbitrary text files. It's effectively Java turned inside out. To generate a text file with Java, one would express the textual results using string literals, and string-producing logic, embedded in a Java class. To generate a text file with JET, the template itself is the literal while Java logic to control what's generated is embedded in, or invoked from, this template. In the end, a JET template is simply compiled into a Java class, inverting the literals and the Java logic.

> JET is provided by the Eclipse Modeling Framework (EMF) and is used extensively in EMF's code generation framework to implement Java code generation. As of EMF 2.19, a specialized JET editor is provided for editing templates much like how one edits Java files in Eclipse. In fact, the JET editor contains an embedded Java editor to help provide support for content assist, quick assist, refactoring, and formatting. The JET compiler and JET builder have also been significantly enhanced for improved fault tolerance and diagnostic support.

## Contents

Getting Started
Configuring a JET Project
Creating a Root JET Template
Creating an `@jet` Directive
JET Color Preferences
JET Literal Content
Creating a Driver
Creating a Model
Creating a Scriptlet
Creating an Expression
Exploiting the Outline with Tag Comments
Creating a Header Comment
Generating Interesting Results
Creating More Complex Scriptlet Logic
Formatting a Multi-line `@jet` Directive
Creating More Complex Scriptlet and Expression Logic
More Interesting Results
Dealing with Multi-line Content
Exploiting Inclusion for Reuse
Editing Multiple Documents in a Single Editor
Generating Included Results
Specialization Using a Skeleton Class
Using Additional `@jet` Attributes
Fully Exploiting all the Features of the JET Editor
Support and Problem Reporting

## Getting Started

Before creating your first JET template, the appropriate EMF JET plug-ins need to be installed. They are available from EMF's Update Site. You can use Help → Install New Software…, copy and paste the preceding update site link, and search for "EMF Code Generation UI" as follows:

## Configuring a JET Project

In general, a file is recognized as a JET template if its file extension ends with `jet`. It must be a UTF-8 encoding text file. By convention, the file extension of the type of text file being generated can be specified either in the file extension or separately, e.g., `*.html.jet` or `*.htmljet` can be specified to indicate that the template generates HTML results.

To compile your JET templates, you will need to convert a normal Java project to a JET project, to add the JET Nature and associated JET Builder. From the context menu of a Java project in the Package explorer, use New → Other...… as follows:

This brings up New wizard, where you can type `JET` in the search field to find the JET conversion wizard as follows:

When you hit Next, a list of Java projects that don't yet have a JET nature will be presented and the project of the context menu will already be check marked:

When you hit Finish, the Properties dialog for the JET Settings will be displayed as follows:

A `templates` folder will have been created and the Template Containers will refer to that. The Source Container will automatically be the first Java source folder of the Java project. You may wish to create a separate Java source folder for the compiled templates if you wish. All root JET templates in the `templates` folder will automatically be compiled as they are changed. You can bring up this dialog again any time from the context menu of the project via Properties…

## Creating a Root JET Template

Now you are ready to create a JET template using New → File from the context menu of the `templates` folder:

Create the file `index.html.jet` as follows:

Creating this file will automatically open the JET editor. Because the template is empty, it will be marked as an error, both in the editor and the workspace. Hovering over the annotation will indicate what's wrong:

Note that despite the error, the template has nevertheless been compiled to produce `Indexhtml.java` in the project's source folder.

## Creating an `@jet` Directive

The JET editor supports content assist, so hit Ctrl-Space for completion suggestions:

In the content assist dialog, you can now see the complete syntax of the language! It really is very simple. You can use this to create the necessary `@jet` directive:

You can give it the package name `org.eclipse.emf.jet`, the class name `Index`, and clear the imports for now until you need them. Then you can save the result to make the workspace free of errors. To inspect the compiled result, you can click on the arrow on the divider at the bottom on the editor (see the mouse cursor below) to inspect the following result:

The selection and the cursor are synchronized between the template part of the editor and the Java part of the editor. E.g., in the above image, you can see the cursor in the template is after the `Index` as is the cursor indicator in the Java part. You generally won't need to concern yourself with this, but it's interesting and can be useful when you have errors in the compiled Java class, though even in that case, the markers will be displayed in the template itself. If you look closely, you'll see that the Java part is styled with background colors based on where from the template that part of the Java is derived, i.e., at this point just the package name and the class name.

## JET Color Preferences

Speaking of colors, a complex JET template can be quite difficult to read without help syntax highlighting. Of course you can choose your own color scheme via JET Color Preferences… on the context menu:

## JET Literal Content

You can now define the content that the template should generate, i.e., a very simple HTML page that you can copy and paste into the editor from the following:

    <!DOCTYPE html>
    <html>
    	<head>
    		<title>Title</title>
    	</head>

    	<body
    		<h1>Heading</h1>
    		<p>Paragraph.</p>
    	</body>
    </html>

The editor will now look like this:

Note in particular that the editor styles any trailing whitespace in literal content with a bounding box. You will generally not want your template to generate results with trailing whitespace. You can remove such things manually, but the formatter will do that automatically, so try hitting Ctrl-Shift-F now.

## Creating a Driver

You can now create a simple driver to generate this template's result and print it to the Console. Copy and paste the following class to the `src` folder in the Package Explorer, and from the context menu of this new class, use Run As → Java Application.

    package org.eclipse.emf.jet.util;

    import org.eclipse.emf.jet.Index;

    public class IndexTest {
    	public static void main(String[] args) {
    		System.out.print(Index.create("\n").generate(null));
    	}
    }

## Creating a Model

Of course at this point, it's completely uninteresting, except maybe for the fact that we can opt to generate the results using the line delimiter of our choice. In general a template will generate results based on the argument that's passed to the `generate` method. To improve the readability of the template, it's a best practice to externalize as much of the Java logic as possible. You can create a simple model to drive what's generated for this template. Copy and past the following simple model to the `src` folder.

    package org.eclipse.emf.jet.util;

    import java.util.ArrayList;
    import java.util.List;

    public class IndexModel {
    	public static final IndexModel SAMPLE_INSTANCE = new IndexModel("Sample Title");

    	static {
    		List<Section> sections = SAMPLE_INSTANCE.getSections();
    		Section sectionOne = new Section("Sample Section One");
    		sections.add(sectionOne);
    		sectionOne.getContent().add(new Section.Paragraph("This is sample section one.\nIt has multi-line content."));

    		Section sectionTwo = new Section("Sample Section Two");
    		sections.add(sectionTwo);
    		sectionTwo.getContent().add(new Section.Paragraph("This is sample section two."));
    		sectionTwo.getContent().add(new Section.Paragraph("This is sample section has two paragraphs."));
    	}

    	private String title;

    	private List<Section> sections = new ArrayList<Section>();

    	public IndexModel(String title) {
    		this.title = title;
    	}

    	public String getTitle() {
    		return title;
    	}

    	public List<Section> getSections() {
    		return sections;
    	}

    	public static class Section {
    		private String heading;

    		private List<Content> content = new ArrayList<Content>();

    		public Section(String heading) {
    			this.heading = heading;
    		}

    		public String getHeading() {
    			return heading;
    		}

    		public List<Content> getContent() {
    			return content;
    		}

    		public static class Content {
    		}

    		public static class Paragraph extends Content {
    			private String text;

    			public Paragraph(String text) {
    				this.text = text;
    			}

    			public String getText() {
    				return text;
    			}
    		}
    	}
    }

## Creating a Scriptlet

Now you can create your first scriptlet. Start a new line before the `<!DOCTYPE html>` and hit Ctrl-Space.

Alternatively, you can just type `<%` and the closing `%>` will automatically be inserted. The JET editor generally supports smart completion to properly close off a starting tag. Note that scriptlets are styled in green, by default.

To use the model class in the template, start typing its name and hit Ctrl-Space again:

In general, Java content assist and quick assist will work in the templates when working within the scriplets. So you can quickly complete a suggested name for the new variable, lookup the `arguments` parameter of the `generate` method that's in scope, and use quick assist to add the cast to produce the following result:

Note that an import of `IndexModel` class was automatically added to the imports of the `@jet` directive, and that problem markers in the compiled Java are mapped back to the template. Here we have a warning about the as-yet unused variable.

## Creating an Expression

Now you can use this new variable to replace the `Title` with your first JET expression. Delete the `Title` and type `<%=` and the `%>` is of course inserted automatically. Then type `m` and hit Ctrl-Space.

When you make this completion, as soon as you enter `.`, the content assist will give you to option to choose `getTitle()` so that you end up with `<%=model.getTitle()%>`. Note that expressions are styled blue by default. Here's how the editor with its Outline appears:

## Exploiting the Outline with Tag Comments

The outline is mostly useful for more complex templates with `@include` directives. But even in a very large template without `@include` directives, the outline can be made more useful by including specialized JET comments in your template to create so-called tags. You can add a tag comment on a new line before the `<head>` HTML tag:

Change the `Tag` to `Head` and it will appear in the outline as follows:

With this approach you can exploit the outline to make it easy to locate sections in large templates. Selections in the outline will of course select the corresponding element in the editor.

JET comments can of course be used to "comment out" sections of your template just as you would use `/* */` to comment out sections of Java code. You can even use a special form of such a comment as the first line of your template. Type Ctrl-Space at the start of the first line in the template:

## Creating a Header Comment

If the first line of a template has a comment of the form `<%--⏎Content⏎--%>`, i.e., the content starts and ends with a line delimiter, this content will be used to generate a Java comment at the start of the compiled template:

## Generating Interesting Results

Now your can test drive your model-driven template by calling the generator with the sample instance from the model. I.e., change the `IndexText.java` too look like this:

    package org.eclipse.emf.jet.util;

    import org.eclipse.emf.jet.Index;

    public class IndexTest {
    	public static void main(String[] args) {
    		System.out.print(Index.create("\n").generate(IndexModel.SAMPLE_INSTANCE));
    	}
    }

Running it will produce the following with `SampleTitle` from the sample model:

    <!DOCTYPE html>
    <html>
    	<head>
    		<title>Sample Title</title>
    	</head>

    	<body
    		<h1>Heading</h1>
    		<p>Paragraph.</p>
    	</body>
    </html>

## Creating More Complex Scriptlet Logic

You can now enhance the template to generate the body from the model. Enter `<%model.getSections();%>` on a line before the `<h1>` HTML tag and use Ctrl-Shift-1 to create a for-each loop:

The following is the result, including the import of the `Section` class in the `@jet` directive:

## Formatting a Multi-line `@jet` Directive

With many imports the `@jet` directive can get very long. But if you add a line break into the imports section, the imports will be formatted on separate files, and they will be sorted. So add a line break between the imports—quoted strings can span multiple lines in JET templates—and enter Ctrl-Shift-F to produce the following.

## Creating Yet More Complex Scriptlet and Expression Logic

When you enter `%>` after the `{`, the smart insert will insert a `<%` before the closing corresponding `}`. Now move the closing `<%}%>` to appear after the `<p>` HTML tag's line.

Note that the JET editor, like the Java editor, highlights matching brackets and supports Ctrl-Shift-P to jump between matching brackets.

You can now edit the template to use the `section`'s title and to iterate over the section contents to find the ones that are paragraphs, and use the paragraph's text in the template.

It's kind of messy formatting, but hit Ctrl-Shift-F to make it pretty again.

The scriptlets have been indented to match the indentation they would have in Java. Note that generally your Java formatting preferences will be used. However spaces will always be used instead of tabs, and braces will always be at the end of each line to make the template more compact.

## More Interesting Results

Your can run our `IndexTest` again to see the result:

    <!DOCTYPE html>
    <html>
    	<head>
    		<title>Sample Title</title>
    	</head>
    	<body
    		<h1>Sample Section One</h1>
    		<p>This is sample section one.
    It has multi-line content.</p>
    		<h1>Sample Section Two</h1>
    		<p>This is sample section two.</p>
    		<p>This is sample section has two paragraphs.</p>
    	</body>
    </html>

## Dealing with Multi-line Content

So that's all working well, except it's not so pretty how a multi-line paragraph's text is formatted. Also, if you think about it, the line delimiters of the inserted paragraph may not match the line delimiters used in the template. We can create a little utility to deal with all that. But before we do, let's change the compiled Java to use a `StringBuilder` instead of a `StringBuffer`. Enter a new line in the `@jet` directive and hit Ctrl-Space

With the `builder` attribute, you can control the type and the name of the builder. It can be any type that supports `append` for any arbitrarily typed argument. The compiled template now looks like this:

The following utility class can be used to format multi-line comment so that it adjust the content to the current indentation in the builder. Copy and paste it into the `src` folder.

    package org.eclipse.emf.jet.util;

    import java.util.regex.Matcher;
    import java.util.regex.Pattern;

    public final class TemplateUtil {
    	private static final Pattern INDENTATION_PATTERN = Pattern.compile("\r?\n.*$");

    	private static final Pattern LINE_PATTERN = Pattern.compile("(\r?\n)");

    	public static String format(StringBuilder builder, String text) {
    		Matcher matcher = INDENTATION_PATTERN.matcher(builder.toString());
    		if (!matcher.find()) {
    			throw new RuntimeException("This cannot be used on the first line of a template's content");
    		}

    		String lineDelimiterIndentation = matcher.group();
    		return LINE_PATTERN.matcher(text).replaceAll(lineDelimiterIndentation);
    	}
    }

You can modify the template to use it, using content completion to import the name and formatting the result so that the template looks like this:

Now we can see that it produces a prettier result:

    <!DOCTYPE html>
    <html>
    	<head>
    		<title>Sample Title</title>
    	</head>
    	<body
    		<h1>Sample Section One</h1>
    		<p>
    			This is sample section one.
    			It has multi-line content.
    		</p>
    		<h1>Sample Section Two</h1>
    		<p>
    			This is sample section two.
    		</p>
    		<p>
    			This is sample section has two paragraphs.
    		</p>
    	</body>
    </html>

## Exploiting Inclusion for Reuse

Consider if you have multiple templates for generating different types of HTML pages and you wanted to include common content in the `<head>` HTML tag of each of them. You could use an `@include` directive for that. First create a new file in the template folder named `head.html.jetinc`. This is recognized as a JET template, though not a top-level template but rather one that is included by another template. The editor will open like this:

There will always be a warning in such a non-root template to let you know that this will not be compiled to a Java class. Furthermore, the information control will be displayed with details. This control is always available (even in root templates) via the tiny yellow star next to the down arrow on the divider. Despite not being compiled by the JET Builder, the editor nevertheless does compile it in-memory to an artificial Java class so that basic Java syntax errors will be detected and diagnosed. You can see that here reflected even in the Package Explorer:

You can now include this template in the original template, inserting a line after the `<title>` HTML tag and using Ctrl-Space to choose a simple `@include` directive. The include directive will be displayed in the outline as follows:

## Editing Multiple Documents in a Single Editor

You can edit the included template in the editor of the including template. This is very useful because the including template, in the general case, provides the context needed to make the included template semantically complete, i.e., in the general case that the included template contains scriptlets and expressions, that only resolve from the context of the including template.

Note that the JET Builder keeps track of which templates include which other templates. This information is available in the editor for any included template and this information provides links for opening the editor for the including template:

## Generating Included Results

You can test the template again to see that the included content appears in the result:

    <!DOCTYPE html>
    <html>
    	<head>
    		<title>Sample Title</title>
    		<!-- Common Included Content -->
    	</head>
    	<body
    		<h1>Sample Section One</h1>
    		<p>
    			This is sample section one.
    			It has multi-line content.
    		</p>
    		<h1>Sample Section Two</h1>
    		<p>
    			This is sample section two.
    		</p>
    		<p>
    			This is sample section has two paragraphs.
    		</p>
    	</body>
    </html>

## Specialization Using a Skeleton Class

Suppose you want to specialize some aspects of the compiled Java class, for example, to control arguments of the `generate` method. You can use the `skeleton` attribute in the `@jet` directive to reference a so-called skeleton. Create a file called `Skeleton.java` in the templates folder and paste the following skeleton into it:

    public class CLASS
    {
      public String generate(IndexModel model)
      {
      }
    }

Then use content assist to add a `skeleton` attribute to the `@jet` directive as follow:

As you can see, the template now has an error. That's because it's compiled using your skeleton and the parameter is named `model` and is of type `IndexModel`. This makes your starting scriptlet not just redundant, but erroneous. Just delete it.

The name of the skeleton class is irrelevant and it's package declaration will be replaced; it must be public though. You could add Javadoc and define other fields, methods, or even nested classes in the skeleton if you wish.

## Using Additional `@jet` Attributes

To touch upon the remaining attributes of the `@jet`, namely `nlString`, `minimize`, and `version` here is an illustrative example:

They have the following significance:

- The `nlString` attribute allows you to specify an arbitrary expression that yields the default line delimiter to be used by the compiled template when none is specified otherwise.
- The `minimize` attribute will direct the compiler to generate minimal constants:
- the constants have shorter names, and common line indentation is factored out; this is only important for very large templates where the constant pool of the final `.class` file is limited to 64K.
- The `version` attribute is completely unused, and with the introduction of comments is not needed.

Note the completeness of the outline view in reflecting a summary of the contents of the editor and keep in mind that it can be used for navigation purposes, e.g, to edit the skeleton.

## Fully Exploiting all the Features of the JET Editor

The JET editor supports a number of capabilities that we've not explorer yet, many that you might expect from working with the Java editor:

- F3 for navigation to the declaration of a selected method, class or variable.
- Alt-Up, Alt-Down, Alt-Left, Alt-Right for extending the current selection just as in the Java Editor.
- Alt-PageUp for selecting the enclosing JET element of the current selection.
- Alt-Shift-R for renaming a local variable of scriptlet.
- Alt-Shift-L for extracting a selected expression to a local variable.
- Ctrl-Shift-P for jumping between matching brackets.
- Ctrl-MouseHover and Ctrl-MouseClick for Java navigation; this also works on `file` and `skeleton` links as well as in the Java part of the editor to navigate to the originating template, if it's different from the current document.

## Support and Problem Reporting

Please address questions to the EMF Forum prefixing the subject with `[jet]`.

Please open problem reports using EMF's Bugzilla.