public class RuntimeInstance extends java.lang.Object implements RuntimeConstants, RuntimeServices
This is the Runtime system for Velocity. It is the single access point for all functionality in Velocity. It adheres to the mediator pattern and is the only structure that developers need to be familiar with in order to get Velocity to perform.
The Runtime will also cooperate with external systems, which can make all needed setProperty() calls before calling init().
----------------------------------------------------------------------- N O T E S O N R U N T I M E I N I T I A L I Z A T I O N ----------------------------------------------------------------------- init() If init() is called by itself the RuntimeInstance will initialize with a set of default values. ----------------------------------------------------------------------- init(String/Properties) In this case the default velocity properties are layed down first to provide a solid base, then any properties provided in the given properties object will override the corresponding default property. -----------------------------------------------------------------------
RuntimeConstants.SpaceGobbling
Modifier and Type | Field and Description |
---|---|
private java.util.Map<java.lang.Object,java.lang.Object> |
applicationAttributes
Opaque reference to something specified by the
application for use in application supplied/specified
pluggable components
|
private ExtProperties |
configuration
Object that houses the configuration options for
the velocity runtime.
|
private java.lang.String |
defaultEncoding
Default encoding
|
private java.util.Set<java.lang.String> |
enabledScopeControls
Scope names for which to provide scope control objects in the context
|
private java.lang.String |
evaluateScopeName
Scope name for evaluate(...) calls.
|
private EventCartridge |
eventCartridge
This stores the engine-wide set of event handlers.
|
private boolean |
hyphenAllowedInIdentifiers
Whether hyphen is allowed in identifiers
|
private boolean |
initialized
Indicate whether the Runtime has been fully initialized.
|
private boolean |
initializing
Indicate whether the Runtime is in the midst of initialization.
|
private org.slf4j.Logger |
log
The Runtime logger.
|
private LogContext |
logContext
The LogContext object used to track location in templates
|
private ExtProperties |
overridingProperties
These are the properties that are laid down over top
of the default properties when requested.
|
private ParserConfiguration |
parserConfiguration
Configured replacement characters in parser grammar
|
private java.lang.reflect.Constructor<? extends Parser> |
parserConstructor
Configured parser class
|
private ParserPool |
parserPool
The Runtime parser pool
|
private ResourceManager |
resourceManager |
private java.util.Map<java.lang.String,Directive> |
runtimeDirectives
This is a hashtable of initialized directives.
|
private java.util.Map<java.lang.String,Directive> |
runtimeDirectivesShared
Copy of the actual runtimeDirectives that is shared between
parsers.
|
private RuntimeConstants.SpaceGobbling |
spaceGobbling
Space gobbling mode
|
private boolean |
stringInterning
Whether to use string interning
|
private Uberspect |
uberSpect
Uberspector
|
private VelocimacroFactory |
vmFactory
VelocimacroFactory object to manage VMs
|
CHECK_EMPTY_OBJECTS, CONTEXT_AUTOREFERENCE_KEY, CONTEXT_SCOPE_CONTROL, CONVERSION_HANDLER_CLASS, CONVERSION_HANDLER_INSTANCE, CUSTOM_DIRECTIVES, DEFAULT_PARSER_CLASS, DEFAULT_RUNTIME_DIRECTIVES, DEFAULT_RUNTIME_LOG_NAME, DEFAULT_RUNTIME_PROPERTIES, DEFINE_DIRECTIVE_MAXDEPTH, DS_RESOURCE_LOADER_DATASOURCE, DS_RESOURCE_LOADER_KEY_COLUMN, DS_RESOURCE_LOADER_TABLE, DS_RESOURCE_LOADER_TEMPLATE_COLUMN, DS_RESOURCE_LOADER_TIMESTAMP_COLUMN, ENCODING_DEFAULT, ERRORMSG_END, ERRORMSG_START, EVENTHANDLER_INCLUDE, EVENTHANDLER_INVALIDREFERENCES, EVENTHANDLER_INVALIDREFERENCES_NULL, EVENTHANDLER_INVALIDREFERENCES_QUIET, EVENTHANDLER_INVALIDREFERENCES_TESTED, EVENTHANDLER_METHODEXCEPTION, EVENTHANDLER_REFERENCEINSERTION, FILE_RESOURCE_LOADER_CACHE, FILE_RESOURCE_LOADER_PATH, INPUT_ENCODING, INTERPOLATE_STRINGLITERALS, INTROSPECTOR_RESTRICT_CLASSES, INTROSPECTOR_RESTRICT_PACKAGES, MAX_NUMBER_LOOPS, NUMBER_OF_PARSERS, PARSE_DIRECTIVE_MAXDEPTH, PARSER_CLASS, PARSER_HYPHEN_ALLOWED, PARSER_POOL_CLASS, PARSER_POOL_SIZE, PROVIDE_SCOPE_CONTROL, RESOURCE_LOADER, RESOURCE_LOADER_CACHE, RESOURCE_LOADER_CHECK_INTERVAL, RESOURCE_LOADER_CLASS, RESOURCE_LOADER_IDENTIFIER, RESOURCE_LOADER_INSTANCE, RESOURCE_LOADER_PATHS, RESOURCE_LOADERS, RESOURCE_MANAGER_CACHE_CLASS, RESOURCE_MANAGER_CLASS, RESOURCE_MANAGER_DEFAULTCACHE_SIZE, RESOURCE_MANAGER_INSTANCE, RESOURCE_MANAGER_LOGWHENFOUND, RUNTIME_LOG_INSTANCE, RUNTIME_LOG_METHOD_CALL_LOG_INVALID, RUNTIME_LOG_NAME, RUNTIME_LOG_REFERENCE_LOG_INVALID, RUNTIME_LOG_TRACK_LOCATION, RUNTIME_REFERENCES_STRICT, RUNTIME_REFERENCES_STRICT_ESCAPE, RUNTIME_STRING_INTERNING, SKIP_INVALID_ITERATOR, SPACE_GOBBLING, STRICT_MATH, UBERSPECT_CLASSNAME, VM_ARGUMENTS_STRICT, VM_BODY_REFERENCE, VM_ENABLE_BC_MODE, VM_LIBRARY, VM_LIBRARY_AUTORELOAD, VM_LIBRARY_DEFAULT, VM_MAX_DEPTH, VM_MESSAGES_ON, VM_PERM_ALLOW_INLINE, VM_PERM_ALLOW_INLINE_REPLACE_GLOBAL, VM_PERM_INLINE_LOCAL
OLD_CHECK_EMPTY_OBJECTS, OLD_CONTEXT_AUTOREFERENCE_KEY, OLD_CONVERSION_HANDLER_CLASS, OLD_CUSTOM_DIRECTIVES, OLD_DEFINE_DIRECTIVE_MAXDEPTH, OLD_DS_RESOURCE_LOADER_DATASOURCE, OLD_DS_RESOURCE_LOADER_KEY_COLUMN, OLD_DS_RESOURCE_LOADER_TEMPLATE_COLUMN, OLD_DS_RESOURCE_LOADER_TIMESTAMP_COLUMN, OLD_ERRORMSG_END, OLD_ERRORMSG_START, OLD_EVENTHANDLER_INCLUDE, OLD_EVENTHANDLER_INVALIDREFERENCES, OLD_EVENTHANDLER_METHODEXCEPTION, OLD_EVENTHANDLER_REFERENCEINSERTION, OLD_FILE_RESOURCE_LOADER_CACHE, OLD_FILE_RESOURCE_LOADER_PATH, OLD_INPUT_ENCODING, OLD_INTERPOLATE_STRINGLITERALS, OLD_MAX_NUMBER_LOOPS, OLD_PARSE_DIRECTIVE_MAXDEPTH, OLD_RESOURCE_LOADER_CHECK_INTERVAL, OLD_RESOURCE_LOADERS, OLD_RESOURCE_MANAGER_DEFAULTCACHE_SIZE, OLD_RESOURCE_MANAGER_LOGWHENFOUND, OLD_RUNTIME_LOG_REFERENCE_LOG_INVALID, OLD_RUNTIME_REFERENCES_STRICT, OLD_RUNTIME_REFERENCES_STRICT_ESCAPE, OLD_SKIP_INVALID_ITERATOR, OLD_SPACE_GOBBLING, OLD_STRICT_MATH, OLD_UBERSPECT_CLASSNAME, OLD_VM_BODY_REFERENCE, OLD_VM_ENABLE_BC_MODE, OLD_VM_LIBRARY, OLD_VM_LIBRARY_DEFAULT, OLD_VM_MAX_DEPTH, OLD_VM_PERM_ALLOW_INLINE, OLD_VM_PERM_ALLOW_INLINE_REPLACE_GLOBAL, OLD_VM_PERM_INLINE_LOCAL
Constructor and Description |
---|
RuntimeInstance()
Creates a new RuntimeInstance object.
|
Modifier and Type | Method and Description |
---|---|
void |
addDirective(Directive directive)
Programatically add a directive.
|
void |
addProperty(java.lang.String key,
java.lang.Object value)
Add a property to the configuration.
|
boolean |
addVelocimacro(java.lang.String name,
Node macro,
java.util.List<Macro.MacroArg> macroArgs,
Template definingTemplate)
Adds a new Velocimacro.
|
void |
clearProperty(java.lang.String key)
Clear the values pertaining to a particular
property.
|
Parser |
createNewParser()
Returns a JavaCC generated Parser.
|
boolean |
evaluate(Context context,
java.io.Writer writer,
java.lang.String logTag,
java.io.Reader reader)
Renders the input reader using the context into the output writer.
|
boolean |
evaluate(Context context,
java.io.Writer out,
java.lang.String logTag,
java.lang.String instring)
Renders the input string using the context into the output writer.
|
java.lang.Object |
getApplicationAttribute(java.lang.Object key)
Gets the application attribute for the given key
|
EventCartridge |
getApplicationEventCartridge()
Returns the event handlers for the application.
|
boolean |
getBoolean(java.lang.String key,
boolean def)
Boolean property accessor method to hide the configuration implementation.
|
ExtProperties |
getConfiguration()
Return the velocity runtime configuration object.
|
private char |
getConfiguredCharacter(java.lang.String configKey,
char defaultChar) |
ContentResource |
getContent(java.lang.String name)
Returns a static content resource from the
resource manager.
|
ContentResource |
getContent(java.lang.String name,
java.lang.String encoding)
Returns a static content resource from the
resource manager.
|
private java.lang.String |
getDefaultEncoding()
Retrieves and caches the configured default encoding
for better performance.
|
Directive |
getDirective(java.lang.String name)
Retrieve a previously instantiated directive.
|
int |
getInt(java.lang.String key)
Int property accessor method to hide the configuration implementation.
|
int |
getInt(java.lang.String key,
int defaultValue)
Int property accessor method to hide the configuration implementation.
|
java.lang.String |
getLoaderNameForResource(java.lang.String resourceName)
Determines if a template exists and returns name of the loader that
provides it.
|
org.slf4j.Logger |
getLog()
Returns the configured logger.
|
org.slf4j.Logger |
getLog(java.lang.String childNamespace)
Get a logger for the specified child namespace.
|
LogContext |
getLogContext()
Get the LogContext object used to tack locations in templates.
|
ParserConfiguration |
getParserConfiguration()
Get the replacement characters configured for this runtime service's parser
|
java.lang.Object |
getProperty(java.lang.String key)
Allows an external caller to get a property.
|
RuntimeConstants.SpaceGobbling |
getSpaceGobbling()
get space gobbling mode
|
java.lang.String |
getString(java.lang.String key)
String property accessor method to hide the configuration implementation
|
java.lang.String |
getString(java.lang.String key,
java.lang.String defaultValue)
String property accessor method with default to hide the
configuration implementation.
|
Template |
getTemplate(java.lang.String name)
Returns a
Template from the resource manager. |
Template |
getTemplate(java.lang.String name,
java.lang.String encoding)
Returns a
Template from the resource manager |
Uberspect |
getUberspect()
Returns the Uberspect object for this Instance.
|
Directive |
getVelocimacro(java.lang.String vmName,
Template renderingTemplate,
Template template)
Returns the appropriate VelocimacroProxy object if vmName
is a valid current Velocimacro.
|
void |
init()
This is the primary initialization method in the Velocity
Runtime.
|
void |
init(java.util.Properties p)
Initialize the Velocity Runtime with a Properties
object.
|
void |
init(java.lang.String configurationFile)
Initialize the Velocity Runtime with a
properties file path.
|
private void |
initializeDirectives()
This methods initializes all the directives
that are used by the Velocity Runtime.
|
private void |
initializeEventHandlers() |
private void |
initializeIntrospection()
Gets the classname for the Uberspect introspection package and
instantiates an instance.
|
private void |
initializeLog()
Initialize the Velocity logging system.
|
private void |
initializeParserPool()
Initializes the Velocity parser pool.
|
private void |
initializeProperties()
Initialize Velocity properties, if the default
properties have not been laid down first then
do so.
|
private void |
initializeResourceManager() |
private void |
initializeScopeSettings() |
private void |
initializeSelfProperties()
Initialize runtime internal properties
|
private EventHandler |
initializeSpecificEventHandler(java.lang.String classname,
java.lang.String paramName,
java.lang.Class<?> EventHandlerInterface) |
boolean |
invokeVelocimacro(java.lang.String vmName,
java.lang.String logTag,
java.lang.String[] params,
Context context,
java.io.Writer writer)
Invokes a currently registered Velocimacro with the params provided
and places the rendered stream into the writer.
|
boolean |
isHyphenAllowedInIdentifiers()
get whether hyphens are allowed in identifiers
|
boolean |
isInitialized()
Returns true if the RuntimeInstance has been successfully initialized.
|
boolean |
isScopeControlEnabled(java.lang.String scopeName)
Get whether to provide a scope control object for this scope
|
boolean |
isVelocimacro(java.lang.String vmName,
Template template)
Checks to see if a VM exists
|
void |
loadDirective(java.lang.String directiveClass)
instantiates and loads the directive with some basic checks
|
SimpleNode |
parse(java.io.Reader reader,
Template template)
Parse the input and return the root of
AST node structure.
|
void |
removeDirective(java.lang.String name)
Remove a directive.
|
boolean |
render(Context context,
java.io.Writer writer,
java.lang.String logTag,
SimpleNode nodeTree)
Initializes and renders the AST
SimpleNode using the context
into the output writer. |
private void |
requireInitialization()
Init or die! (with some log help, of course)
|
void |
reset()
Resets the instance, so Velocity can be re-initialized again.
|
java.lang.Object |
setApplicationAttribute(java.lang.Object key,
java.lang.Object o)
Sets the application attribute for the given key
|
void |
setConfiguration(ExtProperties configuration)
Allow an external system to set an ExtProperties
object to use.
|
private void |
setDefaultProperties()
Initializes the Velocity Runtime with properties file.
|
void |
setProperties(java.util.Properties props)
Add all the properties in props to the RuntimeInstance properties
|
void |
setProperties(java.lang.String fileName)
Add all properties contained in the file fileName to the RuntimeInstance properties
|
void |
setProperty(java.lang.String key,
java.lang.Object value)
Allows an external system to set a property in
the Velocity Runtime.
|
private void |
updateSharedDirectivesMap()
Makes an unsynchronized copy of the directives map
that is used for Directive lookups by all parsers.
|
boolean |
useStringInterning()
Whether to use string interning
|
private VelocimacroFactory vmFactory
private org.slf4j.Logger log
private ParserPool parserPool
private boolean initializing
private volatile boolean initialized
private ExtProperties overridingProperties
private java.util.Map<java.lang.String,Directive> runtimeDirectives
private java.util.Map<java.lang.String,Directive> runtimeDirectivesShared
private ExtProperties configuration
private ResourceManager resourceManager
private EventCartridge eventCartridge
private boolean stringInterning
private java.lang.String evaluateScopeName
private java.util.Set<java.lang.String> enabledScopeControls
private java.util.Map<java.lang.Object,java.lang.Object> applicationAttributes
private Uberspect uberSpect
private java.lang.String defaultEncoding
private RuntimeConstants.SpaceGobbling spaceGobbling
private boolean hyphenAllowedInIdentifiers
private LogContext logContext
private java.lang.reflect.Constructor<? extends Parser> parserConstructor
private ParserConfiguration parserConfiguration
public void init()
init
in interface RuntimeServices
public void reset()
public boolean isInitialized()
isInitialized
in interface RuntimeServices
private void requireInitialization()
private void initializeSelfProperties()
private char getConfiguredCharacter(java.lang.String configKey, char defaultChar)
private void initializeIntrospection()
private void setDefaultProperties()
public void setProperty(java.lang.String key, java.lang.Object value)
setProperty
in interface RuntimeServices
key
- property keyvalue
- property valuepublic void setProperties(java.lang.String fileName)
fileName
- public void setProperties(java.util.Properties props)
props
- public void setConfiguration(ExtProperties configuration)
setConfiguration
in interface RuntimeServices
configuration
- public void addProperty(java.lang.String key, java.lang.Object value)
addProperty
in interface RuntimeServices
key
- value
- public void clearProperty(java.lang.String key)
clearProperty
in interface RuntimeServices
key
- of property to clearpublic java.lang.Object getProperty(java.lang.String key)
getProperty
in interface RuntimeServices
key
- property to returnprivate void initializeProperties()
public void init(java.util.Properties p)
init
in interface RuntimeServices
p
- Velocity properties for initializationpublic void init(java.lang.String configurationFile)
init
in interface RuntimeServices
configurationFile
- private void initializeResourceManager()
private void initializeEventHandlers()
private EventHandler initializeSpecificEventHandler(java.lang.String classname, java.lang.String paramName, java.lang.Class<?> EventHandlerInterface)
private void initializeLog()
private void initializeDirectives()
public void addDirective(Directive directive)
directive
- public Directive getDirective(java.lang.String name)
getDirective
in interface RuntimeServices
name
- name of the directiveDirective
for that namepublic void removeDirective(java.lang.String name)
name
- name of the directive.private void updateSharedDirectivesMap()
public void loadDirective(java.lang.String directiveClass)
directiveClass
- classname of directive to loadprivate void initializeParserPool()
public Parser createNewParser()
createNewParser
in interface RuntimeServices
public SimpleNode parse(java.io.Reader reader, Template template) throws ParseException
parse
in interface RuntimeServices
reader
- Reader retrieved by a resource loadertemplate
- template being parsedParseException
- When the template could not be parsed.private void initializeScopeSettings()
public boolean evaluate(Context context, java.io.Writer out, java.lang.String logTag, java.lang.String instring)
evaluate
in interface RuntimeServices
context
- context to use in rendering input stringout
- Writer in which to render the outputlogTag
- string to be used as the template name for log
messages in case of errorinstring
- input string containing the VTL to be renderedParseErrorException
- The template could not be parsed.MethodInvocationException
- A method on a context object could not be invoked.ResourceNotFoundException
- A referenced resource could not be loaded.public boolean evaluate(Context context, java.io.Writer writer, java.lang.String logTag, java.io.Reader reader)
evaluate
in interface RuntimeServices
context
- context to use in rendering input stringwriter
- Writer in which to render the outputlogTag
- string to be used as the template name for log messages
in case of errorreader
- Reader containing the VTL to be renderedParseErrorException
- The template could not be parsed.MethodInvocationException
- A method on a context object could not be invoked.ResourceNotFoundException
- A referenced resource could not be loaded.public boolean render(Context context, java.io.Writer writer, java.lang.String logTag, SimpleNode nodeTree)
SimpleNode
using the context
into the output writer.context
- context to use in rendering input stringwriter
- Writer in which to render the outputlogTag
- string to be used as the template name for log messages
in case of errornodeTree
- SimpleNode which is the root of the AST to be renderedParseErrorException
- The template could not be parsed.MethodInvocationException
- A method on a context object could not be invoked.ResourceNotFoundException
- A referenced resource could not be loaded.public boolean invokeVelocimacro(java.lang.String vmName, java.lang.String logTag, java.lang.String[] params, Context context, java.io.Writer writer)
invokeVelocimacro
in interface RuntimeServices
vmName
- name of Velocimacro to calllogTag
- string to be used for template name in case of error. if null,
the vmName will be usedparams
- keys for args used to invoke Velocimacro, in java format
rather than VTL (eg "foo" or "bar" rather than "$foo" or "$bar")context
- Context object containing data/objects used for rendering.writer
- Writer for output streamprivate java.lang.String getDefaultEncoding()
public Template getTemplate(java.lang.String name) throws ResourceNotFoundException, ParseErrorException
Template
from the resource manager.
This method assumes that the character encoding of the
template is set by the resource.default_encoding
property. The default is UTF-8.getTemplate
in interface RuntimeServices
name
- The file name of the desired template.ResourceNotFoundException
- if template not found
from any available source.ParseErrorException
- if template cannot be parsed due
to syntax (or other) error.public Template getTemplate(java.lang.String name, java.lang.String encoding) throws ResourceNotFoundException, ParseErrorException
Template
from the resource managergetTemplate
in interface RuntimeServices
name
- The name of the desired template.encoding
- Character encoding of the templateResourceNotFoundException
- if template not found
from any available source.ParseErrorException
- if template cannot be parsed due
to syntax (or other) error.public ContentResource getContent(java.lang.String name) throws ResourceNotFoundException, ParseErrorException
getContent
in interface RuntimeServices
name
- Name of content resource to getResourceNotFoundException
- if template not found
from any available source.ParseErrorException
- When the template could not be parsed.public ContentResource getContent(java.lang.String name, java.lang.String encoding) throws ResourceNotFoundException, ParseErrorException
getContent
in interface RuntimeServices
name
- Name of content resource to getencoding
- Character encoding to useResourceNotFoundException
- if template not found
from any available source.ParseErrorException
- When the template could not be parsed.public java.lang.String getLoaderNameForResource(java.lang.String resourceName)
getLoaderNameForResource
in interface RuntimeServices
resourceName
- Name of template or content resourcepublic org.slf4j.Logger getLog()
getLog
in interface RuntimeServices
public org.slf4j.Logger getLog(java.lang.String childNamespace)
getLog
in interface RuntimeServices
childNamespace
- public LogContext getLogContext()
getLogContext
in interface RuntimeServices
public java.lang.String getString(java.lang.String key, java.lang.String defaultValue)
getString
in interface RuntimeServices
key
- property keydefaultValue
- default value to return if key not
found in resource manager.public Directive getVelocimacro(java.lang.String vmName, Template renderingTemplate, Template template)
getVelocimacro
in interface RuntimeServices
vmName
- Name of velocimacro requestedrenderingTemplate
- Template we are currently rendering. This
information is needed when VM_PERM_ALLOW_INLINE_REPLACE_GLOBAL setting is true
and template contains a macro with the same name as the global macro library.template
- Template which acts as the host for the macropublic boolean addVelocimacro(java.lang.String name, Node macro, java.util.List<Macro.MacroArg> macroArgs, Template definingTemplate)
addVelocimacro
in interface RuntimeServices
name
- Name of velocimacromacro
- root AST node of the parsed macromacroArgs
- Array of macro arguments, containing the
#macro() arguments and default values. the 0th is the name.definingTemplate
- Template containing the source of the macropublic boolean isVelocimacro(java.lang.String vmName, Template template)
isVelocimacro
in interface RuntimeServices
vmName
- Name of the Velocimacro.template
- Template on which to look for the Macro.public java.lang.String getString(java.lang.String key)
getString
in interface RuntimeServices
key
- property keypublic int getInt(java.lang.String key)
getInt
in interface RuntimeServices
key
- Property keypublic int getInt(java.lang.String key, int defaultValue)
getInt
in interface RuntimeServices
key
- property keydefaultValue
- The default value.public boolean getBoolean(java.lang.String key, boolean def)
getBoolean
in interface RuntimeServices
key
- property keydef
- The default value if property not found.public ExtProperties getConfiguration()
getConfiguration
in interface RuntimeServices
public EventCartridge getApplicationEventCartridge()
getApplicationEventCartridge
in interface RuntimeServices
public java.lang.Object getApplicationAttribute(java.lang.Object key)
getApplicationAttribute
in interface RuntimeServices
key
- public java.lang.Object setApplicationAttribute(java.lang.Object key, java.lang.Object o)
setApplicationAttribute
in interface RuntimeServices
key
- o
- The new application attribute.public Uberspect getUberspect()
getUberspect
in interface RuntimeServices
public boolean useStringInterning()
useStringInterning
in interface RuntimeServices
public RuntimeConstants.SpaceGobbling getSpaceGobbling()
getSpaceGobbling
in interface RuntimeServices
public boolean isHyphenAllowedInIdentifiers()
isHyphenAllowedInIdentifiers
in interface RuntimeServices
public boolean isScopeControlEnabled(java.lang.String scopeName)
isScopeControlEnabled
in interface RuntimeServices
scopeName
- public ParserConfiguration getParserConfiguration()
RuntimeServices
getParserConfiguration
in interface RuntimeServices