Fork me on GitHub


  • Simple & Friendly
  • High-Performance
  • High-Quality


HTTL All configurations have reasonable default values, you can not do any configuration, you can have a good performance in common scenarios. Of course, because the ever-changing business scenario, you can configure the HTTL better close your business, and keep the internal usage.

HTTL following configuration will be loaded in order contents:

  1. (HTTL default)
  2. httl-. properties (mode configuration file, you can have more than one)
  3. (applications configuration file)
  4. JVM-D option (only reads the beginning of the key, the key will read key remove)
  5. system environment variables (only reads tohttl_at the beginning of the key, the key will read key nameshttl_to remove)

# This 5 configuration, the latter take precedence effect. After loading the contents of the configuration values ​​will update configuration items loaded before, perhaps, said the former loaded as a default.

If you use the default values, you can not configure the default values, refer to:

mode configurationandMVC integrationwill load the new configuration file, see the corresponding section instructions.

Mode Configuration

mode HTTL role for selective loading of the configuration file. You can set multiple values ​​(or said to be open more than one mode).

mode is setdevelop(turn develop mode), HTTL corresponds Mode names according to their needs taken into meaningful.

mode can be easily configured with a set of configuration values, and can be flexibly switched.

To adjust the mode in the application configuration file to add:

modes + = develop

and add can.

is built in debug mode configuration, the user can directly open the debug mode:


debug mode will load the configuration:

configuration format convention

configurations, configuration items named in the plural, which means that you can fillmultiple values ​​, separated by commas.

  1. =means that override the default configuration.
  2. + =means that the previous value of a configuration value added (can have multiple values ​​for the configuration items)
  3. - =indicates a configuration value to delete the previous value (can have multiple values ​​for the configuration items)

Linux Bash next use environment variables when configuring HTTLNote:

  1. environment variable name does not support the point of use, use underscores.
  2. + =Set environment will not HTTL requirements, instead= +.
  3. - =to set the environment to be wrong, instead= -.
  4. To export environment changes, otherwise the child process can not read, will not take effect.
  5. key name to addhttl_prefix.

Bash HTTL use environment variable configuration examples:

$ export httl_reloadable = true
$ Export httl_cache_capacity = 1024
$ Export httl_import_packages = +,
$ Export httl_import_packages

using JVM-D option when configuring HTTLNote:

  1. keys plushttl.prefix.

using JVM-D option to configure HTTL example:

$ java-Dhttl.reloadable = true \
-Dhttl.import.packages + =,

Configuration List

Remove blank lines
property values ​​Configuration
configuration item configuration instructions example values ​​
modes configuration mode debug
import.packages domain model package import
import.variables public variable import HttpServletRequest request
import.macros public macro import commons_macros.httl
import.methods static method import java.lang.Math
import.getters property access methods get
import.sizers size Access Method size
import.sequences double-dot sequence Mon Tue Wed Thu Fri Sat Sun Mon
forbid.methods double-dot sequence add, remove, clear template file directory / WEB-INF/templates
template.suffix template file suffix . httl
attribute.namespace attribute syntax namespace httl
cache.capacity template cache size 10000
reloadable whether heat load false
precompiled whether precompiled false source code into byte code false template text embedded byte code false
remove.directive.blank.linedirective true save directory before compiling Java code / log / java bytecode compiler directory / log / classes
compile.version generated bytecode version 1.7
lint.unchecked generate a compile error details false dump context data directory / tmp / dumps
dump.codec dump data format $ json.codec
dump.once it only dump once false
dump.override dump file is overwritten false
for.variable iteration state variable name for
filter.variable filter variable name filter
default.variable.type default variable type java.lang.Object
use.render.variable.type to render first variable type compilation true be inherited template directory layouts
extends.variable referred template automatically inherit variables layout
extends.default automatically inherit the default template default.httl
extends.nested automatically inherit the embedded sub-template name nested
input.encoding resource loading code UTF-8
output.encoding template output encoding UTF-8 whether to use binary output true
output.writer whether to use text output true international directory / WEB-INF
message.basename international filename prefix messages
message.suffix internationalization file suffix . properties
message.format international information format message
message.encoding international information is loaded encoding UTF-8
localized whether incoming Area information false
locale default locale information zh_CN default time zone +8
date.format date format yyyy-MM-dd HH: mm: ss
number.format digital format # # #, # # 0. # # #
null.value null output null
true.value True value output content true
false.value False value output content false
logger.level log output level DEBUG
extension point configuration
configuration item configuration instructions example values ​​
engine engine implements httl.spi.engines.DefaultEngine
template.parser template parser httl.spi.parsers.TemplateParser
expression.parser expression parser httl.spi.parsers.ExpressionParser
translator expression translator httl.spi.translators.CompiledTranslator
compiler bytecode compiler httl.spi.compilers.JdkCompiler
loaders resource loader httl.spi.loaders.ClasspathLoader
formatters dynamic value formatter httl.spi.formatters.DateFormatter
value.switchers dynamic value position switch httl.spi.switchers.ScriptValueSwitcher
value.filters html dynamic value filter httl.spi.filters.EscapeXmlFilter
script.value.filters js dynamic value filter httl.spi.filters.EscapeStringFilter
style.value.filters css dynamic value filter httl.spi.filters.EscapeStringFilter
text.switchers static text position switch httl.spi.switchers.ScriptTextSwitcher
text.filters html static text filter httl.spi.filters.ClearBlankLineFilter
script.text.filters js static text filter httl.spi.filters.ClearBlankLineFilter
style.text.filters css static text filter httl.spi.filters.ClearBlankLineFilter
cache template cache java.util.concurrent.ConcurrentHashMap
resolvers environment variable Decider httl.spi.resolvers.EngineResolver
map.converter rendering parameters converter httl.spi.converters.BeanMapConverter
out.converter Render Output Converter httl.spi.converters.ResponseOutConverter
codecs object transcoder list httl.spi.codecs.FastjsonCodec
default.codec default object transcoder httl.spi.codecs.FastjsonCodec
loggers log output httl.spi.loggers.Log4jLogger

template engine configuration

comment syntax used by default: (default value not allocated)

engine = httl.spi.engines.DefaultEngine
translator = httl.spi.translators.CompiledTranslator
template.parser = httl.spi.parsers.TemplateParser
expression.parser = httl.spi.parsers.ExpressionParser

which, engine responsible for assembly, parser responsible for parsing the syntax tree, translator is responsible for the syntax tree into a template instance. Unless you want to change the syntax, or optimize analytical performance, otherwise the three not require configuration.

you can set for the state variable names, default is for: (default value not allocated)

for.variable = for

template cache configuration

default is strong cache, ie all templates and expressions after loading all cache: (default value not allocated)

cache = httl.spi.caches.TemplateAdaptiveCache
cache.capacity =

When configured capacity is greater than 0, AdaptiveCache the adapter to the LRU (least recently used) to achieve, otherwise it will fit into the whole cache implementation.

If your template very much, not enough memory to cache all the templates, you can configure the cache capacity: (LRU discard policy is automatically enabled)

cache.capacity = 10000

development stage, you can open the heat load: (according to the file's last modification time automatically clear the cache)

reloadable = true

template loading configuration

(1) can be configured to the root directory of the template:

If you configure: = / META-INF/templates
template.suffix =. httl

following wording will find that / META-INF/templates/foo.httl template:

engine.getTemplate ("/ foo.httl");

Note: This directory and template.suffix association, if find other suffix will not bring this directory.

example, the following wording will find that / foo.txt file: (will not bring the template directory)

engine.getResource ("/ foo.txt");

(2) can be configured to load the template default encoding, default is UTF-8: (default value not allocated)

input.encoding = UTF-8

(3) you can configure whether to allow the heat load, default is false: (default values ​​do not match)

reloadable = false

turn heat loads, the template engine getTemplate() will check the file lastModified time, and if the new loading time than the last, it is reloaded.

Please note: the old template will not be unloaded, it keeps on changing file causes memory perm area is growing, only in the development phase.

(4) can be configured to start all precompiled template calls loader.list() scan template file.

In directory search, and through template.suffix suffix filter template file.

precompiled default off: (default value not allocated)

precompiled = false
template.suffix =. httl

from Classpath to load

default Classpath to load from that template on any jar package: (default value not allocated)

loaders = httl.spi.loaders.ClasspathLoader =

loaded from a file

loaders = httl.spi.loaders.FileLoader = / home / admin / templates

loaded from the jar package

loaders = httl.spi.loaders.JarLoader = / home / admin / tempaltes.jar

loaded from the zip package

loaders = httl.spi.loaders.ZipLoader = / home / admin /

loaded from the specified url

loaders = httl.spi.loaders.UrlLoader = http://myhost/tempaltes

from war package loaded

loaders = httl.spi.loaders.ServletLoader = / WEB-INF/templates

need to be configured in web.xml ServletLoader the listener:


string loaded from memory

loaders = httl.spi.loaders.StringLoader

then encoded added template content:

StringLoader.add ("foo.httl","# set (User user) $ {}");

loads from multiple sources

loaders = httl.spi.loaders.ClasspathLoader, httl.spi.loaders.FileLoader

or use the"+="Keep the default classpath loaded at the same time, adding new loader, multiple values ​​separated by commas:

loaders + = httl.spi.loaders.FileLoader

template compiler

for template classes compiled into byte code, the default JDK version using adaptive compiler based on: (default values ​​do not match)

compiler = httl.spi.compilers.AdaptiveCompiler

current operating environment for the JDK1.6 previous version, AdaptiveCompiler will fit into JavassistCompiler, otherwise it will fit into JdkCompiler.

you can enforce the use jdk own compiler: (must use JDK run, JRE does not work)

compiler = httl.spi.compilers.JdkCompiler
You can also replace javassist

compile: (if JRE running, use javassist compilation)

compiler = httl.spi.compilers.JavassistCompiler

of course, also need to increase the javassist jar package dependency:

javassist-3.15.0-GA. jar


(1) output options:

If you set = true, at compile template file will be converted into a byte [] data, On output, output directly to OutputStream byte [] stream, in order to avoid run-time output should turn again.

default fully open: (default value not allocated) = true
output.writer = true

If and output.writer open simultaneously, each template will be compiled into two class, and return to the Adaptive Template proxy class. When the user invokes template.render (Map, OutputStream), the actual implementation of the output byte [] the Template class, When the user invokes template.render (Map, Writer), the actual implementation of the Template output String class.

If and output.writer off simultaneously generates only writer templates, representing only open output.writer.

Note: If only open = true, must template.render (Map, OutputStream), otherwise the data conversion will lead to lower performance. If only open output.writer = true, must template.render (Map, Writer), otherwise the data conversion will lead to lower performance.

if you never pass OutputStream or Writer, please close the corresponding configuration switches, reducing the compilation overhead.

(2) Memory Options:

default template source code and template text will not be compiled into byte code: (default value not allocated) = false = false

do it through a Map caching intermediary, the template source code and template text are placed in runtime attribute to save memory perm size.

compiled into bytecode, in a small template, may be slightly faster, but there will be a qualitative leap in the template is greater than 8K, it will lead to failure of the JVM JIT optimization, will be slower, does not recommend changing this option.

(3) version option:

java version of the configuration will affect the bytecode generation version. (The default is the current version of the JDK)

compile.version = 1.6

(4) debugging options:

If you want to know the compiled bytecode is what kind of, you can set the build directory, the directory must be created in advance, the compiler will output to the directory. class files.

before compiling java code is disabled by default save directory directory: (default value not allocated) =

compiled class is disabled by default save directory: (default value not allocated) =

(5) Error Options:

If the template compilation fails, you can open lint.unchecked option to obtain more detailed compilation error message.

more memory loss but this option is only for use during development, is disabled by default. (Default not allocated)

lint.unchecked = false

output formatter

default date format is loaded: (default values ​​do not match)

formatters = httl.spi.formatters.DateFormatter
date.format = yyyy-MM-dd HH: mm: ss =

You can also set the time zone settings, the results will take time to format the value zone: (defaults to the current system time zone) = +8

you can use the"+="Keep the default date format, while adding new formatter, multiple separated by commas:

formatters + = httl.spi.formatters.NumberFormatter
number.format = # # #, # # 0. # # #

You can also set null, true, false values ​​of the output,

null value defaults will output blank, true, false as output: (default values ​​do not match)

null.value =
true.value = true
false.value = false

example, can be equipped as:

null.value = N / A
true.value = yes
false.value = no

output filter

filter is divided into two categories, one is for the template text, one is for dynamic interpolation.

template text filtering will be performed at compile time, compile-time template text that is replaced, does not affect the output performance.

dynamic interpolation filter in the output when executed, cause performance problems need to be careful filtering, multiple separated by commas.

default load dynamic HTML interpolation filter, to prevent HTML injection XSS attacks: (default value not allocated)

value.filters = httl.spi.filters.EscapeXmlFilter
text.filters =

at compile time, you can configure the static text blank lines removed: (compile time, does not affect rendering speed)

text.filters = httl.spi.filters.ClearBlankLineFilter

You can also configure static text at compile time in successive whitespace compressed into a single space: (compile time, does not affect rendering speed)

text.filters = httl.spi.filters.CompressBlankFilter

You can also use filters simultaneously set value.filters and text.filters:

filters = httl.spi.filters.CompressBlankFilter

equivalent to:

value.filters + = httl.spi.filters.CompressBlankFilter
text.filters + = httl.spi.filters.CompressBlankFilter

HTTL default command removes the line blank if you want to keep, configure:

remove.directive.blank.line = false

type import

import package name

default imported java.util package: (default value not allocated)

import.packages = java.util

so you can use the short name of the class within a template, rather than bring the whole package.

you can use the"+="keep the default import packages at the same time, import the new package, multiple packages separated by commas:

import.packages + =,

import variable type declaration

default imported parent, context, template, engine four variables: (default values ​​do not match)

import.variables = Context parent, Template super, Template this, Engine engine

If you are using the built-in MVC integration, integration has been in default import request, response, session, application four variables: (default values ​​do not match)

import.variables + = HttpServletRequest request, HttpServletResponse response, HttpSession session, ServletContext application

so you can use them directly within the template variable instead of each template declaration:

# set (HttpServletRequest request, HttpServletResponse response)

you can use the"+="keep the default import packages at the same time, import the new package, multiple packages separated by commas:

import.variables + = Foo foo, Bar bar

import method

default import DefaultMethod class method: (default value not allocated)

import.methods = httl.spi.methods.DefaultMethod

you can use the"+="default method retained the same time, introduce new methods, multiple classes separated by commas:

import.methods + =

DefaultMethod have static methods such as: (can also be a non-static method)

public static String format (Date self, String format) {
public static char toChar (String self) {
public static Date now() {

you can call in the template:

$ {date.format ("yyyy-MM-dd")}
$ {Str.toChar()}
$ {Now()}

principle: static methods first argument is a reference to the operator itself, followed by the parameters of the incoming call.

If you need setEngine() injected engine instance, or setXxx (String) injection configuration items that can be imported non-static methods, but static methods compiled faster.


/ / will be injected into the engine itself
private Engine engine;
public setEngine (Engine engine) {
	this.engine = engine;

/ / Will be injected in input.encoding = UTF-8 configuration values
private String inputEncoding;
public setInputEncoding (String inputEncoding) {
	this.inputEncoding = inputEncoding;

/ / Non-static method to import
public String include (String templateName) {
	return engine.getTemplate (templateName, inputEncoding). toString();

Use the same way:

$ {include ("foo.httl")}

prohibited methods

HTTL void method invocation is not allowed to keep the template no side effects, as well as multiple rendering idempotent.

If there is some writing method returns a value, you can configure forbid.methods prohibit, prevent developers mistakenly calls.

default ban some common writing method: (default value not allocated)

forbid.methods = add, put, save, insert, modify, update, delete, remove, clear

import property getter

default imported get, getProperty, getAttribute four attribute value method: (default value not allocated)

import.getters = get, getProperty, getAttribute

will look String and Object parameter value of the property methods, such as: get (String) or get (Object)

import size getter

default imported size, length, getSize, getLength four sizes ranging methods: (default value not allocated)

import.sizers = size, length, getSize, getLength

will find the size of the parameter value empty methods, such as: size()

size getter will be used # if() judgment, $ {a? b: c} ternary operator judgment where judgment null values.

import macro

guide specifies all the macros in the template, multiple templates separated by commas, these macros can be used in any other templates, such as:

import.macros = common_macros.httl

Import Sequence

usage such as:

# for (weekday:"Monday".."Sunday")
$ {Weekday}
# End

week and month that contains the default sequence: (default value not allocated)

import.sequences = Mon Tue Wed Thu Fri Sat Sun Mon, \
Monday Tuesday Wednesday Thursday Friday Saturday Sunday Monday, \
Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec Jan, \
January February March May June July August September October November December January

If the same value as before and the last one, which means that can be recycled.

you can use the"+="keep the default sequence, while adding new sequence, the values ​​separated by spaces, multiple sequences, separated by commas:

import.sequences + = Five Elements Gold

log output configuration

default using log4j output log: (default value not allocated)

loggers = httl.spi.loggers.Log4jLogger

If you need to use other tools to output log log can configure your own adapter.

such as using the JDK logging output:

loggers = httl.spi.loggers.JdkLogger

you can simultaneously output to multiple logging tools:

loggers = httl.spi.loggers.Log4jLogger, httl.spi.loggers.JdkLogger

or use the"+="Keep the default log4j output, while increasing new output, multiple separated by commas:

loggers + = httl.spi.loggers.JdkLogger

Note: When the log level to DEBUG, HTTL log output will be compiled template source code for easy troubleshooting.

variable decision

variable that is, from where to get the decision variables, the default is only get attributes from the context: (default value not allocated)

resolvers = httl.spi.resolvers.ContextResolver

If you are using the built-in MVC HTTL integration has been automatically imported ServletResolver,

it readsrequest,session,servletContext, etc. Get variables:

resolvers + = httl.spi.resolvers.ServletResolver

example: the user's locale international information area, starting with a request for the above configuration to get, so you can set the display area according to the user in different languages.

If you want to be directly in the template configuration items are read into that Engine.getProperty() values, you can configure:

resolvers + = httl.spi.resolvers.EngineResolver

If you want to read in the template directly to the JVM startup parameters are java-Dkey = value ie System.getProperty() values, you can configure:

resolvers + = httl.spi.resolvers.SystemResolver

If you want to have read in the template directly into the environment variable export key = value that System.getenv() values, you can configure:

resolvers + = httl.spi.resolvers.EnvironmentResolver

If you want to set the value of the variable global, you can configure:

resolvers + = httl.spi.resolvers.GlobalResovler

Then, through the static methods global setting variable values:

GlobalResovler.put (key, value); / / static