geirm 2003/12/23 07:29:59
Modified: src/java/org/apache/velocity/runtime RuntimeInstance.java
Log:
doco and formatting. No functional changes
Revision Changes Path
1.21 +214 -189
jakarta-velocity/src/java/org/apache/velocity/runtime/RuntimeInstance.java
Index: RuntimeInstance.java
===================================================================
RCS file:
/home/cvs/jakarta-velocity/src/java/org/apache/velocity/runtime/RuntimeInstance.java,v
retrieving revision 1.20
retrieving revision 1.21
diff -u -r1.20 -r1.21
--- RuntimeInstance.java 3 Nov 2003 19:58:27 -0000 1.20
+++ RuntimeInstance.java 23 Dec 2003 15:29:59 -0000 1.21
@@ -123,7 +123,7 @@
* 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.
* -----------------------------------------------------------------------
@@ -142,13 +142,13 @@
* @version $Id$
*/
public class RuntimeInstance implements RuntimeConstants, RuntimeServices
-{
+{
/**
* VelocimacroFactory object to manage VMs
*/
private VelocimacroFactory vmFactory = null;
- /**
+ /**
* 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
@@ -156,12 +156,12 @@
*/
private LogSystem logSystem = new PrimordialLogSystem();
- /**
- * The Runtime parser pool
+ /**
+ * The Runtime parser pool
*/
private SimplePool parserPool;
-
- /**
+
+ /**
* Indicate whether the Runtime has been fully initialized.
*/
private boolean initialized;
@@ -189,7 +189,7 @@
* can be retrieved from the main ExtendedProperties object
* using something like the following:
*
- * ExtendedProperties loaderConfiguration =
+ * ExtendedProperties loaderConfiguration =
* configuration.subset(loaderID);
*
* And a configuration is a lot more convenient to deal
@@ -207,7 +207,7 @@
/*
- * Opaque reference to something specificed by the
+ * Opaque reference to something specificed by the
* application for use in application supplied/specified
* pluggable components
*/
@@ -228,7 +228,7 @@
/*
* make a new introspector and initialize it
*/
-
+
introspector = new Introspector( this );
/*
@@ -268,13 +268,13 @@
initializeIntrospection();
/*
- * initialize the VM Factory. It will use the properties
+ * initialize the VM Factory. It will use the properties
* accessable from Runtime, so keep this here at the end.
*/
vmFactory.initVelocimacro();
info("Velocity successfully started.");
-
+
initialized = true;
}
}
@@ -352,10 +352,10 @@
{
InputStream inputStream = getClass()
.getResourceAsStream('/' + DEFAULT_RUNTIME_PROPERTIES);
-
+
configuration.load( inputStream );
-
- info ("Default Properties File: " +
+
+ info ("Default Properties File: " +
new File(DEFAULT_RUNTIME_PROPERTIES).getPath());
}
catch (IOException ioe)
@@ -368,18 +368,18 @@
* Allows an external system to set a property in
* the Velocity Runtime.
*
- * @param String property key
- * @param String property value
+ * @param key property key
+ * @param value property value
*/
public void setProperty(String key, Object value)
{
if (overridingProperties == null)
{
overridingProperties = new ExtendedProperties();
- }
-
- overridingProperties.setProperty( key, value );
- }
+ }
+
+ overridingProperties.setProperty(key, value);
+ }
/**
* Allow an external system to set an ExtendedProperties
@@ -389,7 +389,7 @@
* parent application's configuration. This is
* the case with Turbine.
*
- * @param ExtendedProperties configuration
+ * @param configuration
*/
public void setConfiguration( ExtendedProperties configuration)
{
@@ -423,33 +423,33 @@
*
* ["file", "classpath"]
*
- * @param String key
- * @param String value
+ * @param key
+ * @param value
*/
public void addProperty(String key, Object value)
{
if (overridingProperties == null)
{
overridingProperties = new ExtendedProperties();
- }
-
- overridingProperties.addProperty( key, value );
+ }
+
+ overridingProperties.addProperty(key, value);
}
-
+
/**
* Clear the values pertaining to a particular
* property.
*
- * @param String key of property to clear
+ * @param key of property to clear
*/
public void clearProperty(String key)
{
if (overridingProperties != null)
{
overridingProperties.clearProperty(key);
- }
+ }
}
-
+
/**
* Allows an external caller to get a property. The calling
* routine is required to know the type, as this routine
@@ -457,9 +457,9 @@
*
* @param key property to return
*/
- public Object getProperty( String key )
+ public Object getProperty(String key)
{
- return configuration.getProperty( key );
+ return configuration.getProperty(key);
}
/**
@@ -472,38 +472,38 @@
*/
private void initializeProperties()
{
- /*
+ /*
* Always lay down the default properties first as
* to provide a solid base.
*/
if (configuration.isInitialized() == false)
{
setDefaultProperties();
- }
-
+ }
+
if( overridingProperties != null)
- {
+ {
configuration.combine(overridingProperties);
}
}
-
+
/**
* Initialize the Velocity Runtime with a Properties
* object.
*
- * @param Properties
+ * @param p
*/
public void init(Properties p) throws Exception
{
overridingProperties = ExtendedProperties.convertProperties(p);
init();
}
-
+
/**
* Initialize the Velocity Runtime with the name of
* ExtendedProperties object.
*
- * @param Properties
+ * @param configurationFile
*/
public void init(String configurationFile)
throws Exception
@@ -518,95 +518,98 @@
/*
* Which resource manager?
*/
-
- String rm = getString( RuntimeConstants.RESOURCE_MANAGER_CLASS );
- if ( rm != null && rm.length() > 0 )
+ String rm = getString(RuntimeConstants.RESOURCE_MANAGER_CLASS);
+
+ if (rm != null && rm.length() > 0)
{
/*
* if something was specified, then make one.
* if that isn't a ResourceManager, consider
* this a huge error and throw
*/
-
+
Object o = null;
-
+
try
{
- o = Class.forName( rm ).newInstance();
+ o = Class.forName(rm).newInstance();
}
- catch (ClassNotFoundException cnfe )
+ catch (ClassNotFoundException cnfe)
{
String err = "The specified class for Resourcemanager ("
- + rm
+ + rm
+ ") does not exist (or is not accessible to the current
classlaoder.";
- error( err );
- throw new Exception( err );
+ error(err);
+
+ throw new Exception(err);
}
-
- if (!(o instanceof ResourceManager) )
+
+ if (!(o instanceof ResourceManager))
{
String err = "The specified class for ResourceManager ("
- + rm
+ + rm
+ ") does not implement
org.apache.runtime.resource.ResourceManager."
+ " Velocity not initialized correctly.";
-
+
error( err);
+
throw new Exception(err);
}
resourceManager = (ResourceManager) o;
-
- resourceManager.initialize( this );
+
+ resourceManager.initialize(this);
}
else
{
/*
* someone screwed up. Lets not fool around...
*/
-
+
String err = "It appears that no class was specified as the"
+ " ResourceManager. Please ensure that all configuration"
+ " information is correct.";
-
- error( err);
- throw new Exception( err );
- }
+
+ error(err);
+
+ throw new Exception(err);
+ }
}
-
+
/**
* Initialize the Velocity logging system.
*
* @throws Exception
*/
private void initializeLogger() throws Exception
- {
+ {
/*
* Initialize the logger. We will eventually move all
* logging into the logging manager.
*/
- if (logSystem instanceof PrimordialLogSystem )
+ if (logSystem instanceof PrimordialLogSystem)
{
PrimordialLogSystem pls = (PrimordialLogSystem) logSystem;
- logSystem = LogManager.createLogSystem( this );
-
+ logSystem = LogManager.createLogSystem(this);
+
/*
- * in the event of failure, lets do something to let it
+ * in the event of failure, lets do something to let it
* limp along.
*/
-
+
if (logSystem == null)
{
logSystem = new NullLogSystem();
}
else
{
- pls.dumpLogMessages( logSystem );
+ pls.dumpLogMessages(logSystem);
}
}
}
-
+
/**
* This methods initializes all the directives
* that are used by the Velocity Runtime. The
@@ -616,16 +619,17 @@
*
* @throws Exception
*/
- private void initializeDirectives() throws Exception
+ private void initializeDirectives()
+ throws Exception
{
/*
* Initialize the runtime directive table.
* This will be used for creating parsers.
*/
runtimeDirectives = new Hashtable();
-
+
Properties directiveProperties = new Properties();
-
+
/*
* Grab the properties file with the list of directives
* that we should initialize.
@@ -633,16 +637,18 @@
InputStream inputStream =
getClass().getResourceAsStream('/' + DEFAULT_RUNTIME_DIRECTIVES);
-
+
if (inputStream == null)
+ {
throw new Exception("Error loading directive.properties! " +
"Something is very wrong if these properties " +
"aren't being located. Either your Velocity " +
"distribution is incomplete or your Velocity " +
"jar file is corrupted!");
-
+ }
+
directiveProperties.load(inputStream);
-
+
/*
* Grab all the values of the properties. These
* are all class names for example:
@@ -650,60 +656,60 @@
* org.apache.velocity.runtime.directive.Foreach
*/
Enumeration directiveClasses = directiveProperties.elements();
-
+
while (directiveClasses.hasMoreElements())
{
String directiveClass = (String) directiveClasses.nextElement();
loadDirective( directiveClass, "System" );
}
-
+
/*
* now the user's directives
*/
-
+
String[] userdirective = configuration.getStringArray("userdirective");
-
+
for( int i = 0; i < userdirective.length; i++)
{
loadDirective( userdirective[i], "User");
}
-
+
}
-
+
/**
* instantiates and loads the directive with some basic checks
- *
- * @param directiveClass classname of directive to load
+ *
+ * @param directiveClass classname of directive to load
*/
- private void loadDirective( String directiveClass, String caption )
- {
+ private void loadDirective(String directiveClass, String caption)
+ {
try
{
- Object o = Class.forName( directiveClass ).newInstance();
-
- if ( o instanceof Directive )
+ Object o = Class.forName(directiveClass).newInstance();
+
+ if (o instanceof Directive)
{
Directive directive = (Directive) o;
runtimeDirectives.put(directive.getName(), directive);
-
- info("Loaded " + caption + " Directive: "
+
+ info("Loaded " + caption + " Directive: "
+ directiveClass);
}
else
{
- error( caption + " Directive " + directiveClass
+ error(caption + " Directive " + directiveClass
+ " is not org.apache.velocity.runtime.directive.Directive."
- + " Ignoring. " );
+ + " Ignoring. ");
}
}
catch (Exception e)
{
- error("Exception Loading " + caption + " Directive: "
- + directiveClass + " : " + e);
+ error("Exception Loading " + caption + " Directive: "
+ + directiveClass + " : " + e);
}
}
-
-
+
+
/**
* Initializes the Velocity parser pool.
* This still needs to be implemented.
@@ -729,7 +735,7 @@
*/
public Parser createNewParser()
{
- Parser parser = new Parser( this );
+ Parser parser = new Parser(this);
parser.setDirectives(runtimeDirectives);
return parser;
}
@@ -739,33 +745,33 @@
* AST node structure.
* <br><br>
* In the event that it runs out of parsers in the
- * pool, it will create and let them be GC'd
+ * 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
+ * expected that the user will set the
* PARSER_POOL_SIZE property appropriately for their
* application. We will revisit this.
*
- * @param InputStream inputstream retrieved by a resource loader
- * @param String name of the template being parsed
+ * @param reader Reader retrieved by a resource loader
+ * @param templateName name of the template being parsed
*/
- public SimpleNode parse( Reader reader, String templateName )
+ public SimpleNode parse(Reader reader, String templateName)
throws ParseException
{
/*
* do it and dump the VM namespace for this template
*/
- return parse( reader, templateName, true );
+ return parse(reader, templateName, true);
}
/**
* Parse the input and return the root of the AST node structure.
*
- * @param InputStream inputstream retrieved by a resource loader
- * @param String name of the template being parsed
+ * @param reader Reader retrieved by a resource loader
+ * @param templateName name of the template being parsed
* @param dumpNamespace flag to dump the Velocimacro namespace for this template
*/
- public SimpleNode parse( Reader reader, String templateName, boolean
dumpNamespace )
+ public SimpleNode parse(Reader reader, String templateName, boolean
dumpNamespace)
throws ParseException
{
@@ -779,14 +785,14 @@
* if we couldn't get a parser from the pool
* make one and log it.
*/
-
+
error("Runtime : ran out of parsers. Creating new. "
+ " Please increment the parser.pool.size property."
+ " The current value is too small.");
parser = createNewParser();
- if( parser != null )
+ if (parser != null)
{
madeNew = true;
}
@@ -801,17 +807,17 @@
try
{
/*
- * dump namespace if we are told to. Generally, you want to
- * do this - you don't in special circumstances, such as
+ * dump namespace if we are told to. Generally, you want to
+ * do this - you don't in special circumstances, such as
* when a VM is getting init()-ed & parsed
*/
- if ( dumpNamespace )
+ if (dumpNamespace)
{
- dumpVMNamespace( templateName );
+ dumpVMNamespace(templateName);
}
- ast = parser.parse( reader, templateName );
+ ast = parser.parse(reader, templateName);
}
finally
{
@@ -830,10 +836,10 @@
}
return ast;
}
-
+
/**
* Returns a <code>Template</code> from the resource manager.
- * This method assumes that the character encoding of the
+ * This method assumes that the character encoding of the
* template is set by the <code>input.encoding</code>
* property. The default is "ISO-8859-1"
*
@@ -848,7 +854,7 @@
public Template getTemplate(String name)
throws ResourceNotFoundException, ParseErrorException, Exception
{
- return getTemplate( name, getString( INPUT_ENCODING, ENCODING_DEFAULT) );
+ return getTemplate(name, getString( INPUT_ENCODING, ENCODING_DEFAULT));
}
/**
@@ -866,7 +872,9 @@
public Template getTemplate(String name, String encoding)
throws ResourceNotFoundException, ParseErrorException, Exception
{
- return (Template) resourceManager.getResource(name,
ResourceManager.RESOURCE_TEMPLATE, encoding);
+ return (Template)
+ resourceManager.getResource(name,
+ ResourceManager.RESOURCE_TEMPLATE, encoding);
}
/**
@@ -887,7 +895,7 @@
* the bytestream should be dumped to the output stream
*/
- return getContent( name, getString( INPUT_ENCODING, ENCODING_DEFAULT));
+ return getContent(name, getString( INPUT_ENCODING, ENCODING_DEFAULT));
}
/**
@@ -900,15 +908,17 @@
* @throws ResourceNotFoundException if template not found
* from any available source.
*/
- public ContentResource getContent( String name, String encoding )
+ public ContentResource getContent(String name, String encoding)
throws ResourceNotFoundException, ParseErrorException, Exception
{
- return (ContentResource)
resourceManager.getResource(name,ResourceManager.RESOURCE_CONTENT, encoding );
+ return (ContentResource)
+ resourceManager.getResource(name,
+ ResourceManager.RESOURCE_CONTENT, encoding);
}
/**
- * Determines is a template exists, and returns name of the loader that
+ * 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.
@@ -916,9 +926,9 @@
* @param resourceName Name of template or content resource
* @return class name of loader than can provide it
*/
- public String getLoaderNameForResource( String resourceName )
+ public String getLoaderNameForResource(String resourceName)
{
- return resourceManager.getLoaderNameForResource( resourceName );
+ return resourceManager.getLoaderNameForResource(resourceName);
}
/**
@@ -932,77 +942,78 @@
if (configuration.isInitialized())
{
return getBoolean(RUNTIME_LOG_WARN_STACKTRACE, false);
- }
+ }
else
{
return false;
- }
+ }
}
/**
* Handle logging.
*
- * @param String message to log
+ * @param level level of message to log
+ * @param message message to log
*/
private void log(int level, Object message)
{
String out;
-
+
/*
* now, see if the logging stacktrace is on
* and modify the message to suit
*/
- if ( showStackTrace() &&
- (message instanceof Throwable || message instanceof Exception) )
+ if (showStackTrace() &&
+ (message instanceof Throwable || message instanceof Exception))
{
out = StringUtils.stackTrace((Throwable)message);
}
else
{
- out = message.toString();
- }
+ out = message.toString();
+ }
/*
* just log it, as we are guaranteed now to have some
* kind of logger - save the if()
*/
- logSystem.logVelocityMessage( level, out);
+ logSystem.logVelocityMessage(level, out);
}
/**
* Log a warning message.
*
- * @param Object message to log
+ * @param message message to log
*/
public void warn(Object message)
{
log(LogSystem.WARN_ID, message);
}
-
- /**
+
+ /**
* Log an info message.
*
- * @param Object message to log
+ * @param message message to log
*/
public void info(Object message)
{
log(LogSystem.INFO_ID, message);
}
-
+
/**
* Log an error message.
*
- * @param Object message to log
+ * @param message message to log
*/
public void error(Object message)
{
log(LogSystem.ERROR_ID, message);
}
-
+
/**
* Log a debug message.
*
- * @param Object message to log
+ * @param message message to log
*/
public void debug(Object message)
{
@@ -1012,13 +1023,13 @@
/**
* String property accessor method with default to hide the
* configuration implementation.
- *
- * @param String key property key
- * @param String defaultValue default value to return if key not
+ *
+ * @param key property key
+ * @param defaultValue default value to return if key not
* found in resource manager.
- * @return String value of key or default
+ * @return value of key or default
*/
- public String getString( String key, String defaultValue)
+ public String getString(String key, String defaultValue)
{
return configuration.getString(key, defaultValue);
}
@@ -1027,50 +1038,51 @@
* Returns the appropriate VelocimacroProxy object if strVMname
* is a valid current Velocimacro.
*
- * @param String vmName Name of velocimacro requested
- * @return String VelocimacroProxy
+ * @param vmName Name of velocimacro requested
+ * @param templateName name of template for namespace
+ * @return VelocimacroProxy
*/
- public Directive getVelocimacro( String vmName, String templateName )
+ public Directive getVelocimacro(String vmName, String templateName)
{
- return vmFactory.getVelocimacro( vmName, templateName );
+ return vmFactory.getVelocimacro(vmName, templateName);
}
/**
* Adds a new Velocimacro. Usually called by Macro only while parsing.
*
- * @param String name Name of velocimacro
- * @param String macro String form of macro body
- * @param String argArray Array of strings, containing the
+ * @param name Name of velocimacro
+ * @param macro String form of macro body
+ * @param argArray Array of strings, containing the
* #macro() arguments. the 0th is the name.
- * @return boolean True if added, false if rejected for some
- * reason (either parameters or permission settings)
+ * @return boolean True if added, false if rejected for some
+ * reason (either parameters or permission settings)
*/
- public boolean addVelocimacro( String name,
- String macro,
- String argArray[],
- String sourceTemplate )
- {
- return vmFactory.addVelocimacro( name, macro, argArray, sourceTemplate );
+ public boolean addVelocimacro(String name,
+ String macro,
+ String argArray[],
+ String sourceTemplate)
+ {
+ return vmFactory.addVelocimacro(name, macro, argArray, sourceTemplate);
}
-
+
/**
* Checks to see if a VM exists
*
- * @param name Name of velocimacro
+ * @param vmName Name of velocimacro
* @return boolean True if VM by that name exists, false if not
*/
- public boolean isVelocimacro( String vmName, String templateName )
+ public boolean isVelocimacro(String vmName, String templateName)
{
- return vmFactory.isVelocimacro( vmName, templateName );
+ return vmFactory.isVelocimacro(vmName, templateName);
}
/**
* tells the vmFactory to dump the specified namespace. This is to support
* clearing the VM list when in inline-VM-local-scope mode
*/
- public boolean dumpVMNamespace( String namespace )
+ public boolean dumpVMNamespace(String namespace)
{
- return vmFactory.dumpVMNamespace( namespace );
+ return vmFactory.dumpVMNamespace(namespace);
}
/* --------------------------------------------------------------------
@@ -1092,42 +1104,42 @@
*/
public String getString(String key)
{
- return configuration.getString( key );
+ return configuration.getString(key);
}
/**
* Int property accessor method to hide the configuration implementation.
*
- * @param String key property key
- * @return int value
+ * @param key property key
+ * @return value
*/
- public int getInt( String key )
+ public int getInt(String key)
{
- return configuration.getInt( key );
+ return configuration.getInt(key);
}
/**
* Int property accessor method to hide the configuration implementation.
*
* @param key property key
- * @param int default value
- * @return int value
+ * @param defaultValue default value
+ * @return value
*/
- public int getInt( String key, int defaultValue )
+ public int getInt(String key, int defaultValue)
{
- return configuration.getInt( key, defaultValue );
+ return configuration.getInt(key, defaultValue);
}
/**
* Boolean property accessor method to hide the configuration implementation.
- *
- * @param String key property key
- * @param boolean default default value if property not found
+ *
+ * @param key property key
+ * @param def default value if property not found
* @return boolean value of key or default value
*/
- public boolean getBoolean( String key, boolean def )
+ public boolean getBoolean(String key, boolean def)
{
- return configuration.getBoolean( key, def );
+ return configuration.getBoolean(key, def);
}
/**
@@ -1139,8 +1151,8 @@
public ExtendedProperties getConfiguration()
{
return configuration;
- }
-
+ }
+
/**
* Return the Introspector for this instance
*/
@@ -1149,14 +1161,27 @@
return introspector;
}
- public Object getApplicationAttribute( Object key)
+ /**
+ * Gets the application attribute for the given key
+ *
+ * @param key
+ * @return
+ */
+ public Object getApplicationAttribute(Object key)
{
- return applicationAttributes.get( key );
+ return applicationAttributes.get(key);
}
- public Object setApplicationAttribute( Object key, Object o )
+ /**
+ * Sets the application attribute for the given key
+ *
+ * @param key
+ * @param o
+ * @return
+ */
+ public Object setApplicationAttribute(Object key, Object o)
{
- return applicationAttributes.put( key, o );
+ return applicationAttributes.put(key, o);
}
public Uberspect getUberspect()
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
