Výukový program JET, část 1. (Úvod do JET)

Souhrn

Generování zdrojového kódu může ve vašich projektech vést k úspoře času a snížit množství zdlouhavého nadbytečného programování. Generování zdrojového kódu může být výkonné, ovšem program, který kód zapisuje, se může velmi rychle začít stávat složitý a obtížně pochopitelný. Jednou z možností zjednodušení a zvýšení čitelnosti je použití šablon.

Projekt rámce Eclipse Modeling Framework (EMF) obsahuje dva velmi výkonné nástroje pro generování zdrojového kódu: JET (Java Emitter Templates) a JMerge (Java Merge). Při použití JET můžete používat syntaxi, která je obdobou syntaxe SJP (podmnožinu syntaxe JSP) a usnadňuje zápis šablon vyjadřujících kód, který chcete generovat. JET je generický stroj šablon, který lze použít ke generování zdrojového kódu SQL, XML, Java a jiných jazyků ze šablon. Nachází se v modulu plug-in org.eclipse.emf.codegen jako součást stažení běhového prostředí EMF.

V tomto článku se naučíte, jak vytvořit šablony JET, jak pomocí charakteru JET a tvůrce JET Builder automaticky překládat šablony na třídy Java a jak pomocí těchto tříd generovat zdrojový kód. Tento článek nabízí rovněž stručné informace o syntaxi JET.

Příspěvek poskytl Remko Popma, Azzurri Ltd., remko.popma@azzurri.jp, 30. července 2003. Použito s oprávněním. Poslední aktualizace: 3. ledna 2007.

Obsah

Začínáme
Model JET
Direktivy
Skriptovací prvky JET
Prostředky

Začínáme

Před vytvořením první šablony budete potřebovat modul plug-in EMF. Pokud jste ho ještě nenainstalovali, učiňte tak nyní ještě před tím, než budete pokračovat s tímto výukovým programem.

Snímky obrazovky jsou založeny na Eclipse SDK verze 3.1.0 RC2 a EMF verze 2.1.0 I200506160200. Minimální požadavek při použití konstrukcí Java 5.0, např. generických typů, je však Eclipse 3.3M4 a EMF 2.3.0M4.

Šablona JET je textový soubor s názvem souboru, který končí na "jet". Budeme postupovat podle konvence EMF, kdy se ke každé příponě souboru vygenerovaného kódu připojí "jet". Přípona .javajet tedy znamená, že šablona vygeneruje soubor .java, šablona .xmljet vygeneruje kód XML a šablony, které generují kód SQL, mají příponu .sqljet atd.

Charakter JET a tvůrce JET Builder

Postupujme tradičně a začněme se šablonou, která vytvoří zprávu "Ahoj světe". První šablonu vytvoříme pomocí následujícího procesu ve čtyřech krocích:

1. Vytvořte nový projekt Java a přidělte mu zdrojovou složku "src".
2. Přidejte k projektu nový charakter JET. Tím se v kořenovém adresáři projektu vytvoří složka s názvem "templates".
3. Změňte vlastnosti JET projektu a zkontrolujte, zda se šablony přeloží do zdrojové složky "src" projektu.
4. Vytvořte nový soubor s názvem "helloworld.txtjet" a uložte ho do složky templates.

Krok 1. Vytvoření projektu

Výběrem volby Soubor > Nový > Projekt v nabídce pracovní plochy vyvolejte průvodce novým projektem. Vytvořte nový projekt Java a přidejte k němu zdrojovou složku s názvem src.

Krok 2. Převedení projektu na projekt JET

Po vytvoření projektu na něj klepněte pravým tlačítkem myši v Průzkumníku balíků nebo v pohledu Hierarchie a vyberte volbu Nový > Další... > Šablony JET > Převést projekty na projekty JET.

Po stisknutí tlačítka Další vyberte právě vytvořený projekt a klepněte na tlačítko Dokončit.

Průvodce přidá charakter JET do projektu a vytvoří složku templates v kořenovém adresáři projektu, jak je patrné na níže uvedeném obrázku. Do projektu se přidá také tvůrce JET, který bude všechny soubory ve složce šablon, jejichž název končí na "jet", automaticky překládat na třídu Java.

Krok 3. Změna nastavení JET

Před vytvořením první šablony zkontrolujme, zda je zdrojová složka src projektu cílovou složkou přeložených šablon. Klepněte pravým tlačítkem myši na projekt a v rozevírací nabídce vyberte volbu "Vlastnosti". V dialogovém okně Vlastnosti projektu vyberte v nabídce po levé straně volbu Nastavení JET a do textového pole "Kontejner zdrojů" zadejte "src" (název vaší zdrojové složky). Na níže uvedeném obrázku je stránka vlastností Nastavení JET dialogového okna Vlastnosti projektu.

Poznámka: Do pole Kontejnery šablon můžete zadat více složek oddělených mezerou nebo středníkem. Pokud však má více šablon v různých složkách stejný název souboru, tvůrce JET Builder automaticky přeloží pouze šablonu v první složce. Chcete-li přeložit všechny šablony, zajistěte, aby měly různé názvy souborů.

Krok 4. Vytvoření souboru šablony JET

Tvůrce JET Builder nyní přeloží všechny šablony na zdrojové soubory Java source ve složce src projektu.

Chcete-li se vyhnout problémům, nejprve vypněte automatická sestavení. V nabídce Projekt zrušte zaškrtnutí volby "Sestavit automaticky".

Se zakázanou volbou "Sestavit automaticky" po stisknutí tlačítka Dokončit neobdržíte následující chybu: "V souboru 'helloworld.txtjet' na řádku 1 ve sloupci 1 chybí direktiva 'jet'", která je zobrazena na níže uvedeném obrázku.

Při povolených automatických sestaveních výše uvedenou chybovou zprávu obdržíte. Naštěstí to neznamená, že došlo ke skutečnému problému, ale pouze to, že se tvůrce JET Builder pokusil přeložit naši šablonu ihned po jejím vytvoření a zjistil, že je dosud prázdná. Stisknutím tlačítka OK zavřete dialogové okno s chybou. Pokud není soubor helloworld.txtjet otevřený, otevřete jej a v editoru zadejte nebo vyjměte a vložte následující obsah.

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

 Ahoj světe!

Pokud jste zaškrtli volbu 'Sestavit automaticky', tvůrce JET Builder soubor šablony po uložení automaticky přeloží. Pokud ne, vyberte v nabídce Projekt volbu "Sestavit projekt".

Protože jsme v prvním řádku šablony určili balík hello a třídu HelloWorldTemplate, tvůrce vytvoří ve složce src balík hello a uloží do tohoto balíku soubor Java HelloWorldTemplate.java, jak je patrné z níže uvedeného obrázku.

Tato třída Java je výsledkem překladu šablony a nazývá se implementační třída šablony. Tato třída má metodu s názvem generate. Jedná se o metodu, která generuje kód označený v šabloně.

Můžeme vytvořit instanci implementační třídy šablony HelloWorldTemplate a vyvolat její metodu generate takto:

Chcete-li implementovat výše uvedené, vytvořte novou třídu s názvem HelloWorldImpl. Klepněte pravým tlačítkem myši na balík hello v Průzkumníku balíků nebo v pohledu Hierarchie a vyberte volbu Nový > Třída.

Pojmenujte třídu "HelloWorldImpl" a ujistěte se, že je zaškrtnutý stub public static void main(String[] args).

Nyní zkopírujte do metody main() následující kód:

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

Chcete-li ji spustit, vyberte v rozevírací nabídce panelu nástrojů "Spustit" volbu "Spustit jako/Aplikace Java". Na konzolu by se měla vytisknout slova "Ahoj světe!".

Předání argumentů šabloně

Proveďme stručné shrnutí. Právě jsme vytvořili první šablonu a vygenerovali jsme s ní nějaký kód. Výsledek možná zatím nebyl příliš impozantní, nicméně jsme již připraveni a můžeme začít zkoumat, k čemu všemu lze JET využít. Dalším krokem je předat šabloně argument.

Přidejte nový soubor šablony JET nebo změňte stávající soubor na následující obsah:

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

Tvůrce JET Builder přeloží tuto šablonu na třídu GreetingTemplate v balíku hello. Opět vytvoříme instanci této třídy šablony (nebo změníme stávající třídu HelloWorldImpl), tentokrát však předáme metodě generate řetězcový argument:

 GreetingTemplate sayHello = new GreetingTemplate();
 String result = sayHello.generate("čtenáři výukového programu");
 System.out.println(result);

Výše uvedený kód vytiskne na konzolu text "Ahoj čtenáři výukového programu!".

Import balíků

Argumentem, který předáte šabloně, může být libovolný objekt. V předchozím příkladu jsme předali metodě generate jako argument řetězec, vy však ve své aplikaci pravděpodobně budete chtít předat modelový objekt. Pokud není argument v balíku java.lang nebo vaše šablona používá jiné třídy, než jaké jsou v balíku java.lang, musíte tyto třídy importovat v direktivě šablony jet. Direktiva jet s atributem imports vypadá takto:

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

Další podrobnosti o direktivě jet a jejích atributech jsou uvedeny v tomto článku v části Informace o syntaxi JET.

V následujícím příkladu vytvoříme šablonu, která vygeneruje kód XML. Abychom dodrželi konvenci EMF, kdy se ke každé příponě souboru vygenerovaného kódu připojí "jet", uložíme tuto šablonu do souboru s názvem importdemo.xmljet. Všimněte si, že šabloně předáváme objekt java.util.List obsahující data, která se použijí při generování kódu XML.

   <%@ 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>

Níže uvedený kód ukazuje, jak vyvolat instanci šablony. Vytvoříme seznam a předáme ho metodě generate implementační třídy šablony:

package hello;

import java.util.ArrayList;

public class XMLDemoImpl {
  public static void main(String[] args) {
    List<String> data = new ArrayList<String>();
    data.add("první");
    data.add("druhý");
    data.add("třetí");

    XMLDemoTemplate generateXml = new XMLDemoTemplate();
    String result = generateXml.generate(data);
    System.out.println(result);
  }
}

Na konzolu se vytiskne následující výsledný kód XML:

 <?xml version="1.0" encoding="UTF-8"?>
 <demo>
   <element>první</element>
   <element>druhý</element>
   <element>třetí</element>
 </demo>

Toto je velmi jednoduchý příklad, který vytváří velmi jednoduchý kód XML. Pomocí šablon JET můžete samozřejmě vytvářet i složitější kód XML s použitím atributů a oborů názvů. V takovém případě vám možná přijde pohodlnější vytvořit zvláštní třídu, která bude lepším modelem dokumentu XML než java.util.ArrayList. Čím složitější bude šablona JET, tím více logiky budete obvykle chtít vložit do modelového objektu předávaného šabloně, abyste šablony udrželi čitelné. Toto blíže prozkoumáme ve druhé části tohoto výukového programu.

Změny značek

Šikovnou vlastností šablon JET je to, že můžete měnit značky, které označují skriptlety v souboru šablony. To je velmi pohodlné, když je syntaxe generovaného kódu velmi podobná výchozí syntaxi JET, například pokud pomocí JET generujete stránky JSP.

V následujícím příkladu pomocí JET vygenerujeme jednoduchou stránku JSP. Změníme značky šablon JET tak, aby používaly posloupnost znaků "<$" pro začátek značky šablony a "$>" pro konec značky šablony. Šablona bude nadále obsahovat řetězce "<%" a "%>", ale stroj JET je již nebude považovat za zvláštní, a tak budou zapsány do výsledku stejně jako jakákoli jiná posloupnost znaků.

Chcete-li změnit značkovače značek, přidejte do direktivy JET na prvním řádku šablony atribut startTag a endTag, stejně jako v níže uvedeném příkladu.

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

 <$ String paramName = (String) argument; /* Toto je provedený skriptlet */ $>
 <$ if (paramName != null) { $>
   <%= request.getParameter("<$=paramName$>") %> <!-- toto je vygenerovaná stránka JSP -->

 <$ } $>

Znovu vyvoláme tuto implementační třídu s řetězcovým argumentem, a to takto:

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

   <%= request.getParameter("button") %> <!-- toto je vygenerovaná stránka JSP -->

Co se děje uvnitř

V předchozím oddílu jsme se věnovali vytváření šablon JET, postupu nastavení charakteru JET k automatickému překladu šablon na implementační třídy Java a použití těchto implementačních tříd Java ke generování kódu.

V tomto oddílu se blíže podíváme na implementační třídy Java, které jsou výsledkem překladu šablony. Uvidíme, proč lze v šabloně použít implicitní objekty argument a stringBuffer, a podíváme se také na úpravu přeložené implementační třídy poskytnutím vlastní "kostry".

Přeložené šablony

Šablona JET se překládá na implementační třídu Java. V implementační třídě Java existují některé objekty, na které lze odkazovat přímo v šabloně JET. Následující příklad ukazuje, jak lze v šabloně použít implicitní objekty argument a stringBuffer.

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

 Ahoj, <%=argument%>!
 <% stringBuffer.append("Ještě jednou ahoj!"); %>

Výše uvedená šablona se přeloží na implementační třídu Java takto:

 package hello;

 public class TranslationDemoTemplate
 {
   protected static String nl;
 public static synchronized TranslationDemoTemplate create(String lineSeparator)
   {
     nl = lineSeparator;
     TranslationDemoTemplate result = new TranslationDemoTemplate();
     nl = null;
     return result;
   }

   protected final String NL = nl == null ? (System.getProperties().getProperty("line.separator")) : nl;
   protected final String TEXT_1 = "Ahoj, ";
   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("Ještě jednou ahoj!");
     return stringBuffer.toString();
   }
 }

Všimněte si, že metoda generate implementační třídy Java přijme parametr Object s názvem argument. Jedná se o stejný objekt, jako argument na druhém řádku šablony. Všimněte si také toho, jak implementační třída Java pomocí objektu StringBuffer shromažďuje výsledný vygenerovaný kód. Na tento objekt lze odkazovat přímo v šabloně pomocí jeho názvu stringBuffer.

Statická metoda create umožňuje aplikaci vytvořit instanci TranslationDemoTemplate, která používá jako oddělovač řádků specifický řetězec.

Změna kostry přeložené implementační třídy

Metoda generate výše uvedené třídy TranslationDemoTemplate se označuje jako část "kostry" implementační třídy. Výchozí kostra používaná strojem JET vypadá takto:

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

Definice kostry vypadá téměř jako normální třída Java, až na název třídy. Název třídy (CLASS) bude nahrazen hodnotou atributu class v direktivě jet. Kromě toho má definice kostry metodu generate, se kterou jsme se již setkali dříve. Změnou kostry můžete upravit implementační třídu šablony, například tak, aby implementovala rozhraní, nebo změnit kteroukoli jinou funkci třídy.

Předpokládejme například, že chcete, aby všechny vaše implementační třídy šablony implementovaly rozhraní. Rozhraní může vypadat například takto:

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

Nastavením atributu skeleton direktivy jet na prvním řádku souboru šablony můžeme stroji JET sdělit, že chceme použít vlastní kostru. Hodnota atributu kostry je identifikátor URI, který ukazuje na soubor, v němž lze najít definici vlastní kostry.

Chcete-li si to vyzkoušet, nejprve pomocí panelu nástrojů nebo nabídky Soubor > Nový vytvořte nový textový soubor bez názvu.

Otevřete typ a vyjměte a vložte do něj následující obsah:

 public class CLASS implements IGenerator
 {
/* (non-javadoc)
    * @see IGenerator#generate(Object)
    */
public String generate(Object argument)
   {
     return "";
   }
 }

Nyní uložte tento soubor jako generator.skeleton do adresáře šablon jako na obrázku níže.

Tento soubor je naše vlastní kostra. Všechny šablony používající tuto kostru budou přeloženy na třídy, které implementují rozhraní IGenerator. Chcete-li použít tuto kostru, přidejte do direktivy jet vaší šablony atribut skeleton, a to takto:

 <%@ jet package="hello" class="GreetingTemplate" skeleton="generator.skeleton" %>
 Ahoj, <%=argument%>!
 Aktuální čas je <%=new java.util.Date()%>. 

Poté, co tvůrce JET Builder přeloží šablonu, vypadá implementační třída takto:

 package hello;

 public class GreetingTemplate implements IGenerator
 {
   protected final String NL = System.getProperties().getProperty("line.separator");
   protected final String TEXT_1 = "Ahoj, ";
   protected final String TEXT_2 = "!" + NL + "Aktuální čas je ";
   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();
   }
 }

Všimněte si, že přeložená šablona nyní implementuje rozhraní IGenerator a metoda generate má nyní komentář, který jsme zadali v souboru generator.skeleton. Toto je jeden příklad postupu úpravy přeložené šablony s definicí kostry. Definice kostry mohou obsahovat také další metody, vnitřní třídy apod. Chcete-li zjistit, co dalšího je možné, budete muset trochu experimentovat.

Informace o syntaxi JET

Pokud jste již někdy používali technologii JSP, bude vám syntaxe JET zřejmě připadat dobře známá. Syntaxe JET je podmnožinou syntaxe JSP, takže se zde možná nedozvíte příliš nového.

V tomto oddílu naleznete poloformální popis a informace o syntaxi JET.

Model JET

Šablona JET se překládá na implementační třídu Java. Tato implementační třída má metodu, jejímž voláním lze získat řetězec výsledku. Tato metoda se obvykle nazývá generate (viz rovněž atribut skeleton direktivy jet).

Pokud není v direktivě jet zadán žádný atribut skeleton, implementační třída Java má následující implicitní objekty, na které lze odkazovat v šabloně JET:

• stringBuffer, který použil objekt java.lang.StringBuffer k sestavení řetězce výsledku při vyvolání metody generate
• argument, který objekt java.lang.Object předal metodě generate

Direktivy

Direktivy jsou zprávy stroji JET. Direktivy mají tuto syntaxi:

<%@ directive { attr="value" }* %>

Za značkou "<%@" a před značkou "%>" může být volitelná mezera.

Direktivy ovlivňují způsob překladu šablony, ale při vyvolání šablony neprodukují žádný výstup v generovaném řetězci.

Direktiva Jet

Direktiva jet definuje počet atributů a sděluje je stroji JET. Soubory šablony JET musí obsahovat direktivu jet na prvním řádku souboru, jinak nelze soubor šablony přeložit. Všechny následné direktivy jet jsou ignorovány. Neznámé atributy vedou k závažným chybám překladu.

Následující direktiva označuje, že šablona by měla být přeložena na implementační třídu Java s názvem HelloWorldTemplate.java v balíku hello. Implementační třída by měla importovat balíky java.io.* a java.util.*.

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

Podrobnosti atributů pro direktivu jet jsou následující:

Direktiva Include

Direktiva include se používá k nahrazení textu anebo kódu během překladu šablony. Direktiva <%@ include file="urlSpec" %> vloží text určeného zdroje do souboru šablony JET. Vložený soubor může obsahovat skriptovací prvky JET, které budou rovněž zpracovány.

Tato direktiva má jediný atribut file. Hodnota tohoto atributu je identifikátor URI umístění souboru, který se má zahrnout. Tento identifikátor URI může být buď absolutní cesta, nebo relativní cesta. Relativní atributy URI se vždy interpretují jako relativní vůči složce šablony obsahující direktivu include.

Příklad:

Následující příklad vyžádá při překladu zahrnutí souboru s informacemi o autorských právech.

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

Poznámka: JET podporuje myšlenku potlačení cest šablony. Stroj JET lze nakonfigurovat tak, aby používal více kontejnerů šablon. V takovém případě má první kontejner přednost před druhým, druhý před třetím atd. To znamená, že pokud ve více kontejnerech šablon existují soubory šablon nebo soubory začlenění se stejným názvem, použije se soubor v první složce a další soubory se ignorují. Klienti aplikací založených na JET mohou pomocí tohoto mechanizmu poskytovat vlastní soubory začlenění, které potlačí původní soubory začlenění bez úpravy šablony původní aplikace.

Skriptovací prvky JET

JET má dva druhy prvků skriptovacího jazyka: skriptlety a výrazy. Skriptlet je fragment výrazu a výraz je úplný výraz Java.

Jednotlivé skriptovací prvky mají následující syntaxi naloženou na znacích "<%":

 <% toto je skriptlet %>
 <%= toto je výraz %>

Mezera za značkou "<%" a "<%=" a před značkou je volitelná "%>".

Chcete-li ve skriptletu použít posloupnost znaků %> jako znaky literálu, nikoli jako ukončení skriptletu, můžete změnit jejich význam zadáním %\>. Podobně lze změnit význam posloupnosti znaků <% pomocí <\%.

Skriptlety

Skriptlety mohou obsahovat libovolný fragment platného kódu Java.

Skriptlety se provádějí při vyvolání šablony. To, zda vytvoří nebo nevytvoří výstup do řetězce výsledku, závisí na skutečném kódu skriptletu. Skriptlety mohou mít vedlejší účinky a upravovat objekty, které jsou v nich viditelné.

Poté, co jsou všechny fragmenty skriptletů v dané překladové jednotce zkombinovány v pořadí, v jakém jsou uvedeny v šabloně JET, měly by dávat platný příkaz nebo posloupnost příkazů Java.

 <% if (Calendar.getInstance().get(Calendar.AM_PM) == Calendar.AM) {%>
 Dobré ráno
 <% } else { %>
 Dobré odpoledne
 <% } %>

Syntaxe

<% scriptlet %>

Výrazy

Prvek výrazu JET je výraz Java, který se vyhodnotí, a výsledek se připojí k objektu StringBuffer metodou generate. Výrazy se vyhodnocují při vyvolání šablony.

Pokud nelze výsledek výrazu připojit k objektu StringBuffer, dojde při překladu k chybě. Obsahem výrazu JET musí být úplný výraz Java.

Jsou podporovány vedlejší účinky ve výrazech. Projeví se při vyhodnocení výrazu JET. Výrazy JET se v šabloně JET vyhodnocují zleva doprava.

V následujícím příkladu je k výsledku StringBuffer připojeno aktuální datum.

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

Syntaxe

<%= výraz %>

Prostředky

http://www.javaworld.com/javaworld/jw-11-2001/jw-1102-codegen.html

http://www.eclipse.org/emf/