Common Template Engine

一. 扩展总接口
org.commontemplate.config.Configuration
配置总接口，通过getXXX方式向引擎提供配置
org.commontemplate.standard.ConfigurationSettings
配置的setter实现，提供与Configuration的getter配对的setter，通常用于IoC注入方式，也可以编程调用setter
org.commontemplate.standard.StandardConfiguration
标准配置实现，内置了chain的封装，可以直接调用addXXX方法，简化编程设置方式

二. 扩展点
说明：
“注册方法”均指：StandardConfiguration的设置函数
“配置方法”均指：内置的properties配置方案，并且继承了标准配置

1. 国际化扩展
相关接口：
org.commontemplate.config.ResourceBundleProvider
注册方法：
setResourceBundleProvider(ResourceBundleProvider)
setMessageBaseName(String baseName) (注：使用内置的PropertiesResourceBundleProvider)
配置方法：
resourceBundleProvider=org.commontemplate.standard.i18n.PropertiesResourceBundleProvider()
resourceBundleProvider.baseName=messages
参考实现：
org.commontemplate.standard.i18n.PropertiesResourceBundleProvider

2. 模板资源加载器扩展
相关接口：
org.commontemplate.core.ResourceLoader (模板源加载接口)
org.commontemplate.core.Resource (模板源)
注册方法：
setResourceLoader(ResourceLoader)
配置方法：
resourceLoader=com.xxx.YourResourceLoader()
参考实现：
org.commontemplate.standard.loader包下相关类

3. 缓存策略扩展
相关接口：
org.commontemplate.config.Cache
注册方法：
setTemplateCache(Cache)
setStandardCache(String cacheStrategy, int cacheMaxSize) (注：标准cacheStrategy支持NONE, STRONG, SOFT, WEAK, FIFO, LRU, MRU, OSCACHE, EHCACHE)
配置方法：
templateCache=org.commontemplate.standard.cache.LRUCache()
templateCache.maxSize=1000
参考实现：
org.commontemplate.standard.cache包下相关类

4. 热加载控制
引擎在每次从缓存中返回模板之前都会回调ReloadController.shouldReload(String templateName)，
如果返回true，引擎将重新读取模板源，
并调用ResourceComparator.isModified(Resource oldSource, Resource newSource)进行比较，
若模板源已更改，则重新解析模板源并刷新缓存。
相关接口：
org.commontemplate.config.ReloadController
org.commontemplate.config.ResourceComparator
注册方法：
setReloadController(ReloadController)
setModificationCheckInterval(long) (注：使用内置的org.commontemplate.standard.reload.IntervalReloadController)
setResourceComparator(ResourceComparator)
配置方法：
reloadController.modificationCheckInterval=36000
参考实现：
org.commontemplate.standard.reload包下相关类

5. 模板名称过滤器扩展
在加载及缓存之前进行路径过滤，用于保证同一个模板的引用名称总是相同。
如：/xxx/yyy.mtl与/xxx/zzz/../yyy.mtl表示同一模板，但会被解析及缓存多次，所以应该用过滤器将其转换成相同的名称。
相关接口：
org.commontemplate.config.TemplateNameFilter
注册方法：
addTemplateNameFilter(TemplateNameFilter) (注：添加的TemplateNameFilter会按顺序组成过滤链)
配置方法：
templateNameFilters[200]=com.xxx.XxxFilter
参考实现：
org.commontemplate.standard.filter.TemplateNameRelativer (注：此过滤器过滤 ../ 和 ./ 等相对路径)

6. 模板源过滤器扩展
相关接口：
org.commontemplate.config.TemplateReaderFilter
注册方法：
addTemplateReaderFilter(TemplateReaderFilter)
配置方法：
templateReaderFilters[200]=com.xxx.XxxFilter
参考实现：
org.commontemplate.standard.webapp.AttributeSyntaxCoatFilter

7. 非指令文本块过滤器扩展
相关接口：
org.commontemplate.config.TextFilter
注册方法：
addTextFilter(TextFilter)
配置方法：
textFilters[200]=com.xxx.XxxFilter
参考实现：
org.commontemplate.standard.webapp.CommentSyntaxCoatFilter

8. 日志扩展
相关接口：
org.commontemplate.core.Logger
注册方法：
setLogger(Logger)
setCommonsLogging()
配置方法：
logger=org.commontemplate.standard.log.CommonsLogging()
参考实现：
org.commontemplate.core.Logger.DEFAULT
org.commontemplate.standard.log包下相关类

9. 事件监听与扩展
相关接口：
com.commontemplate.core.EventListener
com.commontemplate.core.Event
注册方法：
addEventListener(EventListener)
addAsynchronousEventListener(EventListener)
配置方法：
eventListeners[100]=com.xxx.XxxListener (注：下标号任意，只用于排序)
asynchronousEventListeners[100]=com.xxx.XxxListener
参考实现：
…
引擎发布的事件：
com.commontemplate.core.event包下相关类

10. 语法扩展
相关类：
org.commontemplate.config.Syntax (指令语法及特殊指令设置)
org.commontemplate.config.Keywords (表达式关键字设置)
注册方法：
setSyntax(Syntax)
setKeywords(Keywords)
配置方法：
syntaxString="${}#*!end"
keywordsString=null,true,false,this,super,context
默认使用：
Syntax.DEFAULT
Keywords.DEFAULT

11. 指令扩展
相关接口：
org.commontemplate.config.LineDirectiveHandler
org.commontemplate.config.StartDirectiveHandler
org.commontemplate.config.MiddleDirectiveHandler
注册方法：
addDirectiveHandler(String name, LineDirectiveHandler)
addDirectiveHandler(String name, StartDirectiveHandler)
(注：方法名重载，用于表明Line, Start, Middle等指令注册在同一个集合中，相互之间名称不能重复)
配置方法：
directive{xxx}=com.xxx.XXXDirective
参考实现：
org.commontemplate.standard.directive及其子包下相关类
注意事项：
DirectiveHandler应该保证线程安全，最简单的保证方式是：
(1) 若DirectiveHandler实现类中没有任何属性，则该实现类一定是线程安全的。
(2) 若DirectiveHandler实现类中所有属性都是final的(或只在构造函数中赋值)，则该实现类也是线程安全的。
(3) 正确同步所有属性修改。

12. 操作符扩展
相关接口：
org.commontemplate.config.BinaryOperatorHandler
org.commontemplate.config.UnaryOperatorHandler
注册方法：
addBinaryOperatorHandler(String name, BinaryOperatorHandler)
addUnaryOperatorHandler(String name, UnaryOperatorHandler)
addBinaryOperatorPriority(String name, int priority) (注：不设置将默认为0)
addUnaryOperatorPriority(String name, int priority) (注：不设置，符号型默认为0，名称型默认为functionPriority)
setFunctionPriority(int priority)
参考实现：
org.commontemplate.standard.operator及其子包下相关类
注意事项：
OperatorHandler应该保证线程安全，方式同上面的DirectiveHandler
OperatorHandler不应该改变操作数的状态，如：两个集合相加，应将两个集合的项添加到一个新的集合中，而不是将其中一个集合的项添加到另一个集合中。
特殊操作数：
(a) 操作数延迟求值：
用于短路情况，声明Lazy后，参数将以LazyOperand的实例传入，需使用operand = ((LazyOperand)operand).evaluate()方式取其真实值。
如：Boolean的And/Or操作，左操作数决定右操作数是否需要求值，就要用到RightOperandLazy。
相关标识：BinaryOperatorHandler.isLeftOperandLazy(), BinaryOperatorHandler.isRightOperandLazy(), UnaryOperatorHandler.isOperandLazy()
(b) 操作数名称化：
如果操作数为无引号字符串时，不将其作为变量取值，而作为字符串，
如：对象的属性${bean.property}，键值对的键${key:value}等，
与加号对比：bean + property，property将作为变量，而不是名称，
相关标识：BinaryOperatorHandler.isLeftOperandNamed(), BinaryOperatorHandler.isRightOperandNamed(), UnaryOperatorHandler.isOperandNamed()
(c) 操作数函数化：
如果操作数为函数时，不将其作为函数一元操作符运算，而作为org.commontemplate.util.Funtion封装，
如：对象的属性${bean.function()}
与加号对比：bean + function()，bean将与function()的返回值相加，
相关标识：BinaryOperatorHandler.isRightOperandFunctioned(), UnaryOperatorHandler.isOperandFunctioned()
关于函数：
函数其实就是非符号(与变量名规则相同)的一元操作符，注册及使用方式与一元操作符一致，
非符号一元操作符的操作数必需有括号，否则将视为变量，
如：已注册了“abs”一元操作符，则必需用abs(operand)，而不能用abs operand，否则在复杂表达式中与变量引起歧义，
对比：符号一元操作符“!”，可以用“! operand”，也可以用“!(operand)”

13. 属性扩展 (注：该扩展用于为"."点号操作符提供数据)
相关接口：
org.commontemplate.standard.property.PropertyHandler
org.commontemplate.standard.property.StaticPropertyHandler
注册方法：
addPropertyHandler(Class beanClass, String propertyName, PropertyHandler)
addStaticPropertyHandler(String propertyName, StaticPropertyHandler)
配置方法：
property{java.lang.String.xxx}=com.xxx.XXXPropertyHandler
staticProperty{xxx}=com.xxx.XXXPropertyHandler
参考实现：
org.commontemplate.standard.property包及其子包相关类

14. 方法扩展 (该扩展用于为"."点号操作符提供数据，并且只有在配置functionAvailable=true时才有效)
相关接口：
org.commontemplate.standard.function.FunctionHandler
org.commontemplate.standard.function.StaticFunctionHandler
注册方法：
addFunctionHandler(Class beanClass, String functionName, FunctionHandler)
addStaticFunctionHandler(String functionName, StaticFunctionHandler)
配置方法：
function{java.lang.String.xxx}=com.xxx.XXXFunctionHandler
staticFunction{xxx}=com.xxx.XXXFunctionHandler
参考实现：
org.commontemplate.standard.function包及其子包相关类

15. 序列扩展 (该扩展用于为".."双点号操作符提供数据)
相关接口：
org.commontemplate.standard.operator.sequence.StringSequenceOperatorHandler
org.commontemplate.standard.operator.sequence.StringSequence
注册方法：
addStringSequence(String[] sequence)
addStringSequence(String[] sequence, boolean cycle, boolean ignoreCase)
配置方法：
sequence<weekDays>=Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday
参考实现：
org.commontemplate.standard.operator.sequence包下相关类