Limbo Overview

Wilfred Springer

1. Introduction
Limbo is the code name of an expression language used in Preon1. It allows you to evaluate expressions on a certain context. The expression language is fairly simple; it supports basic logical and arithmetic operators, and it supports attribute references and item references.

Example 1. Simple Limbo Examples
3 * 4 3 * person.age 2 ^ group.persons[3].age person.age >= 12 ... and that's probably where the correspondence with the JSP Expression Language and other expression languages ends. Because there is a big difference with those languages. And that difference is not based on notation (syntax and grammar), but on the way you apply Limbo. Here are some of the differences of Limbo: • Limbo supports early binding. That is, it will validate the correctness of the expression before it actually validates it. So, when you build the expression, you know if it is an expression that can be evaluated at runtime within a certain context. • Limbo allows you to bind to any context, not just state exposed through bean properties or private fields. • The Limbo API allows you to export the expression as a natural language based human readable snippet of text. Limbo originates from a project to capture dependencies in different fields in a binary media format in an unambiguous way. Using Limbo, that project is capable of generating a human readable description of the encoding format. Expressions like the ones mentioned in Example 1, “Simple Limbo Examples” could be rendered into this:

3 times 4 3 times the age of a person 2 to the power of the age of the third person in the group the age of the person is greater than or equal to 2

This article is a tutorial on Limbo. It will explain the language itself, but it will also explain how you weave it into your own project.


Limbo used to be a separate project, however when moving to Preon 2.0, knowing that Limbo is only used inside Preon, it did not seem to make an aweful lot of sense to keep it a separate project, especially with some refactoring that had to be done.


Limbo Overview

2. The Language
The first thing you need to know about Limbo is that it is an expression language, intended to execute on a certain context. The context might be a fairly complicated data structure, or it may not. Two things are for sure: Limbo only allows you to refer to things by name or their index, and Limbo does not allow you to define complex structures in the language itself. Let's start with the most commons example: let's look at an simple example object-based data structure. In Figure 1, “Simple data model”, Persons have a name and an age, a father and mother, and optionally some children of their own.

Figure 1. Simple data model

Based on this, here are some example Limbo expressions, given that the context is a person.

age // the age of the current person age >= 35 // the age is greater than or equal to 35 father.age // the age of the father father.age + mother.age >= 70 // the sum of the age of the father and // the age of the mother is greater than //or equal to 70 children[0].age < 7

There are a couple of lessons to learn from the example above. First of all, valid Limbo expressions always evaluate to boolean values or integer values. You wonder why? Well, simply because we did not need anything else. The whole purpose of Limbo is to express arithmetical and logical relationships between things. Producing text simply has never been a requirement. The next thing to notice is that the expressions do not look all that different than Java expressions2. It supports arithmetic operators ('+', '-', '/', '*', '^'), comparison operators ('>', '<', '>=', '<=', '==') and logical operators ('&&', '||', '!'). The third thing to notice is that you can refer to attributes as well as items. (In that sense, Limbo is comparable to Python.) In this example, that works out quite well. Objects also have attributes and some types of objects might have items. However, it is important to remember that Limbo does not bind to objects only. Limbo is able to bind to any model exposed as 'things' with attributes and items. Integer literals can be expressed as decimals (1254), hexadecimals (0xFF, 0xff, etc.) or as binary numbers (0b10101011, 0b1001, etc.). Limbo ignores all whitespace.


Notice that I say it does not look all that different. It actually more different than you might expect. More on that somewhere else.


Limbo Overview

3. The API

3.1. Getting Started
Let's start with a simple example first:

Example 2. Simple expression
Expression<Integer, Person> doubleAge = Expressions .from(Person.class) .toInteger("age * 2"); Person wilfred = new Person(); = "Wilfred"; wilfred.age = 35; assert 70 == doubleAge.eval(wilfred); In the first line, we build the Expression instance. Since the expression is based on a Person object, the from(...) method takes Person class reference. After that, we specify that we expect an integer result, and pass the expression at the same time. (The builder methods actually have a couple of other options, but we will leave that out for now.) Once the Expression has been built, evaluating is simply calling eval(...) on the expression, passing in the Person instance. And - like you could have expected - the result is 70. Note there is no cast in order to compare to 70, courtesy of the use of generics and auto unboxing.

3.2. The ReferenceContext
I said before that Limbo is capable of binding to anything capable of representing itself as 'things' with named attributes and numbered items. Let me refine that: it is capable of binding to anything for which you can implement a ReferenceContext. So, when in Example 2, “Simple expression” you passed in a Person class, under the hood, Limbo wrapped that inside a ReferenceContext. Now, if you ever used an expression language like the JSP EL, then you are probably aware of a similar mechanism in that expression language. JSP EL has a VariableResolver. Your EL expression can be evaluated against anything, as long as there is a VariableResolver capable of resolving the named things. One of the differences between Limbo's ReferenceContext and JSP EL's VaribleResolver is that the ReferenceContext is parameterized with type of context passed in at evaluation time. Typically, with JSP EL, you will evaluate your expression against a context of of type java.lang.Object. The Java compiler will not be able to verify if the subtype of java.lang.Object you pass in is actually something against which you can evaluate the expression. If you are creating an expression in Limbo, you will always need to construct that expression parameterized ReferenceContext, in which the type parameter is the type of object on which you can apply the expression. So if you have an expression you want to evaluate against an instance of Person, you need to construct the Expression based on a ReferenceContext<Person>.


Limbo Overview

Now, you probably wonder why all of that is relevant. What's the purpose of adding the extra complexity of having to deal with parameterized types. After all, the JSP EL works fine with a non-parameterized VariableResolver, and expressions accepting java.lang.Object instances. The real reason for this is that Limbo is capable of early binding. ReferenceContext implementations can make guarantees on the validity of references used in the expression. Which means that the Expression based on that ReferenceContext can guarantee it will be capable of acting upon a certain context. Example 3, “ReferenceContext and References” shows how you build references using a ReferenceContext. In this case, the data model to which we bind is a Java version of the object model outlined in Figure 1, “Simple data model”. The ClassReferenceContext used in this case not only allows you to build references to data contained by an instance of that class, but will also check for the existence of those attributes. Any attempt to reference something that is not defined by the class will generate a BindingException.

Example 3. ReferenceContext and References
ReferenceContext<Person> context = new ClassReferenceContext<Person>(Person.class); Reference<Person> personsName = context.selectAttribute("name"); Reference<Person> fathersName = context.selectAttribute("father").selectAttribute("name"); Person wilfred = new Person(); = "Wilfred"; wilfred.age = 35; Person levi = new Person(); = "Levi"; levi.age = 8; levi.father = wilfred; assert "Levi".equals(personsName.resolve(levi)); assert "Wilfred".equals(fathersName.resolve(levi)); assert "Wilfred".equals(personsName.resolve(wilfred)); // ... and this will throw a BindingException Reference<Person> gender = context.selectAttribute("gender");

3.3. Natural Language Description
Early validation is not the only benefit we gain from ReferenceContexts supporting early binding. Another benefit is that we basically gather enough information to generate a fairly decent description of the References created. In the example above, the fathersName reference will be printed as: "the name (a String) of the father (a Person) of a Person ". Now, this description might not be ideally suited in your case, but the way your reference is rendered is also determined by the ReferenceContext. You can basically render it any way you like, as long as you are willing to go through the trouble of implementing your own ReferenceContext.


Limbo Overview

4. Embedding Limbo
If you ever consider using Limbo, you will most likely do that for its abilities to provide early validation of expressions, and the ability to turn expressions into human-readable descriptions. There is a problem here though. Limbo doesn't define a single ideal way of 'early binding' the expression to a context. You may feel that binding an expression to private inner variables of an object makes perfect sense. Other people will consider that to be malpractice, and require a way to have early validation of expressions bound to getters and setters. So where do you encode these policies? Similarly, Limbo also does not define a single ideal way to turn expressions into human readable language. Of course, you will most likely benefit from Limbo's abilities to turn the main part of the expression into human readable text, but you will probably have a preference for deciding how references should be translated in human readable text. Like, do you want it to be like 'the age of the person', 'the value of the age property of a Person object', or 'person.age'? Again, what do you implement in order to encode these policies? The ReferenceContext is the answer to both of these questions. So basically, embedding Limbo in a context, normally starts by implementing a ReferenceContext. And, in all honesty, that's basically it. Once you start by implementing a ReferenceContext, you will quickly run into having the need to implement various References yourself, you so probably need to take a peek at that interface as well. I currently can't tell you which ReferenceContexts and References you will want to implement. That will be based totally on your own needs. However, I can give you some examples on the use of ReferenceContexts in Preon itself. That should give you a bit of a flavor on what you can do.

5. Limbo in Preon

5.1. BindingsContext
References in expressions used in Preon are not bound to properties. And although references typically resolve to values of (private) fields, the reverse doesn't hold. So, not every (private) field can be addressed by a reference in Preon. In fact, in general only fields that have been marked as 'bound' can be referenced from an expression. Other (private) fields are not even seen. The reason behind this is fairly simple. Preon's objective is to make sure that you can always generate documentation on the encoded representation from the annotated data structure. If the 'specification' (data structure + annotations) would contain references to fields that have been populated outside of Preon's control, then that description would have 'dangling' references; references that point to something of which we don't know anything at all. So essentially, it would leave holes in the documentation. That's where the BindingsContext comes into play. Almost all references in Preon are rooted in the BindingsContext. While constructing the Codec, Preon will construct a BindingsContext for every nontrivial class for which it needs a Codec. So it won't construct a BindingsContext for a Codec decoding a Date, or an Integer, but it will create an instance for your own homegrown class with a couple of 'bound' fields. Now, if you closely examine the ReferenceContext's interface, then you will notice that it has selectAttribute and selectItem methods. When creating a reference to the value of a bound field named 'foobar', then what essentially is happening is that (in case of a named attribute), the selectAttribute is called


Limbo Overview

with the name 'foobar'. The BindingsContext will return a Reference object that eventually will resolve correctly into the value of foobar. Remember that Reference itself is not the end of it. A Reference can be used to determine a value at runtime, but it also offers the option of selecting other parts of the data structure by calling one of the Reference's own selectAttribute or selectItem methods.

5.2. ImportSupportingObjectResolverContext
This one definitely deserves an explanation, even it were only because of its incredible long name. In the previous section, I already alluded to the fact that not all references are references to bound fields. Preon uses more than one ReferenceContext, and this one in particular is sometimes wrapped around an existing ReferenceContext in order to make sure you can refer to constants. So this is how it works. If you want to refer to constant values inside your expressions, then you will need to have a way to define those constants. Preon simply allows you to define these constants as you would normally do in Java. However, that does not automatically pull them into scope of your expressions. In order to 'import' these constant definitions, you place an @ImportStatic annotation on top of the class containing references to these constants. The ImportSupportingObjectResolverContext will be instantiated by the ObjectCodecFactory for every class for which it creates a Codec, if and only if that class has the @ImportStatic annotation.

5.3. Index in Offset Expressions
When you use @BoundList, then Preon allows you to specify an offset attribute; that offset attribute can be an expression. The expression allows you to calculate the starting position of an element, given a certain context. Question of course is which element? It turns out that the offset attribute actually introduces a new variable, on top of all variables already in scope. That variable is the 'index'. You can express the offset of an element in terms of that index, by simply referring to that variable. The 'index' variable doesn't come to life just like that. Just like with all of the other examples shown before, it requires a ReferenceContext to make sure the framework understands the existence of this variable. That particular ReferenceContext is also responsible for generating a proper human readable description for that reference in case the framework requires it.

6. Summary
Limbo originally started out as a project to have an expression language catering for the needs of Preon: it required an expression language with APIs for embedding it inside a context that required early binding, and an API for turning expressions into human readable text. The ReferenceContext is one of the central abstractions for having early validation. From the ReferenceContext, you will create References. Those References embody everything there is to know about a reference, including information on how the reference should be rendered into a human-readable descriptive reference.


Limbo Overview

Limbo was eventually folded back into Preon as the preon-el module, in order to ease migration to Preon 2.0.


Sign up to vote on this title
UsefulNot useful