simple.template.velocity
Class VelocityContainer

java.lang.Object
  extended by simple.template.velocity.VelocityContainer
All Implemented Interfaces:
Container, Database

public class VelocityContainer
extends java.lang.Object
implements Container

The VelocityContainer provides an implementation of the Container object for Velocity. This can be used with a TemplateEngine to provide template documents written in the Velocity Templating Language (VTL) to service objects. This container will use an XML Java properties file named either velocity.xml or Velocity.xml to configure itself.

The Java properties file used for configuration is searched for within the current working directory. However, if there is a Locator object supplied then it is used to search for the properties file. The means of searching is determined by the Locator object.

A subclassed implementation of this Container typically implements the lookup(String) method inorder to populate a database with various tools or objects. This can done by creating a Context instance and delegating to the lookup(String, Object) method once the Context has been populated.

Author:
Niall Gallagher
See Also:
VelocityEngine

Field Summary
protected  org.apache.velocity.context.Context data
          The internal storage used by this instance.
 
Constructor Summary
VelocityContainer()
          Constructor for the VelocityContainer object.
VelocityContainer(Context context)
          Constructor for the VelocityContainer object.
VelocityContainer(org.apache.velocity.app.VelocityEngine engine)
          Constructor for the VelocityContainer object.
VelocityContainer(org.apache.velocity.app.VelocityEngine engine, Context context)
          Constructor for the VelocityContainer object.
 
Method Summary
 boolean contains(java.lang.String name)
          The contains method is used to determine if a mapping exists for the given name.
 boolean exists(java.lang.String path)
          Determines whether the named template exists.
 java.lang.Object get(java.lang.String name)
          The get method is used to retrieve the value mapped to the specified name.
protected  void init(Context context)
          In the event that the VelocityEngine instance is uninitialized this attempts to load a Java properties file to provide configuration information.
protected  void init(Locator lookup)
          In the event that the VelocityEngine instance is uninitialized this attempts to load a Java properties file to provide configuration information.
 java.util.Set keySet()
          To ascertain what mappings exist, the names of all values previously put into this database can be retrieved with this method.
 Document lookup(java.lang.String path)
          Looks for the named template and wraps the template within a new Document instance.
 Document lookup(java.lang.String path, boolean share)
          Looks for the named template and wraps the template within a new Document instance.
 Document lookup(java.lang.String path, java.lang.Object data, boolean share)
          Looks for the named template and wraps the template within a new Document instance.
 void put(java.lang.String name, java.lang.Object value)
          The put method is used to insert a mapping in the database that pairs the issued name with the issued value.
 void remove(java.lang.String name)
          The remove method is used to remove the mapping from the database.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface simple.template.Database
contains, get, keySet, put, remove
 

Field Detail

data

protected org.apache.velocity.context.Context data
The internal storage used by this instance.

Constructor Detail

VelocityContainer

public VelocityContainer()
                  throws java.lang.Exception
Constructor for the VelocityContainer object. The instance created will contain an empty set of properties and initializes the engine by using a Java properties file located within the current working directory.

Throws:
java.lang.Exception - if there is an initialization problem

VelocityContainer

public VelocityContainer(Context context)
                  throws java.lang.Exception
Constructor for the VelocityContainer object. The instance created will contain an empty set of properties and initializes the engine by using a Java properties file located using the supplied Locator object.

Parameters:
context - the context used to locate the properties
Throws:
java.lang.Exception - if there is an initialization problem

VelocityContainer

public VelocityContainer(org.apache.velocity.app.VelocityEngine engine)
                  throws java.lang.Exception
Constructor for the VelocityContainer object. The instance created will contain an empty set of properties and initializes the engine by using a Java properties file located within the current working directory.

If a specialized VelocityEngine instance is required one can be provided, this enables properties, such as the template root and application attributes to be set.

Parameters:
engine - this is the engine used by this instance
Throws:
java.lang.Exception - if there is an initialization problem

VelocityContainer

public VelocityContainer(org.apache.velocity.app.VelocityEngine engine,
                         Context context)
                  throws java.lang.Exception
Constructor for the VelocityContainer object. The instance created will contain an empty set of properties and initializes the engine by using a Java properties file located using the supplied Locator object.

If a specialized VelocityEngine instance is required one can be provided, this enables properties, such as the template root and application attributes to be set.

Parameters:
engine - this is the engine used by this instance
context - the context used to locate the properties
Throws:
java.lang.Exception - if there is an initialization problem
Method Detail

init

protected void init(Context context)
             throws java.lang.Exception
In the event that the VelocityEngine instance is uninitialized this attempts to load a Java properties file to provide configuration information. By default the properties are located in an XML file named velocity.xml. If the properties file cannot be loaded from the supplied Context instance then this will attempt to initialize the engine without any specified properties.

Parameters:
context - the context used to locate the properties
Throws:
java.lang.Exception - if there is a problem on initialization

init

protected void init(Locator lookup)
             throws java.lang.Exception
In the event that the VelocityEngine instance is uninitialized this attempts to load a Java properties file to provide configuration information. By default the properties are located in an XML file named velocity.xml. If the properties file cannot be loaded from the supplied Locator instance then this will attempt to initialize the engine without any specified properties.

Parameters:
lookup - the locator used to locate the properties
Throws:
java.lang.Exception - if there is a problem on initialization

exists

public boolean exists(java.lang.String path)
Determines whether the named template exists. This is used to determine if the lookup method will locate a template given the specified path. If the template is accessible this returns true, otherwise false is returned.

Specified by:
exists in interface Container
Parameters:
path - this is the path used to locate the template
Returns:
true if the template exists, false if it does not

lookup

public Document lookup(java.lang.String path)
                throws java.lang.Exception
Looks for the named template and wraps the template within a new Document instance. Resolving the location of the template is left up the templating system, typically this requires a file path reference to locate the template.

The document created by this method is transient, that is, it is a unique instance. This means that changes to the properties of any created document object affect only that instance. By default this assumes the UTF-8 encoding.

Specified by:
lookup in interface Container
Parameters:
path - this is the path used to locate the template
Returns:
the specified template wrapped within a document
Throws:
java.lang.Exception - this is thrown if the is a problem with locating or rendering the specified template

lookup

public Document lookup(java.lang.String path,
                       boolean share)
                throws java.lang.Exception
Looks for the named template and wraps the template within a new Document instance. Resolving the location of the template is left up the templating system, typically this requires a file path reference to locate the template.

The document created by this method is transient, that is, it is a unique instance. This means that changes to the properties of any created document object affect only that instance. By default this assumes the UTF-8 encoding.

Parameters:
path - this is the path used to locate the template
share - should the data model be shared or inherited
Returns:
the specified template wrapped within a document
Throws:
java.lang.Exception - this is thrown if the is a problem with locating or rendering the specified template

lookup

public Document lookup(java.lang.String path,
                       java.lang.Object data,
                       boolean share)
                throws java.lang.Exception
Looks for the named template and wraps the template within a new Document instance. Resolving the location of the template is left up the templating system, typically this requires a file path reference to locate the template.

The document created by this method is transient, that is, it is a unique instance. This means that changes to the properties of any created document object affect only that instance. By default this assumes the UTF-8 encoding.

This method allows the Context used by the document object to be specified. This is useful if various tools need to be added to the database before it is used by the document, such as rendering tools and various others.

Parameters:
path - this is the path used to locate the template
data - this provides a set of default properties
Returns:
the specified template wrapped within a document
Throws:
java.lang.Exception - this is thrown if the is a problem with locating or rendering the specified template

put

public void put(java.lang.String name,
                java.lang.Object value)
The put method is used to insert a mapping in the database that pairs the issued name with the issued value. The value can be referenced in future by its name. Properties set with this method will be set within this instances data source, which is available to subclasses.

Specified by:
put in interface Database
Parameters:
name - this is the name of the value being inserted
value - this is the named value that is inserted

get

public java.lang.Object get(java.lang.String name)
The get method is used to retrieve the value mapped to the specified name. If a value does not exist matching the given name, then this returns null. All the property values retrieved by this method are obtained from an internal source that is accessible to subclasses.

Specified by:
get in interface Database
Parameters:
name - this is the name of the value to be retrieved
Returns:
returns the value if it exists or null otherwise

remove

public void remove(java.lang.String name)
The remove method is used to remove the mapping from the database. This method either removes the value or returns silently if the name does not exist. This removes the mapping from the internal data source.

Specified by:
remove in interface Database
Parameters:
name - this is the name of the value to be removed

keySet

public java.util.Set keySet()
To ascertain what mappings exist, the names of all values previously put into this database can be retrieved with this method. This will return a Set that contains the names of all the mappings added to this.

Specified by:
keySet in interface Database
Returns:
this returns all the keys for existing mappings

contains

public boolean contains(java.lang.String name)
The contains method is used to determine if a mapping exists for the given name. This returns true if the mapping exists or false otherwise.

Specified by:
contains in interface Database
Parameters:
name - this is the name of the mapping to determine
Returns:
returns true if a mapping exists, false otherwise