FreeMarker Manual - JSR-223 scripting support

JSR-223 scripting support

FreeMarker can be used as a scripting language within a JSR-223 "Scripting for the Java(TM) Platform" specification. You need not do anything special, just have freemarker.jar in your classpath for this to work.

Basic usage

The simplest example use would be:

import javax.script.*;
 
ScriptEngineManager mgr = new ScriptEngineManager();
ScriptEngine engine = mgr.getEngineByName("FreeMarker");
engine.put("who", "World");
engine.eval("Hello ${who}!");

This will print "Hello World!" to System.out (as that's the default output for scripts).

To obtain an engine instance, you can use the ScriptEngineManager.getEngineByName() using names "FreeMarker", "Freemarker", "freemarker", "ftl", or "FTL". You can also use ScriptEngineManager.getEngineByExtension() with file extensions "ftl" and "fm".

Template preparsing

JSR-223 also allows compilation of scripts as efficient means of reusing it (in FreeMarker's case "compilation" equals "parsing"). Here's how you would create a compiled script of a FreeMarker template:

import javax.script.*;
 
ScriptEngineManager mgr = new ScriptEngineManager();
ScriptEngine engine = mgr.getEngineByName("FreeMarker");
CompiledScript script = ((Compilable)engine).compile("Hello ${who}!");
engine.put("who", "World");
script.eval();
engine.put("who", "everyone");
script.eval();

This will print "Hello World!" followed by "Hello everyone!". The template was parsed only once and used twice.

Use cases

The primary way to use FreeMarker remains through the direct use of freemarker.* classes. Support for javax.script.* is meant to enable use of FreeMarker in frameworks that use javax.script.* as a generic way of working with any language, without knowing anything about it. This support enables FreeMarker to be integrated into such frameworks.

There are also limitations in the Java script framework. For one thing, JSR-223 doesn't have an include mechanism and indeed wouldn't play too nicely with one, since it itself has no concept of script loading or resource management - to evaluate/compile a script, you pass its source as a java.lang.String or java.io.Reader to the script engine. Identification (using URLs or whatever other resource identifier) is not addressed by the specification, so there's no way to refer back to this script from another one using the embed, include or import FTL directives.

That said, if the only language you want to use is FreeMarker, then you'd better use it directly and not burden your software architecture with an additional abstraction layer. If later you actually end up needing support for multiple languages, and JSR-223 looks to you as a good fit, you can always refactor your code.

Customization

You can instruct the script engine that you don't want the template output to go to the engine's output writer, but instead you want it to be returned as the return value of the eval() call:

import javax.script.*;
import freemarker.ext.script.*;

import javax.script.*;
 
ScriptEngineManager mgr = new ScriptEngineManager();
ScriptEngine engine = mgr.getEngineByName("FreeMarker");
engine.put(FreeMarkerScriptConstants.STRING_OUTPUT, Boolean.TRUE);
engine.put("who", "World");
String output = engine.eval("Hello ${who}!");

You can also specify your own Configuration instance to use, in any of the two following ways:

import javax.script.*;
import freemarker.template.*;
import freemarker.ext.script.*;
 
ScriptEngineManager mgr = new ScriptEngineManager();
ScriptEngine engine = mgr.getEngineByName("FreeMarker");
Configuration config = createMyCustomConfiguration();
((FreeMarkerScriptEngine)engine).setConfiguration(config);

import javax.script.*;
import freemarker.template.*;
import freemarker.ext.script.*;
 
ScriptEngineManager mgr = new ScriptEngineManager();
ScriptEngine engine = mgr.getEngineByName("FreeMarker");
Configuration config = createMyCustomConfiguration();
engine.put(FreeMarkerScriptConstants.CONFIGURATION, config);

Actually, you can bind an instance of java.util.Properties into the engine under the name FreeMarkerScriptConstants.CONFIGURATION, but that is highly discouraged as it'll result in a new configuration instance being created and populated from the properties on each evaluation of the script (however, if you use compilation, a new configuration will be created once per compilation, and then that instance will be used for all evaluations of the compiled script). This option can be handy in situations where you absolutely must avoid any dependency on freemarker.* classes for some reason.

If you are running FreeMarker in a JVM with a security manager, attempts to override configuration in any of the above ways are subject to a permission check. You will need to grant this permission to your code in your security policy file:

grant codeBase "file:/path/to/myGreatCode.jar" 
{
  ...
  permission freemarker.core.FreeMarkerPermission "setScriptEngineConfiguration";
  ...
};

You can even override the default configuration used for all engines by invoking a method on the script engine factory:

import javax.script.*;
import freemarker.template.*;
import freemarker.ext.script.*;
 
ScriptEngineManager mgr = new ScriptEngineManager();
for(ScriptEngineFactory factory : mgr.getEngineFactories()) {
    if(factory instanceof FreeMarkerScriptEngineFactory) {
        Configuration config = createMyCustomConfiguration();
        ((FreeMarkerScriptEngineFactory)factory).setConfiguration(config);
    }
}

Note however, that if you are running FreeMarker in a JVM with a security manager, this is also subject to a (different) permission check. You will need to grant this permission to your code:

grant codeBase "file:/path/to/myGreatCode.jar" 
{
  ...
  permission freemarker.core.FreeMarkerPermission "setScriptEngineFactoryConfiguration";
  ...
};


Page generated: 2008-07-16 22:54:16 GMT	FreeMarker Manual -- For FreeMarker 2.4pre1 - INCOMPLETE/OUTDATED!