The best Markup Builder I could build in Java

Using Groovy MarkupBuilders spoiled me for other ways to create HTML pages from code. Others think the same. But in some organizations you have to use Java and can't use Groovy - at least when you can't sneak it in.

So I tinkered around in Java to see what's the best MarkupBuilder I can write with Java. Using DSLs and Fluent Interfaces (times(5).loop), I came up with a nice solution. It's not Groovy, but it works.

   Page page = page(
      html(
        body(
          // A comment
          h1("Name games"),
          p("Hello ${coolName}, and hello", "id:${id}"),
          ul(
            new Loop("stefanie", "${name}") {
              protected Element each(String item) {
                return li(item);
              }
            }),
          loop("[${number}] ", "number", 1, 2, 3),
          text("..."),
          box("Warning private!"),
          p("Are you dynamic?"),
          // Some dynamic content
          new Action() {
            protected String with(Context context) {
              return "I'm dynamic, " + context.get("name") + ".";
            }
          }
        )
      )
    );

There are some tricks to make it better than most such Markup Builders in Java. I tried to use ideas from building DSLs in Java. Those are using static imports and varargs. The body, html and other elements are static imports from a MarkupBuilder class.

  public static Element body(String body) {
    return new Element("body", body);
  }
  public static Element body(Element... elements) {
    return new Element("body", elements);
  }
  ...

The varargs helps with adding a variable number of childs to an element:

h1(
   p("One"),
   p("Two"),
   p("Three")
);

Another problem is how to put object values into the generated markup. String concatenation leads to noisy code

  "Hello " + name + "!"

so I decided to use a expression language where the Java unified expression language comes to mind. There is an open source version available called JUEL. Now I can use

  "Hello ${name}!"

Attributes are also treated as expressions and seperated by commas, their names and values seperated with a colon.

   p("Hello ${coolName}, and hello", "id:${id}, class:list"),

Loop and Action classes allow for dynamic content.

          
          ul(
            new Loop("stefanie", "${name}") {
              protected Element each(String item) {
                return li(item);
              }
           }),

I've used the template design pattern for this, again with expressions, in a way Spring provides JDBC templates. Another nice idea is with static methods it's also easy to develop custom, semantic tags, so the developer doesn't need to know or see the actual HTML markup which is created. For example I used a box "tag" which translates to

public static Element box(String text) {
  return div(
                 p(text)
           );
}

Closures in Java 7 will make it much easier to write a MarkupBuilder. The Action and Loop inner classes will go away and the code will be more Groovy like. When they add syntactic sugar to create maps I can drop the "name:value, name:${value}" style for attributes and move to [ "name" : value, "name": value ] instead, which doesn't need the EL to work. With some small things to add the MarkupBuilder can be used for JSON or XML.

I'm interested and open to all techniques and ideas to improve the markup builder.

Thanks for listening.

Fluent Interface for Regular Expressions

Some years ago when we migrated Radeox - a wiki engine - to a new Regular Expression engine, we had to change lots of Regular Expressions. Today I would do it in a different way, with Fluent Interfaces. Joshua has a solution for building Regular expressions with a Fluent Interface, about which I wrote before.

Regex socialSecurityNumberCheck = 
  new Regex(Pattern.With.AtBeginning 
    .Digit.Repeat.Exactly(3) 
    .Literal("-").Repeat.Optional 
    .Digit.Repeat.Exactly(2) 
    .Literal("-").Repeat.Optional 
    .Digit.Repeat.Exactly(4) 
    .AtEnd);

Not only is this solution easier to understand than using a String for regular expressions, migrating from ORO Regex to JDK Regex for example would be easy with this solution. The solution we chose was to create two engine implementations for ORO and JDK regex: Compiler (JdkCompiler,OroCompiler), MatchResult (JdkMatchResult,OroMatchResult), Matcher (JdkMatcher,OroMatcher) and so on. For example:

public class OroCompiler extends Compiler {
  private Perl5Compiler internalCompiler;

  private boolean multiline;

  public OroCompiler() {
    this.internalCompiler = new Perl5Compiler();
  }

  public void setMultiline(boolean multiline) {
    this.multiline = multiline;
  }

  public Pattern compile(String regex) {
    org.apache.oro.text.regex.Pattern pattern = null;
    try {
      pattern = internalCompiler.compile(regex,
         (multiline ? Perl5Compiler.MULTILINE_MASK : Perl5Compiler.SINGLELINE_MASK) | Perl5Compiler.READ_ONLY_MASK);
    } catch (MalformedPatternException e) {
      // handle later
    }

    return new OroPattern(regex, multiline, pattern);
  }
}

The actual regular expressions are stored in Java .properties files, to make them easily exchangable. The bold expression looks like this for example:

filter.bold.match=(^|>|[\\p{Punct}\\p{Space}]+)__(.*?)__([\\p{Punct}\\p{Space}]+|<|$)

With the migration of Radeox to a new regex implementation I had to write and implement several interfaces and it wasn't very easy to both support ORO and the JDK implementation. It wan't easy either to change the slightly different pattern dialact from ORO to JDK. With a Fluent Interface, just change the Fluent Interface, no need to think about different Java Regex APIs and to think about different syntaxes.

Thanks for listening.

Creating a fluent interface for Google Collections

Chris wrote about functional programming in Java. As an example he used Google Collections which "is a suite of new collections and collection-related goodness for Java 5.0".

Looking at his post he gives the following code on how to use Goolge Collections

files = Iterables.transform(
  Iterables.filter(
      Iterables.filter(getPagesList(),WebPage.class),undeletedPages),
  new PagesToFilesTransformation()))

This is very verbose and hard to read. Mostly due to the static method calls and the seperation of the first "filter" and the "new PagesToFilesTransformation()" parameter. Using a static import we can reduce this to:

import static Iterables.*;

transform(
   filter( 
      filter(getPagesList(),WebPage.class), undeletedPages), 
   new PagesToFilesTransformation()))

Better. I'll show you how to make this even more readable with a fluent interface. I use the following example for this:

List names = Arrays.asList("Stephan", "Chris", "Mike", "Miha", "Katrin");

Iterable filtered =  Iterables.filter(
  Iterables.filter(names, or( isEqualTo("Katrin"), isEqualTo("Miha"))),
    lengthLessThan(5)) ;

We want to move this code to a fluent interface. Martin Fowler wrote about Fluent Interfaces on his bliki and there is a entry on Wikipedia. They were made popular by JMock as a way to specify mock expectations.

logger.expects(once()).method("setLoggingLevel").with(eq(newLevel));

What is a fluent interface though? For me it's an interface to an API which is more consistent and readable. Which helps you do several steps with an API in a correct way. It's often implemented with speaking method names and call chaining. These together create the illusion of natural, descriptive language. When the chained methods return the correct type, most often it's impossible to call the wrong methods or methods in the wrong sequence. Therefor fluent interfaces create better readable code with less bugs. Which distinguishes them from domain specific languages (like in Ruby on Rails), macro programming (Lisp) or plain language constructs (methods which take closures) like "[1..5].each { ... }". The differences is fluent 😉 "5.times.each {...}" could be considered a simple fluent interface.

The most recent fluent interface in Java with some fame is Quaere, a kind of LINQ for Java for querying object graphs. There even is a promising Quaere API for JPA. I really think fluent interfaces are useful, although others think they are stupid. I keep to myself what I think is stupid and we see where this all is going to.

Back to our example. I've recently shown how to create a fluent interface for object creation. One for Google Collections might look like this:

Iterable<T> filtered = 
    with(names)
   .filter( or(isEqualTo("Chris"), isEqualTo("Miha")))
   .filter(lengthLessThan(5));

This example isn't optimal, but much more readable than the one given by Chris. The or() part could be improved because it doesn't look very nice. This will change with closures. Fluent interfaces will boom with closures in Java 7.

In the comment to his blog post, Chris mentions "Making a fluent interface to do this might be a little risky, because I think there’s an expectation* that a method like Iterable.filter() wouldn’t modify the source iterable itself, but rather would return a new, filtered iterable." We do not need to modify the Iterable, we only hold a reference and create new fluent interfaces on the fly as needed. Our code to enable a fluent interface for Google Collections this is rather simple:

public class FluentIterable<T> implements Iterable<T> {
  private Iterable<T> iterable;

  public FluentIterable(Iterable<T> iterable) {
    this.iterable = iterable;
  }

  public static <T> FluentIterable<T> with(Iterable<T> iterable) {
    return new FluentIterable<T>(iterable);
  }

  public FluentIterable<T> filter(Predicate<? super T> predicate) {
    return new FluentIterable<T>(
        Iterables.filter(this.iterable, predicate)
    );
  }

  public Iterator<T> iterator() {
    return this.iterable.iterator();
  }
}

This example has several main points. The with() static method call is descriptive and creates a fluent interface object for us to hold the Iterable object. Second most methods in fluent interfaces return the object itself. We create a new fluent interface object in filter to wrap the filtered iterable and enable chaining. My last example with object creation did hold the same bean and did not create new objects on the fly. This really depends on what should be done. We could have set the new iterable instead of creating a new wrapper like this:

  public FluentIterable<T> filter(Predicate predicate) {
    Iterable filtered = Iterables.filter(this.iterable, predicate);
    this.iterable = filtered;
    return this;
  }

This mostly depends on your style and if you think immutable objects are good or bad. For this I prefer the immutable Fluent Interface object over the mutable. Perhaps this is a pattern.

Conculsion:: A fluent interface for Google Collections would be useful. It's more readable, less error prone and flows. Although my example works and is usable, there needs to go more work into a fluent interface for Google Collections to make it useful. For example support more Predicates and support transformations.

Thanks for listening.