org.rythmengine
Class RythmEngine

java.lang.Object
  extended by org.rythmengine.RythmEngine
All Implemented Interfaces:
IEventDispatcher

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
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
 
Field Summary
 RythmEngine.RenderSettings renderSettings
          The RenderSettings instance keep the environment settings for one render operation
 
Constructor Summary
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
 Object accept(IEvent event, Object param)
          Not an API for user application
 void addExtendRelationship(org.rythmengine.internal.compiler.TemplateClass parent, org.rythmengine.internal.compiler.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

 org.rythmengine.internal.compiler.TemplateClassCache classCache()
          Get class cache of the engine

 org.rythmengine.internal.compiler.TemplateClassManager classes()
          Get template class manager of the engine

 org.rythmengine.internal.compiler.TemplateClassLoader classLoader()
          Get class loader of the engine

 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

 org.rythmengine.internal.dialect.DialectManager dialectManager()
          Not an API
 Object eval(String script)
          Evaluate a script and return executing result.
 Object eval(String script, Map<String,Object> context)
           
 IEventDispatcher eventDispatcher()
           
 ExtensionManager extensionManager()
          Return ExtensionManager of this engine
static RythmEngine get()
          Get the current engine instance from a ThreadLocal variable which is set previously.
<T> T
getProperty(String key)
          Get user property by key
 ITemplate getRegisteredTemplate(String tmplName)
          Get a template registered to the engine by name

 org.rythmengine.internal.compiler.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.
 org.rythmengine.internal.compiler.TemplateClass getTemplateClass(ITemplateResource resource)
          (3rd party API, not for user application) Get an new template class by template resource
 String id()
          Return the instance RythmConfigurationKey.ENGINE_ID
static boolean insideSandbox()
          Check if the current rendering is dominated by a Sandbox

 void invalidate(org.rythmengine.internal.compiler.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 registerPropertyAccessor(IPropertyAccessor... accessors)
          Register user implemented IPropertyAccessor
 void registerTemplate(ITemplate template)
          Register a template.
 void registerTemplate(String name, ITemplate template)
          Register a tag using the given name

 RythmEngine registerTemplateClass(org.rythmengine.internal.compiler.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.
 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 renderString(String template, Object... args)
          Alias of renderString(String, Object...)

 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 void 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 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

 String testTemplate(String name, org.rythmengine.internal.compiler.TemplateClass callerClass)
          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

renderSettings

public RythmEngine.RenderSettings renderSettings
The RenderSettings instance keep the environment settings for one render operation

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 void 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 -

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 RythmConfigurationKey.ENGINE_ID

Returns:
the 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 org.rythmengine.internal.compiler.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 org.rythmengine.internal.compiler.TemplateClassLoader classLoader()
Get class loader of the engine

Note, this method should not be used by user application

Returns:
template class loader

classCache

public org.rythmengine.internal.compiler.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 org.rythmengine.internal.dialect.DialectManager dialectManager()
Not an API

Returns:
DialectManager instance

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

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 -

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 org.rythmengine.internal.compiler.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 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)
Alias of renderString(String, Object...)

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

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> context)

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 org.rythmengine.internal.compiler.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(org.rythmengine.internal.compiler.TemplateClass tc)
Register a template class and return self

Parameters:
tc -
Returns:
this engine instance

testTemplate

public String testTemplate(String name,
                           org.rythmengine.internal.compiler.TemplateClass callerClass)
Check if a template exists and return it's name

Not an API for user application

Parameters:
name -
callerClass -
Returns:
template 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 -

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(org.rythmengine.internal.compiler.TemplateClass parent,
                                  org.rythmengine.internal.compiler.TemplateClass child)
Not an API for user application

Parameters:
parent -
child -

invalidate

public void invalidate(org.rythmengine.internal.compiler.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

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



Copyright © 2013. All Rights Reserved.