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 like Turbine. Runtime properties can
set and then the Runtime is initialized.
Turbine for example knows where the templates
are to be loaded from, and where the velocity
log file should be placed.
So in the case of Velocity cooperating with Turbine
the code might look something like the following:
Runtime.setProperty(Runtime.FILE_RESOURCE_LOADER_PATH, templatePath);
Runtime.setProperty(Runtime.RUNTIME_LOG, pathToVelocityLog);
Runtime.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
-----------------------------------------------------------------------
Runtime.init()
If Runtime.init() is called by itself the Runtime will
initialize with a set of default values.
-----------------------------------------------------------------------
Runtime.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.
-----------------------------------------------------------------------
applicationAttributes
private Map applicationAttributes
configuration
private ExtendedProperties configuration
Object that houses the configuration options for
the velocity runtime. The ExtendedProperties object allows
the convenient retrieval of a subset of properties.
For example all the properties for a resource loader
can be retrieved from the main ExtendedProperties object
using something like the following:
ExtendedProperties loaderConfiguration =
configuration.subset(loaderID);
And a configuration is a lot more convenient to deal
with then conventional properties objects, or Maps.
initialized
private boolean initialized
Indicate whether the Runtime has been fully initialized.
logSystem
private LogSystem logSystem
The Runtime logger. We start with an instance of
a 'primordial logger', which just collects log messages
then, when the log system is initialized, we dump
all messages out of the primordial one into the real one.
overridingProperties
private ExtendedProperties overridingProperties
These are the properties that are laid down over top
of the default properties when requested.
parserPool
private SimplePool parserPool
The Runtime parser pool
runtimeDirectives
private Hashtable runtimeDirectives
This is a hashtable of initialized directives.
The directives that populate this hashtable are
taken from the RUNTIME_DEFAULT_DIRECTIVES
property file. This hashtable is passed
to each parser that is created.
addProperty
public void addProperty(String key,
Object value)
Add a property to the configuration. If it already
exists then the value stated here will be added
to the configuration entry. For example, if
resource.loader = file
is already present in the configuration and you
addProperty("resource.loader", "classpath")
Then you will end up with a Vector like the
following:
["file", "classpath"]
- addProperty in interface RuntimeServices
addVelocimacro
public boolean addVelocimacro(String name,
String macro,
argArray[] ,
String sourceTemplate)
Adds a new Velocimacro. Usually called by Macro only while parsing.
- addVelocimacro in interface RuntimeServices
- boolean True if added, false if rejected for some
reason (either parameters or permission settings)
clearProperty
public void clearProperty(String key)
Clear the values pertaining to a particular
property.
- clearProperty in interface RuntimeServices
createNewParser
public Parser createNewParser()
Returns a JavaCC generated Parser.
- Parser javacc generated parser
dumpVMNamespace
public boolean dumpVMNamespace(String namespace)
tells the vmFactory to dump the specified namespace. This is to support
clearing the VM list when in inline-VM-local-scope mode
- dumpVMNamespace in interface RuntimeServices
getBoolean
public boolean getBoolean(String key,
boolean def)
Boolean property accessor method to hide the configuration implementation.
- getBoolean in interface RuntimeServices
- boolean value of key or default value
getConfiguration
public ExtendedProperties getConfiguration()
Return the velocity runtime configuration object.
- getConfiguration in interface RuntimeServices
- ExtendedProperties configuration object which houses
the velocity runtime properties.
getInt
public int getInt(String key)
Int property accessor method to hide the configuration implementation.
- getInt in interface RuntimeServices
- int value
getInt
public int getInt(String key,
int defaultValue)
Int property accessor method to hide the configuration implementation.
- getInt in interface RuntimeServices
key
- property key
- int value
getLoaderNameForResource
public String getLoaderNameForResource(String resourceName)
Determines is a template exists, and returns name of the loader that
provides it. This is a slightly less hokey way to support
the Velocity.templateExists() utility method, which was broken
when per-template encoding was introduced. We can revisit this.
- getLoaderNameForResource in interface RuntimeServices
resourceName
- Name of template or content resource
- class name of loader than can provide it
getProperty
public Object getProperty(String key)
Allows an external caller to get a property. The calling
routine is required to know the type, as this routine
will return an Object, as that is what properties can be.
- getProperty in interface RuntimeServices
key
- property to return
getString
public String getString(String key)
String property accessor method to hide the configuration implementation
- getString in interface RuntimeServices
key
- property key
- value of key or null
getString
public String getString(String key,
String defaultValue)
String property accessor method with default to hide the
configuration implementation.
- getString in interface RuntimeServices
- String value of key or default
getVelocimacro
public Directive getVelocimacro(String vmName,
String templateName)
Returns the appropriate VelocimacroProxy object if strVMname
is a valid current Velocimacro.
- getVelocimacro in interface RuntimeServices
- String VelocimacroProxy
init
public void init(Properties p)
throws Exception
Initialize the Velocity Runtime with a Properties
object.
- init in interface RuntimeServices
init
public void init(String configurationFile)
throws Exception
Initialize the Velocity Runtime with the name of
ExtendedProperties object.
- init in interface RuntimeServices
initializeDirectives
private void initializeDirectives()
throws Exception
This methods initializes all the directives
that are used by the Velocity Runtime. The
directives to be initialized are listed in
the RUNTIME_DEFAULT_DIRECTIVES properties
file.
initializeLogger
private void initializeLogger()
throws Exception
Initialize the Velocity logging system.
initializeParserPool
private void initializeParserPool()
Initializes the Velocity parser pool.
This still needs to be implemented.
initializeProperties
private void initializeProperties()
Initialize Velocity properties, if the default
properties have not been laid down first then
do so. Then proceed to process any overriding
properties. Laying down the default properties
gives a much greater chance of having a
working system.
initializeResourceManager
private void initializeResourceManager()
throws Exception
isVelocimacro
public boolean isVelocimacro(String vmName,
String templateName)
Checks to see if a VM exists
- isVelocimacro in interface RuntimeServices
- boolean True if VM by that name exists, false if not
loadDirective
private void loadDirective(String directiveClass,
String caption)
instantiates and loads the directive with some basic checks
directiveClass
- classname of directive to load
log
private void log(int level,
Object message)
Handle logging.
parse
public SimpleNode parse(Reader reader,
String templateName)
throws ParseException
Parse the input and return the root of
AST node structure.
In the event that it runs out of parsers in the
pool, it will create and let them be GC'd
dynamically, logging that it has to do that. This
is considered an exceptional condition. It is
expected that the user will set the
PARSER_POOL_SIZE property appropriately for their
application. We will revisit this.
- parse in interface RuntimeServices
parse
public SimpleNode parse(Reader reader,
String templateName,
boolean dumpNamespace)
throws ParseException
Parse the input and return the root of the AST node structure.
- parse in interface RuntimeServices
dumpNamespace
- flag to dump the Velocimacro namespace for this template
setApplicationAttribute
public Object setApplicationAttribute(Object key,
Object o)
setConfiguration
public void setConfiguration(ExtendedProperties configuration)
Allow an external system to set an ExtendedProperties
object to use. This is useful where the external
system also uses the ExtendedProperties class and
the velocity configuration is a subset of
parent application's configuration. This is
the case with Turbine.
- setConfiguration in interface RuntimeServices
setDefaultProperties
private void setDefaultProperties()
Initializes the Velocity Runtime with properties file.
The properties file may be in the file system proper,
or the properties file may be in the classpath.
setProperty
public void setProperty(String key,
Object value)
Allows an external system to set a property in
the Velocity Runtime.
- setProperty in interface RuntimeServices
showStackTrace
private boolean showStackTrace()
Added this to check and make sure that the configuration
is initialized before trying to get properties from it.
This occurs when there are errors during initialization
and the default properties have yet to be layed down.