Bean wrapper

The freemarker.ext.beans.BeansWrapper is an object wrapper that was originally added to FreeMarker so arbitrary POJO-s (Plain Old Java Objects) can be wrapped into TemplateModel interfaces. Since then it has becomed the normal way of doing things, and in fact the DefaultObjectWrapper itself is a BeansWrapper extension. So everything described here goes for the DefaultObjectWrapper too, except that the DefaultObjectWrapper will wrap String, Number, Date, array, Collection (like List), Map, Boolean and Iterator objects with the freemarker.template.SimpleXxx classes, and W3C DOM nodes with freemarker.ext.dom.NodeModel (more about wrapped W3C DOM...), so for those the above described rules doesn't apply.

You will want to use BeansWrapper instead of DefaultObjectWrapper when any of these stands:

Below is a summary of the TemplateModel-s that the BeansWrapper creates. Let's assume that the object is called obj before wrapping, and model after wrapping for the sake of the following discussion.

TemplateHashModel functionality

Every object will be wrapped into a TemplateHashModel that will expose JavaBeans properties and methods of the object. This way, you can use model.foo in the template to invoke obj.getFoo() or obj.isFoo() methods. (Note that public fields are not visible directly; you must write a getter method for them.) Public methods are also retrievable through the hash model as template method models, therefore you can use the model.doBar() to invoke object.doBar(). More on this on discussion of method model functionality.

If the requested key can not be mapped to a bean property or method, the framework will attempt to locate the so-called "generic get method", that is a method with signature public any-return-type get(String) or public any-return-type get(Object) and invoke that method with the requested key. Note that this allows convenient access to mappings in a java.util.Map and similar classes - as long as the keys of the map are Strings and some property or method name does not shadow the mapping. (There is a solution to avoid shadowing, read on.) Also note that the models for java.util.ResourceBundle objects use the getObject(String) as the generic get method.

If you call setExposeFields(true) on a BeansWrapper instance, it will also expose public, non-static fields of classes as hash keys and values. I.e. if foo is a public, non-static field of the class Bar, and bar is a template variable wrapping an instance of Bar, then bar.foo expression will evaluate as the value of the field foo of the bar object. The public fields in all superclasses of the class are also exposed.

A word on security

By default, you will not be able to access several methods that are considered not safe for templating. For instance, you can't use synchronization methods (wait, notify, notifyAll), thread and thread group management methods (stop, suspend, resume, setDaemon, setPriority), reflection (Field setXxx methods, Method.invoke, Constructor.newInstance, Class.newInstance, Class.getClassLoader etc.) and various dangerous methods in System and Runtime classes (exec, exit, halt, load, etc.). The BeansWrapper has several security levels (called "levels of method exposure"), and the default called EXPOSE_SAFE is probably suited for most applications. There is a no-safeguard level called EXPOSE_ALL that allows you to call even the above unsafe methods, and a strict level EXPOSE_PROPERTIES_ONLY that will expose only bean property getters. Finally, there is a level named EXPOSE_NOTHING that will expose no properties and no methods. The only data you will be able to access through hash model interface in this case are items in maps and resource bundles, as well as objects returned from a call to generic get(Object) or get(String) methods - provided the affected objects have such method.

TemplateScalarModel functionality

Models for java.lang.String objects will implement TemplateScalarModel whose getAsString() method simply delegates to toString(). Note that wrapping String objects into Bean wrappers provides much more functionality than just them being scalars: because of the hash interface described above, the models that wrap Strings also provide access to all String methods (indexOf, substring, etc.).

TemplateNumberModel functionality

Model wrappers for objects that are instances of java.lang.Number implement TemplateNumberModel whose getAsNumber() method returns the wrapped number object. Note that wrapping Number objects into Bean wrappers provides much more functionality than just them being number models: because of the hash interface described above, the models that wrap Numbers also provide access to all their methods.

TemplateCollectionModel functionality

Model wrappers for native Java arrays and all classes that implement java.util.Collection will implement TemplateCollectionModel and thus gain the additional capability of being usable through list directive.

TemplateSequenceModel functionality

Model wrappers for native Java arrays and all classes that implement java.util.List will implement TemplateSequenceModel and thus their elements will be accessible by index using the model[i] syntax. You can also query the length of the array or the size of the list using the model?size built-in.

Also, every method that takes a single parameter that is assignable through reflective method invocation from a java.lang.Integer (these are int, long, float, double, java.lang.Object, java.lang.Number, and java.lang.Integer) also implements this interface. What this means is that you have a convenient way for accessing the so-called indexed bean properties: model.foo[i] will translate into obj.getFoo(i).

TemplateMethodModel functionality

All methods of an object are represented as TemplateMethodModelEx objects accessible using a hash key with method name on their object's model. When you call a method using model.method(arg1, arg2, ...) the arguments are passed to the method as template models. The method will first try to unwrap them - see below for details about unwrapping. These unwrapped arguments are then used for the actual method call. In case the method is overloaded, the most specific method will be selected using the same rules that are used by the Java compiler to select a method from several overloaded methods. In case that no method signature matches the passed parameters, or that no method can be chosen without ambiguity, a TemplateModelException is thrown.

Methods of return type void return TemplateModel.NOTHING, so they can be safely called with the ${obj.method(args)} syntax.

Models for instances of java.util.Map also implement TemplateMethodModelEx as a means for invoking their get() method. As it was discussed previously, you can use the hash functionality to access the "get" method as well, but it has several drawbacks: it's slower because first property and method names are checked for the key; keys that conflict with property and method names will be shadowed by them; finally you can use String keys only with that approach. In contrast, invoking model(key) translates to model.get(key) directly: it's faster because there's no property and method name lookup; it is subject to no shadowing; and finally it works for non-String keys since the argument is unwrapped just as with ordinary method calls. In effect, model(key) on a Map is equal to model.get(key), only shorter to write.

Models for java.util.ResourceBundle also implement TemplateMethodModelEx as a convenient way of resource access and message formatting. A single-argument call to a bundle will retrieve the resource with the name that corresponds to the toString() value of the unwrapped argument. A multiple-argument call to a bundle will also retrieve the resource with the name that corresponds to the toString() value of the unwrapped argument, but it will use it as a format pattern and pass it to java.text.MessageFormat using the unwrapped values of second and later arguments as formatting parameters. MessageFormat objects will be initialized with the locale of the bundle that originated them.

Unwrapping rules

When invoking a Java method from a template, its arguments need to be converted from template models back to Java objects. Assuming that the target type (the declared type of the method's formal parameter) is denoted as T, the following rules are tried in the following order:

Accessing static methods

The TemplateHashModel returned from BeansWrapper.getStaticModels() can be used to create hash models for accessing static methods and fields of an arbitrary class.

And you will get a template hash model that exposes all static methods and static fields (both final and non-final) of the java.lang.System class as hash keys. Suppose that you put the previous model in your root model:

From now on, you can use ${File.SEPARATOR} to insert the file separator character into your template, or you can even list all roots of your file system by:

Of course, you must be aware of the potential security issues this model brings.

You can even give the template authors complete freedom over which classes' static methods they use by placing the static models hash into your template root model with

This object exposes just about any class' static methods if it's used as a hash with class name as the key. You can then use expression like ${statics["java.lang.System"].currentTimeMillis()} in your template. Note, however that this has even more security implications, as someone could even invoke System.exit() using this model if the method exposure level is weakened to EXPOSE_ALL.

Note that in above examples, we always use the default BeansWrapper instance. This is a convenient static wrapper instance that you can use in most cases. You are also free to create your own BeansWrapper instances and use them instead especially when you want to modify some of its characteristics (like model caching, security level, or the null model representation).

Accessing enums

The TemplateHashModel returned from BeansWrapper.getEnumModels() can be used to create hash models for accessing values of enums on JRE 1.5 or later. (An attempt to invoke this method on an earlier JRE will result in an UnsupportedOperationException.)

And you will get a template hash model that exposes all enum values of the java.math.RoundingMode class as hash keys. Suppose that you put the previous model in your root model:

From now on, you can use RoundingMode.UP as an expression to reference the UP enum value in your template.

You can even give the template authors complete freedom over which enum classes they use by placing the enum models hash into your template root model with

This object exposes any enum class if it's used as a hash with class name as the key. You can then use expression like ${enums["java.math.RoundingMode"].UP} in your template.

The exposed enum values can be used as scalars (they'll delegate to their toString() method), and can be used in equality and inequality comparisons as well.

Note that in above examples, we always use the default BeansWrapper instance. This is a convenient static wrapper instance that you can use in most cases. You are also free to create your own BeansWrapper instances and use them instead especially when you want to modify some of its characteristics (like model caching, security level, or the null model representation).