uk.ac.ed.epcc.webapp.content

Class TemplateFile

java.lang.Object

uk.ac.ed.epcc.webapp.content.TemplateFile

public class TemplateFile
extends java.lang.Object

Parameterised text files. TemplateFile created (05/12/1999) This class provides a method for reading files known as templates which can contain tokens of the form %%token_name%%. These tokens may be replaced with values set with setProperty() and will appear in place of the tokens in the output when the file is written to a Writer or PrintStream using write(). For example, to set the title in a simple template we would do:

 TemplateFile tf = TemplateFile.getTemplateFile("template.html"); // Load the page template
 tf.setProperty("page_title", "Our Page"); // Apply the property
 tf.write(output_writer); // When finished, write the template
 

Properties may also be given default values in the template file, like so: %%property=default_value%%

Regions
Regions within a template file are marked with the syntax:
:= [text]
:= "%%begin{" ("," ("true"|"false")) "}%%"
:= "%%end{" () "}%%"
:= ('0..9' | 'a..z' | 'A..Z' | '_' | '-')+
e.g.:
%%begin{region1}%% text in region1 %%end{region1}%%
or
%%begin{region2, true}%% text in region2 %%end{}%%
where is an alphanumeric (or '_' and '-')

Regions are *disabled* by default and may be enabled with: setRegionEnabled(, );

Regions may be nested (though not overlapping) and can contain the usual substitution tokens.

  Document Structure:
   TemplateFile:
     Region: top_region (usually name == null)
       Region*: <sub_region>
       Property*: <property>
         String
         TemplateFile
         Object[]
 

FUTURE: Retire cached template files which haven't been accessed for a while (idea: make the getTemplateFile method clean up every so often - it's synchronized so shouldn't pose a problem)

Possibly add a thread which is activated every second to reload modified cached templates rather than checking their modification time each time they are accessed.. might be faster in some cases.

Region pasting:

Add location types and allow regions to be pasted into them e.g. In HTML document:

   %%begin{thing}%%Thing: %%thing_value%% %%end{thing}%%
   '
   %%some_region%%
 

In Java code:

  template_file.setProperty("thing_value", "SomeThing");
 
  TemplateFile region1 = template_file.getTemplateRegion("region_1"));
  region1.setProperty("thing_value", "SomeThing");
  
  template_file.setProperty("some_region", region1);
  
  TemplateFile email = ...
  
  email.setRegionEnabled("name_section", true);
  
  
  Vector user_accounts = new Vector();
  for(int i=0; i<num_user_accounts
  TemplateFile user_account_region = email.getRegion("user_account_region");
  user_account_region.setProperty("username", jhdkjd
  user_accounts.add(user_account_region);
  }
  
  email.setProperty("user_accounts", user_accounts);
 

Improve Memory Allocation: By requesting a template file and then handing it back to the template file manager (which at some stage 'cleans' the returned template files) fewer template files will need to be created and destroyed.

See Also:

TemplateFinder

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	TemplateFile.DefaultPropertyPolicy
static interface	TemplateFile.PropertyPolicy Interface for policy object to add objects to template output.

Constructor Summary

Constructors

Modifier	Constructor and Description
	TemplateFile(java.lang.String file_contents) Parses a String into the TemplateFile
protected	TemplateFile(TemplateFile template)
protected	TemplateFile(TemplateFile template, uk.ac.ed.epcc.webapp.content.TemplateFile.Region region)

Method Summary

Modifier and Type	Method and Description
java.lang.String	getFilename()
static TemplateFile	getFromString(java.lang.String template_string)
java.lang.Object	getProperty(java.lang.String name)
TemplateFile	getTemplateRegion(java.lang.String region_name) Fetches a representation of the TemplateFile which appears to contain only the region named.
boolean	hasRegion(java.lang.String region_name) test to see if a region exists
boolean	isEmpty()
boolean	isSet(java.lang.String property_name)
void	prettyPrint(java.io.Writer out) Provides a formatted description of the TemplateFile including region structure, properties and current values.
protected void	prettyPrintRegion(java.io.Writer out, uk.ac.ed.epcc.webapp.content.TemplateFile.Region region, int d)
java.util.Set<java.lang.String>	propertyNames()
void	setProperties(java.util.Map h) Sets a set of properties from a hashtable
void	setProperties(java.util.ResourceBundle resource) Sets all named tokens in the resource properties to be the resource values
void	setProperties(java.lang.String prefix, java.util.Map h)
void	setProperty(java.lang.String property_name, double value) Sets the value of a property to a double precision floating point number.
void	setProperty(java.lang.String property_name, int value) Sets the value of a property to an integer.
void	setProperty(java.lang.String property_name, long value) Sets the value of a property to an integer.
void	setProperty(java.lang.String property_name, java.lang.Object property_value) Sets the value of a property
void	setRegionEnabled(java.lang.String region_name, boolean enabled) Sets a region to be enabled/disabled (in fact sets all regions with that name) Any spaces in the region_name parameter will be mapped to underscores to produce a valid region name
void	setUnsetProperties(java.util.Map h)
java.lang.String	toString()
void	write(java.io.OutputStream out) Convenience method - outputs the TemplateFile with it's current values to the OutputStream.
void	write(TemplateFile.PropertyPolicy policy, java.io.Writer out)
void	write(java.io.Writer out) Outputs the TemplateFile with it's current values to the Writer.
protected void	writeRegion(java.io.Writer out, TemplateFile.PropertyPolicy policy, uk.ac.ed.epcc.webapp.content.TemplateFile.Region region)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TemplateFile

public TemplateFile(java.lang.String file_contents)

Parses a String into the TemplateFile

Parameters:

file_contents - The String to be parsed

TemplateFile

protected TemplateFile(TemplateFile template)

TemplateFile

protected TemplateFile(TemplateFile template,
                       uk.ac.ed.epcc.webapp.content.TemplateFile.Region region)

Method Detail

getFilename

public java.lang.String getFilename()

getProperty

public java.lang.Object getProperty(java.lang.String name)

isEmpty

public boolean isEmpty()

propertyNames

public java.util.Set<java.lang.String> propertyNames()

getTemplateRegion

public TemplateFile getTemplateRegion(java.lang.String region_name)

Fetches a representation of the TemplateFile which appears to contain only the region named.

Parameters:

region_name - Name of the region

Returns:

TemplateFile

prettyPrint

public void prettyPrint(java.io.Writer out)
                 throws java.io.IOException

Provides a formatted description of the TemplateFile including region structure, properties and current values.

Parameters:

out -

Throws:

java.io.IOException

prettyPrintRegion

protected void prettyPrintRegion(java.io.Writer out,
                                 uk.ac.ed.epcc.webapp.content.TemplateFile.Region region,
                                 int d)
                          throws java.io.IOException

Throws:

java.io.IOException

setProperties

public void setProperties(java.util.Map h)

Sets a set of properties from a hashtable

Parameters:

h - Hashtable containing properties.

setProperties

public void setProperties(java.lang.String prefix,
                          java.util.Map h)

setUnsetProperties

public void setUnsetProperties(java.util.Map h)

setProperties

public void setProperties(java.util.ResourceBundle resource)

Sets all named tokens in the resource properties to be the resource values

Parameters:

resource -

setProperty

public void setProperty(java.lang.String property_name,
                        double value)

Sets the value of a property to a double precision floating point number.

Parameters:

property_name - Name of the property to be set

value - New double value for the property

setProperty

public void setProperty(java.lang.String property_name,
                        int value)

Sets the value of a property to an integer.

Parameters:

property_name - Name of the property to be set

value - New integer value for the property

setProperty

public void setProperty(java.lang.String property_name,
                        long value)

Sets the value of a property to an integer.

Parameters:

property_name - Name of the property to be set

value - New integer value for the property

setProperty

public void setProperty(java.lang.String property_name,
                        java.lang.Object property_value)

Sets the value of a property

Parameters:

property_name - Name of the property to be set

property_value - New value for the property

isSet

public boolean isSet(java.lang.String property_name)

setRegionEnabled

public void setRegionEnabled(java.lang.String region_name,
                             boolean enabled)

Sets a region to be enabled/disabled (in fact sets all regions with that name) Any spaces in the region_name parameter will be mapped to underscores to produce a valid region name

Parameters:

region_name - Name of the region to be set

enabled - true if region is to be enabled, false to disable the region

hasRegion

public boolean hasRegion(java.lang.String region_name)

test to see if a region exists

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

Returns:

A String containing the current contents of the TemplateFile. If there was a problem, null is returned.

write

public void write(java.io.OutputStream out)
           throws java.io.IOException

Convenience method - outputs the TemplateFile with it's current values to the OutputStream.

Parameters:

out -

Throws:

java.io.IOException

write

public void write(java.io.Writer out)
           throws java.io.IOException

Outputs the TemplateFile with it's current values to the Writer.

Parameters:

out -

Throws:

java.io.IOException

write

public void write(TemplateFile.PropertyPolicy policy,
                  java.io.Writer out)
           throws java.io.IOException

Throws:

java.io.IOException

writeRegion

protected void writeRegion(java.io.Writer out,
                           TemplateFile.PropertyPolicy policy,
                           uk.ac.ed.epcc.webapp.content.TemplateFile.Region region)
                    throws java.io.IOException

Throws:

java.io.IOException

getFromString

public static TemplateFile getFromString(java.lang.String template_string)