org.rythmengine

Class RythmEngine

java.lang.Object

org.rythmengine.RythmEngine

All Implemented Interfaces:

IEventDispatcher

@Versioned
public class RythmEngine
extends Object
implements IEventDispatcher

Not Thread Safe

A Rythm Template Engine is the entry to the Rythm templating system. It provides a set of APIs to render template. Each JVM allows multiple RythmEngine instance, with each one represent a set of configurations.

The Rythm facade contains a default RythmEngine instance to make it easy to use for most cases

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RythmEngine.OutputMode Defines the output method for render result.
class	RythmEngine.RenderSettings Define the render time settings, which is intialized each time a renderXX method get called
static class	RythmEngine.TemplateTestResult Transport Template Test Result especially if there was an error thrown

Field Summary

Fields

Modifier and Type	Field and Description
RythmEngine.RenderSettings	renderSettings The RenderSettings instance keep the environment settings for one render operation
static String[]	VALID_SUFFIXES Valid Suffixes
static osgl.version.Version	VERSION

Constructor Summary

Constructors

Constructor and Description
RythmEngine() Create a rythm engine instance with default configuration
RythmEngine(File file) Create a rythm engine instance with either template root or configuration file specified
RythmEngine(Map<String,?> userConfiguration) Create a rythm engine instance with user supplied configuration data
RythmEngine(Properties userConfiguration)

Method Summary

Modifier and Type	Method and Description
Object	accept(IEvent event, Object param) Not an API for user application
void	addExtendRelationship(TemplateClass parent, TemplateClass child) Not an API for user application
void	cache(String key, Object o, int ttl, Object... args) Cache object using key and args for ttl seconds
void	cache(String key, Object o, String duration, Object... args) Store object o into cache service with ttl equals to duration specified.
Serializable	cached(String key, Object... args) Get cached value using key and a list of argument values
TemplateClassCache	classCache() Get class cache of the engine
TemplateClassManager	classes() Get template class manager of the engine
TemplateClassLoader	classLoader() Get class loader of the engine
static void	clear() Clear the engine threadlocal variable
String	commonsToString(Object obj, ToStringOption option, org.apache.commons.lang3.builder.ToStringStyle style) Render template in AutoToString mode by one object instance which state is to be output and option and apache commons to string stype.
RythmConfiguration	conf() Return configuration of the engine
IDateFormatFactory	dateFormatFactory()
DialectManager	dialectManager() Not an API
Object	eval(String script) Evaluate a script and return executing result.
Object	eval(String script, Map<String,Object> params)
Object	eval(String script, Object context, Map<String,Object> params)
IEventDispatcher	eventDispatcher()
void	evict(String key) Evict an object from cache service by key
ExtensionManager	extensionManager() Return ExtensionManager of this engine
static RythmEngine	get() Get the current engine instance from a ThreadLocal variable which is set previously.
String	getId() Alias of id()
<T> T	getProperty(String key) Get user property by key
ITemplate	getRegisteredTemplate(String tmplName) Get a template registered to the engine by name
TemplateClass	getRegisteredTemplateClass(String name) Return TemplateClass from a tag name
ITemplate	getTemplate(File file, Object... args) Get an new template instance by template source file and an array of arguments.
ITemplate	getTemplate(String template, Object... args) Get an new template instance from a String and an array of render args.
TemplateClass	getTemplateClass(ITemplateResource resource) (3rd party API, not for user application) Get an new template class by template resource
String	id() Return the instance ID
static boolean	insideSandbox() Check if the current rendering is dominated by a Sandbox
void	invalidate(TemplateClass parent) Not an API for user application
void	invokeTemplate(int line, String name, ITemplate caller, ITag.__ParameterList params, ITag.__Body body, ITag.__Body context) Invoke a template
void	invokeTemplate(int line, String name, ITemplate caller, ITag.__ParameterList params, ITag.__Body body, ITag.__Body context, boolean ignoreNonExistsTag) Invoke a tag
boolean	isDevMode() Is the engine running in development mode?
boolean	isProdMode() Is the engine running in product mode?
boolean	isSingleton() Is this engine the default Rythm.engine instance?
Rythm.Mode	mode() Return the engine mode
static RythmEngine.OutputMode	outputMode() Not an API.
RythmEngine	prepare(ICodeType codeType) Prepare the render operation environment settings
RythmEngine	prepare(ICodeType codeType, Locale locale, Map<String,Object> usrCtx) Prepare the render operation environment settings
RythmEngine	prepare(Locale locale) Prepare the render operation environment settings
RythmEngine	prepare(Map<String,Object> userContext) Prepare the render operation environment settings
void	registerFastTag(JavaTagBase tag)
void	registerFormatter(Class<IFormatter>... formatterClasses) Register formatters
void	registerFormatter(IFormatter... formatters)
void	registerPropertyAccessor(IPropertyAccessor... accessors) Register user implemented IPropertyAccessor
void	registerResourceLoader(ITemplateResourceLoader... loaders)
void	registerTemplate(ITemplate template) Register a template.
void	registerTemplate(String name, ITemplate template) Register a tag using the given name
RythmEngine	registerTemplateClass(TemplateClass tc) Register a template class and return self
void	registerTransformer(Class<?>... transformerClasses) Register transformers using namespace specified in the namespace value defined in the annotation.
void	registerTransformer(String namespace, String waivePattern, Class<?>... transformerClasses) Register transformers using namespace specified to replace the namespace value defined in the annotation.
String	render(File file, Object... args) Render template with source specified by file instance and an array of render args.
void	render(OutputStream os, File file, Object... args) Render template with source specified by file instance and an array of render args.
void	render(OutputStream os, String template, Object... args) Render template by string parameter and an array of template args.
String	render(String template, Object... args) Render template by string parameter and an array of template args.
void	render(Writer w, File file, Object... args) Render template with source specified by file instance and an array of render args.
void	render(Writer w, String template, Object... args) Render template by string parameter and an array of template args.
static void	renderCleanUp()
String	renderIfTemplateExists(String template, Object... args) Render template if specified template exists, otherwise return empty string
String	renderStr(String template, Object... args) Render template by string typed inline template content and an array of template args.
String	renderStr(String key, String template, Object... args) Render template by string typed inline template content and an array of template args.
String	renderString(String template, Object... args) Render result from a direct template content.
String	renderString(String key, String template, Object... args) Render result from a direct template content.
TemplateResourceManager	resourceManager() Get resource manager of the engine
void	restart(RuntimeException cause) Restart the engine with an exception as the cause.
Sandbox	sandbox() Create a Sandbox instance to render the template
Sandbox	sandbox(Map<String,Object> context) Create a Sandbox instance with user supplied context
static boolean	set(RythmEngine engine) Set the engine instance to a ThreadLocal variable, thus it is easy to get the current RythmEngine dominating the rendering process.
void	setDateFormatFactory(IDateFormatFactory factory)
void	setProperty(String key, Object val) Set user property to the engine.
void	shutdown() Shutdown this rythm engine
String	substitute(File file, Object... args) Render template in substitute mode by File typed template source and an array of render args.
String	substitute(String template, Object... args) Render template in substitute mode by string typed template source and an array of render args.
boolean	templateRegistered(String tmplName) Whether a template is registered to the engine by name specified
RythmEngine.TemplateTestResult	testTemplate(String name, TemplateClass callerClass, ICodeType codeType) Check if a template exists and return it’s name
String	toString()
String	toString(Object obj) Render template in AutoToString mode by one object instance which state is to be output.
String	toString(Object obj, ToStringOption option, ToStringStyle style) Render template in AutoToString mode by one object instance which state is to be output and option and stype.
String	toString(String template, Object obj) Render template in ToString mode by string typed template source and one object instance which state is to be output.
String	version() Return Version string of the engine instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

VERSION

public static final osgl.version.Version VERSION

renderSettings

public RythmEngine.RenderSettings renderSettings

The RenderSettings instance keep the environment settings for one render operation

VALID_SUFFIXES

public static final String[] VALID_SUFFIXES

Valid Suffixes

Constructor Detail

RythmEngine

public RythmEngine()

Create a rythm engine instance with default configuration

See Also:

RythmConfigurationKey

RythmEngine

public RythmEngine(File file)

Create a rythm engine instance with either template root or configuration file specified

Parameters:

file - if is directory then the template root, otherwise then the configuration file

See Also:

RythmConfigurationKey

RythmEngine

public RythmEngine(Properties userConfiguration)

RythmEngine

public RythmEngine(Map<String,?> userConfiguration)

Create a rythm engine instance with user supplied configuration data

Parameters:

userConfiguration -

See Also:

RythmConfigurationKey

Method Detail

set

public static boolean set(RythmEngine engine)

Set the engine instance to a ThreadLocal variable, thus it is easy to get the current RythmEngine dominating the rendering process.

Note, this method is NOT an API to be called by user application

Parameters:

engine -

Returns:

true if engine instance set to the threadlocal, false if the threadlocal has set an instance already

clear

public static void clear()

Clear the engine threadlocal variable

get

public static RythmEngine get()

Get the current engine instance from a ThreadLocal variable which is set previously.

Note, this method is NOT an API to be called by user application

Returns:

the engine

insideSandbox

public static boolean insideSandbox()

Check if the current rendering is dominated by a Sandbox

Note, this method is NOT an API to be called by user application

Returns:

true if the current thread is running in Sandbox mode

toString

public String toString()

Overrides:

toString in class Object

conf

public RythmConfiguration conf()

Return configuration of the engine

Usually user application should not call this method

Returns:

rythm configuration

version

public String version()

Return Version string of the engine instance. The version string is composed by Rythm version and the configured plugin version. The version string will be used by Rythm to see if compiled bytecodes cached on disk should be refreshed in an new version or not.

Note, this method is not generally used by user application

Returns:

engine version along with plugin version

mode

public Rythm.Mode mode()

Return the engine mode

Returns:

engine running mode

id

public String id()

Return the instance ID

Returns:

the engine id

getId

public String getId()

Alias of id()

Returns:

the engine id

isSingleton

public boolean isSingleton()

Is this engine the default Rythm.engine instance?

Note, not to be used by user application

Returns:

true if this is the default engine

isProdMode

public boolean isProdMode()

Is the engine running in product mode?

Returns:

true if engine is running in prod mode

isDevMode

public boolean isDevMode()

Is the engine running in development mode?

Returns:

true if engine is running is debug mode

resourceManager

public TemplateResourceManager resourceManager()

Get resource manager of the engine

Note, this method should not be used by user application

Returns:

resource manager

classes

public TemplateClassManager classes()

Get template class manager of the engine

Note, this method should not be used by user application

Returns:

template class manager

classLoader

public TemplateClassLoader classLoader()

Get class loader of the engine

Note, this method should not be used by user application

Returns:

template class loader

classCache

public TemplateClassCache classCache()

Get class cache of the engine

Note, this method should not be used by user application

Returns:

template class cache

extensionManager

public ExtensionManager extensionManager()

Return ExtensionManager of this engine

Returns:

extension manager

dialectManager

public DialectManager dialectManager()

Not an API

Returns:

DialectManager instance

setDateFormatFactory

public void setDateFormatFactory(IDateFormatFactory factory)

dateFormatFactory

public IDateFormatFactory dateFormatFactory()

prepare

public final RythmEngine prepare(ICodeType codeType,
                                 Locale locale,
                                 Map<String,Object> usrCtx)

Prepare the render operation environment settings

Parameters:

codeType -

locale -

usrCtx -

Returns:

the engine instance itself

prepare

public final RythmEngine prepare(ICodeType codeType)

Prepare the render operation environment settings

Parameters:

codeType -

Returns:

the engine instance itself

prepare

public final RythmEngine prepare(Locale locale)

Prepare the render operation environment settings

Parameters:

locale -

Returns:

the engine instance itself

prepare

public final RythmEngine prepare(Map<String,Object> userContext)

Prepare the render operation environment settings

Parameters:

userContext -

Returns:

the engine instance itself

setProperty

public void setProperty(String key,
                        Object val)

Set user property to the engine. Note The property is not used by the engine program it’s purely a place for user to add any tags or properties to the engine and later get fetched out and use in the user application

Parameters:

key -

val -

getProperty

public <T> T getProperty(String key)

Get user property by key

Type Parameters:

T -

Parameters:

key -

Returns:

the property being cast to type T

registerFormatter

public void registerFormatter(Class<IFormatter>... formatterClasses)

Register formatters

Parameters:

formatterClasses -

registerFormatter

public void registerFormatter(IFormatter... formatters)

registerTransformer

public void registerTransformer(Class<?>... transformerClasses)

Register transformers using namespace specified in the namespace value defined in the annotation.

Parameters:

transformerClasses -

registerTransformer

public void registerTransformer(String namespace,
                                String waivePattern,
                                Class<?>... transformerClasses)

Register transformers using namespace specified to replace the namespace value defined in the annotation.

Parameters:

transformerClasses -

registerPropertyAccessor

public void registerPropertyAccessor(IPropertyAccessor... accessors)

Register user implemented IPropertyAccessor

Parameters:

accessors -

registerResourceLoader

public void registerResourceLoader(ITemplateResourceLoader... loaders)

getTemplate

public ITemplate getTemplate(String template,
                             Object... args)

Get an new template instance from a String and an array of render args. The string parameter could be either a template file path or the inline template source content.

When the args array contains only one element and is of Map type the the render args are passed to template by name, otherwise they passes to template instance by position

Parameters:

template -

args -

Returns:

template instance

getTemplateClass

public TemplateClass getTemplateClass(ITemplateResource resource)

(3rd party API, not for user application) Get an new template class by template resource

Parameters:

resource - the template resource

Returns:

template class

getTemplate

public ITemplate getTemplate(File file,
                             Object... args)

Get an new template instance by template source file and an array of arguments.

When the args array contains only one element and is of Map type the the render args are passed to template by name, otherwise they passes to template instance by position

Parameters:

file - the template source file

args - the render args. See getTemplate(String, Object...)

Returns:

template instance

render

public String render(String template,
                     Object... args)

Render template by string parameter and an array of template args. The string parameter could be either a path point to the template source file, or the inline template source content. The render result is returned as a String

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

template - either the path of template source file or inline template content

args - render args array

Returns:

render result

render

public void render(OutputStream os,
                   String template,
                   Object... args)

Render template by string parameter and an array of template args. The string parameter could be either a path point to the template source file, or the inline template source content. The render result is output to the specified binary output stream

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

os - the output stream

template - either the path of template source file or inline template content

args - render args array

render

public void render(Writer w,
                   String template,
                   Object... args)

Render template by string parameter and an array of template args. The string parameter could be either a path point to the template source file, or the inline template source content. The render result is output to the specified character based writer

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

w - the writer

template - either the path of template source file or inline template content

args - render args array

render

public String render(File file,
                     Object... args)

Render template with source specified by file instance and an array of render args. Render result return as a String

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

file - the template source file

args - render args array

Returns:

render result

render

public void render(OutputStream os,
                   File file,
                   Object... args)

Render template with source specified by file instance and an array of render args. Render result output into the specified binary OutputStream

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

os - the output stream

file - the template source file

args - render args array

render

public void render(Writer w,
                   File file,
                   Object... args)

Render template with source specified by file instance and an array of render args. Render result output into the specified binary Writer

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

w - the writer

file - the template source file

args - render args array

renderStr

public String renderStr(String key,
                        String template,
                        Object... args)

Render template by string typed inline template content and an array of template args. The render result is returned as a String

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

template - the inline template content

args - the render args array

Returns:

render result

renderStr

public String renderStr(String template,
                        Object... args)

Render template by string typed inline template content and an array of template args. The render result is returned as a String

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

template - the inline template content

args - the render args array

Returns:

render result

renderString

public String renderString(String template,
                           Object... args)

Render result from a direct template content. The content will also be used as the template key to generate the recommended class name

Parameters:

template - the template content

args - the render args

Returns:

render result

renderString

public String renderString(String key,
                           String template,
                           Object... args)

Render result from a direct template content. The template key has been provided as well

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

key - the template key which will be used to generate

template - the inline template content

args - the render args array

Returns:

render result

substitute

public String substitute(String template,
                         Object... args)

Render template in substitute mode by string typed template source and an array of render args. The string parameter could be either a path point to the template source file, or the inline template source content. Return render result as String

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

template - either the template source file path or the inline template content

args - the render args array

Returns:

render result

substitute

public String substitute(File file,
                         Object... args)

Render template in substitute mode by File typed template source and an array of render args. Return render result as String

See getTemplate(java.io.File, Object...) for note on render args

Parameters:

file - the template source file

args - the render args array

Returns:

render result

toString

public String toString(String template,
                       Object obj)

Render template in ToString mode by string typed template source and one object instance which state is to be output. The string parameter could be either a path point to the template source file, or the inline template source content. Return render result as String

Parameters:

template - either the template source file path or the inline template content

obj - the object instance which state is to be output as a string

Returns:

render result

toString

public String toString(Object obj)

Render template in AutoToString mode by one object instance which state is to be output. Return render result as String

Parameters:

obj - the object instance which state is to be output as a string

Returns:

render result

toString

public String toString(Object obj,
                       ToStringOption option,
                       ToStringStyle style)

Render template in AutoToString mode by one object instance which state is to be output and option and stype. Return render result as String

Parameters:

obj - the object instance which state is to be output as a string

option - the output option

style - the output style

Returns:

render result

commonsToString

public String commonsToString(Object obj,
                              ToStringOption option,
                              org.apache.commons.lang3.builder.ToStringStyle style)

Render template in AutoToString mode by one object instance which state is to be output and option and apache commons to string stype. Return render result as String

Parameters:

obj - the object instance which state is to be output as a string

option - the output option

style - the output style specified as apache commons ToStringStyle

Returns:

render result

renderIfTemplateExists

public String renderIfTemplateExists(String template,
                                     Object... args)

Render template if specified template exists, otherwise return empty string

Parameters:

template - the template source path

args - render args. See getTemplate(String, Object...)

Returns:

render result

eval

public Object eval(String script)

Evaluate a script and return executing result. Note the API is not mature yet don’t use it in your application

Parameters:

script -

Returns:

the result

eval

public Object eval(String script,
                   Map<String,Object> params)

eval

public Object eval(String script,
                   Object context,
                   Map<String,Object> params)

templateRegistered

public boolean templateRegistered(String tmplName)

Whether a template is registered to the engine by name specified

Not an API for user application

Parameters:

tmplName -

Returns:

true if there is a template with the name specified

getRegisteredTemplate

public ITemplate getRegisteredTemplate(String tmplName)

Get a template registered to the engine by name

Not an API for user application

Parameters:

tmplName -

Returns:

the template instance

getRegisteredTemplateClass

public TemplateClass getRegisteredTemplateClass(String name)

Return TemplateClass from a tag name

Not an API for user application

Parameters:

name -

Returns:

template class

registerTemplateClass

public RythmEngine registerTemplateClass(TemplateClass tc)

Register a template class and return self

Parameters:

tc -

Returns:

this engine instance

testTemplate

public RythmEngine.TemplateTestResult testTemplate(String name,
                                                   TemplateClass callerClass,
                                                   ICodeType codeType)

Check if a template exists and return it’s name

Not an API for user application

Parameters:

name -

callerClass -

Returns:

the result including the callers name

registerFastTag

public void registerFastTag(JavaTagBase tag)

registerTemplate

public void registerTemplate(ITemplate template)

Register a template.

Not an API for user application

registerTemplate

public void registerTemplate(String name,
                             ITemplate template)

Register a tag using the given name

Not an API for user application

Parameters:

name -

template -

invokeTemplate

public void invokeTemplate(int line,
                           String name,
                           ITemplate caller,
                           ITag.__ParameterList params,
                           ITag.__Body body,
                           ITag.__Body context)

Invoke a template

Not an API for user application

Parameters:

line -

name -

caller -

params -

body -

context -

invokeTemplate

public void invokeTemplate(int line,
                           String name,
                           ITemplate caller,
                           ITag.__ParameterList params,
                           ITag.__Body body,
                           ITag.__Body context,
                           boolean ignoreNonExistsTag)

Invoke a tag

Not an API for user application

Parameters:

line -

name -

caller -

params -

body -

context -

ignoreNonExistsTag -

cache

public void cache(String key,
                  Object o,
                  int ttl,
                  Object... args)

Cache object using key and args for ttl seconds

Not an API for user application

Parameters:

key -

o -

ttl - if zero then defaultTTL used, if negative then never expire

args -

cache

public void cache(String key,
                  Object o,
                  String duration,
                  Object... args)

Store object o into cache service with ttl equals to duration specified.

The duration is a string to be parsed by @{link #durationParser}

The object o is associated with given key and a list of argument values

Not an API for user application

Parameters:

key -

o -

duration -

args -

evict

public void evict(String key)

Evict an object from cache service by key

Parameters:

key - identify the object should be removed from cache service

cached

public Serializable cached(String key,
                           Object... args)

Get cached value using key and a list of argument values

Not an API for user application

Parameters:

key -

args -

Returns:

cached item

addExtendRelationship

public void addExtendRelationship(TemplateClass parent,
                                  TemplateClass child)

Not an API for user application

Parameters:

parent -

child -

invalidate

public void invalidate(TemplateClass parent)

Not an API for user application

Parameters:

parent -

sandbox

public Sandbox sandbox()

Create a Sandbox instance to render the template

Returns:

an new sandbox instance

sandbox

public Sandbox sandbox(Map<String,Object> context)

Create a Sandbox instance with user supplied context

Parameters:

context -

Returns:

an new sandbox instance

eventDispatcher

public IEventDispatcher eventDispatcher()

accept

public Object accept(IEvent event,
                     Object param)

Not an API for user application

Specified by:

accept in interface IEventDispatcher

Parameters:

event -

param -

Returns:

event handler process result

outputMode

public static RythmEngine.OutputMode outputMode()

Not an API.

Returns:

output mode

renderCleanUp

public static void renderCleanUp()

restart

public void restart(RuntimeException cause)

Restart the engine with an exception as the cause.

Note, this is not supposed to be called by user application

Parameters:

cause -

shutdown

public void shutdown()

Shutdown this rythm engine