1. First and most important to write setTitle(title) is better
   supported by IDEs than set("title", title). Same for getRegion()
   instead of get("region").
2. Further more such an interface could help to clarify the model-like nature of Snippetory
   template to people who are new to this concept. Most people seem to expect a template to
   be a script.
3. And, last but not least, the code gets more concise and a little bit more friendly to the eye.

On the other hand using a tool for code generation has several challenges and draw
backs. Changes in template code need to be reflected in the generated classes instantly.
The generated code has to be available while packaging or debugging on systems
where no templates are edited. And to support use of different template fragments
by the same binding logic some kind of compatibility would be nice. (Of course, the
mentioned fragments might be entire files, too.) Even tough each problem has its
solution, setting up a project with Snipperory would get more complicated.
However, the first step is to write a generator to get an idea how this could feel.
I already did that and even though it’s not a really useful tool for now, I’d like to share it
here.
As always with Snippetory it consists of a template and some java code. And as the template
might give you the better idea how it should work I’ll start with that.

//Syntax:C_COMMENTS
package /*${package*/org.jproggy.snippetory.toolyng.beanery/*}*/;

import org.jproggy.snippetory.Template;
import org.jproggy.snippetory.spi.TemplateWrapper;
// ${ class

/*${i}*/public class /*${name case="camelizeUpper"*/Bean/*}*/ extends TemplateWrapper {
/*${i}*/	public /*${name case="camelizeUpper"*/Bean/*}*/ (Template template) {
/*${i}*/			super(template);
/*${i}*/	}
//${ region prefix="\n"
/*${i}*/	public /*${name case="camelizeUpper"*/Bean/*}*/ get/*${name case="camelizeUpper"}*/() {
/*${i}*/		return new /*${name case="camelizeUpper"*/Bean/*}*/(get("/*${name}*/"));
/*${i}*/	}
// region }
//${ location prefix="\n"
/*${i}*/	public /*${parent case="camelizeUpper"*/Bean/*}*/ set/*${name case="camelizeUpper"}*/(Object value) {
/*${i}*/		set("/*${name}*/", value);
/*${i}*/		return this;
/*${i}*/	}
// location }
/// use region with full line mark up to avoid additional line breaks
//${ classes
//   classes }
/*${i*/	/*i}*/}
// class }

The first thing you might have mentioned is the strange location simply call ‘i’ at the beginning
of each line. To understand this you have to be aware, the nested regions of the template are
modelled by nested inner classes of the generated interface class. And ‘i` is the indentation
of the inner classes. The case format normalizes the names to java naming convention. Of
course, this simple approach will cause errors if names like ‘class’ are used in the template.
However, this shows the Snippetory Abstraction Layer in action. The different presentations
of the same data are handled by the template, using formats. Thus presentation logic is separated
from binding logic. (No, it can’t be repeated often enough
Now, let’s look at the java side.

	public Template boil(Template subject, String packageName, String className) {
		target.set("package", packageName);
		Template classTpl = target.get("class");
		generate(classTpl, subject, className, "");
		classTpl.render();
		return target;
	}
	protected void generate(Template classTpl, Template subject, String regionName, String i) {
		classTpl.set("name", regionName).set("i", i);
		for (String location : subject.names()) {
			classTpl.get("location").set("name", location).set("parent", regionName).set("i", i).render();
		}

		for (String region : subject.regionNames()) {
			classTpl.get("region").set("name", region).set("i", i).render();
			Template regionTpl = target.get("class");
			generate(regionTpl, subject.get(region), region, i + indent);
			regionTpl.render(classTpl, "classes");
		}
	}

The binding code doesn’t provide too much special. The template tree is traversed recursively
and there isn`t much data to bind.
Each region responds with a get-method and a type, each location creates a set-method.
Here you can have a look at the complete code for now. The main method allows building a start
configuration in your IDE, So one can play arround with minor convenience.

package org.jproggy.snippetory.toolyng.beanery;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStreamWriter;

import org.jproggy.snippetory.Repo;
import org.jproggy.snippetory.Template;

public class Beanery {
	private Template target = Repo.readStream(getClass().getResourceAsStream("Bean.java")).parse();
	private String indent;

	public static void main(String[] args) throws IOException {
		if (args.length != 3) {
			System.out.println("Usage: templatePath targetDir qualifiedClassName");
			return;
		}
		new Beanery().generate(args[0], args[1], args[2]);
	}

	public Beanery() {
		indent = target.get("class","i").toString();
	}

	public void generate(String templatePath, String targetDir, String qualifiedClassName)
			throws IOException {
		Template template = Repo.readFile(templatePath).parse();
		String[] parts = qualifiedClassName.split("\\.");
		StringBuilder packageHelper = new StringBuilder();
		for (int i = 0; i < parts.length - 1; i++) { 			if (i > 0) packageHelper.append('.');
			packageHelper.append(parts[i]);
		}
		Template result = boil(template, packageHelper.toString(), parts[parts.length - 1]);
		File targetPath = new File(targetDir, qualifiedClassName.replace(".", "/") + ".java");
		targetPath.getParentFile().mkdirs();
		OutputStreamWriter out = new OutputStreamWriter(new FileOutputStream(targetPath), "utf-8");
		result.render(out);
	}

	/**
	 * Build an Object-oriented Interface Layer. This layer consists of a get-method for each
	 * region, a class for each region used as return type of the getter, and a set method
	 * for each location. This construct allows convenient navigation of templates by
	 * the syntax completion feature available in most IDEs.
	 * @param subject The template that shall get the interface layer
	 * @param packageName
	 * @param className
	 * @return
	 */
	public Template boil(Template subject, String packageName, String className) {
		target.set("package", packageName);
		Template classTpl = target.get("class");
		generate(classTpl, subject, className, "");
		classTpl.render();
		return target;
	}
	protected void generate(Template classTpl, Template subject, String regionName, String i) {
		classTpl.set("name", regionName).set("i", i);
		for (String location : subject.names()) {
			classTpl.get("location").set("name", location).set("parent", regionName).set("i", i).render();
		}

		for (String region : subject.regionNames()) {
			classTpl.get("region").set("name", region).set("i", i).render();
			Template regionTpl = target.get("class");
			generate(regionTpl, subject.get(region), region, i + indent);
			regionTpl.render(classTpl, "classes");
		}
	}
}

Any comments and ideas are highly appreciated.

Bernd Ebertz

Head, found and chief technology evanelist of

For a long time I have been thinking about conditional sections. I always thought to need a special syntax for this. This would have added complexity to the system and the directions I thought about it’d be hard to integrate into the XML_ALIKE syntax. But now that I made the name for locations optional I analyzed this for regions, too. And I figured out that t: is a valid tag name in XML. Thus I’ll simply make them nameless sections. I think this is pretty intuitive and doesn’t require a new syntactical construct. Like nameless locations need at least one attribute to make sense, nameless regions need at least one named(!) location (or region) to make sense. It will only be rendered if a none-null value is written to at least one of the enclosed named locations. It doesn’t matter if the set, append, or render method is used. Conditional regions are fully transparent on java site. Names defined in conditional regions appear exactly as they were defined outside.

Unfortunately, C comments syntax is not able to support conditional regions this way as it uses the name (that’s repeated at the end) to distinguish regions from ordinary locations. However, I consider removing C comments syntax anyway as it follows an approach contrary to the one of Fluyt.

</pre>
<table>
<tbody>
<tr>
<th>{v: msg='product.name'}</th>
<th>{v: msg='cart.count'}</th>
<th>{v: msg='cart.price'}</th>
</tr>
<tr>
<td>{v:name}

<hr />

{v:hint}</td>
<td>{v:count}</td>
<td>{v:price} {v:currency)</td>
</tr>
</tbody>
</table>
<pre>

Of course conditional regions can be nested. In fact I expect this to be a typical use case. However, conditional regions serve another purpose: They can provide meta data that spans over several other locations, but not a complete named region. Adding another named region would affect binding logic, even though the issue is bound to technical or presentational purposes.

{v: msg='product.name' strech='30'} {v: msg='cart.count' strech='9r'} {v: msg='cart.price' strech='16r`}
===========================================================

{v:name strech='30'               } {v:count strech='9r`            } {v:price} {v:currency)

{v:hint}

{v: default='' strech=`40r`                                         } ----------------
{v: msg='cart.sum' strech=`40r`                                     } {v:price} {v:currency)

Formatting interface

Another big topic is the re-design of the formatting. There is quite a number of features I want to add:

• Multiple attributes per Formatter.
• Formatter should consume data, that is provided via set method calls
• Better handling of status for formatters.
• Control over encoding. Thus they need to know about the target encoding, and have to be able to define the encoding they return.
• Distinction between the convention of a provided null value and no value at all
• Multi-step conversion

This will be done by providing an additional interface for most of the features and change the return
type of the format method to Object.

New syntax: Fluyt

Looking around on other engines I recognized a tendency to provide razor-like syntax. Razor is a template
syntax for .net. It’s very brief and sparse with letters. Though, I thought it would be nice to have a
syntax, that’s not that wordy and more consistent within itself (first) and to others (maybe I’ll build
a complete syntax family upon Fluyt). Even though razor gave the idea, Fluyt is not really based on
razor.

Fluyt will be reduced to a single syntactical element consisting on 3 segments. Each segment is optional,
but there has to be at least one. The segments are:

• Name
• Meta data (surrounded by round brackets)
• A template region (I’m not yet really sure how to do it, but most likely curly brackets will be involved. At the moment I prefer single curly brackets with an additional dollar sign for closing. Between the bracket and the dollar the name can be repeated for optional sanity.

$[<name>][([<atribute>='value'...])][{<content area>}[<name>]$]

In addition we have the 3-slash-comment from C_COMMENT syntax and the normal syntax selector.

$cart{
$(msg='product.name' strech='30') $(msg='cart.count' strech='9r') $(msg='cart.price' strech='16r`)
===========================================================
$cart-entry{
/// we can define the length of the complete expression "$price $currency" with a continual region
$name(strech='30' ) $count(strech='9r` ) $(strech='16r'){$price $currency}$
${
$hint
}$
/// This name is optional. But it makes it simpler to follow the source.
}cart-entry$
$(default='' strech=`40r` ) ----------------
$(msg='cart.sum' strech=`40r` ) $(strech='16r){$price $currency}$
/// this regions closes without giving its name 'cart'
}$

More information on

   Template test = Repo.parse("Hello {v:who}");
   test.set("who", world).render(System.out);

No additional dependencies, no problems just simplicity and fun.
Another simple example on

Snippetory ships with a powerful and extensible abstraction layer. A central element is the encoding. The encoding is designed to handle technical issues of a specific output format when different encodings are integrated within each other. If we take HTML as base an URL might be integrated as is, plain text needs some characters to be escaped, and wiki will need some complicated thing…

Let’s look at some examples to get an idea how this works. Once I implemented a date picker based on jQuery. First I simply initialized it by putting a formatted and localized date into the input field like

<input type="text" name="start" value="{v:start date='medium'}" />

This worked fine for German and English, however Italian failed because java makes quiet different assumptions how the preferred format in the different languages look like, while jQuery thinks another way. Though, I needed a language agnostic way to hand over the parameter:

$( ".selector" ).datepicker({ defaultDate: {v:preset date='JS_JS' });

Though, we can see, that formatting is sometimes in the responsibility of the template, though it should be possible to handle it there. However, it is part of the interface to the controller, which has to parse it. Though, the responsibility is not clear and has to be clarified wisely.

See you on

Very similar things happen when separating template and logic:

See you on

If you need precise information things get even more complicated. Is an empty array empty for the EL empty keyword? Takes some time to find it out. And a number of quirks every day. Want to express the size of a collection? You need an additional field some where. And the tool support, considered one of main advantages, is not very fun. At least in while the HTML support is sufficient and java even great, JSP doesn’t really do the job. Opening a field definition accessed via EL? Nope. Opening a tag definition? Nope. Adding library definition when entering name space shortcut? Nope. Re-factoring a piece of code into a JSP tag? Again, not there. OK, I didn’t submit. I did never try to make this better. But the fact is the community does not preserve the power to support JSP adequately. And the complexity of JSP makes those additions more important the less complex technologies. 

But enough complaining. Let’s implement the interface example using JSP. Generally it is common to implement a special view model and fill it in the so-called controller. This in necessary to get the interface a little more explicit, and to decouple execution order and presentation order. And, due to the reduced functionality of EL, the real model is not expressive enough to take over logic responsibilities. In fact this is a price we pay whenever using JSP, though I have to include this in the example. Next question is where to write this logic, i.e. How does the controller look like?

package org.jproggy.examples.inftfgen.jsp;

import java.io.IOException;
import java.util.ArrayList;
import java.util.Collection;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
import java.util.TreeSet;

import javax.servlet.Filter;
import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;
import javax.servlet.annotation.WebFilter;

/**
 * Servlet Filter implementation class InterfaceGenController
 */
@WebFilter("/intfgen.jsp")
public class InterfaceGenController implements Filter {

    /**
     * Default constructor.
     */
    public InterfaceGenController() {
    }

	public void destroy() {
	}

	public void doFilter(ServletRequest request, ServletResponse response,
			FilterChain chain) throws IOException, ServletException {
		try {
			Class<!--?--> intf = Class.forName(request.getParameter("intf"));
			Set<String> types = new TreeSet<String>();
			InterfaceDefinition interfaceDefinition = new InterfaceDefinition();
			interfaceDefinition.setName(intf.getSimpleName());
			interfaceDefinition.setPackageName(intf.getPackage().getName());
			Collection availablePackages = new HashSet();
			availablePackages.add(intf.getPackage().getName());
			availablePackages.add("java.lang");

			for (Class<?> parent: intf.getInterfaces()) {
				if (!availablePackages.contains(parent.getPackage())) {
					types.add(parent.getName());
				}
				interfaceDefinition.addParent(parent.getSimpleName());
			}

			for (java.lang.reflect.Method refMethod : intf.getDeclaredMethods()) {
				Method method = copyMethod(types, availablePackages, refMethod);
				interfaceDefinition.addMethod(method);
			}

			groupTypes(types, interfaceDefinition);

			// pass the request along the filter chain
			chain.doFilter(request, response);
		} catch (Exception e) {
			throw new IOException(e);
		}

	}

	private void groupTypes(Set types,
			InterfaceDefinition interfaceDefinition) {
		String oldPrefix = "";
		ImportGroup group = null;
		for (String type : types) {
			String prefix = type.split("\\.")[0];
			if (!oldPrefix.equals(prefix)) {
				if (group != null) interfaceDefinition.addImportgroups(group);
				group = new ImportGroup();
			}
			group.addImport(type);
		}
		if (group != null) interfaceDefinition.addImportgroups(group);
	}

	private Method copyMethod(Set types, Collection availablePackages,
			java.lang.reflect.Method refMethod) {
		Method method = new Method();
		method.setName(refMethod.getName());
		Class<!--?--> returnType = refMethod.getReturnType();
		if (!availablePackages.contains(returnType.getPackage())) {
			types.add(returnType.getName());
		}
		method.setName(returnType.getSimpleName());
		for (Class<?> type : refMethod.getParameterTypes()) {
			if (!availablePackages.contains(type.getPackage())) {
				types.add(type.getName());
			}
			method.addParamterType(type.getSimpleName());
		}
		return method;
	}

	public void init(FilterConfig fConfig) throws ServletException {
	}

	public static class InterfaceDefinition {
		String packageName;
		String name;
		List<ImportGroup> importgroups = new ArrayList();
		List<String> parents = new ArrayList<String>();
		List<Method> methods = new ArrayList<Method>();
		public String getPackageName() {
			return packageName;
		}
		public void setPackageName(String packageName) {
			this.packageName = packageName;
		}
		public String getName() {
			return name;
		}
		public void setName(String name) {
			this.name = name;
		}
		public List getImportgroups() {
			return importgroups;
		}
		public void addImportgroups(ImportGroup group) {
			importgroups.add(group);
		}
		public List getParents() {
			return parents;
		}
		public void addParent(String parent) {
			parents.add(parent);
		}
		public List getMethods() {
			return methods;
		}
		public void addMethod(Method method) {
			methods.add(method);
		}
	}
	public static class ImportGroup {
		List<String> imports = new ArrayList<String>();

		public List getImports() {
			return imports;
		}

		public void addImport(String imp) {
			this.imports.add(imp);
		}
	}
	public static class Method {
		String name;
		String returnType;
		List paramterTypes = new ArrayList();
		public String getName() {
			return name;
		}
		public void setName(String name) {
			this.name = name;
		}
		public String getReturnType() {
			return returnType;
		}
		public void setReturnType(String returnType) {
			this.returnType = returnType;
		}
		public List getParamterTypes() {
			return paramterTypes;
		}
		public void addParamterType(String paramterType) {
			this.paramterTypes.add(paramterType);
		}
	}
}

As I don’t want to advertise for a special framework, and using any of them would be an overkill in such a simple example I decided to use a filter. For simplicities sake I will add the model classes as inner classes to the filter. It’s still quite a bit of code. The model makes half of the lines, but, granted, not that much of the complexity.

After the data is gathered we can start looking at the JSP. This will not really look like a template. And to get the white-spaces controlled I’ll have to write somewhat awkward:

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core"
%>package ${interfaceDefinition.packageName};

<c:forEach var="group" items="${interfaceDefinition.importgroups}"
><c:forEach var="import" items="${group.imports}"
> import ${import};
</c:forEach>
</c:forEach>public interface ${interfaceDefinition.name} extends <c:forEach var="parent"
items="${interfaceDefinition.parents}" varStatus="status"
>${parent}<c:if test="${not status.first}">, </c:if
></c:forEach> {
<c:forEach var="method" items="${interfaceDefinition.methods}"
>  ${method.returnType} ${method.name}( <c:forEach var="parameterType" items="method.parameterTypes"
varStatus="status"><c:if test="${not status.first}"
>, </c:if>${parameterType} arg${status.index}</c:forEach> );
</c:forEach>}

To me it’s kind of hard to figure out this is a template for an interface definition even though I’ve already seen some interface definitions and some templates, too. Let’s look at the Snippetory template again:

package {v:packageName};

<t:imports>
import {v:name};
</t:imports>

public interface {v:name} extends {v:parent delimiter=", "} {
<t:methods>
  {v:return_type} {v:name}(<t:parameters delimiter=", ">{v:type} {v:name}</t:parameters>);
</t:methods>
}

In this case it’s clear on first sight. A template for an interface definition. No doubt about it. While the Java code is, ignoring the model, quite similar in quantity, the difference on template side is drastic. Even though it’s not just the sheer amount code, but there is an elegance that make our work really a bit simpler. A location mark for instance is a real template construct with support for escaping according to the surrounding encoding (like the <c:out/> tag does for XML and only for XML), formatting, and nice little helper like the delimiter attribute, that solves a typical template problem.

Of course, all the brilliant tags provided by all those people will not work on Snippetory. But I’ve never used one of that is not really simple to implement. Most are simply workarounds for JSP problems. But yes, there are some valuable tags, too, that would require a significant effort to re-implement using Snippetory. But the about 350 pages I deal and dealt with do not use them. And they’ve been implemented by quite different people. I skip performance tests here. On one hand I expect JSP to be a little bit faster. But on the other hand the lower implementation effort wights this pretty well. Performance is more interesting to me where the programming model is similar. And of course where Snippetory can win. That’s all for today. Maybe I’ll get back to JSP some day and try another example.

Have fun,

Sir RotN